staticmcp_stdio_bridge 0.0.1

# 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

```bash
cargo install static_mcp_bridge
```

Or build from source:

```bash
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`)

```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`:
```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`:
```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

```bash
# 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:

```bash
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
```json
{
  "contents": [
    {
      "uri": "file://example.txt",
      "mimeType": "text/plain",
      "text": "File content here"
    }
  ]
}
```

### Tool Responses
```json
{
  "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
```bash
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
```python
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
```bash
#!/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](https://github.com/example/resume-mcp) - Personal resume and portfolio

---

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