feat(mcp): ship cypher-mcp, an MCP server for the front-end#10
Merged
Conversation
Adds a stdio MCP (Model Context Protocol) server that exposes the
parse / analyze / plan / optimize / cost / columns pipeline as
tools, so any MCP client (Claude Code, Cursor, Windsurf, Continue,
…) can drive the front-end without writing a custom adapter.
Layered to keep the library lean:
- New optional dep `serde_json` and a new `mcp` Cargo feature gate
the protocol code; default builds and library consumers' dep
trees are untouched.
- `pub mod mcp` (cfg-gated) holds the protocol envelope and tool
dispatch.
- `src/bin/cypher-mcp.rs` is a thin stdio loop that delegates to
`mcp::handle_request`.
- `[[bin]] cypher-mcp` declares `required-features = ["mcp"]`, so
the binary only exists when the feature is on.
Eight tools, every one taking a `query` string:
- `cypher_parse` - AST debug-print + clause count.
- `cypher_validate` - quick yes/no around parse + analyze, returns
errors with severity / code / message.
- `cypher_analyze` - bindings + every issue from the analyzer.
- `cypher_plan` - tree-pretty-printed plan; optional `optimize`
flag applies the rewriter first.
- `cypher_optimize` - before / after the optimizer runs to
fixpoint, plus a `changed` flag.
- `cypher_explain` - the headline tool: every pipeline stage in one
response (parse, analyze, plan, optimized_plan, cost, output and
required input columns).
- `cypher_cost` - `Estimate { cardinality, cost }` from the default
`CardinalityCostModel`.
- `cypher_columns` - `output_columns` and `required_input_columns`
for the optimized plan.
Protocol envelope implements MCP `2024-11-05`: `initialize`,
`tools/list`, `tools/call`, `ping`, with `notifications/initialized`
silently swallowed and unknown methods returning JSON-RPC -32601.
Tool-level failures come back as `isError: true` content (what MCP
clients expect), not JSON-RPC errors.
20 integration tests in `tests/mcp.rs` (cfg-gated on the feature)
cover protocol envelope, four error paths, and every tool's happy +
sad path. CI updated to `cargo test --all-features` and
`cargo clippy --all-features` so the gates actually exercise the
new code; a separate `cargo build --lib` step keeps the
default-feature library config honest (catches accidental dep
leakage from `mcp` into what downstream consumers see).
Verified end-to-end against the release binary with a 22-case
external Python harness (full MCP handshake, all 8 tools' happy +
sad paths). `claude mcp list` reports cypher-rs as Connected after
`claude mcp add`.
README gains an "MCP Server" section between the library Usage
example and "What separation buys you" with build / register /
tool-table / sample-prompt material; CHANGELOG logs the new
surface under [Unreleased].
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
protosphinx
added a commit
that referenced
this pull request
May 2, 2026
Adds a stdio MCP (Model Context Protocol) server that exposes the
parse / analyze / plan / optimize / cost / columns pipeline as
tools, so any MCP client (Claude Code, Cursor, Windsurf, Continue,
…) can drive the front-end without writing a custom adapter.
Layered to keep the library lean:
- New optional dep `serde_json` and a new `mcp` Cargo feature gate
the protocol code; default builds and library consumers' dep
trees are untouched.
- `pub mod mcp` (cfg-gated) holds the protocol envelope and tool
dispatch.
- `src/bin/cypher-mcp.rs` is a thin stdio loop that delegates to
`mcp::handle_request`.
- `[[bin]] cypher-mcp` declares `required-features = ["mcp"]`, so
the binary only exists when the feature is on.
Eight tools, every one taking a `query` string:
- `cypher_parse` - AST debug-print + clause count.
- `cypher_validate` - quick yes/no around parse + analyze, returns
errors with severity / code / message.
- `cypher_analyze` - bindings + every issue from the analyzer.
- `cypher_plan` - tree-pretty-printed plan; optional `optimize`
flag applies the rewriter first.
- `cypher_optimize` - before / after the optimizer runs to
fixpoint, plus a `changed` flag.
- `cypher_explain` - the headline tool: every pipeline stage in one
response (parse, analyze, plan, optimized_plan, cost, output and
required input columns).
- `cypher_cost` - `Estimate { cardinality, cost }` from the default
`CardinalityCostModel`.
- `cypher_columns` - `output_columns` and `required_input_columns`
for the optimized plan.
Protocol envelope implements MCP `2024-11-05`: `initialize`,
`tools/list`, `tools/call`, `ping`, with `notifications/initialized`
silently swallowed and unknown methods returning JSON-RPC -32601.
Tool-level failures come back as `isError: true` content (what MCP
clients expect), not JSON-RPC errors.
20 integration tests in `tests/mcp.rs` (cfg-gated on the feature)
cover protocol envelope, four error paths, and every tool's happy +
sad path. CI updated to `cargo test --all-features` and
`cargo clippy --all-features` so the gates actually exercise the
new code; a separate `cargo build --lib` step keeps the
default-feature library config honest (catches accidental dep
leakage from `mcp` into what downstream consumers see).
Verified end-to-end against the release binary with a 22-case
external Python harness (full MCP handshake, all 8 tools' happy +
sad paths). `claude mcp list` reports cypher-rs as Connected after
`claude mcp add`.
README gains an "MCP Server" section between the library Usage
example and "What separation buys you" with build / register /
tool-table / sample-prompt material; CHANGELOG logs the new
surface under [Unreleased].
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ships an MCP (Model Context Protocol) server so any MCP-compatible agent — Claude Code, Cursor, Windsurf, Continue — can drive the cypher-rs front-end as tools, without writing a custom adapter.
What landed
Verification
Test plan