buildsomething01/generic_mcp_server

Generic MCP Server

A generic, metadata-driven Model Context Protocol (MCP) server implementation that automatically discovers tools from Firestore and dynamically routes tool calls to their respective endpoints.

Overview

This MCP server provides a flexible, scalable architecture for managing tools without requiring code changes. Tools are registered in Google Cloud Firestore, and the server automatically:

• Discovers tools from the Firestore registry at startup
• Dynamically routes tool calls to their configured endpoints
• Supports streaming and synchronous responses
• Manages sessions for MCP protocol compliance

Features

• 🔄 Automatic Tool Discovery: Tools are loaded from Firestore on startup
• 🎯 Dynamic Routing: Tool calls are routed to endpoints defined in metadata
• 📡 Streaming Support: Supports both streaming and synchronous tool execution
• 🔐 Session Management: Maintains MCP session state for client interactions
• 🐳 Docker Ready: Includes Dockerfile for containerized deployment
• ☁️ Cloud Native: Built for Google Cloud Platform with Firestore integration

Architecture

┌─────────────┐
│   Client    │
└──────┬──────┘
       │ MCP Protocol (JSON-RPC)
       ▼
┌─────────────────────┐
│   MCP Server        │
│   (FastAPI)         │
└──────┬──────────────┘
       │
       ├──► Firestore (Tool Registry)
       │    └──► Tool Metadata
       │
       └──► Dynamic Routing
            └──► External Services (run_url)

How It Works

1. Tool Registration: Tools are registered in Firestore's tool_registry collection with their metadata
2. Discovery: On startup, the server loads all tools from Firestore
3. Capability Building: Server builds MCP capabilities based on discovered tools
4. Dynamic Routing: When a tool is called, the server routes the request to the run_url specified in the tool's metadata

Prerequisites

• Python 3.11+
• Google Cloud Project with Firestore enabled
• Google Cloud credentials configured (via gcloud auth application-default login or service account)

Installation

Using pip

pip install -r requirements.txt

Using pipenv

pipenv install

Configuration

Firestore Setup

1. Create a Firestore database in your Google Cloud project
2. Create a collection named tool_registry
3. Add tool documents with the following structure:

{
  "name": "tool_name",
  "description": "Tool description",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "Parameter description"
      }
    },
    "required": ["param1"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "result": {"type": "string"}
    }
  },
  "run_url": "https://your-service.com/endpoint",
  "metadata": {
    "service": "service-name"
  }
}

Seeding Firestore

Use the provided seed script to populate Firestore with tool definitions:

python firestore/seed.py

Make sure to update the project ID in firestore/seed.py to match your Google Cloud project.

Running the Server

Local Development

uvicorn main:app --reload --port 8080

Production (with Gunicorn)

gunicorn main:app -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8080 --workers 2

Docker

# Build the image
docker build -t mcp-server .

# Run the container
docker run -p 8080:8080 \
  -v /path/to/gcloud/credentials.json:/app/credentials.json \
  -e GOOGLE_APPLICATION_CREDENTIALS=/app/credentials.json \
  mcp-server

API Endpoints

MCP Handler

POST /mcp

Main MCP protocol endpoint that handles JSON-RPC requests.

Supported Methods

• initialize: Initialize a new MCP session
• tools/list: List all available tools
• tools/call: Execute a tool with optional streaming

Example Request

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "get_pet",
    "arguments": {
      "pet_id": "123"
    },
    "stream": false
  }
}

Example Response

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\": \"123\", \"name\": \"Fluffy\"}"
      }
    ]
  }
}

Tool Metadata Schema

Each tool in Firestore must have the following structure:

Project Structure

petstore_mcp_server/
├── main.py                 # FastAPI application entry point
├── mcp/
│   ├── registry.py        # Firestore tool registry loader
│   └── router.py          # MCP protocol router
├── transport/
│   └── sse_transport.py   # SSE transport implementation
├── firestore/
│   └── seed.py            # Firestore seeding script
├── requirements.txt       # Python dependencies
├── Dockerfile             # Docker configuration
└── README.md             # This file

Development

Adding a New Tool

1. Add tool metadata to Firestore's tool_registry collection
2. Ensure the run_url points to a valid endpoint
3. Restart the server to load the new tool

No code changes required! The server will automatically discover and expose the new tool.

Testing

# Test tool listing
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list"
  }'

# Test tool execution
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "get_pet",
      "arguments": {"pet_id": "123"}
    }
  }'

MCP Protocol Compliance

This server implements the Model Context Protocol specification:

• Protocol Version: 2025-03-26
• Transport: HTTP POST with JSON-RPC 2.0
• Session Management: Via Mcp-Session-Id header
• Streaming: Supported via Server-Sent Events (SSE)

Dependencies

• fastapi: Web framework
• uvicorn: ASGI server
• gunicorn: Production WSGI server
• httpx: HTTP client for routing tool calls
• google-cloud-firestore: Firestore client library

License

[Add your license here]

Contributing

[Add contribution guidelines here]

Support

[Add support information here]