---
title: @specdiff/mcp Server
description: MCP server reference for @specdiff/mcp — expose breaking-change detection tools to AI coding agents.
url: https://pr-1-7cfcfe393d12.thally.app/specdiff-mcp-server
---

# @specdiff/mcp Server

MCP server reference for @specdiff/mcp — expose breaking-change detection tools to AI coding agents.

MCP server reference for `@specdiff/mcp` v0.1.0. The binary is `specdiff-mcp`
and communicates over stdio transport.

## Setup

Add the server to your `.mcp.json` or `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "specdiff": {
      "command": "npx",
      "args": ["-y", "@specdiff/mcp"]
    }
  }
}
```

The server registers four tools that expose Specdiff's core functionality to
coding agents.

---

## Tools

### specdiff_compare

Compares a before and after document.

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `beforePath` | `string` | no | — | File path (relative to cwd) for the before document |
| `afterPath` | `string` | no | — | File path for the after document |
| `before` | `string` | no | — | Inline before document text |
| `after` | `string` | no | — | Inline after document text |
| `kind` | `string` | no | `"auto"` | `"auto"`, `"openapi"`, or `"json-schema"` |
| `failOn` | `string` | no | `"breaking"` | Threshold for the `passed` boolean |
| `ignoreRules` | `string[]` | no | — | Rule codes to exclude |

Returns DiffResult JSON with `passed: boolean` and `failOn`.

### specdiff_explain_rule

| Input | Type | Required |
| --- | --- | --- |
| `code` | `string` | yes |

Returns the full `RuleInfo` for a single rule code, or an error if the code is
unknown.

### specdiff_list_rules

Takes no input. Returns the full `RuleInfo[]` catalogue as JSON.

### specdiff_format

| Input | Type | Required |
| --- | --- | --- |
| `result` | `DiffResult` | yes |
| `format` | `string` | yes |

Accepts `"text"` or `"markdown"` as format. Renders the result as a formatted
report string.

---

## Path security

All file paths are resolved against `process.cwd()`. Paths that escape the
working directory are rejected before any file system access occurs.

---

## Programmatic API

### createSpecdiffServer

```ts
function createSpecdiffServer(
  options?: SpecdiffServerOptions,
): McpServer;
```

Creates an un-connected `McpServer` with the four Specdiff tools registered.

### SpecdiffServerOptions

```ts
interface SpecdiffServerOptions {
  cwd?: string;
}
```

`cwd` defaults to `process.cwd()`.

### TOOL_NAMES

```ts
const TOOL_NAMES: {
  compare: "specdiff_compare";
  explainRule: "specdiff_explain_rule";
  listRules: "specdiff_list_rules";
  format: "specdiff_format";
};
```

### resolveInsideCwd

```ts
function resolveInsideCwd(
  cwd: string,
  filePath: string,
): string;
```

Resolves a user-supplied path inside `cwd`. Throws if the resolved path
escapes the working directory.

### parseDocumentText

```ts
function parseDocumentText(
  text: string,
  fileName?: string,
): unknown;
```

Parses text as JSON or YAML using the file extension as a hint.

---

## Programmatic usage example

```ts
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createSpecdiffServer } from "@specdiff/mcp";

const server = createSpecdiffServer({ cwd: process.cwd() });
await server.connect(new StdioServerTransport());
```