Redmine API工具服务器

Redmine OpenAPI MCP服务器

MCP服务器，将Easy Redmine API操作动态公开为MCP工具，在运行时从 openapi.json.

先决条件

• Node.js 18.17+（内置fetch的节点18+）
• 这 openapi.json 项目根目录中的文件（已存在）

安装

npm install

配置

设置您的Redmine基础URL和API密钥。支持两种身份验证选项（根据OpenAPI安全方案）：

• 标头API键（默认）： X-Redmine-API-Key
• 查询API密钥： key

环境变量：

• REDMINE_BASE_URL 例如 https://redmine.emistr.cz
• REDMINE_API_KEY 您的API密钥

创建一个 .env 基于 .env.example:

cp .env.example .env
# then edit values

您还可以使用以下命令覆盖每次工具调用 baseUrl, apiKey，以及 apiKeyIn （“header”|“query”）。

开发

npm run dev

这将通过stdio启动MCP服务器。

构建与运行

npm run build
npm start

运作原理

• 倒像 openapi.json
• 迭代所有路径和HTTP方法（GET/POST/PUT/PATCH/DELETE）
• 为每个操作创建MCP工具（名称使用 operationId 如果存在）
• 工具输入支持：
  • pathParams 对于模板化片段，如 {id}
  • query 用于查询字符串参数
  • headers 添加/覆盖请求标头
  • body 用于写入方法上的JSON有效载荷
  • baseUrl, apiKey, apiKeyIn 用于每次呼叫覆盖

示例工具调用（概念性）

输入：

{
  "pathParams": { "id": 123, "format": "json" },
  "query": { "limit": 25 },
  "headers": { "Accept": "application/json" }
}

实例

列出最后5个问题（按更新desc排序）：

{
  "query": { "limit": 5, "sort": "updated_on:desc" }
}

获取单个问题（例如，id 18944）：

{
  "pathParams": { "id": 18944, "format": "json" }
}

与MCP客户端集成

配置您的MCP客户端以通过节点（stdio）启动此服务器：

• 命令： node dist/index.js （或 npm run dev 在开发过程中）
• 运输：stdio
• 环境：套 REDMINE_BASE_URL, REDMINE_API_KEY

示例：Windsurf/Codeium mcp_gonfig.json代码段

{
  "mcpServers": {
    "redmine-openapi": {
      "command": "pwsh",
      "args": [
        "-NoProfile",
        "-Command",
        "Set-Location -Path 'J:\\GIT\\mcp-redmine\\CascadeProjects\\windsurf-project'; npm run dev"
      ],
      "env": {
        "REDMINE_BASE_URL": "https://your-redmine.example.com/",
        "REDMINE_API_KEY": "<your_api_key>",
        "REDMINE_INSECURE_SSL": "false"
      },
      "disabled": false
    }
  }
}

注意：您可以在本地保守秘密 .env 并依靠 dotenv 而不是直接将它们放入客户端配置中。

故障排除

• 自签名TLS：设置 REDMINE_INSECURE_SSL=true （仅限开发）。
• 缺失 format：服务器自动注入 {format:"json"} 对于包含以下内容的路径 {format}.
• GET payload：如果你错误地发送了GET参数 body，服务器将它们视为 query.
• 基本URL：如果 REDMINE_BASE_URL 为空，服务器尝试 servers[0].url 从 openapi.json.