Hyancie MCP

动态可配置MCP服务器

该项目提供了一个用Go编写的动态、可配置的MCP（模型上下文协议）服务器。它的主要目的是包装现有的HTTP API，并将其作为MCP工具公开，而不需要对Go源代码进行任何更改。只需编辑即可添加和配置新工具 config.json 文件。

特性

• 声明性工具创建：完全在a中定义工具 config.json 文件。
• 无需Go编程：只需编辑配置即可添加新工具。
• HTTP方法支持：与合作 GET, POST, PUT，以及其他标准HTTP方法。
• 灵活的标题：添加任意数量的自定义HTTP头，非常适合API密钥、承载令牌或任何其他身份验证方案。
• 强大的响应映射：一个灵活的系统，可以将复杂的JSON响应（包括嵌套对象和数组）解析为模型的干净、人类可读的输出。

运作原理

服务器充当人工智能模型和任何外部HTTP API之间的桥梁。当模型调用工具时，服务器会在中查找工具的定义 config.json，构造适当的HTTP请求，将其发送给目标API，然后根据映射规则解析响应，然后将格式化的结果返回给模型。

sequenceDiagram
    participant Model as AI Model
    participant MCPServer as hyancie-mcp Server
    participant Config as config.json
    participant API as External HTTP API

    Model->>+MCPServer: Call tool('get_weather_cn', {city: 'Beijing'})
    MCPServer->>+Config: Read tool definition
    Config-->>-MCPServer: Return tool details (URL, auth, etc.)
    MCPServer->>+API: Make HTTP GET request to api.example.com/weather?city=Beijing
    API-->>-MCPServer: Return JSON weather data
    MCPServer->>+Config: Read output_mapping rules
    Config-->>-MCPServer: Return mapping rules
    MCPServer->>-Model: Return formatted result: "温度:22|湿度:50|..."

img.png

入门指南

先决条件

• 去1.18或更高。

构建

要生成可执行文件，请从项目根目录运行以下命令：

go build -o hyancie-mcp.exe ./cmd/hyancie

执行

服务器可以在两种传输模式下运行： stdio （用于与父进程进行本地通信）或 sse （使用服务器发送事件公开HTTP服务器）。

标准模式（默认）：

./hyancie-mcp.exe

SSE模式：

您可以指定SSE服务器的地址。

./hyancie-mcp.exe -t sse --sse-address 0.0.0.0:8001 --sse-base-url https://xx.com

配置(config.json 深潜）

此文件是服务器的核心。它定义了服务器的身份及其提供的工具。

重要提示： 这 config.json 文件必须位于与编译的可执行文件相同的目录中（例如。， hyancie-mcp.exe).服务器将在启动时在那里查找它。

根域

• server_name （string）：您的MCP服务器的名称。
• server_version （string）：服务器的版本。
• sse_address （string）：SSE服务器的默认地址。
• mcp_tools （array）：工具定义对象的数组。

工具对象(mcp_tools[])

中的每个对象 mcp_tools array定义了一个工具。

• tool_name （string，必填）：工具的唯一标识符（例如。， get_weather_cn).
• description （string，必填）：对工具功能的清晰描述。这就是AI模型用来决定何时使用该工具的原因。
• input_schema （object，必填）：使用JSON模式定义工具的参数。

- type：应该是“对象”。 - properties：一个对象，其中每个键都是一个参数名称，值是一个定义其值的模式 type 和 description。您还可以添加 default 如果模型没有为非必需的参数提供回退值，请在此处输入键以提供回退值。 - required：列出强制参数的字符串数组。

• request （object，必填）：配置传出的HTTP请求。

- method （string）：HTTP方法（例如“GET”、“POST”）。 - url （字符串）：API终结点。对于 GET 请求，使用 {placeholder} 在URL中插入参数的语法 POST/PUT，论点来自 input_schema 作为JSON请求体发送。

• headers （array，可选）：一个对象数组，用于定义随请求一起发送的自定义HTTP标头。这是处理身份验证的标准方法（例如，API密钥、承载令牌）。

- 数组中的每个对象都必须有一个 name （字符串）和a value （字符串）。

• output_mapping （数组，必需）：一个强大的系统，用于将API的JSON响应解析为模型的基于文本的平面格式。

- json_key （string）：从JSON响应中提取的密钥。支持嵌套对象的点表示法(main.temp)数组索引(weather[0].description). - description （string）：提取值的人类可读标签（例如“温度”）。 - type （string）：可以 "primitive" 或 "array". - primitive：用于提取字符串、数字或布尔值等简单值。 - array：用于处理对象列表。 - limit （整数，可选）：与 type: "array" 限制数组中处理的项目数量。 - items （数组，可选）：与 type: "array"。这是一个嵌套 output_mapping 它定义了如何处理数组中的每个对象。

使用示例

示例1：简单GET请求(get_weather_cn)

此工具获取天气数据。这 city 参数插入到URL中，并添加自定义标头进行身份验证。输出映射从JSON响应中提取简单的嵌套值。

配置：

{
  "tool_name": "get_weather_cn",
  "description": "根据城市名称获取实时天气信息。",
  "request": {
    "method": "GET",
    "url": "https://api.example.com/weather?city={city}&unit=metric"
  },
  "headers": [
    {
      "name": "X-Api-Key",
      "value": "your-secret-api-key-goes-here"
    }
  ],
  "input_schema": { ... },
  "output_mapping": [
    { "json_key": "main.temp", "description": "温度", "type": "primitive" },
    { "json_key": "main.humidity", "description": "湿度", "type": "primitive" },
    { "json_key": "weather[0].description", "description": "天气状况", "type": "primitive" }
  ]
}

结果： 温度:22|湿度:50|天气状况:clear sky

示例2：复杂数组处理(food-info-search)

此工具执行搜索并处理结果列表。这 output_mapping 为了 results 密钥类型为 array。它迭代前3个项目，并对每个项目应用嵌套 items 映射以提取 title, url，以及 content.

配置：

{
  "tool_name": "food-info-search",
  "description": "食品网页搜索工具。提取并格式化前3个搜索结果。",
  "request": { ... },
  "input_schema": { ... },
  "output_mapping": [
    {
      "json_key": "results",
      "type": "array",
      "description": "搜索结果",
      "limit": 3,
      "items": [
        { "json_key": "title", "description": "标题", "type": "primitive" },
        { "json_key": "url", "description": "链接", "type": "primitive" },
        { "json_key": "content", "description": "简介", "type": "primitive" }
      ]
    }
  ]
}

结果： 搜索结果:[项1:{标题:..., 链接:...} | 项2:{标题:..., 链接:...} | 项3:{标题:..., 链接:...}]

客户端

Python客户端示例可在 client/ 目录。请查看 client/README.md 有关如何使用它的说明。

许可证

该项目根据GPLv2.0许可证获得许可。