⚠️ 重要通知
这个仓库是……的一部分 实验研究 关于使用…… 使用Python创建一个通用的MCP服务器，能够服务 *工具*， *资源* e *提示（词）* 通过JSON以声明式的方式。
此处包含的代码和示例 不应在生产中使用。 没有稳定性、安全性、兼容性或维护方面的保证。 使用后果自负。
MCP HTTP 中心（或“集线器”）
服务器 MCP（模型上下文协议） 在Python中，作为...作用的 HTTP API与MCP客户端之间的通用网关 （如ChatGPT、Copilot或其他支持该协议的应用程序）。
允许定义 *工具*， *资源* e *提示* 在JSON文件中——无需手动编写端点代码。 支持：
- 电话 HTTP（超文本传输协议） (GET, POST, PUT 等)
- 发送 表单编码（form-urlencoded） e multipart/form-data
- 答案 JSON（JavaScript Object Notation，JavaScript对象表示法）， 文本 或者 二进制的
- 认证（Bearer、API密钥、Basic、OAuth2客户端凭据）
- 带有变量的占位符
{id}，{token}等 - JSON响应中的过滤器
- 通过（某种方式/途径）进行配置
.env
______________________________________________________________________
📦 安装
docker-compose up -d之后，需要在容器内部安装依赖项：
docker-compose exec --user 1000 app bash -c 'pip install -r requirements.txt'______________________________________________________________________
🧩 设置 .env
创建一个文件 .env 在项目根目录下（或复制到 .env.example):
# Servidor MCP
HOST=0.0.0.0
PORT=8030
SERVER_NAME=MCP-HTTP-Hub
# Arquivos de definição
TOOLS_FILE=config/tools.json
PROMPTS_FILE=config/prompts.json
RESOURCES_FILE=config/resources.json
# HTTP padrão
HTTP_TIMEOUT=15
HTTP_VERIFY_SSL=false
MAX_MULTIPART_MB=25
# Logs
LOG_LEVEL=debug
# Tokens de exemplo
API_TOKEN=seu_token_aqui
MAPS_KEY=chave_googlemaps
CRM_CLIENT_ID=abc123
CRM_CLIENT_SECRET=def456______________________________________________________________________
🚀 执行
docker-compose exec app python mcp-server.py预期输出：
DEBUG: Carregando tools de config/tools.json
DEBUG: Tool carregada: product-details - Obtém informações de um produto
INFO: Started server process [53]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8030 (Press CTRL+C to quit)______________________________________________________________________
🧠 概念
每种定义都从一个JSON文件中读取：
| 类型 | 功能 |
|---|---|
| 工具 | 可操作的活动（HTTP调用、API） |
资源 可通过URI查询的端点content://...) | |
| 提示（或触发词） | 文本消息模型（本地或HTTP） |
______________________________________________________________________
🔧 定义工具
文件： config/tools.json
每个工具都是一个具有以下属性的对象：
| 字段 | 描述 |
|---|---|
name 工具的唯一名称 | |
description | 简要描述 |
args | 参数和类型 (int， str， bool， float） |
http | HTTP 配置（详情如下） |
示例1 — 简单的GET请求
[
{
"name": "mystore-produto",
"description": "Busca informações de produto",
"args": { "codigo": "str" },
"http": {
"method": "GET",
"url": "https://api.my.store/products/{codigo}",
"response": "json"
}
}
]示例2 — 使用POST方法 form-urlencoded
[
{
"name": "login",
"description": "Autentica o usuário no serviço X",
"args": { "username": "str", "password": "str" },
"http": {
"method": "POST",
"url": "https://example.com/api/login",
"form": {
"user": "{username}",
"pass": "{password}"
},
"response": "json"
}
}
]示例3 — 文件上传（多部分）
[
{
"name": "upload-avatar",
"description": "Envia um avatar de usuário",
"args": { "user_id": "int", "path": "str" },
"http": {
"method": "POST",
"url": "https://api.example.com/users/{user_id}/avatar",
"multipart": {
"avatar": {
"file": "{path}",
"filename": "avatar-{user_id}.png",
"content_type": "image/png"
},
"note": "Upload via MCP"
},
"response": "json"
}
}
]______________________________________________________________________
📚 定义资源
文件： config/resources.json
嗯 *资源* 由URI读取 content://...可以带有参数：
[
{
"uri": "content://my.store/produto/{codigo}",
"description": "Detalhe do produto por código",
"args": { "codigo": "str" },
"http": {
"method": "GET",
"url": "https://api.my.store/products/{codigo}",
"response": "json"
}
}
]______________________________________________________________________
💬 定义提示词
文件： config/prompts.json
示例1 — 静态文本
[
{
"name": "saudacao",
"description": "Mensagem de boas-vindas",
"text": "Olá! Em que posso ajudar hoje?"
}
]示例2 — 带有参数的模板
[
{
"name": "pergunta",
"description": "Gera uma pergunta com base em um tema",
"content": "Qual a sua opinião sobre {tema}?",
"params": ["tema"]
}
]示例3 — 通过HTTP进行动态提示
[
{
"name": "noticias",
"description": "Obtém manchetes de tecnologia",
"http": {
"method": "GET",
"url": "https://api.example.com/news?topic=tech",
"response": "json"
},
"render": {
"mode": "text",
"template": "Principais manchetes: {titles}"
}
}
]______________________________________________________________________
🔐 认证 (http.auth)
钥匙 auth 可以在任何区块内添加 "http"。 它支持四种主要类型：
| 类型 | 描述 |
|---|---|
bearer 简单令牌（Authorization: Bearer ...) | |
api_key | 在头部或查询字符串中的键 |
basic | 基本HTTP认证 |
oauth2_client_credentials | 带令牌缓存的完整OAuth2流程 |
______________________________________________________________________
1️⃣ 持有者令牌（Bearer Token）
"auth": {
"type": "bearer",
"token_env": "API_TOKEN"
}或者使用论据：
"auth": {
"type": "bearer",
"token_template": "{token}"
}______________________________________________________________________
2️⃣ API密钥
头球
"auth": {
"type": "api_key",
"in": "header",
"name": "X-API-Key",
"value_env": "API_KEY"
}查询字符串：
"auth": {
"type": "api_key",
"in": "query",
"name": "key",
"value_env": "MAPS_KEY"
}______________________________________________________________________
3️⃣ 基本认证
"auth": {
"type": "basic",
"username_env": "BASIC_USER",
"password_env": "BASIC_PASS"
}______________________________________________________________________
4️⃣ OAuth2 客户端凭据
具有自动缓存和在收到401响应时刷新的功能：
"auth": {
"type": "oauth2_client_credentials",
"token_url": "https://auth.example.com/oauth/token",
"client_id_env": "CRM_CLIENT_ID",
"client_secret_env": "CRM_CLIENT_SECRET",
"scope": "contacts.read",
"audience": "https://api.crm.example.com/",
"timeout": 10
}Token 已获取，并已缓存 expires_in - 30s并重复使用直到过期。
______________________________________________________________________
⚡️ 快速小贴士
- 占位符:
{variavel}它被上下文值（参数 + 环境）所替代。 - JSON过滤器:
"filter": {"where_contains": {"campo": "{q}"}}过滤结果。 - 表格:
"form"→application/x-www-form-urlencoded。 - 文件：
"multipart"→multipart/form-data. - SSL 自签名证书:
HTTP_VERIFY_SSL=false忽略验证。 - 日志：
LOG_LEVEL=debug显示加载和请求的详细信息。
______________________________________________________________________
🧪 测试中
工具列表：
http POST http://localhost:8030/mcp \
jsonrpc=2.0 id:=1 \
method=tools/list召唤一个工具：
http POST http://localhost:8030/mcp \
jsonrpc=2.0 id:=2 \
method=tools/call \
params:='{"name":"product-details","arguments":{"codigo":"ABC123"}}'在目录内 tests 有一些带有使用示例的Bash脚本。
______________________________________________________________________
🛠️ 许可证
MIT（麻省理工学院）——免费使用和修改。