Metadata-Version: 2.4
Name: cypherwolf-mcp
Version: 0.1.6
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

**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](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"
    }
  }
}
```

### Claude Code (`settings.json`)

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

```bash
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](#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/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

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

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