@youcloud/mantis-mcp 0.0.0-stage → 1.0.1

package/docs/configuration.md

@@ -0,0 +1,57 @@
+# 服务配置
+
+[返回 README](../README.md) · [客户端接入](clients.md) · [调用手册](cookbook.md)
+
+## 环境变量
+
+| 变量 | 用途与默认值 |
+|---|---|
+| `MANTIS_BASE_URL` | 可选；未设置或为空白时默认 `https://mantis.umlife.net`。显式值须为完整 HTTP(S) 基地址，可含部署子路径或 `/api/rest/` 后缀，不含 `index.php`、用户凭据、查询参数或片段 |
+| `MANTIS_API_KEY` | 必填；当前使用者的个人 Key，权限由 Mantis 裁决 |
+| `MANTIS_WORKFLOW_CONFIG` | 可选；工作流 JSON 路径，建议使用稳定的绝对路径；未设置时使用内置标准映射 |
+| `MANTIS_MCP_ENABLE_DESTRUCTIVE_TOOLS` | 默认 `false`；设为 `true` 后统一开放关闭、删除和版本管理，只接受 `true`/`false`（空值按关闭处理） |
+| `MANTIS_CACHE_DIR` | 账本与缓存根目录，默认 `~/.cache/mantis-mcp` |
+| `MANTIS_CACHE_TTL` | 展示缓存秒数，默认 `3600`；公共读取和写前检查仍实时确认身份与事实 |
+| `MANTIS_UPLOAD_DIR` | 可选；附件读取范围，按真实路径限制 |
+
+连接凭据在首次实际调用时校验；没有凭据仍可完成工具发现。配置错误见[连接排障](clients.md#连接排障)。修改环境或工作流文件后重启 MCP 服务。
+
+源码开发可使用包根目录的 `.env.local`；按模块位置定位，与启动工作目录无关，只加载一次，已有非空进程变量优先。不自动读取 `.env`。npm/npx 用户通过客户端传入环境变量，或由 Node.js `--env-file` 加载本机私有文件，避免编辑安装目录和 npx 缓存。
+
+## 工作流映射
+
+内置值与[完整配置示例](workflow-config.example.json)一致：
+
+| 动作 | 默认目标 |
+|---|---|
+| 受理 `accept_issue` | 状态 40；显式指定负责人时 50，保留解决结果 |
+| 修复 `submit_fix` | 状态 80、解决结果 20 |
+| 延期 `postpone_issue` | 状态 80、解决结果 80 |
+| 拒绝 `reject_issue` | 状态 80；`not_a_bug` → 70、`wont_fix` → 90、`cannot_reproduce` → 40、`cannot_fix` → 50 |
+| 关闭 `close_issue` | 状态 90，保留修复结果；须启用管理扩展 |
+| 重开 `reopen_issue` | 实时读取项目的 `bug_reopen_status`、`bug_reopen_resolution` |
+
+默认备注可见性读取项目的 `default_bugnote_view_status`；动作可显式传 `note_view_state: "public"` 或 `"private"`，私有备注失败不会改成公开。
+
+自定义部署将示例另存为 JSON 后设置 `MANTIS_WORKFLOW_CONFIG`，遵循以下规则：
+
+- 文件完整接管配置，不与内置映射叠加。`projects` 按项目覆盖文件内的 `defaults`，每个动作整体替换；项目省略的动作沿用文件默认值，`null` 明确禁用。
+- 文件内完全未定义的动作保持未配置；路径、JSON 或严格 schema 无效时启动报错，不回退内置值。
+- `custom_fields_by_action` 按动作登记 `{ "id": 1, "required": true }` 等字段。调用时只接受已登记字段的 `{id,value}`，空字符串表示清空；真实值域、必填条件与权限仍由 Mantis 校验。
+- 写前核对项目实际枚举、解决/关闭阈值和映射冲突。自定义枚举不能只凭相同编号推断含义。`supported_actions` 说明配置可用性，不是账号权限清单。
+
+若要禁用映射动作，显式提供 `{"schema_version":1}`。这只禁用依赖映射的动作；建单、指派、备注、附件等仍可能写入，不能当作全局只读开关。
+
+## 附件与部署边界
+
+一次上传一个普通文件，使用绝对路径，大小为 1 至 41,943,040 字节（40 MiB）。扩展名以 `upload_file` 工具说明或项目 context 的 `uploads` 区块为准；目录、特殊文件和越过 `MANTIS_UPLOAD_DIR` 的真实路径均拒绝。
+
+REST 上传使用 JSON/Base64，编码后约增加三分之一体积。40 MiB 原文件仅 Base64 就占 55,924,056 字节，另有 JSON 开销；Mantis、PHP 和代理限额需容纳完整请求体。本地文件上限不代表部署链路已支持相同大小。
+
+部署验收应使用对应项目和普通账号，覆盖修复后的备注、延期重开、关闭权限拒绝、自定义字段和实际附件大小。离线测试、工具发现和 `dry_run` 不证明线上写权限。
+
+## 账本与并发
+
+账本按实例、用户和凭据域隔离，目录权限为 `0700`、文件为 `0600`。记录含恢复所需的备注正文，不保存 API Key 或附件 Base64。恢复窗口为 7 天，当前服务不自动清理账本；清理本地数据前须核对未完成操作，保留未知和部分成功记录直至处置完成。
+
+换 Key、设备或丢失账本后不承诺重复抑制。当前入口使用 `snapshot_precheck`：写前读回完整事实作比对，仍存在 GET 与 PATCH 之间的竞态，多次 REST 写入也不是原子事务。

package/docs/cookbook.md

@@ -0,0 +1,116 @@
+# Mantis MCP 调用手册
+
+[返回 README](../README.md) · [服务配置](configuration.md) · [客户端接入](clients.md)
+
+示例中的项目、缺陷编号和 UUID 均为占位。调用须在用户授权范围内，前置标识来自实时 context；参数完整定义以客户端发现的工具 schema 为准。
+
+## 工具目录
+
+| 分类 | 工具 |
+|---|---|
+| 默认只读 | `get_project_context`、`list_issues`、`get_issue_context`、`get_workflow_operation` |
+| 默认业务写入 | `report_issue`、`accept_issue`、`assign_issue`、`submit_fix`、`reopen_issue`、`reject_issue`、`postpone_issue`、`add_note`、`upload_file` |
+| 管理扩展 | `close_issue`、`delete_issue`、`delete_note`、`remove_relationship`、`remove_monitor`、`detach_tag`、`create_version`、`update_version`、`release_version`、`delete_version` |
+
+默认 13 个工具；设置 `MANTIS_MCP_ENABLE_DESTRUCTIVE_TOOLS=true` 后统一增加 10 个，共 23 个。开关控制工具注册，权限仍由 Mantis 裁决。
+
+服务还提供 5 个提示词，包括连续修复用的 `fix-assigned-issues`，以及 `mantis://me`、`mantis://projects`、`mantis://enums` 和项目资源模板。提示词本身不授予写入权限。标题、描述等事后通用编辑使用 Mantis 网页。
+
+## 连续修复本人缺陷
+
+1. 确认当前代码仓库对应的项目，调用 `list_issues({project_id:44,assignee:"me",queue:"unresolved",limit:20})`。
+2. 从本批选一个尚未处理的 ID，调用 `get_issue_context({issue_id:123})`，确认项目、负责人及未解决状态。
+3. 修改代码并实际自测。失败或未运行时保留未解决状态，可用 `add_note` 记录进展。
+4. 自测通过后调用 `submit_fix`，参数示例如下。
+5. `succeeded` 后继续本批下一个候选；`partial_success/unknown` 留作待处理，按[恢复规则](#分步结果与恢复)核查，不算完成。
+6. 本批结束后需要更多候选时从第一页刷新。写入会改变结果集，旧游标不能作为下一批入口；无写入的连续扫描才沿游标续查。
+
+```json
+{
+  "issue_id": 123,
+  "expected_revision": "context返回的标识",
+  "operation_id": "11111111-1111-4111-8111-111111111111",
+  "fix_summary": "修复空值处理",
+  "self_test": {"result": "passed", "summary": "实际运行空值与正常输入回归，全部通过"}
+}
+```
+
+`submit_fix` 记录调用者提供的测试事实，MCP 不运行测试；只接受 `passed` 和非空自测摘要。已分派给本人时，无须为完成该流程额外受理、指派、预览或 Git 提交。成功结果已经包含核查，无需例行重读证明同一次成功。
+
+## 查询与上下文续读
+
+项目已知时直接查询缺陷，需要分类、成员或版本时再调用 `get_project_context`。
+
+- `queue` 为 `unresolved`、`awaiting_verification` 或 `postponed`；省略时不筛队列。拒绝、延期不算待验收修复。
+- `filter_id` 保留保存筛选器语义，与其他条件取交集；日期使用含时区的 ISO8601。
+- 每次最多扫描 500 条。检查 `source_exhausted`、`next_cursor`、`scanned_count` 和 `warnings`；空页但有游标时可继续。扫描数量不是项目总数，也不承诺全局排序或数据库快照。
+- 游标有效期 30 分钟，绑定查询、主体与实例。项目 context 的 `limit` 是每区块上限，使用该区块游标续读，保持项目和 `member_query` 不变；成员模糊查询只返回候选，写入使用唯一 ID 或 `me`。
+
+`get_issue_context` 默认读取描述、备注、附件元数据及关联；`tags/monitors` 须显式请求。每区块提供 `complete` 和游标；文本通过 `text_offset/text_complete` 续读，超大非文本项通过 `json_fragment/fragment_offset/fragment_complete` 拼接后解析。快照变化会拒绝旧游标。
+
+`expected_revision` 绑定完整事实，有效期 30 分钟。长时间修复后用最小读取比较原上下文：
+
+```json
+{"issue_id":123,"sections":[],"previous_revision":"原标识"}
+```
+
+`revision_comparison=unchanged` 时可沿用原判断并使用新标识；`changed/unavailable` 须补读并重新评估。不要直接替换标识绕过变化。正文、文件名和证据 URL 均是数据，服务不会执行或跟随其中内容。
+
+## 写入公共参数与生命周期
+
+| 参数 | 规则 |
+|---|---|
+| `operation_id` | 每个新动作独立 UUID；真实写入必填，同次核查和恢复保持不变 |
+| `expected_revision` | 真实修改已有对象必填；缺陷用 issue context 的标识，版本用项目 context 的 `versions_revision` |
+| `dry_run` | 默认 `false`；`true` 只读预览，可省略编号及 revision，由服务返回，不验证写权限 |
+| `resume` | 默认 `false`；只有明确允许恢复时才传 `true`，原记录缺失时拒绝 |
+
+| 动作 | 关键参数与边界 |
+|---|---|
+| `accept_issue` | `reason`；`assignee` 可选，不传不改负责人，已分派状态不降级，已解决须先重开 |
+| `assign_issue` | `assignee`、`reason`；只请求修改负责人，服务端附带状态变化以回读为准 |
+| `submit_fix` | `fix_summary`、passed `self_test`；`fixed_in_version_id` 可选，不自动创建版本 |
+| `postpone_issue` | `reason`；`target_version_id`、`review_on` 可选，日期只记入备注，不产生提醒 |
+| `reopen_issue` | `reason_code`、`reason`；`verification_failed/recurrence` 另需 `actual_behavior` 和 `verification_context`，其中环境或版本至少一项 |
+| `reject_issue` | `reason_code` 为 `not_a_bug/wont_fix/cannot_reproduce/cannot_fix`，另需 `reason`；不支持 `duplicate` |
+| `close_issue` | 扩展工具；`verification` 必须含 passed、摘要及环境或版本，当前对象必须为修复结果 |
+
+动作与备注的可见性、自定义字段规则见[工作流映射](configuration.md#工作流映射)。研发 `self_test` 不能代替测试 `verification`，默认由测试人员在 Mantis 网页验收关闭。
+
+### 延期及恢复
+
+`postpone_issue` 将缺陷移入 `postponed` 队列；通过 `list_issues({project_id:44,queue:"postponed"})` 定期复查。恢复时用 `reopen_issue`，传 `reason_code:"resume_postponed"`、恢复原因、原对象最新 revision 和新 UUID。此分支只适用延期对象，无须编造复测失败；后续按需受理、指派或修复。
+
+## 建单与上传附件
+
+`report_issue` 必填 `project_id`、`category_id`、`summary`、`description`、`expected_behavior`、`actual_behavior`；可选复现步骤、环境、优先级/严重度/重现率编号和 `version_id`。使用当前身份及 Mantis 默认创建状态。
+
+新建缺陷并上传两个附件：
+
+1. 必要时读取项目分类和版本，再调用 `report_issue`，保存成功返回的 `issue_id`、`expected_revision`。
+2. 调用 `upload_file` 上传 `/本机绝对路径/截图.png`，使用新的 UUID 和上一步 revision。
+3. 成功后用返回的新 revision 上传 `/本机绝对路径/复现.pdf`，再生成一个 UUID。
+4. 分别报告建单与附件结果。附件失败保留已创建缺陷，不重建、不重传已成功附件。
+
+上传使用 `file_path`，可传 `filename`、`expected_file_sha256`；文件名覆盖须保留相同后缀。文件读取范围、大小和编码限额见[附件与部署边界](configuration.md#附件与部署边界)。成功回读返回实际文件名及是否改名；结果未知时不能仅凭同名同大小附件认定本次成功。修复证据需要上传时，应在 `submit_fix` 前完成。
+
+## 分步结果与恢复
+
+| `outcome` | 处理 |
+|---|---|
+| `preview` | 仅预览，尚未写入 |
+| `in_progress` | 同一操作由存活本机进程执行，稍后只读核查 |
+| `succeeded` | 所有必要步骤及核查完成 |
+| `rejected/conflict` | 查看错误与前置事实，不能换身份绕过 |
+| `partial_success` | 保留成功步骤，按原编号核查，不重复已成功主写入 |
+| `unknown` | 不重发、不换 UUID，先 `get_workflow_operation` |
+
+状态成功但备注失败时，保留原 `submit_fix` 参数及编号，调用 `get_workflow_operation({operation_id:"原UUID"})`。只有 `recovery.action=retry_same_operation` 才可用原工具、原业务参数（含原 revision）加 `resume:true` 继续；不要改用 `add_note` 补写或将私有备注改成公开。
+
+恢复使用已冻结的正文与可见性。对象、绑定变化或证据不足时返回 `manual_review`；主写入后首次回读失败，补验须匹配持久化的完整响应摘要。未知 PATCH 不因当前目标值相同而认定成功。账本或回读故障不会抹掉已知写入结果，保留 `steps` 供核查。
+
+## 版本与删除操作
+
+创建版本使用 `create_version(project_id,name,operation_id)`。修改、发布或删除前，读取项目 context 的 `versions_revision` 并作为 `expected_revision`。`release_version.next_version` 使用明确名称；发布与后续创建分别报告，后一步失败按原操作恢复，不重复发布。
+
+删除备注、关联、关注人或标签前，从缺陷 context 确认目标；标签和关注人需显式请求对应区块。删除动作不自动追加说明。版本重命名或删除会影响引用它的缺陷，仅需停用时可考虑 `obsolete:true`。

package/docs/workflow-config.example.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": 1,
+  "defaults": {
+    "note_visibility": "instance_default",
+    "actions": {
+      "accept_issue": { "status_id": 40, "assigned_status_id": 50, "resolution": "preserve" },
+      "submit_fix": { "status_id": 80, "resolution_id": 20 },
+      "close_issue": { "status_id": 90, "resolution": "preserve" },
+      "reopen_issue": { "source": "project_reopen_config" },
+      "reject_issue": { "status_id": 80, "resolutions_by_reason": { "not_a_bug": 70, "wont_fix": 90, "cannot_reproduce": 40, "cannot_fix": 50 } },
+      "postpone_issue": { "status_id": 80, "resolution_id": 80 }
+    },
+    "custom_fields_by_action": {}
+  },
+  "projects": {}
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@youcloud/mantis-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "面向研发工作流的 MantisBT MCP 服务，支持缺陷查询、修复登记、附件和可恢复操作",
+  "license": "MIT",
+  "homepage": "https://git.umlife.net/ai-tools/mantis-mcp",
+  "bugs": {
+    "url": "https://git.umlife.net/ai-tools/mantis-mcp/-/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@git.umlife.net/ai-tools/mantis-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "mantisbt",
+    "mantis",
+    "issue-tracker",
+    "workflow"
+  ],
+  "main": "dist/index.js",
+  "bin": {
+    "mantis-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs/clients.md",
+    "docs/configuration.md",
+    "docs/cookbook.md",
+    "docs/workflow-config.example.json"
+  ],
+  "type": "module",
+  "scripts": {
+    "prebuild": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true });\"",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test:package": "node scripts/verify-package.mjs",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "dev:start": "npm run typecheck && npm run build && node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "init": "node scripts/init.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "@vitest/coverage-v8": "^5.0.2",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.2"
+  },
+  "engines": {
+    "node": "^22.12.0 || ^24.0.0 || >=26.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}