@youcloud/mantis-mcp 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 更新记录
 
+## [1.0.1] - 2026-10-18
+
+- `MANTIS_BASE_URL` 未设置或为空白时默认使用 `https://mantis.umlife.net`，仍可显式指定其他部署地址。
+- 简化客户端配置示例，内部使用只需提供个人 `MANTIS_API_KEY`；缺少 Key 和显式配置无效时仍在请求前报错。
+
 ## [1.0.0] - 2026-10-18
 
 - 提供缺陷查询、受理、指派、修复登记、延期、重开、拒绝、备注和附件等 13 个默认工具；管理扩展增加关闭、删除及版本管理等 10 个工具。

package/README.md

@@ -9,14 +9,14 @@
 需要 Node.js `^22.12.0 || ^24.0.0 || >=26.0.0`，开发和 CI 使用 22.x。
 
 ```bash
-npm install --global @youcloud/mantis-mcp@1.0.0
+npm install --global @youcloud/mantis-mcp@1.0.1
 ```
 
 也可按客户端示例通过 `npx` 启动固定版本。安装需要下载生产依赖，无需自行编译 TypeScript。
 
 ## 开始使用
 
-1. 在 Mantis 生成个人 API Key，通过 `MANTIS_BASE_URL`、`MANTIS_API_KEY` 传入；不要把真实 Key 写入共享配置。
+1. 在 Mantis 生成个人 API Key，通过 `MANTIS_API_KEY` 传入；默认连接内部 Mantis，不要把真实 Key 写入共享配置。
 2. 按[客户端接入](docs/clients.md)配置 Codex、Claude Code、Cursor 或 Trae。
 3. 调用 `get_project_context({})` 确认当前身份与可见项目，再按[调用手册](docs/cookbook.md)查询和处理缺陷。
 

package/dist/connection-config.js

@@ -1,3 +1,4 @@
+export const DEFAULT_MANTIS_BASE_URL = 'https://mantis.umlife.net';
 /** 消息只包含固定提示和变量名称，不保留原始值或底层异常。 */
 export class ConnectionConfigError extends Error {
     code;
@@ -22,16 +23,11 @@ export function normalizeBaseUrl(value) {
     }
     return url.replace(/\/api\/rest\/?$/i, '').replace(/\/$/, '');
 }
-export function validateConnectionConfig(baseUrl = '', apiKey = '') {
-    const missing = [];
-    if (!baseUrl.trim())
-        missing.push('MANTIS_BASE_URL');
-    if (!apiKey.trim())
-        missing.push('MANTIS_API_KEY');
-    if (missing.length) {
-        throw new ConnectionConfigError('CONFIG_MISSING', `缺少必需的连接环境变量：${missing.join('、')}。请在启动 MCP 客户端的环境中设置后重启客户端`);
+export function validateConnectionConfig(baseUrl = DEFAULT_MANTIS_BASE_URL, apiKey = '') {
+    if (!apiKey.trim()) {
+        throw new ConnectionConfigError('CONFIG_MISSING', '缺少必需的连接环境变量：MANTIS_API_KEY。请在启动 MCP 客户端的环境中设置后重启客户端');
     }
-    const normalized = normalizeBaseUrl(baseUrl);
+    const normalized = normalizeBaseUrl(baseUrl.trim() || DEFAULT_MANTIS_BASE_URL);
     try {
         new Headers({ Authorization: apiKey });
     }

package/docs/clients.md

@@ -2,7 +2,7 @@
 
 [返回 README](../README.md) · [服务配置](configuration.md) · [调用手册](cookbook.md)
 
-以下示例均启动本地 stdio 服务。使用变量引用的示例，需先在**启动客户端的环境**中设置并导出 `MANTIS_BASE_URL`、`MANTIS_API_KEY`，配置中的引用保持原样，不替换成真实 Key。Trae 示例通过 Node.js 加载本机私有环境文件，见对应小节。仅在编辑器的集成终端中设置变量，通常不能更新已经运行的编辑器进程；具体检查方法见[连接排障](#连接排障)。
+以下示例均启动本地 stdio 服务，默认连接内部 Mantis。使用变量引用的示例，只需先在**启动客户端的环境**中设置并导出 `MANTIS_API_KEY`，配置中的引用保持原样，不替换成真实 Key。连接其他部署时，再按对应客户端的语法传入可选的 `MANTIS_BASE_URL`，格式见[服务配置](configuration.md#环境变量)。Trae 示例通过 Node.js 加载本机私有环境文件，见对应小节。仅在编辑器的集成终端中设置变量，通常不能更新已经运行的编辑器进程；具体检查方法见[连接排障](#连接排障)。
 
 已有配置文件时，只合并 `mantis` 条目，保留其他服务。各客户端的顶层字段和变量引用语法不同，请使用对应示例：
 
@@ -24,8 +24,8 @@
 ```toml
 [mcp_servers.mantis]
 command = "npx"
-args = ["-y", "@youcloud/mantis-mcp@1.0.0"]
-env_vars = ["MANTIS_BASE_URL", "MANTIS_API_KEY"]
+args = ["-y", "@youcloud/mantis-mcp@1.0.1"]
+env_vars = ["MANTIS_API_KEY"]
 startup_timeout_sec = 60
 tool_timeout_sec = 180
 ```
@@ -42,9 +42,8 @@ tool_timeout_sec = 180
     "mantis": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@youcloud/mantis-mcp@1.0.0"],
+      "args": ["-y", "@youcloud/mantis-mcp@1.0.1"],
       "env": {
-        "MANTIS_BASE_URL": "${MANTIS_BASE_URL}",
         "MANTIS_API_KEY": "${MANTIS_API_KEY}"
       }
     }
@@ -64,9 +63,8 @@ tool_timeout_sec = 180
     "mantis": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@youcloud/mantis-mcp@1.0.0"],
+      "args": ["-y", "@youcloud/mantis-mcp@1.0.1"],
       "env": {
-        "MANTIS_BASE_URL": "${env:MANTIS_BASE_URL}",
         "MANTIS_API_KEY": "${env:MANTIS_API_KEY}"
       }
     }
@@ -82,10 +80,9 @@ tool_timeout_sec = 180
 
 Trae 官方文档仅列出 `${workspaceFolder}` 变量替换；本例用 Node.js 的 `--env-file` 读取凭据，MCP JSON 只保存本机路径。
 
-先按 [README 安装说明](../README.md#安装)全局安装本包，运行 `npm root --global` 获取全局模块目录；在该目录后追加 `/@youcloud/mantis-mcp/dist/index.js`，即为下方所需的服务入口路径。然后在项目目录之外创建仅本人可读的 `mantis.env` 文件，在本机填写实际地址和个人 Key：
+先按 [README 安装说明](../README.md#安装)全局安装本包，运行 `npm root --global` 获取全局模块目录；在该目录后追加 `/@youcloud/mantis-mcp/dist/index.js`，即为下方所需的服务入口路径。然后在项目目录之外创建仅本人可读的 `mantis.env` 文件，在本机填写个人 Key：
 
 ```dotenv
-MANTIS_BASE_URL=https://mantis.example.org
 MANTIS_API_KEY="替换为你的个人 API Key"
 ```
 
@@ -125,7 +122,7 @@ MANTIS_API_KEY="替换为你的个人 API Key"
 
 | 错误码 | 含义与处理 |
 |---|---|
-| `CONFIG_MISSING` | 缺少连接变量，消息只列出缺失名称；HTTP 请求尚未发送 |
+| `CONFIG_MISSING` | 缺少必填的 `MANTIS_API_KEY`；HTTP 请求尚未发送 |
 | `CONFIG_INVALID` | 地址或 Key 格式无效；地址须为完整 HTTP(S) 基地址，可含部署子路径或 `/api/rest/` 后缀，不含用户凭据、查询参数或片段；HTTP 请求尚未发送 |
 | `REQUEST_PREPARATION_FAILED` | 本地构造请求失败，HTTP 请求尚未发送；核对输入或提交脱敏错误报告 |
 | `MANTIS_FORBIDDEN` | 服务端返回 HTTP 401/403，核对个人 Key 和账号权限 |
@@ -137,6 +134,6 @@ Codex 的 `env_vars` 只允许并转发启动环境中已有的变量，不会
 可在用于启动客户端的终端中执行以下检查，只输出是否存在，不打印凭据；这不能证明另一个已运行进程的环境相同。
 
 ```bash
-node -e 'for (const k of ["MANTIS_BASE_URL", "MANTIS_API_KEY"]) console.log(k + ": " + (process.env[k]?.trim() ? "已设置" : "缺失"))'
+node -e 'console.log("MANTIS_API_KEY: " + (process.env.MANTIS_API_KEY?.trim() ? "已设置" : "缺失")); console.log("MANTIS_BASE_URL: " + (process.env.MANTIS_BASE_URL?.trim() ? "已设置" : "使用默认地址"))'
 ```
 

package/docs/configuration.md

@@ -6,7 +6,7 @@
 
 | 变量 | 用途与默认值 |
 |---|---|
-| `MANTIS_BASE_URL` | 必填；完整 HTTP(S) 基地址，可含部署子路径或 `/api/rest/` 后缀，不含 `index.php`、用户凭据、查询参数或片段 |
+| `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`（空值按关闭处理） |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youcloud/mantis-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "面向研发工作流的 MantisBT MCP 服务，支持缺陷查询、修复登记、附件和可恢复操作",
   "license": "MIT",
   "homepage": "https://git.umlife.net/ai-tools/mantis-mcp",