Spec Forge MCP

Minimal NestJS MCP server for extracting tables from documents into one JSON file.

Local Setup

Install dependencies and build the server:

npm install
npm run build

Create .env from .env.example and add your OpenRouter key:

AI_API_KEY=your-openrouter-api-key
AI_BASE_URL=https://openrouter.ai/api/v1
AI_MAX_CHUNK_CHARACTERS=40000
DEFAULT_TABLE_OUTPUT_PATH=output/document-tables.json
HTTP_HOST=127.0.0.1
HTTP_PORT=3000
HTTP_ALLOWED_ORIGIN=*

The document table tool currently uses this hardcoded OpenRouter model:

anthropic/claude-3-haiku

Run HTTP MCP

Start the local HTTP MCP server:

npm run start:http

The MCP endpoint will be:

http://127.0.0.1:3000/mcp

Health check:

curl http://127.0.0.1:3000/health

Connect Claude Desktop

Claude Desktop may not connect directly to local HTTP MCP URLs from claude_desktop_config.json. Use mcp-remote as the bridge: Claude Desktop talks stdio to mcp-remote, and mcp-remote talks HTTP to this server.

Keep this server running with:

npm run start:http

Then open Claude Desktop:

Settings -> Developer -> Edit Config

On macOS, the config file is usually:

~/Library/Application Support/Claude/claude_desktop_config.json

Add this server under mcpServers:

{
  "mcpServers": {
    "spec-forge-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:3000/mcp",
        "--allow-http",
        "--transport",
        "http-first"
      ]
    }
  }
}

If your config already has other MCP servers, only add the spec-forge-mcp block inside the existing mcpServers object.

Fully quit and reopen Claude Desktop. After restart, Claude should show the extract_document_tables tool.

Direct HTTP Clients

Clients that support Streamable HTTP MCP can connect directly to:

http://127.0.0.1:3000/mcp

Example Prompt

Use extract_document_tables on /Users/faisal/Documents/example.pdf and save the JSON to /Users/faisal/Documents/tables.json

The tool will always generate one JSON file.

Docker

Build the image locally:

docker build -t spec-forge-mcp .

Run the container (loads variables from .env):

docker run --env-file .env -p 3000:3000 --rm spec-forge-mcp

Or use Docker Compose:

docker compose up --build

Make sure AI_API_KEY (and any other AI_* vars) are present in your .env before starting.