StaticMCP STDIO Bridge

A lightweight stdio bridge server that serves StaticMCP files.

How It Works

The StaticMCP Bridge acts as a translation layer between the MCP protocol and your static JSON files:

1. Manifest: A mcp.json file describes available resources and tools
2. Resources: Static JSON files in resources/ directory
3. Tools: Pre-computed tool responses in tools/ directory structure
4. Bridge: This server dynamically routes MCP requests to the appropriate JSON files

More about StaticMCP on https://staticmcp.com.

Installation

cargo install static_mcp_bridge

Or build from source:

git clone https://github.com/StaticMCP/StaticMCP
cd StaticMCP/bridge
cargo build --release

Quick Start

1. Create a StaticMCP Directory Structure

my-static-mcp/
  ├── mcp.json                       # Manifest file
  ├── resources/
  │     ├── README.md.json           # Resource responses
  │     └── config.json.json
  └── tools/
        ├── search/
        │     ├── rust.json          # Tool response for search("rust")
        │     └── javascript.json    # Tool response for search("javascript")
        └── analyze/
              └── file.json          # Tool response for analyze("file")

2. Create the Manifest (mcp.json)

{
  "serverInfo": {
    "name": "My StaticMCP Server",
    "version": "1.0.0"
  },
  "capabilities": {
    "resources": [
      {
        "uri": "file://README.md",
        "name": "Project README",
        "description": "Main project documentation"
      }
    ],
    "tools": [
      {
        "name": "search",
        "description": "Search for information",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": { "type": "string" }
          }
        }
      }
    ]
  }
}

3. Create Resource Files

resources/README.md.json:

{
  "contents": [
    {
      "uri": "file://README.md",
      "mimeType": "text/markdown",
      "text": "# My Project\n\nThis is a sample README..."
    }
  ]
}

4. Create Tool Response Files

tools/search/rust.json:

{
  "content": [
    {
      "type": "text",
      "text": "Here are search results for 'rust':\n\n1. Rust Programming Language\n2. Systems programming\n3. Memory safety"
    }
  ]
}

5. Run the Bridge

# Local directory
static-mcp-bridge ./my-static-mcp

# Remote URL (hosted static files)
static-mcp-bridge https://mysite.com/my-mcp

Usage with MCP Inspector

Test your StaticMCP server using the official MCP Inspector:

npx @modelcontextprotocol/inspector static-mcp-bridge https://yourdomain.com/your-mcp

File Path Conventions

The bridge automatically maps MCP requests to file paths:

Resources

• file://path/to/file → resources/path/to/file.json
• custom://resource → resources/resource.json

Tools

• Single argument: tools/{tool_name}/{arg_value}.json
• Two arguments: tools/{tool_name}/{arg1}/{arg2}.json (sorted)

Examples:

• search("rust") → tools/search/rust.json
• analyze(file="test.txt", format="json") → tools/analyze/json/test.txt.json

Response Format

Resource Responses

{
  "contents": [
    {
      "uri": "file://example.txt",
      "mimeType": "text/plain",
      "text": "File content here"
    }
  ]
}

Tool Responses

{
  "content": [
    {
      "type": "text",
      "text": "Tool response text"
    }
  ]
}

Deployment Options

Static Web Hosting

Deploy your StaticMCP files to any static hosting service:

• Vercel: vercel --prod
• Netlify: Drag & drop or Git integration
• GitHub Pages: Push to gh-pages branch
• AWS S3: Upload files to S3 bucket with public access
• CDN: Use CloudFlare, AWS CloudFront, etc.

Example with Vercel

cd my-static-mcp
echo '{"builds": [{"src": "**", "use": "@vercel/static"}]}' > vercel.json
vercel --prod

Then use: static-mcp-bridge https://my-mcp.vercel.app

Building StaticMCP Content

You can generate your StaticMCP files using any method:

Python Script

import json
import os

# Generate tool responses
for query in ['rust', 'javascript', 'python']:
    result = {"content": [{"type": "text", "text": f"Results for {query}..."}]}
    os.makedirs(f'tools/search', exist_ok=True)
    with open(f'tools/search/{query}.json', 'w') as f:
        json.dump(result, f)

Build Process

#!/bin/bash
# generate-mcp.sh

echo "Generating StaticMCP content..."
python scripts/generate_resources.py
python scripts/generate_tools.py
echo "StaticMCP content ready!"

Advanced Features

Error Handling

If a requested file doesn't exist, the bridge returns an appropriate MCP error response.

CORS Support

When serving over HTTP, the bridge handles CORS headers automatically.

Caching

All responses are highly cacheable since content is static. Consider setting long cache headers when serving files.

Examples

Check out these example StaticMCP implementations:

• Resume MCP - Personal resume and portfolio

StaticMCP Bridge - Turn any static file hosting into a powerful MCP server! 🚀