Parser

CI npm license

Snapshot, parse, validate, and document Model Context Protocol servers.

MCP Protocol Compatibility

Built against the MCP specification. Supports all released protocol versions:

Protocol Version	Status
2025-11-25	Current stable
2025-06-18	Supported
2025-03-26	Supported
2024-11-05	Supported

All three MCP transports are supported: stdio, SSE, and streamable HTTP.

Install

npm install mcp-parser

Quick Start

import { snapshot, validate, generateMarkdown } from "mcp-parser";
import { writeFile } from "node:fs/promises";

const spec = await snapshot({
  transport: { type: "stdio", command: "node", args: ["server.js"] },
});

const result = validate(spec);
if (!result.valid) {
  for (const d of result.diagnostics) {
    console.error(`${d.severity}: ${d.path} - ${d.message}`);
  }
}

await writeFile("mcp.json", JSON.stringify(spec, null, 2));
await writeFile("mcp.md", generateMarkdown(spec));

What is mcp.json?

A static snapshot of an MCP server's capabilities: its tools, resources, and prompts. Think of it as openapi.json for MCP servers.

MCP servers describe themselves at runtime via tools/list, resources/list, and prompts/list. An mcp.json captures that live surface in a versionable file for documentation, validation, diffing, and tooling that should not need a running server.

See mcp-schema for the full type definitions and JSON Schema.

API

parse(path, options?)

Parse an mcp.json file into a typed McpSpec object.

const spec = await parse("./mcp.json");
console.log(spec.server.name);   // "my-server"
console.log(spec.tools?.length); // 5

Options:

• dereference (default: true). Resolves $ref pointers using the spec's $defs.

parseString(content, options?)

Parse a JSON string directly.

const spec = parseString('{ "mcpSpec": "0.3.1", ... }');

validate(spec)

Validate an McpSpec for correctness and best practices.

const result = validate(spec);
// result.valid: boolean (true if no errors)
// result.diagnostics: array of { severity, path, message }

Checks for:

• Required fields (mcpSpec, server, tool names, inputSchema)
• Duplicate tool/resource/prompt names
• Missing descriptions (warnings)
• Invalid inputSchema types

snapshot(options)

Connect to a running MCP server and capture a static snapshot. Supports all three MCP transports.

import { snapshot } from "mcp-parser";
import { writeFile } from "node:fs/promises";

// stdio
const spec = await snapshot({
  transport: { type: "stdio", command: "node", args: ["server.js"] },
});

// SSE
const spec = await snapshot({
  transport: { type: "sse", url: "http://localhost:3000/sse" },
});

// Streamable HTTP
const spec = await snapshot({
  transport: { type: "streamable-http", url: "http://localhost:3000/mcp" },
});

await writeFile("mcp.json", JSON.stringify(spec, null, 2));

All transports support an optional timeout (default: 30s). SSE and HTTP transports accept a headers object for authentication.

generateMarkdown(spec)

Generate a full markdown reference document.

generateLlmsTxt(spec, baseUrl?)

Generate a compact llms.txt-style index. This is a compatibility export for tools and docs sites that already consume the convention, not a guarantee that model providers will discover or fetch it automatically.

const txt = generateLlmsTxt(spec, "https://docs.example.com");

generateLlmsFullTxt(spec)

Generate a complete markdown reference with the server context inline.

const full = generateLlmsFullTxt(spec);

CLI

# Parse and pretty-print
mcp-parser parse ./mcp.json

# Validate
mcp-parser validate ./mcp.json

# Snapshot via stdio
mcp-parser snapshot --stdio "node server.js" -o mcp.json

# Snapshot via SSE
mcp-parser snapshot --sse http://localhost:3000/sse -o mcp.json

# Snapshot via streamable HTTP
mcp-parser snapshot --http http://localhost:3000/mcp -o mcp.json

# With auth headers
mcp-parser snapshot --sse http://localhost:3000/sse --header "Authorization:Bearer tok" -o mcp.json

# Generate markdown reference (default)
mcp-parser generate ./mcp.json -o mcp.md

# Generate compact context index
mcp-parser generate ./mcp.json --format llms-txt -o llms.txt

# Generate full context reference
mcp-parser generate ./mcp.json --format llms-full-txt -o llms-full.txt

MCP Specification Resources

• MCP Specification (current stable)
• Specification repo (includes JSON Schema for each protocol version)
• TypeScript SDK (@modelcontextprotocol/sdk)
• Python SDK (mcp on PyPI)

Related

• mcp-schema: TypeScript types and JSON Schema for MCP specs
• sourcey: generate documentation from MCP specs, OpenAPI, and markdown

License

MIT