README.md•7.24 kB
# BYOB MCP Server 🚀
**Bring Your Own Binary**: A dynamic MCP server built on Cloudflare Workers, Containers, and D1.
Enables AI agents to discover and invoke containerized tools registered at runtime—no redeployment needed.
## Quick Start
```bash
# Install dependencies
npm install
# Start local dev server
npm run dev
# In another terminal, test the API
bash test-api.sh
# Deploy to production
npm run deploy
```
## What This Is
A proof-of-concept demonstrating:
- ✅ **Dynamic Tool Registry** - Tools stored in D1, queried by MCP server
- ✅ **Containerized Execution** - Each tool runs in isolated Cloudflare Container
- ✅ **MCP Protocol** - AI agents discover tools via Model Context Protocol
- ✅ **HTTP Registration API** - Register new tools without redeploying
- ✅ **Scale-to-Zero** - Containers only run when tools are invoked
## Architecture
```
AI Agent (Claude) ──[MCP]──> Cloudflare Worker ──[HTTP]──> Universal Container
│ (ToolRunner)
└──[SQL]──> D1 Registry
Supports:
• Echo
• Uppercase
• JQ
• Git Clone
```
## Pre-Built Demo Tools
All four tools run in a single universal container:
1. **echo_message** - Echoes back any JSON input
2. **why_are_we_yelling** - Converts text to UPPERCASE
3. **query_json** - Processes JSON with jq filters
4. **summarize_repo_readme** - Clones a GitHub repo and summarizes its README
## API Endpoints
### GET /
Health check and server info
### GET /api/tools
List all registered tools
### POST /api/register-tool
Register a new tool
```json
{
"name": "my_tool",
"description": "What this tool does",
"containerClass": "echo",
"schema": {
"type": "object",
"properties": {
"input": {"type": "string"}
}
}
}
```
### POST /mcp
MCP protocol endpoint (connect your AI agent here)
## Example: Register a Tool
```bash
curl -X POST http://localhost:8787/api/register-tool \
-H "Content-Type: application/json" \
-d '{
"name": "whisper",
"description": "Echoes message in lowercase",
"containerClass": "toolrunner",
"schema": {
"type": "object",
"properties": {
"message": {"type": "string"}
},
"required": ["message"]
}
}'
```
## Connect to Claude Desktop
Edit your Claude Desktop config:
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"byob-server": {
"url": "http://localhost:8787/mcp"
}
}
}
```
Restart Claude Desktop, then ask:
- "What tools do you have available?"
- "Can you echo the message 'Hello BYOB!'?"
- "Use why_are_we_yelling with text: hello world"
- "Summarize the README from https://github.com/fiberplane/mcp-lite"
## Documentation
- **[PROJECT_SUMMARY.md](./PROJECT_SUMMARY.md)** - High-level overview
- **[HACKATHON.md](./HACKATHON.md)** - Full architecture and setup guide
- **[DEMO.md](./DEMO.md)** - Step-by-step demo script
- **[CLAUDE.md](./CLAUDE.md)** - Development instructions (for AI assistants)
## Project Structure
```
├── src/
│ ├── index.ts # Main Worker + MCP server
│ ├── containers.ts # Container class definitions
│ └── types.ts # TypeScript interfaces
├── containers/
│ ├── Dockerfile # Universal container image
│ ├── server.js # Multi-tool HTTP server
│ └── README.md # Container documentation
├── migrations/
│ ├── 0001_initial_schema.sql
│ └── 0002_seed_example_tools.sql
└── wrangler.jsonc # Cloudflare configuration
```
## Adding New Tools
Since all tools use the same universal container, adding new tools is simple:
### Option 1: Via API (No redeployment needed)
```bash
curl -X POST http://localhost:8787/api/register-tool \
-H "Content-Type: application/json" \
-d '{"name":"my_tool", "description":"...", ...}'
```
### Option 2: Extend the Container
To add new operation types:
1. Edit `containers/server.js` to handle new input patterns
2. Add new tool definitions to `migrations/0002_seed_example_tools.sql`
3. Redeploy
The single container approach keeps things simple for demos while still demonstrating the BYOB architecture.
## Technology Stack
- **Runtime:** Cloudflare Workers (V8 Isolates)
- **MCP:** mcp-lite (not @modelcontextprotocol/sdk)
- **Web Framework:** Hono
- **Database:** Cloudflare D1 (SQLite)
- **Containers:** Cloudflare Containers (Durable Objects)
- **Schema:** Zod + JSON Schema
## Deployment
### Local Development
```bash
npm run dev
# Server runs on http://localhost:8787
```
### Production Deployment
1. Run migrations on remote database:
```bash
npx wrangler d1 execute byob-tools-registry --remote \
--file=./migrations/0001_initial_schema.sql
npx wrangler d1 execute byob-tools-registry --remote \
--file=./migrations/0002_seed_example_tools.sql
```
2. Deploy Worker and Containers:
```bash
npm run deploy
```
**Note:** First deployment takes 2-5 minutes to build Docker images.
3. Update Claude Desktop config with your production URL:
```json
{
"mcpServers": {
"byob-server": {
"url": "https://byob-mcp-server.YOUR_ACCOUNT.workers.dev/mcp"
}
}
}
```
## Testing
```bash
# Automated API tests
bash test-api.sh
# Manual health check
curl http://localhost:8787/
# List tools
curl http://localhost:8787/api/tools | jq
# Test MCP protocol
curl -X POST http://localhost:8787/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
## Key Features
### Dynamic Discovery
Tools registered in D1 appear immediately to all connected AI agents—no redeployment required.
### Secure Isolation
Each container runs in an isolated sandbox with resource limits and ephemeral storage.
### Serverless Scale
Containers scale to zero when idle. Pay only for actual tool invocations.
### Standard Interface
All containers expose `POST /execute` endpoint accepting/returning JSON.
## Limitations
**Container classes must be defined at deploy time** in `wrangler.jsonc`. True runtime BYOB would require automatic Worker rebuild/redeploy when new containers are registered.
**Workaround:** Multiple logical tools can share the same container class, allowing significant flexibility without redeployment.
## Resources
- [Cloudflare Containers Docs](https://developers.cloudflare.com/containers/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [mcp-lite GitHub](https://github.com/fiberplane/mcp-lite)
- [Containers Examples](https://github.com/cloudflare/containers-demos)
## License
MIT - Built for hackathon demonstration
## Contributing
This is a hackathon prototype. For questions or suggestions, open an issue!
---
**Built with** ☁️ Cloudflare Workers | 🐳 Containers | 🗄️ D1 | 🤖 MCP