cypherwolf-mcp 0.1.0

CypherWolf MCP server — Neo4j Cypher query revision from a curated corpus, for @neo4j.com users.

cypherwolf-mcp

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

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.

---

Install

pip install cypherwolf-mcp

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

Sign in (first run)

Before the MCP server can revise queries, 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.

Configure your MCP client

Point your MCP client at the cypherwolf-mcp console script (installed on your PATH by pip).

Cursor (~/.cursor/mcp.json)

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

Claude Code (settings.json)

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

Restart the client after editing the config. The cypherwolf server exposes a single tool, revise_query.

Coworker testing checklist

After the PyPI upload is live, use these steps for Neo4j coworker testing while the source repo remains private:

1. Install or upgrade the package:

   python -m pip install --upgrade cypherwolf-mcp
   

2. Sign in once:

   cypherwolf-mcp auth
   

   Use your @neo4j.com email, then paste the 6-digit code emailed to you. The package stores a 30-day session token at ~/.cypherwolf/credentials.json with file mode 0600.

3. Add the MCP server to Cursor:

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

4. Restart Cursor and confirm a cypherwolf MCP server with one tool, revise_query, is available.

   For Claude Code, use the settings.json snippet in Configure your MCP client.

5. Ask Cursor to call revise_query with a Cypher query and optional schema context. The shim is already pointed at the deployed service: https://cypherwolf-shim-ez6emjisaa-uc.a.run.app.

Expected auth behavior:

• [e-mail] emails are rejected.
• Expired or revoked sessions return an auth-required response telling you to rerun cypherwolf-mcp auth.
• Queries and rewrites are logged to Neo4j-internal storage keyed by your email, as disclosed during sign-in.

The revise_query tool

Arg	Required	Description
query	yes	The Cypher query to revise.
context	no	Schema or context details (labels, indexes, cardinalities).
neo4j_version	no	Target Neo4j version, e.g. "5.26".
mode	no	Optional tuning mode, e.g. "verbose".

Response (structured JSON):

{
  "option_a": "MATCH (u:User {id: $id}) RETURN u",
  "option_b": "…optional second rewrite…",
  "validation_gates": ["Equality predicate on :User(id) — confirm CREATE INDEX …"],
  "why": ["Corpus precedent (Slack, Fauth): …"],
  "top_n": ["[0.91] Slack — Fauth: supernode pagination"],
  "no_rewrite_reason": null
}

• Corpus-gap is a success. When the corpus has no relevant precedent, option_a is null and no_rewrite_reason explains why ("corpus-gap"). CypherWolf never bluffs a rewrite.
• On an auth / rate-limit / upstream error the tool returns a structured payload with an error field and a matching no_rewrite_reason ("auth-required", "rate-limited", "upstream-unavailable") rather than throwing.

Configuration

Environment variable	Default	Purpose
CYPHERWOLF_SHIM_URL	https://cypherwolf-shim-ez6emjisaa-uc.a.run.app	CypherWolf service base URL.
CYPHERWOLF_SESSION_TOKEN	(unset)	Supply a session token directly, bypassing the on-disk cache (CI / scripted use).

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.

---

Publishing

The package is prepared for public PyPI as cypherwolf-mcp. The source repo can stay private during the Neo4j-only coworker-testing phase because the wheel ships no secrets and all access control is enforced by the hosted shim's @neo4j.com email-code gate.

Current publish status: distribution artifacts build and pass twine check, but the first production PyPI upload is blocked until an account-scoped pypi.org API token is available. A project-scoped token cannot create the first release because the cypherwolf-mcp project does not exist on PyPI yet.

Build the artifacts

cd mcp
python -m build            # produces dist/cypherwolf_mcp-<version>-py3-none-any.whl + .tar.gz

Verify a clean install in a throwaway venv:

python -m venv /tmp/cw && /tmp/cw/bin/pip install dist/cypherwolf_mcp-*.whl
/tmp/cw/bin/cypherwolf-mcp --help
/tmp/cw/bin/pip freeze | grep -iE 'google|neo4j'   # must be empty

First production publish — one-shot account token

Use an account-scoped PyPI API token exactly once to create the production cypherwolf-mcp project. Build from a committed tree, publish, verify the public install, then remove the account token from the release path.

cd mcp
rm -rf dist build *.egg-info
python -m build
python -m twine check dist/*
python -m twine upload dist/*

After upload, verify in a clean environment:

python -m venv /tmp/cw-pypi
/tmp/cw-pypi/bin/pip install cypherwolf-mcp
/tmp/cw-pypi/bin/cypherwolf-mcp --help
/tmp/cw-pypi/bin/pip freeze | grep -iE 'google|neo4j'   # must be empty

Ongoing publish path — PyPI Trusted Publishing via GitHub Actions

Trusted Publishing (OIDC) is preferred over a long-lived API token: no secret to store or rotate.

1. On PyPI, add a Trusted Publisher for the neo-gerlt/cypherwolf repo, workflow .github/workflows/publish-mcp.yml, and environment pypi.
2. Cut a GitHub Release, or run the workflow manually if PyPI's Trusted Publisher settings allow it. The workflow builds mcp/, runs twine check, and publishes with OIDC.
3. Retire the account-scoped token after Trusted Publishing is confirmed.

Alternative — manual publish after the project exists

cd mcp
python -m build
python -m twine upload dist/*        # with a project-scoped token

Release checklist

• Bump version in pyproject.toml and cypherwolf/__init__.py for each release.

• Build from repos/cypherwolf/mcp/ and publish with Trusted Publishing or a scoped PyPI token. Do not commit any token to the repo.

• Verify a fresh install in a clean virtual environment:

  python -m venv /tmp/cw && /tmp/cw/bin/pip install cypherwolf-mcp
  /tmp/cw/bin/cypherwolf-mcp --help
  /tmp/cw/bin/pip freeze | grep -iE 'google|neo4j'   # must be empty
  

• Repo split to neo-gerlt/cypherwolf-mcp remains deferred (follow-on #10) and is not required to publish — a pyproject.toml rooted at mcp/ ships the wheel from the monorepo today.