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.

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"
    }
  }
}

Claude Code (settings.json)

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

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.6
  [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.

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 (or Claude Code), ask the assistant to revise a Cypher 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. 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/mcp.json, or Claude Code settings.json), 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.