AI导哈

元数据驱动MCP服务器

一个基于元数据的模型上下文协议(MCP)服务器实现，自动从Firestore发现工具并动态路由工具调用至相应端点。

  • by buildsomething01
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 buildsomething01/generic_mcp_server

使用说明

通用MCP服务器

一种通用的、元数据驱动的模型上下文协议（MCP）服务器实现，可自动从Firestore中发现工具，并将工具调用动态路由到各自的端点。

概述

此MCP服务器提供了一种灵活、可扩展的架构，用于管理工具，而不需要更改代码。工具已在Google Cloud Firestore中注册，服务器会自动执行以下操作：

  • 发现工具 启动时从Firestore注册表中
  • 动态路由 工具调用到其配置的端点
  • 支持流媒体 以及同步响应
  • 管理会话 符合MCP协议

特性

  • 🔄 自动工具发现：启动时从Firestore加载工具
  • 🎯 动态路由：工具调用被路由到元数据中定义的端点
  • 📡 流媒体支持：支持流式和同步工具执行
  • 🔐 会话管理：维护客户端交互的MCP会话状态
  • 🐳 Docker就绪：包括用于容器化部署的Dockerfile
  • ☁️ 云原生：为谷歌云平台构建，集成Firestore

建筑

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

运作原理

  1. 工具注册：工具已在Firestore中注册 tool_registry 包含元数据的集合
  2. 发现：启动时，服务器从Firestore加载所有工具
  3. 能力建设：服务器基于发现的工具构建MCP功能
  4. 动态路由：当调用工具时，服务器将请求路由到 run_url 在工具的元数据中指定

先决条件

  • Python 3.11+
  • 启用Firestore的谷歌云项目
  • 已配置Google Cloud凭据（通过 gcloud auth application-default login 或服务帐户）

安装

使用pip

pip install -r requirements.txt

使用pipenv

pipenv install

配置

Firestore设置

  1. 在Google Cloud项目中创建Firestore数据库
  2. 创建一个名为的集合 tool_registry
  3. 添加具有以下结构的工具文档：
{
  "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"
  }
}

种子仓库

使用提供的种子脚本用工具定义填充Firestore：

python firestore/seed.py

确保在中更新项目ID firestore/seed.py 以匹配您的Google Cloud项目。

运行服务器

本地开发

uvicorn main:app --reload --port 8080

制作（与Gunicorn合作）

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

码头工人

# 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终点

MCP处理器

发布 /mcp

处理JSON-RPC请求的主MCP协议端点。

支持的方法

  • initialize：初始化新的MCP会话
  • tools/list：列出所有可用工具
  • tools/call：执行带有可选流媒体的工具

示例请求

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

示例响应

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

工具元数据架构

Firestore中的每个工具都必须具有以下结构：

字段 类型 必填 描述
name string 是 唯一工具标识符
description string 是 人类可读的工具描述
parameters object 是 输入参数的JSON模式
output_schema object 否 输出结构的JSON模式
run_url string 是 将工具调用路由到的HTTP端点
metadata object 否 其他元数据（例如，服务名称）

项目结构

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

发展

添加新工具

  1. 将工具元数据添加到Firestore tool_registry 收集
  2. 确保 run_url 指向有效端点
  3. 重新启动服务器以加载新工具

无需更改代码！服务器将自动发现并公开新工具。

测试

# 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协议合规性

此服务器实现了模型上下文协议规范：

  • 协议版本： 2025-03-26
  • 传输：使用JSON-RPC 2.0的HTTP POST
  • 会话管理：通过 Mcp-Session-Id 头球
  • 流媒体：通过服务器发送事件（SSE）支持

依赖项

  • fastapi：Web框架
  • uvicorn：ASGI服务器
  • gunicorn：生产WSGI服务器
  • httpx：用于路由工具调用的HTTP客户端
  • google-cloud-firestore：Firestore客户端库

许可证

[在此处添加您的许可证]

贡献

[在此处添加贡献指南]

支持

[在此处添加支持信息]

相关 MCP