AI导哈

HTTP协议转换服务器

一个基于Python的MCP（Model Context Protocol）服务器，作为HTTP API和MCP客户端之间的桥梁，支持通过JSON文件定义工具、资源和提示，无需手动编程端点。

  • by rpopuc
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 rpopuc/poc-mcp-python

使用说明

⚠️ 重要通知

这个仓库是……的一部分 实验研究 关于使用…… 使用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（麻省理工学院）——免费使用和修改。

相关 MCP