Skip to content
ModernizeSpec

MCP Server Integration

The MCP Server integration provides deterministic access to ModernizeSpec data. Unlike context injection (probabilistic), tool calls are structured API calls with typed inputs and outputs. The server can also write back to spec files, enabling agents to update migration progress.

Who Reads It

Section titled “Who Reads It”

Claude Code, Claude Desktop, VS Code, ChatGPT — any MCP-capable host.

How It Works

Section titled “How It Works”

A ModernizeSpec MCP server runs as a local process. It loads the spec files from .agents/modernization/ and exposes them as MCP tools. The agent calls these tools via structured API calls.

Setup

Section titled “Setup”

Configuration

Section titled “Configuration”

Add to .mcp.json in your project root for auto-discovery by Claude Code:

{
  "mcpServers": {
    "modernizespec": {
      "command": "npx",
      "args": ["@modernizespec/mcp-server"],
      "cwd": "."
    }
  }
}

Install

Section titled “Install”
Terminal window
npm install @modernizespec/mcp-server

Available Tools

Section titled “Available Tools”

modernize_get_context

Section titled “modernize_get_context”

Get the modernization context for a specific file. Returns the bounded context, extraction tier, dependencies, and parity status.

server.tool(
  "modernize_get_context",
  { filePath: z.string().describe("Path to the file being modified") },
  async ({ filePath }) => {
    const context = spec.domains.getContextForFile(filePath);
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          boundedContext: context.name,
          type: context.type,
          extractionTier: spec.complexity.getTier(context.name),
          dependencies: context.dependencies,
          parityStatus: spec.migrationState.getParityStatus(context.name),
        }, null, 2),
      }],
    };
  }
);

modernize_check_sequence

Section titled “modernize_check_sequence”

Check whether a module can be safely extracted by verifying its dependencies are complete.

server.tool(
  "modernize_check_sequence",
  { module: z.string().describe("Module to extract") },
  async ({ module }) => {
    const sequence = spec.extractionPlan.getSequence(module);
    const blockers = sequence.filter(s => s.status !== "completed");
    return {
      content: [{
        type: "text",
        text: blockers.length > 0
          ? `Cannot extract ${module} yet. Blocked by: ${blockers.map(b => b.name).join(", ")}`
          : `${module} is clear for extraction. No sequencing blockers.`,
      }],
    };
  }
);

modernize_update_progress

Section titled “modernize_update_progress”

Update migration progress for a bounded context. This writes back to migration-state.json.

server.tool(
  "modernize_update_progress",
  {
    context: z.string(),
    entitiesMigrated: z.number(),
    parityPassing: z.number(),
    parityTotal: z.number(),
  },
  async (args) => {
    spec.migrationState.updateContext(args.context, {
      entitiesMigrated: args.entitiesMigrated,
      parityTests: { passing: args.parityPassing, total: args.parityTotal },
    });
    await spec.save();
    return { content: [{ type: "text", text: `Updated ${args.context} progress.` }] };
  }
);

Full Server Example

Section titled “Full Server Example”
import { McpServer } from "@modelcontextprotocol/server";
import { ModernizeSpec } from "@modernizespec/sdk";
import { z } from "zod";


const server = new McpServer({
  name: "modernizespec",
  version: "1.0.0",
});


const spec = await ModernizeSpec.load(process.cwd());


// Register tools (as shown above)
server.tool("modernize_get_context", /* ... */);
server.tool("modernize_check_sequence", /* ... */);
server.tool("modernize_update_progress", /* ... */);

Strengths and Limitations

Section titled “Strengths and Limitations”
AspectDetail
StrengthDeterministic — structured tool calls, not prose interpretation
StrengthTyped inputs and outputs with validation
StrengthRead + write — agent can update progress, resolve blockers
StrengthComposable — build custom tools on top of the SDK
LimitationRequires MCP-capable host
LimitationMore setup than dropping Markdown files
LimitationServer process must be running

Next Steps

Section titled “Next Steps”