zentao-bugfix-mcp 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/.env.example +36 -0
  2. package/README.en.md +207 -0
  3. package/README.md +207 -0
  4. package/bin/zentao-bugfix-mcp.js +2 -0
  5. package/dist/main.d.ts +1 -0
  6. package/dist/main.js +63845 -0
  7. package/dist/main.js.map +1 -0
  8. package/package.json +43 -0
package/.env.example ADDED
@@ -0,0 +1,36 @@
1
+ ZENTAO_BASE_URL="http://192.168.4.66"
2
+ ZENTAO_ACCOUNT="admin"
3
+ ZENTAO_PASSWORD="Abcd1234"
4
+ ZENTAO_TOKEN=""
5
+
6
+ # 当前密码仅适用于内网开发测试环境；生产、个人或其他环境凭证不要提交到仓库。
7
+
8
+ ZENTAO_ALLOWED_PRODUCTS=""
9
+ ZENTAO_ALLOWED_PROJECTS=""
10
+ ZENTAO_ALLOWED_EXECUTIONS=""
11
+
12
+ ZENTAO_ALLOW_WRITE_COMMENT="false"
13
+ ZENTAO_ALLOW_ASSIGN_BUG="false"
14
+ ZENTAO_ALLOW_RESOLVE_BUG="false"
15
+ ZENTAO_ALLOW_CLOSE_BUG="false"
16
+ ZENTAO_ALLOW_ALL_REST_WRITE="true"
17
+
18
+ ZENTAO_ATTACHMENT_DIR="/tmp/zentao-bugfix-mcp"
19
+
20
+ # 在线 MCP Streamable HTTP。非 localhost 监听必须配置认证。
21
+ ZENTAO_MCP_HTTP_HOST="127.0.0.1"
22
+ ZENTAO_MCP_HTTP_PORT="4333"
23
+ ZENTAO_MCP_HTTP_PATH="/mcp"
24
+ ZENTAO_MCP_HTTP_AUTH_TOKEN=""
25
+ ZENTAO_MCP_ALLOWED_ORIGINS=""
26
+ ZENTAO_MCP_TRUST_PROXY="false"
27
+ ZENTAO_MCP_REQUEST_BODY_LIMIT="1048576"
28
+ ZENTAO_MCP_FILE_DOWNLOAD_TOKEN_TTL_SECONDS="600"
29
+
30
+ # 在线后台管理和本地持久化配置。生产建议配置 ZENTAO_CONFIG_SECRET。
31
+ ZENTAO_DATA_DIR="/tmp/zentao-bugfix-mcp-data"
32
+ ZENTAO_CONFIG_SECRET=""
33
+ ZENTAO_ADMIN_PASSWORD=""
34
+ ZENTAO_ADMIN_TOKEN=""
35
+ ZENTAO_REQUEST_LOG_RETENTION_DAYS="14"
36
+ ZENTAO_REQUEST_LOG_MAX_MB="100"
package/README.en.md ADDED
@@ -0,0 +1,207 @@
1
+ # ZenTao Bugfix MCP stdio / 禅道 Bug 修复 MCP stdio
2
+
3
+ English | [中文](README.md)
4
+
5
+ **English**
6
+
7
+ `zentao-bugfix-mcp` is the local stdio MCP package for AI-assisted ZenTao Bug fixing workflows. It is designed for local AI clients such as Codex, Cursor, Claude Code, and any MCP client that can start a subprocess and talk MCP JSON-RPC over stdio.
8
+
9
+ Use this package when an AI coding agent needs to read ZenTao Bugs, inspect source-derived REST v1 API metadata, download attachments, and perform controlled REST v1 calls while the actual code changes, verification, and commits happen in the target business repository.
10
+
11
+ **中文**
12
+
13
+ `zentao-bugfix-mcp` 是面向 AI 辅助禅道 Bug 修复流程的本地 stdio MCP 包。它适用于 Codex、Cursor、Claude Code，以及所有能够启动子进程并通过 stdio 进行 MCP JSON-RPC 通信的 MCP 客户端。
14
+
15
+ 当 AI 编码 Agent 需要读取禅道 Bug、查询从源码生成的 REST v1 API 元数据、下载附件，或执行受控 REST v1 调用时，使用这个包。实际的代码定位、文件修改、验证和提交仍然由调用方 Agent 在目标业务仓库中完成。
16
+
17
+ ## Capability Snapshot
18
+
19
+ - 9 MCP tools are registered by the stdio server.
20
+ - 142 REST v1 routes are cataloged from ZenTao 22.1 source code.
21
+ - 135 implemented REST v1 routes are callable through `zentao_call_api`.
22
+ - 7 routes are intentionally marked as missing entries and return `API_ROUTE_NOT_IMPLEMENTED`.
23
+ - 221 HTTP method entries are described in the catalog: 101 `GET`, 74 `POST`, 22 `PUT`, and 24 `DELETE`.
24
+ - The confirmed REST base path is `${ZENTAO_BASE_URL}/api.php/v1`.
25
+ - The API catalog is generated from ZenTao source, not from demo pages or handwritten examples.
26
+
27
+ ## Registered Tools
28
+
29
+ | Tool | Purpose | Write behavior |
30
+ | --- | --- | --- |
31
+ | `zentao_health_check` | Check config, catalog status, authentication capability, and write switches. | Read-only |
32
+ | `zentao_get_workflow_guide` | Read built-in workflow guide topics for Bug fixing, API catalog usage, attachments, and write rules. | Read-only |
33
+ | `zentao_search_api` | Search the local REST v1 catalog without calling ZenTao. | Read-only |
34
+ | `zentao_call_api` | Call cataloged ZenTao REST v1 APIs with path params, query, body, and dry-run support. | Real non-GET calls require `ZENTAO_ALLOW_ALL_REST_WRITE=true` |
35
+ | `zentao_list_bugs` | List Bugs by product, project, or execution scope with normalized summaries and raw response data. | Read-only |
36
+ | `zentao_list_my_work` | Read the current user's ZenTao "My Work" list, defaulting to Bugs assigned to the current user. | Read-only |
37
+ | `zentao_get_bug` | Read a single Bug detail with normalized summary and raw response data. | Read-only |
38
+ | `zentao_download_file` | Download a ZenTao attachment into `ZENTAO_ATTACHMENT_DIR`. | Filesystem write limited to attachment directory |
39
+ | `zentao_add_bug_comment` | Prepare Bug comment write-back. The current REST v1 catalog has no `/comments` entry, so this remains dry-run. | Dry-run by default |
40
+
41
+ ## Architecture
42
+
43
+ The stdio package is intentionally thin. It owns the local process entry and MCP transport, while shared tool registration and ZenTao behavior live in workspace packages:
44
+
45
+ ```text
46
+ AI MCP client
47
+ -> zentao-bugfix-mcp binary
48
+ -> apps/mcp-stdio/src/main.ts
49
+ -> @modelcontextprotocol/sdk StdioServerTransport
50
+ -> @zentao-bugfix/mcp-tools
51
+ createMcpServer()
52
+ registerTools()
53
+ -> @zentao-bugfix/zentao-core
54
+ ReloadableZentaoRuntime
55
+ ZentaoService
56
+ ZentaoClient
57
+ local REST v1 catalog
58
+ workflow guide data
59
+ -> ZenTao REST v1: ${ZENTAO_BASE_URL}/api.php/v1
60
+ ```
61
+
62
+ Package boundaries:
63
+
64
+ | Area | Location | Responsibility |
65
+ | --- | --- | --- |
66
+ | stdio MCP package | `apps/mcp-stdio` | Published npm package, CLI binary, stdio transport, smoke test |
67
+ | MCP tool registration | `packages/mcp-tools` | MCP server creation, tool schemas, safe result envelope, tool call observer hook |
68
+ | ZenTao core runtime | `packages/zentao-core` | Config loading, auth, REST v1 client, catalog lookup, normalizers, attachment handling, workflow guide lookup |
69
+ | REST v1 catalog data | `packages/zentao-core/data/zentao-api-v1-catalog.json` | Generated route metadata from ZenTao 22.1 source |
70
+ | HTTP MCP server | `apps/mcp-http` | Separate Streamable HTTP MCP deployment target |
71
+ | Debug and web UI | `apps/debug-api`, `apps/web`, `apps/admin-web` | Local REST explorer, development UI, and online admin console |
72
+
73
+ The stdio server does not directly implement business-specific code fixes. It exposes ZenTao context and controlled API access to the caller agent; the caller agent remains responsible for locating code, editing files, running tests, and committing changes in the target repository.
74
+
75
+ ## Install and Run
76
+
77
+ Use with `npx`:
78
+
79
+ ```bash
80
+ npx zentao-bugfix-mcp
81
+ ```
82
+
83
+ Install globally:
84
+
85
+ ```bash
86
+ npm install -g zentao-bugfix-mcp
87
+ zentao-bugfix-mcp
88
+ ```
89
+
90
+ Run from this workspace during development:
91
+
92
+ ```bash
93
+ pnpm install
94
+ pnpm build:stdio
95
+ node apps/mcp-stdio/bin/zentao-bugfix-mcp.js
96
+ ```
97
+
98
+ Run only this package:
99
+
100
+ ```bash
101
+ pnpm --filter zentao-bugfix-mcp build
102
+ pnpm --filter zentao-bugfix-mcp start
103
+ ```
104
+
105
+ ## MCP Client Configuration
106
+
107
+ ```json
108
+ {
109
+ "mcpServers": {
110
+ "zentao-bugfix": {
111
+ "command": "zentao-bugfix-mcp",
112
+ "env": {
113
+ "ZENTAO_BASE_URL": "http://192.168.4.66",
114
+ "ZENTAO_ACCOUNT": "admin",
115
+ "ZENTAO_PASSWORD": "Abcd1234",
116
+ "ZENTAO_TOKEN": "",
117
+ "ZENTAO_ALLOW_ALL_REST_WRITE": "true"
118
+ }
119
+ }
120
+ }
121
+ }
122
+ ```
123
+
124
+ The example above targets the current internal development test environment. Keep `ZENTAO_ALLOW_ALL_REST_WRITE` disabled outside trusted test environments unless the client is explicitly allowed to perform real non-GET REST calls.
125
+
126
+ For local source development, point the client to the repository binary after building:
127
+
128
+ ```json
129
+ {
130
+ "mcpServers": {
131
+ "zentao-bugfix": {
132
+ "command": "node",
133
+ "args": ["/Users/zoujunkun/study/zentao-bugfix-mcp/apps/mcp-stdio/bin/zentao-bugfix-mcp.js"],
134
+ "env": {
135
+ "ZENTAO_BASE_URL": "http://192.168.4.66",
136
+ "ZENTAO_ACCOUNT": "admin",
137
+ "ZENTAO_PASSWORD": "Abcd1234",
138
+ "ZENTAO_TOKEN": "",
139
+ "ZENTAO_ALLOW_ALL_REST_WRITE": "true"
140
+ }
141
+ }
142
+ }
143
+ }
144
+ ```
145
+
146
+ ## Environment Variables
147
+
148
+ | Variable | Required | Purpose |
149
+ | --- | --- | --- |
150
+ | `ZENTAO_BASE_URL` | Yes | ZenTao site root. The server appends `/api.php/v1`. |
151
+ | `ZENTAO_TOKEN` | No | Existing ZenTao REST token. Used before account/password auth. |
152
+ | `ZENTAO_ACCOUNT` | No | Account used to request a token when `ZENTAO_TOKEN` is empty. |
153
+ | `ZENTAO_PASSWORD` | No | Password used with `ZENTAO_ACCOUNT`. |
154
+ | `ZENTAO_ALLOWED_PRODUCTS` | No | Optional comma-separated allowlist for product-scoped reads. |
155
+ | `ZENTAO_ALLOWED_PROJECTS` | No | Optional comma-separated allowlist for project-scoped reads. |
156
+ | `ZENTAO_ALLOWED_EXECUTIONS` | No | Optional comma-separated allowlist for execution-scoped reads. |
157
+ | `ZENTAO_ALLOW_ALL_REST_WRITE` | No | Enables real non-GET calls through `zentao_call_api`. |
158
+ | `ZENTAO_ATTACHMENT_DIR` | No | Directory for downloaded attachments. Defaults to `/tmp/zentao-bugfix-mcp`. |
159
+
160
+ Authentication order:
161
+
162
+ 1. Use `ZENTAO_TOKEN` if it is provided.
163
+ 2. Otherwise call `POST /api.php/v1/tokens` with `ZENTAO_ACCOUNT` and `ZENTAO_PASSWORD`.
164
+
165
+ The test credentials shown in examples are only for the current internal development test environment. Do not use production, personal, or other environment credentials in committed docs, logs, or test records.
166
+
167
+ ## Safety Model
168
+
169
+ The default design is read-first and catalog-gated:
170
+
171
+ - `zentao_call_api` only calls routes present in the generated REST v1 catalog.
172
+ - `GET` calls are allowed by default.
173
+ - `POST /tokens` is allowed for authentication.
174
+ - Other `POST`, `PUT`, `PATCH`, and `DELETE` calls require `ZENTAO_ALLOW_ALL_REST_WRITE=true`.
175
+ - `dryRun=true` returns the prepared request without performing the write.
176
+ - Missing catalog entries return `API_ROUTE_NOT_IMPLEMENTED`; the server does not silently fall back to legacy endpoints.
177
+ - Attachment downloads are confined to `ZENTAO_ATTACHMENT_DIR`.
178
+ - The server never defaults to resolving, closing, or assigning Bugs.
179
+
180
+ ## Development
181
+
182
+ Useful commands from the workspace root:
183
+
184
+ ```bash
185
+ pnpm typecheck
186
+ pnpm build:stdio
187
+ pnpm smoke:mcp
188
+ pnpm pack:stdio
189
+ ```
190
+
191
+ Useful commands inside this package:
192
+
193
+ ```bash
194
+ pnpm build
195
+ pnpm typecheck
196
+ pnpm smoke
197
+ ```
198
+
199
+ The smoke test starts the built stdio server and lists the tools exposed through MCP.
200
+
201
+ ## Related Documentation
202
+
203
+ - Workspace README: `../../README.md`
204
+ - Deployment notes: `../../docs/DEPLOYMENT.md`
205
+ - Development rules: `../../docs/DEVELOPMENT.md`
206
+ - Tool contract: `../../docs/TOOL_CONTRACT.md`
207
+ - Generated REST v1 catalog docs: `../../docs/ZENTAO_API_V1.md`
package/README.md ADDED
@@ -0,0 +1,207 @@
1
+ # ZenTao Bugfix MCP stdio / 禅道 Bug 修复 MCP stdio
2
+
3
+ 中文 | [English](README.en.md)
4
+
5
+ **中文**
6
+
7
+ `zentao-bugfix-mcp` 是面向 AI 辅助禅道 Bug 修复流程的本地 stdio MCP 包。它适用于 Codex、Cursor、Claude Code，以及所有能够启动子进程并通过 stdio 进行 MCP JSON-RPC 通信的 MCP 客户端。
8
+
9
+ 当 AI 编码 Agent 需要读取禅道 Bug、查询从源码生成的 REST v1 API 元数据、下载附件，或执行受控 REST v1 调用时，使用这个包。实际的代码定位、文件修改、验证和提交仍然由调用方 Agent 在目标业务仓库中完成。
10
+
11
+ **English**
12
+
13
+ `zentao-bugfix-mcp` is the local stdio MCP package for AI-assisted ZenTao Bug fixing workflows. It is designed for local AI clients such as Codex, Cursor, Claude Code, and any MCP client that can start a subprocess and talk MCP JSON-RPC over stdio.
14
+
15
+ Use this package when an AI coding agent needs to read ZenTao Bugs, inspect source-derived REST v1 API metadata, download attachments, and perform controlled REST v1 calls while the actual code changes, verification, and commits happen in the target business repository.
16
+
17
+ ## 能力概览
18
+
19
+ - stdio Server 当前注册 9 个 MCP tools。
20
+ - 从禅道 22.1 源码 catalog 出 142 条 REST v1 route。
21
+ - 其中 135 条已实现 REST v1 route 可通过 `zentao_call_api` 调用。
22
+ - 7 条 route 明确标记为缺 entry，调用时返回 `API_ROUTE_NOT_IMPLEMENTED`。
23
+ - catalog 中包含 221 个 HTTP method entry：101 个 `GET`、74 个 `POST`、22 个 `PUT`、24 个 `DELETE`。
24
+ - 已确认 REST 基路径为 `${ZENTAO_BASE_URL}/api.php/v1`。
25
+ - API catalog 来源于禅道源码，不依赖页面演示文档或手写示例。
26
+
27
+ ## 已注册工具
28
+
29
+ | Tool | 用途 | 写操作行为 |
30
+ | --- | --- | --- |
31
+ | `zentao_health_check` | 检查配置、catalog 状态、认证能力和写操作开关。 | 只读 |
32
+ | `zentao_get_workflow_guide` | 读取内置工作流指南模块，包括 Bug 修复、API catalog 使用、附件和写操作规则。 | 只读 |
33
+ | `zentao_search_api` | 查询本地 REST v1 catalog，不访问禅道服务。 | 只读 |
34
+ | `zentao_call_api` | 调用 catalog 中已登记的禅道 REST v1 API，支持 path params、query、body 和 dry-run。 | 非 GET 真实调用需要 `ZENTAO_ALLOW_ALL_REST_WRITE=true` |
35
+ | `zentao_list_bugs` | 按产品、项目或执行维度读取 Bug 列表，返回归一化摘要和原始响应。 | 只读 |
36
+ | `zentao_list_my_work` | 读取当前登录用户的禅道“我的工作”列表，默认返回指派给当前用户的 Bug。 | 只读 |
37
+ | `zentao_get_bug` | 读取单个 Bug 详情，返回归一化摘要和原始响应。 | 只读 |
38
+ | `zentao_download_file` | 下载禅道附件到 `ZENTAO_ATTACHMENT_DIR`。 | 文件写入限制在附件目录 |
39
+ | `zentao_add_bug_comment` | 准备 Bug 评论回写。当前 REST v1 catalog 中没有 `/comments` entry，因此保持 dry-run。 | 默认 dry-run |
40
+
41
+ ## 架构设计
42
+
43
+ stdio 包刻意保持轻量，只负责本地进程入口和 MCP 传输；工具注册和禅道访问行为由 workspace 内共享包承载：
44
+
45
+ ```text
46
+ AI MCP client
47
+ -> zentao-bugfix-mcp binary
48
+ -> apps/mcp-stdio/src/main.ts
49
+ -> @modelcontextprotocol/sdk StdioServerTransport
50
+ -> @zentao-bugfix/mcp-tools
51
+ createMcpServer()
52
+ registerTools()
53
+ -> @zentao-bugfix/zentao-core
54
+ ReloadableZentaoRuntime
55
+ ZentaoService
56
+ ZentaoClient
57
+ local REST v1 catalog
58
+ workflow guide data
59
+ -> ZenTao REST v1: ${ZENTAO_BASE_URL}/api.php/v1
60
+ ```
61
+
62
+ 包边界：
63
+
64
+ | 模块 | 位置 | 职责 |
65
+ | --- | --- | --- |
66
+ | stdio MCP 包 | `apps/mcp-stdio` | 发布到 npm 的包、CLI binary、stdio transport、smoke test |
67
+ | MCP 工具注册 | `packages/mcp-tools` | MCP server 创建、工具 schema、安全结果信封、工具调用观察钩子 |
68
+ | 禅道核心运行时 | `packages/zentao-core` | 配置加载、认证、REST v1 client、catalog 查询、归一化、附件处理、workflow guide 查询 |
69
+ | REST v1 catalog 数据 | `packages/zentao-core/data/zentao-api-v1-catalog.json` | 从禅道 22.1 源码生成的 route 元数据 |
70
+ | HTTP MCP Server | `apps/mcp-http` | 独立的 Streamable HTTP MCP 部署目标 |
71
+ | Debug 和 Web UI | `apps/debug-api`、`apps/web`、`apps/admin-web` | 本地 REST explorer、开发调试 UI、在线后台管理 |
72
+
73
+ stdio Server 不直接实现业务代码修复。它向调用方 Agent 提供禅道上下文和受控 API 访问能力；调用方 Agent 负责在目标仓库中定位代码、修改文件、运行测试并提交变更。
74
+
75
+ ## 安装与运行
76
+
77
+ 使用 `npx`：
78
+
79
+ ```bash
80
+ npx zentao-bugfix-mcp
81
+ ```
82
+
83
+ 全局安装：
84
+
85
+ ```bash
86
+ npm install -g zentao-bugfix-mcp
87
+ zentao-bugfix-mcp
88
+ ```
89
+
90
+ 在当前 workspace 中开发运行：
91
+
92
+ ```bash
93
+ pnpm install
94
+ pnpm build:stdio
95
+ node apps/mcp-stdio/bin/zentao-bugfix-mcp.js
96
+ ```
97
+
98
+ 只运行当前包：
99
+
100
+ ```bash
101
+ pnpm --filter zentao-bugfix-mcp build
102
+ pnpm --filter zentao-bugfix-mcp start
103
+ ```
104
+
105
+ ## MCP 客户端配置
106
+
107
+ ```json
108
+ {
109
+ "mcpServers": {
110
+ "zentao-bugfix": {
111
+ "command": "zentao-bugfix-mcp",
112
+ "env": {
113
+ "ZENTAO_BASE_URL": "http://192.168.4.66",
114
+ "ZENTAO_ACCOUNT": "admin",
115
+ "ZENTAO_PASSWORD": "Abcd1234",
116
+ "ZENTAO_TOKEN": "",
117
+ "ZENTAO_ALLOW_ALL_REST_WRITE": "true"
118
+ }
119
+ }
120
+ }
121
+ }
122
+ ```
123
+
124
+ 上面的示例面向当前内网开发测试环境。除非明确允许客户端执行真实非 GET REST 调用，否则不要在可信测试环境之外开启 `ZENTAO_ALLOW_ALL_REST_WRITE`。
125
+
126
+ 本地源码开发时，先完成构建，再让客户端直接指向仓库内 binary：
127
+
128
+ ```json
129
+ {
130
+ "mcpServers": {
131
+ "zentao-bugfix": {
132
+ "command": "node",
133
+ "args": ["/Users/zoujunkun/study/zentao-bugfix-mcp/apps/mcp-stdio/bin/zentao-bugfix-mcp.js"],
134
+ "env": {
135
+ "ZENTAO_BASE_URL": "http://192.168.4.66",
136
+ "ZENTAO_ACCOUNT": "admin",
137
+ "ZENTAO_PASSWORD": "Abcd1234",
138
+ "ZENTAO_TOKEN": "",
139
+ "ZENTAO_ALLOW_ALL_REST_WRITE": "true"
140
+ }
141
+ }
142
+ }
143
+ }
144
+ ```
145
+
146
+ ## 环境变量
147
+
148
+ | 变量 | 是否必需 | 用途 |
149
+ | --- | --- | --- |
150
+ | `ZENTAO_BASE_URL` | 是 | 禅道站点根路径。Server 会拼接 `/api.php/v1`。 |
151
+ | `ZENTAO_TOKEN` | 否 | 已有禅道 REST token，优先使用。 |
152
+ | `ZENTAO_ACCOUNT` | 否 | `ZENTAO_TOKEN` 为空时，用于换取 token 的账号。 |
153
+ | `ZENTAO_PASSWORD` | 否 | 配合 `ZENTAO_ACCOUNT` 使用的密码。 |
154
+ | `ZENTAO_ALLOWED_PRODUCTS` | 否 | 可选的产品维度读取白名单，逗号分隔。 |
155
+ | `ZENTAO_ALLOWED_PROJECTS` | 否 | 可选的项目维度读取白名单，逗号分隔。 |
156
+ | `ZENTAO_ALLOWED_EXECUTIONS` | 否 | 可选的执行维度读取白名单，逗号分隔。 |
157
+ | `ZENTAO_ALLOW_ALL_REST_WRITE` | 否 | 允许 `zentao_call_api` 执行真实非 GET 调用。 |
158
+ | `ZENTAO_ATTACHMENT_DIR` | 否 | 附件下载目录，默认 `/tmp/zentao-bugfix-mcp`。 |
159
+
160
+ 认证顺序：
161
+
162
+ 1. 如果提供了 `ZENTAO_TOKEN`，优先使用 token。
163
+ 2. 否则使用 `ZENTAO_ACCOUNT` 和 `ZENTAO_PASSWORD` 调用 `POST /api.php/v1/tokens` 换取 token。
164
+
165
+ 示例中的测试账号密码仅适用于当前内网开发测试环境。生产、个人或其他环境凭证不得写入已提交文档、日志或验收记录。
166
+
167
+ ## 安全模型
168
+
169
+ 默认设计是优先只读，并且所有通用 API 调用都受 catalog 约束：
170
+
171
+ - `zentao_call_api` 只能调用生成的 REST v1 catalog 中存在的 route。
172
+ - 默认允许 `GET` 调用。
173
+ - 认证用 `POST /tokens` 默认允许。
174
+ - 其他 `POST`、`PUT`、`PATCH`、`DELETE` 需要 `ZENTAO_ALLOW_ALL_REST_WRITE=true`。
175
+ - `dryRun=true` 只返回准备好的请求，不执行写入。
176
+ - 缺 entry 的 catalog route 返回 `API_ROUTE_NOT_IMPLEMENTED`，Server 不会静默退回 legacy endpoint。
177
+ - 附件下载限制在 `ZENTAO_ATTACHMENT_DIR`。
178
+ - Server 不默认解决 Bug、不默认关闭 Bug、不默认指派 Bug。
179
+
180
+ ## 开发
181
+
182
+ 在 workspace 根目录常用命令：
183
+
184
+ ```bash
185
+ pnpm typecheck
186
+ pnpm build:stdio
187
+ pnpm smoke:mcp
188
+ pnpm pack:stdio
189
+ ```
190
+
191
+ 在当前包目录常用命令：
192
+
193
+ ```bash
194
+ pnpm build
195
+ pnpm typecheck
196
+ pnpm smoke
197
+ ```
198
+
199
+ smoke test 会启动构建后的 stdio Server，并通过 MCP 列出当前暴露的 tools。
200
+
201
+ ## 相关文档
202
+
203
+ - Workspace README：`../../README.md`
204
+ - 部署说明：`../../docs/DEPLOYMENT.md`
205
+ - 开发规范：`../../docs/DEVELOPMENT.md`
206
+ - 工具契约：`../../docs/TOOL_CONTRACT.md`
207
+ - 自动生成的 REST v1 catalog 文档：`../../docs/ZENTAO_API_V1.md`
package/bin/zentao-bugfix-mcp.js ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ import '../dist/main.js'
package/dist/main.d.ts ADDED
@@ -0,0 +1 @@
1
+ #!/usr/bin/env node