MantisBT MCP Server

MantisBT MCP Server

英语 · 德语

一个 Model Context Protocol (MCP) 服务，可将 MantisBT REST API 集成到 Claude Code 和其他支持 MCP 的客户端中。直接在编辑器中读取、创建和更新问题。

要求

• Node.js ≥ 22
• 已启用 REST API 的 MantisBT 安装（版本 2.23+）
• MantisBT API 令牌（在 我的账户 → API 令牌 中创建）

安装

通过 npx（推荐）：

添加到 ~/.claude/claude_desktop_config.json（Claude Desktop）或本地的 claude_desktop_config.json（Claude Code）：

{
  "mcpServers": {
    "mantisbt": {
      "command": "npx",
      "args": ["-y", "@dpesch/mantisbt-mcp-server"],
      "env": {
        "MANTIS_BASE_URL": "https://your-mantis.example.com/api/rest",
        "MANTIS_API_KEY": "your-api-token"
      }
    }
  }
}

本地构建：

git clone https://codeberg.org/dpesch/mantisbt-mcp-server
cd mantisbt-mcp-server
npm run init
npm run build

{
  "mcpServers": {
    "mantisbt": {
      "command": "node",
      "args": ["/path/to/mantisbt-mcp-server/dist/index.js"],
      "env": {
        "MANTIS_BASE_URL": "https://your-mantis.example.com/api/rest",
        "MANTIS_API_KEY": "your-api-token"
      }
    }
  }
}

配置

环境变量

变量	必需	默认值	描述
MANTIS_BASE_URL	✅	–	MantisBT 安装的基本 URL。接受 https://your-mantis.example.com 和 https://your-mantis.example.com/api/rest 两种格式，系统会自动规范化 /api/rest 后缀。
MANTIS_API_KEY	✅	–	用于身份验证的 API 令牌
MANTIS_USE_INDEX_PHP	–	auto	当无法使用 URL 重写时设为 true，此时 REST 请求会使用 /api/rest/index.php/，而不是 /api/rest/。当 MANTIS_BASE_URL 以 /api/rest/index.php 结尾时会自动检测；显式设置的值始终优先。参见操作指南。
MANTIS_CACHE_DIR	–	~/.cache/mantisbt-mcp	元数据缓存目录
MANTIS_CACHE_TTL	–	3600	缓存有效期，单位为秒
TRANSPORT	–	stdio	传输模式：stdio 或 http
PORT	–	3000	HTTP 模式的端口
MCP_HTTP_HOST	–	127.0.0.1	HTTP 模式的绑定地址。已从 0.0.0.0 更改为 127.0.0.1——现在服务默认仅监听 localhost。Docker 或远程访问时设为 0.0.0.0。
MCP_HTTP_TOKEN	✅（HTTP 模式）	–	/mcp 端点的 Bearer 令牌（Authorization: Bearer <token>）。当 TRANSPORT=http 时必需——未设置此令牌时，服务会拒绝以 HTTP 模式启动，因此工具绝不会在未经身份验证的情况下暴露。stdio 模式下会忽略此变量。/health 端点始终公开。
MANTIS_SEARCH_ENABLED	–	false	设为 true 以启用语义搜索
MANTIS_SEARCH_BACKEND	–	vectra	向量存储后端：vectra（纯 JavaScript）或 sqlite-vec（需要手动安装）
MANTIS_SEARCH_DIR	–	{MANTIS_CACHE_DIR}/search	搜索索引目录
MANTIS_SEARCH_MODEL	–	Xenova/paraphrase-multilingual-MiniLM-L12-v2	嵌入模型名称（首次使用时下载一次，约 80 MB）
MANTIS_SEARCH_THREADS	–	1	嵌入模型的 ONNX intra-op 线程数。默认值为 1，以防止多核机器和 WSL 上的 CPU 饱和。只有在索引重建速度很重要，且主机专用于此工作负载时才增加。
MANTIS_UPLOAD_DIR	–	–	将 upload_file 的 file_path 限定为此目录中的文件（会阻止通过 ../ 进行路径遍历）。在 stdio 模式下，除非设置此变量，否则 file_path 不受限制。在 HTTP 模式下，file_path 从服务的文件系统读取，因此除非设置此变量，否则该功能会被禁用——HTTP 客户端应改用 content（Base64）参数上传。

可用工具

问题

工具	描述
get_issue	根据数字 ID 获取问题；可选的 select 用于投影字段，以缩小响应大小
get_issues	在一次调用中按 ID 获取多个问题（1–50 个 ID）；缺失或无法访问的 ID 会在对应位置返回 null，而不会导致调用失败
list_issues	按项目、状态、作者等条件筛选问题；可选的 select 用于投影字段，status 用于客户端状态筛选 — 规范的英文状态名称（如 "new"、"resolved"）按 ID 匹配，因此在本地化安装中也不受语言影响
create_issue	创建新问题；severity 和 priority 必须使用规范的英文名称（如 minor、major、normal、high）— 调用 get_issue_enums 可查看所有有效值及其本地化标签；可选的 handler 参数可接受用户名，作为 handler_id 的替代项（根据项目成员解析）；可选的 custom_fields 用于设置自定义字段值
update_issue	更新现有问题；枚举字段（status、priority、severity、resolution、reproducibility）接受规范英文名称、本地化名称或数字 ID — 服务会自动将名称解析为 ID；支持 custom_fields 和可选的 note 参数，可在同一次调用中附加备注（例如状态变更原因）
delete_issue	删除问题

备注

工具	描述
list_notes	列出问题的所有备注
add_note	为问题添加备注
delete_note	删除备注

附件

工具	描述
list_issue_files	列出问题的附件
upload_file	向问题上传文件 — 首选：本地 file_path（服务会自动读取并编码）；备用：Base64 编码的 content + filename（仅在无法使用 file_path 时使用）

关联关系

工具	描述
add_relationship	在两个问题之间创建关联关系；可选的 type_name 参数接受字符串名称（如 "related_to"、"duplicate_of"），可替代数字 type_id
remove_relationship	移除问题的一项关联关系（使用关联关系对象中的 id，而非类型）

监视者

工具	描述
add_monitor	将用户添加为问题的监视者
remove_monitor	将用户从问题的监视者中移除

标签

工具	描述
list_tags	列出所有可用标签；当 GET /tags 返回 404 时，回退到元数据缓存（先运行 sync_metadata 以填充缓存）
attach_tags	为问题附加标签
detach_tag	从问题中移除标签

项目

工具	描述
list_projects	列出所有可访问的项目；返回规范化的项目数据（与 sync_metadata 缓存保持一致）
get_project_versions	获取项目的版本；可选的 obsolete 和 inherit 布尔值用于包含已弃用版本或从父项目继承的版本；每个版本都包含 timestamp 字段（版本日期）；修改版本请参阅 create_version、update_version、release_version、delete_version
create_version	在项目中创建新版本；返回已创建的版本对象（id、name、description、released、obsolete、timestamp）；需要 manage_project_threshold（默认值：manager）
update_version	更新现有版本；只修改传入的字段（至少需要一个字段）；重命名会改写所有引用该版本的问题中的 version/target_version/fixed_in_version；需要 manage_project_threshold（默认值：manager）
release_version	将版本标记为已发布并设置其日期（默认为当前日期）；可通过 next_version 在同一步骤中创建后续版本；需要 manage_project_threshold（默认值：manager）
delete_version	永久删除版本——此操作不可撤销，MantisBT 会清除所有引用该版本的问题中的 version/target_version/fixed_in_version；建议使用 update_version 并设置 obsolete=true 作为非破坏性替代方案；需要 manage_project_threshold（默认值：manager）
get_project_categories	获取项目的类别
get_project_users	获取项目的用户
find_project_member	按名称、真实姓名或电子邮件搜索项目成员（不区分大小写的子字符串匹配）；可选的 query 和 limit（默认值为 10，最大值为 100）；优先使用缓存

语义搜索 （可选）

语义搜索不会进行精确关键词匹配，而是理解查询背后的含义。用自然语言提问——即使措辞不匹配，搜索引擎也能找到概念相关的问题：

• “重置密码后无法登录”——找到与身份验证边缘情况有关的问题
• “结账页面的性能问题”——无论使用的具体术语是什么，都能呈现相关报告
• “发票列表中有重复条目”——也能找到描述为“显示两次”“重复记录”等的问题

嵌入模型（约 80 MB）完全在离线状态下运行——无需 OpenAI 密钥，也无需外部 API。首次启动时下载一次，并缓存在本地。每次服务启动时都会增量索引问题（仅重新索引新增和已更新的问题）。

设置 MANTIS_SEARCH_ENABLED=true 即可启用。

工具	描述
search_issues	对所有已索引的问题进行自然语言搜索——返回前 N 个结果及余弦相似度分数；可选的 select（以逗号分隔的字段名称）可为每个结果补充指定的问题字段；可选的 highlight（布尔值，默认值为 false）会为每个结果添加 highlights 字段，其中包含从 summary 和 description 中提取的关键词匹配摘录（匹配词以 **粗体** 显示）
rebuild_search_index	构建或更新搜索索引；full: true 会清除索引并从头重建
get_search_index_status	返回搜索索引当前的填充状态：已索引的问题数量与总数，以及上次同步的时间戳

应该选择哪个后端？

	vectra （默认）	sqlite-vec
依赖项	无（纯 JS）	需要原生构建工具
安装	已包含	npm install sqlite-vec better-sqlite3
适用场景	最多约 10,000 个问题	10,000 个以上问题
性能	足以满足大多数配置	处理大型语料库时更快

请从 vectra 开始。如果索引或查询时间明显变慢，再切换到 sqlite-vec。

npm install sqlite-vec better-sqlite3
# then set MANTIS_SEARCH_BACKEND=sqlite-vec

元数据与系统

工具	描述
get_issue_fields	返回 list_issues 的 select 参数可用的所有字段名称
get_metadata	获取精简的元数据摘要：项目／标签数量，以及各项目的用户／版本／类别数量；如需完整数组，请使用 get_metadata_full
get_metadata_full	以压缩 JSON 格式返回完整的原始元数据缓存（所有项目的完整字段、各项目的用户／版本／类别，以及所有标签）
sync_metadata	刷新元数据缓存
list_filters	列出已保存的筛选器
get_current_user	获取你自己的用户资料
list_languages	列出可用语言
get_config	显示服务配置（基本 URL、缓存 TTL）
get_issue_enums	返回所有问题枚举字段（严重性、状态、优先级、解决方案、可复现性）的有效 ID／名称对 — 在调用 create_issue / update_issue 前使用此工具查找正确的值；在本地化安装中，每个条目可能包含 canonical_name，即标准的英文 API 名称
get_mantis_version	获取 MantisBT 版本并检查更新
get_mcp_version	返回此 mantisbt-mcp-server 实例的版本

可用资源

MCP 资源是可通过 URI 寻址的只读数据，客户端无需调用工具即可直接获取。它们是 MCP 的第三种基本构件，与工具和提示词并列。请注意，相较于工具，MCP 客户端对资源的支持并不普遍 — 请查阅客户端文档。

资源 URI	描述
mantis://me	已通过身份验证的 API 用户资料（实时获取）
mantis://projects	所有可访问的 MantisBT 项目，以精简列表形式呈现（基于缓存，通过 sync_metadata 刷新）
mantis://projects/{id}	项目综合视图：一次调用返回项目字段、用户、版本和类别；优先使用缓存，并支持列出所有可用项目 URI
mantis://enums	所有问题枚举字段的有效值：严重性、优先级、状态、解决方案、可复现性（实时获取）

可用提示词

MCP 提示词模板是对话开场内容，用于指导大模型收集结构化输入，然后调用相应的工具。它们本身不是工具 — 而是用于启动引导式工作流。

提示词	必需参数	可选参数	描述
create-bug-report	project_id、category、summary、description	steps_to_reproduce、expected、actual、environment	引导用户填写结构化错误报告，并调用 create_issue
create-feature-request	project_id、category、summary、description	use_case	引导用户提交功能请求，并调用 create_issue
summarize-issue	issue_id	–	通过 get_issue 获取问题并返回简洁摘要
project-status	project_id	–	通过 list_issues 列出问题，并按严重性分组生成状态报告

HTTP 模式

用作独立服务（例如在远程设置中）时使用。HTTP 模式下必须设置 MCP_HTTP_TOKEN — 未设置时服务将拒绝启动：

MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
  TRANSPORT=http PORT=3456 node dist/index.js

# With explicit bind address (required for Docker/remote):
# MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
#   TRANSPORT=http PORT=3456 MCP_HTTP_HOST=0.0.0.0 node dist/index.js

每个 /mcp 请求都必须发送 Authorization: Bearer <token>。通过 HTTP 使用时，除非设置了 MANTIS_UPLOAD_DIR，否则 upload_file 的 file_path 将被禁用 — 请改用 content（Base64）参数。

健康检查：GET http://localhost:3456/health（始终公开，无需令牌）

文档

• 使用手册 — 面向工具的操作指南，包含所有已注册工具的可直接复制粘贴的参数示例
• 使用示例 — 适用于日常用例的自然语言提示词示例（无需指定工具名称）

开发

npm run init         # First-time setup: install deps, git hooks, typecheck
npm run build        # Compile TypeScript → dist/
npm run typecheck    # Type check without output
npm run dev          # Watch mode for development
npm test             # Run tests (vitest)
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Coverage report

许可证

MIT – 参见 LICENSE

贡献

欢迎贡献！请阅读 CONTRIBUTING.md。 代码库：codeberg.org/dpesch/mantisbt-mcp-server