Metadata-Version: 2.4
Name: cypherwolf-mcp
Version: 0.1.11
Summary: CypherWolf MCP server — Neo4j Cypher query revision from a curated corpus, for @neo4j.com users.
Author: Neo4j Customer Success
License: Proprietary
Project-URL: Homepage, https://github.com/neo-gerlt/cypherwolf
Project-URL: Repository, https://github.com/neo-gerlt/cypherwolf
Keywords: neo4j,cypher,mcp,query-tuning
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: httpx
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# cypherwolf-mcp

<img src="../assets/cypherwolf-logo-small.png" alt="CypherWolf logo" width="128">

**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](https://pipx.pypa.io) —
it isolates the dependencies and puts the `cypherwolf-mcp` command on your `PATH`:

```bash
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:

```bash
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`)

```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`.

```bash
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:

```toml
[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:

```bash
cypherwolf-mcp status
```

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

```
CypherWolf self-test
  [PASS] version         cypherwolf-mcp 0.1.10
  [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](#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/`.

```bash
# 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

| Arg | Required | Description |
|---|---|---|
| `query` | yes | The Cypher query to evaluate against corpus precedent. |
| `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):

```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.
- **Rate limit.** Each login session may make 500 `revise_query` calls per
  clock hour. Past that the tool raises an error that states the limit and
  when it resets (for example, *"CypherWolf rate limit reached (500 requests per
  hour). The limit resets in 23 minutes (at 13:00 UTC); try again then."*).
  Re-authenticating does not reset it. Against an older service the message
  falls back to *"Please wait a moment and try again."*

## 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.

---

Maintaining or releasing the package? See [PUBLISHING.md](PUBLISHING.md).
