MCP Rest Forge

mcp休息锻造

一个轻量级的、配置驱动的MCP服务器，将精心策划的REST API调用公开为模块化工具，使您的代理能够进行有意的API交互。

目的

mcp-rest-forge 允许您将任何REST API转换为MCP服务器，该服务器的工具在指定HTTP方法、端点路径、头、查询参数和请求主体的YAML文件中定义。这允许您创建一个模块化、安全和最小的服务器，可以在不修改应用程序代码的情况下轻松扩展。

发布

所有官方版本 mcp休息锻造 发表于 。由于此MCP服务器是用Go编写的，因此每个版本都为macOS、Linux和Windows提供了预编译的可执行文件，可以随时下载和运行。

或者，如果您已安装Go，则可以安装 mcp休息锻造 使用以下命令直接从源代码获取：

go install github.com/UnitVectorY-Labs/mcp-rest-forge@latest

配置

服务器使用命令行参数、环境变量和YAML文件进行配置。

命令行参数

• --forgeConfig：指定包含YAML配置文件的文件夹的路径(forge.yaml 以及工具定义）。如果设置，则优先于 FORGE_CONFIG 环境变量。如果两者都没有设置，应用程序将返回错误并退出。
• --forgeDebug：如果提供，则启用详细的调试日志记录 stderr REST调用的HTTP请求/响应元数据经过净化（敏感标头/查询参数已编辑，令牌值未记录，除字节计数外省略了请求/响应体）。如果设置，则优先于 FORGE_DEBUG 环境变量。

环境变量

• FORGE_CONFIG：指定包含YAML配置文件的文件夹的路径(forge.yaml 以及工具定义）。如果使用 --forgeConfig 未设置。
• FORGE_DEBUG：如果设置为 true （不区分大小写），允许详细的调试日志记录 stderr REST调用的HTTP请求/响应元数据经过净化（敏感标头/查询参数已编辑，令牌值未记录，除字节计数外省略了请求/响应体）。如果使用 --forgeDebug 未设置。

伪造yaml

配置文件夹使用特殊的配置文件 forge.yaml 指定通用配置属性。

可以在文件中指定以下属性：

• name：MCP服务器的名称
• base_url：REST API的基本URL（例如。 https://api.github.com)
• headers：应用于所有请求的默认HTTP标头的映射（可选）
• token_command：用于请求Bearer令牌的命令 Authorization 标题（可选）
• env：传递给token命令的环境变量映射（可选）
• env_passthrough：如果设置为 true，将调用mcp rest forge时使用的所有环境变量传递给token命令；如果与 env，变量来自 env 将优先（可选，默认为 false)

示例配置如下：

name: "ExampleServer"
base_url: "https://api.github.com"
token_command: "gh auth token"
headers:
  Accept: "application/vnd.github+json"
  X-GitHub-Api-Version: "2022-11-28"

工具配置

位于该文件夹中的所有其他YAML文件都被视为工具配置文件。每个YAML文件都为MCP服务器定义了一个工具。

可以在文件中指定以下属性：

• name：MCP工具的名称
• description：MCP工具的描述
• method：要使用的HTTP方法（例如。 GET, POST, PUT, PATCH, DELETE)
• path：附加到的URL路径 base_url；支持 {{paramName}} 从输入中替换模板（路径替换是URL路径转义）
• headers：此特定工具的其他HTTP标头的映射；与合并并覆盖来自的标头 forge.yaml （可选）；支持 {{paramName}} 模板替换
• query_params：请求中包含的查询参数列表（可选）

- name：查询参数名称 - value：查询参数值；支持 {{paramName}} 从输入中替换模板。如果在运行时省略了引用的可选输入，则省略查询参数。

• body：请求体配置（可选）

- content_type：请求正文的Content-Type标头（例如。 application/json) - template：将正文内容作为字符串模板；支持 {{paramName}} 从输入中替换模板

• inputs：MCP工具定义并传递给REST请求的输入列表

- name：输入的名称 - type：参数类型；可以是 string 或 number - description：MCP工具使用的参数说明 - required：布尔值，指定是否需要该属性

• annotations：提供有关工具行为提示的MCP注释（可选）

- title：该工具的人类可读标题，可用于UI显示（可选） - readOnlyHint：如果为true，则表示工具不修改其环境（可选，默认值：false） - destructiveHint：如果为true，该工具可能会执行破坏性更新（仅在readOnlyHint为false时才有意义）（可选，默认值：true） - idempotentHint：如果为true，则使用相同的参数重复调用该工具没有额外效果（仅在readOnlyHint为false时有意义）（可选，默认值：false） - openWorldHint：如果为true，该工具可能会与外部实体的“开放世界”交互（可选，默认值：true）

• output：REST响应的输出格式（可选，默认为 raw)

- raw：按原样传递服务器响应（默认） - json：返回最小化的JSON，删除不必要的空格 - toon：将JSON响应转换为TOON格式（面向令牌的对象表示法），以便在LLM中高效使用令牌

示例：带Path参数的GET请求

name: "getUser"
description: "Fetch basic information about a user by `username`."
method: "GET"
path: "/users/{{username}}"
inputs:
  - name: "username"
    type: "string"
    description: "The GitHub `username` that uniquely identifies the account."
    required: true
annotations:
  title: "Get User Information"
  readOnlyHint: true
  destructiveHint: false
  idempotentHint: true
  openWorldHint: true
output: "toon"

示例：带查询参数的GET请求

name: "listUserRepos"
description: "List public repositories for a specified GitHub user."
method: "GET"
path: "/users/{{username}}/repos"
query_params:
  - name: "sort"
    value: "{{sort}}"
  - name: "per_page"
    value: "{{per_page}}"
inputs:
  - name: "username"
    type: "string"
    description: "The GitHub `username` whose repositories to list."
    required: true
  - name: "sort"
    type: "string"
    description: "Sort by `created`, `updated`, `pushed`, or `full_name`."
    required: false
  - name: "per_page"
    type: "number"
    description: "Number of results per page (max 100)."
    required: false
output: "toon"

示例：带有JSON正文的POST请求

name: "createIssue"
description: "Create a new issue in a repository."
method: "POST"
path: "/repos/{{owner}}/{{repo}}/issues"
body:
  content_type: "application/json"
  template: |
    {
      "title": "{{title}}",
      "body": "{{body}}"
    }
inputs:
  - name: "owner"
    type: "string"
    description: "The repository owner."
    required: true
  - name: "repo"
    type: "string"
    description: "The repository name."
    required: true
  - name: "title"
    type: "string"
    description: "The issue title."
    required: true
  - name: "body"
    type: "string"
    description: "The issue body content."
    required: true
annotations:
  readOnlyHint: false
  destructiveHint: false
  idempotentHint: false
  openWorldHint: true
output: "json"

验证和请求语义

• 配置文件以严格模式解析；未知的YAML字段会导致启动错误（有助于捕捉拼写错误）。
• path, headers，以及 body.template 占位符必须引用声明的必需输入。
• query_params 可以参考可选输入；缺少可选输入会导致相应的查询参数被省略。
• 当 body.content_type 是JSON(application/json)，呈现的主体必须是有效的JSON，否则在发送上游请求之前，工具调用将失败。
• 上游非2xx REST响应作为MCP工具错误返回（而不是成功的工具输出）。
• 出站REST请求使用默认的30秒超时。

输出格式

这 output 配置参数允许您指定REST响应的格式。这在使用LLM时特别有用，因为不同的格式可以优化令牌效率。

可用输出格式

原始 （默认）

• 按照接收到的完全正确地传递REST服务器响应
• 未进行任何转换或修改
• 当您需要服务器提供原始格式时使用

JSON

• 返回最小化的JSON，删除所有不必要的空格
• 与格式化JSON相比，减少了令牌的使用
• 非常适合在保持JSON兼容性的同时减少有效载荷大小
• 如果响应不是有效的JSON，则自动回退到原始输出

卡通

• 将JSON响应转换为TOON格式（面向令牌的对象表示法）
• 对于统一的表格数据，可以将令牌使用量减少30-60%
• 针对LLM消费进行了优化，具有紧凑、人类可读的输出
• 使用 卡通格式/卡通走 图书馆
• 如果响应不是有效的JSON或转换失败，则自动回退到原始输出

在流式HTTP模式下运行

默认情况下，服务器在stdio模式下运行，但如果要在可流式传输的HTTP模式中运行，可以指定 --http 带有服务器地址和端口的命令行标志（例如： --http 8080).这将使用MCP客户端可以连接到的以下端点运行服务器：

http://localhost:8080/mcp

./mcp-rest-forge --http 8080

如果您没有指定 token_command 在配置中，如果将“Authorization”标头传递给MCP服务器，它将从传入的MCP请求传递到后端REST端点。

局限性

• 每个实例 mcp-rest-forge 只能与单个基本URL上的单个REST API一起使用。
• REST端点都作为工具而不是资源公开。