|
| 1 | +# MCP Server |
| 2 | + |
| 3 | +The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that allows AI assistants to interact with external tools and data sources. The `pred` CLI includes a built-in MCP server that exposes the full reduction graph, problem creation, solving, and reduction capabilities to any MCP-compatible AI assistant (such as Claude Code, Cursor, or Windsurf). |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +Install the `pred` CLI tool: |
| 8 | + |
| 9 | +```bash |
| 10 | +cargo install problemreductions-cli |
| 11 | +``` |
| 12 | + |
| 13 | +Or build from source: |
| 14 | + |
| 15 | +```bash |
| 16 | +git clone https://github.com/CodingThrust/problem-reductions |
| 17 | +cd problem-reductions |
| 18 | +make cli # builds target/release/pred |
| 19 | +``` |
| 20 | + |
| 21 | +## Configuration |
| 22 | + |
| 23 | +### Claude Code |
| 24 | + |
| 25 | +Add the following to your project's `.mcp.json` file (or `~/.claude/mcp.json` for global configuration): |
| 26 | + |
| 27 | +```json |
| 28 | +{ |
| 29 | + "mcpServers": { |
| 30 | + "problemreductions": { |
| 31 | + "command": "pred", |
| 32 | + "args": ["mcp"] |
| 33 | + } |
| 34 | + } |
| 35 | +} |
| 36 | +``` |
| 37 | + |
| 38 | +### Generic MCP Client |
| 39 | + |
| 40 | +Any MCP client that supports the stdio transport can connect to the server by running: |
| 41 | + |
| 42 | +```bash |
| 43 | +pred mcp |
| 44 | +``` |
| 45 | + |
| 46 | +The server communicates over stdin/stdout using the MCP JSON-RPC protocol. |
| 47 | + |
| 48 | +## Available Tools |
| 49 | + |
| 50 | +The MCP server provides 10 tools organized into two categories: **graph query tools** for exploring the reduction graph, and **instance tools** for working with concrete problem instances. |
| 51 | + |
| 52 | +### Graph Query Tools |
| 53 | + |
| 54 | +| Tool | Parameters | Description | |
| 55 | +|------|-----------|-------------| |
| 56 | +| `list_problems` | *(none)* | List all registered problem types with aliases, variant counts, and reduction counts | |
| 57 | +| `show_problem` | `problem` (string) | Show details for a problem type: variants, size fields, schema, and incoming/outgoing reductions | |
| 58 | +| `neighbors` | `problem` (string), `hops` (int, default: 1), `direction` ("out"\|"in"\|"both", default: "out") | Find neighboring problems reachable via reduction edges within a given hop distance | |
| 59 | +| `find_path` | `source` (string), `target` (string), `cost` (string, default: "minimize-steps"), `all` (bool, default: false) | Find a reduction path between two problems, optionally minimizing a size field or returning all paths | |
| 60 | +| `export_graph` | *(none)* | Export the full reduction graph as JSON (nodes, edges, overheads) | |
| 61 | + |
| 62 | +### Instance Tools |
| 63 | + |
| 64 | +| Tool | Parameters | Description | |
| 65 | +|------|-----------|-------------| |
| 66 | +| `create_problem` | `problem_type` (string), `params` (JSON object) | Create a problem instance from parameters and return its JSON representation. Supports graph problems, SAT, QUBO, SpinGlass, KColoring, Factoring, and random graph generation | |
| 67 | +| `inspect_problem` | `problem_json` (string) | Inspect a problem JSON or reduction bundle: returns type, size metrics, available solvers, and reduction targets | |
| 68 | +| `evaluate` | `problem_json` (string), `config` (array of int) | Evaluate a configuration against a problem instance and return the objective value or feasibility | |
| 69 | +| `reduce` | `problem_json` (string), `target` (string) | Reduce a problem instance to a target type, returning a reduction bundle with the transformed instance and path metadata | |
| 70 | +| `solve` | `problem_json` (string), `solver` ("ilp"\|"brute-force", default: "ilp"), `timeout` (int, default: 0) | Solve a problem instance or reduction bundle using ILP or brute-force, with optional timeout | |
| 71 | + |
| 72 | +## Available Prompts |
| 73 | + |
| 74 | +The server provides 3 prompt templates that guide the AI assistant through common workflows: |
| 75 | + |
| 76 | +| Prompt | Arguments | Description | |
| 77 | +|--------|-----------|-------------| |
| 78 | +| `analyze_problem` | `problem_type` (required) | Analyze a problem type: show its definition, variants, size fields, and reduction edges | |
| 79 | +| `reduction_walkthrough` | `source` (required), `target` (required) | End-to-end reduction walkthrough: find a path, create an instance, reduce it, and solve the result | |
| 80 | +| `explore_graph` | *(none)* | Explore the reduction graph: list all problems, export the graph, and analyze its structure | |
| 81 | + |
| 82 | +## Example Usage with Claude Code |
| 83 | + |
| 84 | +Once configured, you can interact with the reduction graph naturally through conversation: |
| 85 | + |
| 86 | +``` |
| 87 | +> What problems can MaximumIndependentSet reduce to? |
| 88 | +
|
| 89 | +> Walk me through reducing a 5-vertex MIS instance to QUBO |
| 90 | +
|
| 91 | +> Create a random graph with 8 vertices and solve the MaxCut problem on it |
| 92 | +
|
| 93 | +> Find all reduction paths from Satisfiability to SpinGlass |
| 94 | +``` |
| 95 | + |
| 96 | +The AI assistant will automatically call the appropriate MCP tools to answer your questions, create problem instances, perform reductions, and solve problems. |
| 97 | + |
| 98 | +## Testing with MCP Inspector |
| 99 | + |
| 100 | +You can test the MCP server using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector): |
| 101 | + |
| 102 | +```bash |
| 103 | +npx @modelcontextprotocol/inspector pred mcp |
| 104 | +``` |
| 105 | + |
| 106 | +This opens a web UI where you can: |
| 107 | + |
| 108 | +1. Browse the list of available tools and their schemas |
| 109 | +2. Call tools with custom parameters and inspect the JSON responses |
| 110 | +3. Browse and invoke prompt templates |
| 111 | +4. Verify the server is working correctly before configuring your AI assistant |
| 112 | + |
| 113 | +## Running MCP Tests |
| 114 | + |
| 115 | +To run the MCP server test suite: |
| 116 | + |
| 117 | +```bash |
| 118 | +make mcp-test |
| 119 | +``` |
| 120 | + |
| 121 | +This runs both unit tests (tool logic) and integration tests (MCP protocol-level tool calls). |
0 commit comments