cypherwolf-mcp

CypherWolf revises Neo4j Cypher queries against a curated corpus of Neo4j engineering precedent, returning compatibility-gated precedent options plus the index/constraint validation gates to confirm before applying changes.

It ships as a single-tool MCP server (revise_query) that runs locally over stdio and proxies to the CypherWolf HTTPS service. Access is restricted to @neo4j.com users. The package holds no API key, no shared secret, and no Aura credentials — all access control is enforced server-side via an email gate plus a 30-day session token.

Get set up in about two minutes: install → sign in → add to your MCP client → cypherwolf-mcp status to confirm → ask for a rewrite.

Quick start: hand this to your AI assistant

Give this README to Cursor, Claude Code or Codex (attach it or paste it in) and say: "Follow this file to install and configure CypherWolf." The assistant can do steps 1, 3 and 4 for you.

Step 2 (sign in) is yours to do. cypherwolf-mcp auth prompts for your email and a 6-digit code emailed to you, so run it yourself in a normal terminal window, not from inside the assistant or an IDE task runner, which can't answer the prompts.

Notes for the assistant: run step 1, then ask the user to complete step 2 and tell you when it's done. After that, do step 3 for the client in use (merge into existing config, never overwrite it) and step 4. Don't read or print ~/.cypherwolf/credentials.json, and don't change anything that isn't described here.

1. Install

CypherWolf is a standalone CLI, so install it with pipx — it isolates the dependencies and puts the cypherwolf-mcp command on your PATH:

pipx install cypherwolf-mcp

Requires Python 3.10+. Dependencies are just mcp and httpx — no database driver, no cloud SDKs.

Don't have pipx? Install it (brew install pipx on macOS, or python3 -m pip install --user pipx) and run pipx ensurepath. On Homebrew/externally-managed Python, pip install cypherwolf-mcp fails with a PEP 668 error — pipx is the supported path. (A manual pip install inside an activated virtualenv also works if you prefer.)

Upgrade later with pipx upgrade cypherwolf-mcp.

2. Sign in

Sign in once in a normal terminal with your Neo4j email:

cypherwolf-mcp auth

You will see the following disclosure, then be prompted for your email and a 6-digit code sent to it:

This will email a 6-digit code to verify your @neo4j.com address. Your queries and the rewrites are saved to a Neo4j-internal folder under your email for internal use only.

The resulting session token is cached at ~/.cypherwolf/credentials.json (mode 0600) and is valid for 30 days. After it expires — or if the token is revoked — the tool will ask you to run cypherwolf-mcp auth again.

3. Add CypherWolf to your MCP client

Point your MCP client at the cypherwolf-mcp console script (installed on your PATH by the step above), then restart the client.

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "cypherwolf": {
      "command": "cypherwolf-mcp"
    }
  }
}

If ~/.cursor/mcp.json already lists other servers, add the cypherwolf entry alongside them; don't replace the file. Restart Cursor, then confirm a cypherwolf server with one tool, revise_query, appears in Settings → MCP.

Claude Code

Register the server with the claude mcp add command (user scope, so it works in every project). Claude Code does not read MCP servers from settings.json.

claude mcp add cypherwolf --scope user -- cypherwolf-mcp
claude mcp list

claude mcp list should show cypherwolf as connected. Start a new Claude Code session afterwards.

Codex (~/.codex/config.toml)

Codex CLI configures MCP servers as TOML tables (not JSON). If the file already exists, append this table rather than replacing the file:

[mcp_servers.cypherwolf]
command = "cypherwolf-mcp"

If cypherwolf-mcp is not on the PATH Codex launches with, use an absolute path (find it with which cypherwolf-mcp, typically ~/.local/bin/cypherwolf-mcp). Restart Codex, then confirm with codex mcp list.

The cypherwolf server exposes a single tool, revise_query.

4. Confirm it works

Before you rely on it, run the built-in self-test — no MCP client required:

cypherwolf-mcp status

It checks the whole chain and prints one line per stage:

CypherWolf self-test
  [PASS] version         cypherwolf-mcp 0.1.8
  [PASS] credentials     you@neo4j.com, token age 2d (re-auth at 30d)
  [PASS] shim round-trip revise_query('RETURN 1') → 200 in 0.41s (https://cypherwolf-shim-ez6emjisaa-uc.a.run.app)

All checks passed. CypherWolf is ready to use.

cypherwolf-mcp auth needs an interactive terminal; run from an assistant or IDE task runner it will tell you to open a normal terminal window.

If any line says [FAIL], it tells you exactly what to fix (for example, run cypherwolf-mcp auth again). The command exits non-zero on failure, so you can use it in scripts.

5. First rewrite

In Cursor, Claude Code or Codex, ask the assistant to tune, optimize or review a Neo4j query with CypherWolf, for example:

Use cypherwolf to revise MATCH (u:User) WHERE u.id = $id RETURN u.

CypherWolf returns compatibility-gated precedent candidates plus the validation gates to confirm before applying. Assistants are told to call revise_query when you ask to tune, optimize or review a query, not for every Cypher they write, because each request is logged under your email. Naming CypherWolf in your prompt is the most reliable trigger. See The revise_query tool for the response shape.

Uninstall

Removing CypherWolf is just as simple. The only local state it writes is the credentials cache at ~/.cypherwolf/.

# 1. Remove the "cypherwolf" server entry from your MCP client config
#    Cursor: delete it from ~/.cursor/mcp.json
#    Claude Code: claude mcp remove cypherwolf
#    Codex: delete the [mcp_servers.cypherwolf] table from ~/.codex/config.toml
#    Then restart the client.

# 2. Remove the package.
pipx uninstall cypherwolf-mcp        # or: pip uninstall cypherwolf-mcp

# 3. Remove the local credentials cache (the only local state CypherWolf writes).
rm -rf ~/.cypherwolf/

That is a complete, clean removal — nothing else is left on your machine.

The revise_query tool

Response (structured JSON):

{
  "option_a": "MATCH (u:User {id: $id}) RETURN u",
  "option_b": "…optional second rewrite…",
  "recommendation_tier": "recommend",
  "review_required": false,
  "same_domain": true,
  "validation_gates": ["Equality predicate on :User(id) — confirm CREATE INDEX …"],
  "why": ["Corpus precedent (Slack, Fauth): …"],
  "top_n": ["[0.91] Slack — Fauth: supernode pagination"],
  "guidance": ["Advice note 1", "Advice note 2"],
  "no_rewrite_reason": null
}

• option_a/option_b are compatibility-gated precedent candidates, not guaranteed semantic equivalents of the input query. Review before applying.
• recommendation_tier is recommend for higher-confidence candidates and draft when CypherWolf surfaces a lower-confidence but hard-safe candidate. Drafts always set review_required: true.
• same_domain reports whether the candidate shares a label/relationship anchor with your query. A draft with same_domain: false is a structural lookalike from a different schema — the error field flags it as a pattern reference, not a rewrite. Don't adopt that option_a; use only the validation_gates and guidance.
• On abstain responses, guidance carries 3-5 extracted advice notes from top evidence rows so users still get actionable hints when no safe rewrite is selected.
• Abstain is a success. When confidence is too low or the corpus has no usable precedent, option_a is null and no_rewrite_reason explains why (for example "low-confidence" or "corpus-gap"). CypherWolf never bluffs.
• Operational failures are real errors. A dead service, an expired session, or a rate limit raises a clear MCP error (for example, "CypherWolf authentication is required — run cypherwolf-mcp auth") rather than a half-answer. Run cypherwolf-mcp status to pinpoint the cause.

Configuration

Credentials cache: ~/.cypherwolf/credentials.json (mode 0600), holding {email, session_token, issued_at}.

Privacy

Your submitted queries and the returned rewrites are logged server-side to a Neo4j-internal storage location, keyed by your email, for internal use only. See the sign-in disclosure above.

Maintaining or releasing the package? See PUBLISHING.md.