zentao-rest-v1-mcp 1.0.0
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.
- package/LICENSE +22 -0
- package/README.md +89 -0
- package/dist/config.d.ts +11 -0
- package/dist/config.js +76 -0
- package/dist/errors.d.ts +36 -0
- package/dist/errors.js +56 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +3143 -0
- package/dist/types.d.ts +176 -0
- package/dist/types.js +2 -0
- package/dist/utils/analyzer.d.ts +45 -0
- package/dist/utils/analyzer.js +183 -0
- package/dist/utils/formatter.d.ts +25 -0
- package/dist/utils/formatter.js +157 -0
- package/dist/utils/imageDownloader.d.ts +43 -0
- package/dist/utils/imageDownloader.js +176 -0
- package/dist/utils/suggestions.d.ts +28 -0
- package/dist/utils/suggestions.js +200 -0
- package/dist/zentaoLegacyApi.d.ts +291 -0
- package/dist/zentaoLegacyApi.js +1472 -0
- package/dist/zentaoRestV1Api.d.ts +82 -0
- package/dist/zentaoRestV1Api.js +580 -0
- package/package.json +59 -0
- package/src/config.ts +95 -0
- package/src/errors.ts +69 -0
- package/src/index.ts +3881 -0
- package/src/types.ts +206 -0
- package/src/utils/analyzer.ts +224 -0
- package/src/utils/formatter.ts +182 -0
- package/src/utils/imageDownloader.ts +239 -0
- package/src/utils/suggestions.ts +245 -0
- package/src/zentaoLegacyApi.ts +1663 -0
- package/src/zentaoRestV1Api.ts +622 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 maxenlin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
package/README.md
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# zentao-rest-v1-mcp
|
|
2
|
+
|
|
3
|
+
面向禅道开源版的 MCP 服务。优先使用 REST v1,只有明确的 REST v1 路由不兼容时才回退 Legacy Session API。
|
|
4
|
+
|
|
5
|
+
## 特性
|
|
6
|
+
|
|
7
|
+
- 支持禅道 REST v1 Token 认证。
|
|
8
|
+
- 支持任务、Bug、需求、测试用例和测试单的查询与操作。
|
|
9
|
+
- 支持创建任务、更新任务、开始任务、完成任务、关闭任务和解决 Bug。
|
|
10
|
+
- 写入操作遵循“写入一次、写后回读”,避免重复提交。
|
|
11
|
+
- 读取接口在明确不兼容时回退 Legacy;认证失败、参数错误和写入结果不明时不自动切换通道。
|
|
12
|
+
- 支持 `ZENTAO_TIMEOUT_MS` 和 `ZENTAO_SESSION_TTL_MS` 配置。
|
|
13
|
+
|
|
14
|
+
## 系统要求
|
|
15
|
+
|
|
16
|
+
- Node.js `>=18.0.0`
|
|
17
|
+
- 禅道开源版实例,已启用对应 REST API 能力
|
|
18
|
+
|
|
19
|
+
## 安装
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install -g zentao-rest-v1-mcp
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## MCP 配置
|
|
26
|
+
|
|
27
|
+
```json
|
|
28
|
+
{
|
|
29
|
+
"mcpServers": {
|
|
30
|
+
"zentao-rest-v1": {
|
|
31
|
+
"command": "zentao-rest-v1-mcp",
|
|
32
|
+
"args": [],
|
|
33
|
+
"env": {
|
|
34
|
+
"ZENTAO_URL": "https://your-zentao.example/zentao",
|
|
35
|
+
"ZENTAO_USERNAME": "your-account",
|
|
36
|
+
"ZENTAO_PASSWORD": "your-password",
|
|
37
|
+
"ZENTAO_TIMEOUT_MS": "30000",
|
|
38
|
+
"ZENTAO_SESSION_TTL_MS": "3000000"
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
也可以直接运行本地构建产物:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
node dist/index.js
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## 核心工具
|
|
52
|
+
|
|
53
|
+
- 读取:`getBugDetail`、`getTaskDetail`、`getMyBugs`、`getMyTasks`、`getStoryDetail`
|
|
54
|
+
- 任务:`createTask`、`updateTask`、`startTask`、`finishTask`、`closeTask`
|
|
55
|
+
- Bug:`updateBug`、`resolveBug`
|
|
56
|
+
- 测试:`createTestCase`、`runTestCase`
|
|
57
|
+
|
|
58
|
+
任务完成流程必须遵循:
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
wait → startTask → doing → finishTask → done → closeTask → closed
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
完成任务时必须提交实际开始时间 `realStarted` 和不早于它的实际完成时间 `finishedDate`,不能只提交日期。
|
|
65
|
+
|
|
66
|
+
## 本地开发
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
pnpm install --frozen-lockfile
|
|
70
|
+
pnpm run build
|
|
71
|
+
pnpm run test:smoke
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## 配置说明
|
|
75
|
+
|
|
76
|
+
- `ZENTAO_URL`:禅道站点地址,通常包含 `/zentao` 部署路径。
|
|
77
|
+
- `ZENTAO_USERNAME`:禅道账号。
|
|
78
|
+
- `ZENTAO_PASSWORD`:禅道密码,仅通过环境变量传入,不写入源码和日志。
|
|
79
|
+
- `ZENTAO_TIMEOUT_MS`:请求超时时间,默认 `30000` 毫秒。
|
|
80
|
+
- `ZENTAO_SESSION_TTL_MS`:Token 本地缓存时间,默认 `3000000` 毫秒。
|
|
81
|
+
|
|
82
|
+
## 许可证
|
|
83
|
+
|
|
84
|
+
MIT。原始 Legacy MCP 实现及其许可证声明保留在本包中。
|
|
85
|
+
|
|
86
|
+
## 相关链接
|
|
87
|
+
|
|
88
|
+
- [禅道开源版](https://github.com/easysoft/zentaopms)
|
|
89
|
+
- [本项目仓库](https://github.com/cwj9195/agent-config-sync/tree/main/mcp/zentao-rest-v1)
|
package/dist/config.d.ts
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export interface ZentaoConfig {
|
|
2
|
+
url: string;
|
|
3
|
+
username: string;
|
|
4
|
+
password: string;
|
|
5
|
+
apiVersion: 'legacy';
|
|
6
|
+
timeoutMs?: number;
|
|
7
|
+
sessionTtlMs?: number;
|
|
8
|
+
}
|
|
9
|
+
export declare function saveConfig(config: ZentaoConfig): void;
|
|
10
|
+
export declare function loadConfig(): ZentaoConfig | null;
|
|
11
|
+
export declare function isConfigured(): boolean;
|
package/dist/config.js
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import fs from 'fs';
|
|
2
|
+
import os from 'os';
|
|
3
|
+
import path from 'path';
|
|
4
|
+
// 定义配置文件路径
|
|
5
|
+
const CONFIG_DIR = path.join(os.homedir(), '.zentao');
|
|
6
|
+
const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
|
|
7
|
+
const DEFAULT_TIMEOUT_MS = 30000;
|
|
8
|
+
const DEFAULT_SESSION_TTL_MS = 3000000;
|
|
9
|
+
/**
|
|
10
|
+
* 读取正整数环境变量,非法值回退到默认值。
|
|
11
|
+
* @param name 环境变量名
|
|
12
|
+
* @param fallback 默认值
|
|
13
|
+
* @returns 正整数配置
|
|
14
|
+
*/
|
|
15
|
+
function readPositiveInteger(name, fallback) {
|
|
16
|
+
const value = Number(process.env[name]);
|
|
17
|
+
return Number.isInteger(value) && value > 0 ? value : fallback;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* 补齐本地 MCP 运行配置。
|
|
21
|
+
* @param config 禅道配置
|
|
22
|
+
* @returns 带稳定性参数的配置
|
|
23
|
+
*/
|
|
24
|
+
function withRuntimeConfig(config) {
|
|
25
|
+
return {
|
|
26
|
+
...config,
|
|
27
|
+
timeoutMs: config.timeoutMs || readPositiveInteger('ZENTAO_TIMEOUT_MS', DEFAULT_TIMEOUT_MS),
|
|
28
|
+
sessionTtlMs: config.sessionTtlMs || readPositiveInteger('ZENTAO_SESSION_TTL_MS', DEFAULT_SESSION_TTL_MS),
|
|
29
|
+
apiVersion: 'legacy'
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
// 保存配置
|
|
33
|
+
export function saveConfig(config) {
|
|
34
|
+
// 确保配置目录存在
|
|
35
|
+
if (!fs.existsSync(CONFIG_DIR)) {
|
|
36
|
+
fs.mkdirSync(CONFIG_DIR, { recursive: true });
|
|
37
|
+
}
|
|
38
|
+
// 强制设置为 legacy
|
|
39
|
+
const legacyConfig = {
|
|
40
|
+
...config,
|
|
41
|
+
apiVersion: 'legacy'
|
|
42
|
+
};
|
|
43
|
+
// 写入配置文件
|
|
44
|
+
fs.writeFileSync(CONFIG_FILE, JSON.stringify(legacyConfig, null, 2));
|
|
45
|
+
}
|
|
46
|
+
// 读取配置(优先从环境变量读取,其次从配置文件)
|
|
47
|
+
export function loadConfig() {
|
|
48
|
+
// 优先从环境变量读取配置
|
|
49
|
+
const envUrl = process.env.ZENTAO_URL;
|
|
50
|
+
const envUsername = process.env.ZENTAO_USERNAME;
|
|
51
|
+
const envPassword = process.env.ZENTAO_PASSWORD;
|
|
52
|
+
if (envUrl && envUsername && envPassword) {
|
|
53
|
+
return withRuntimeConfig({
|
|
54
|
+
url: envUrl,
|
|
55
|
+
username: envUsername,
|
|
56
|
+
password: envPassword,
|
|
57
|
+
apiVersion: 'legacy'
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
// 如果环境变量不存在,从配置文件读取
|
|
61
|
+
try {
|
|
62
|
+
if (fs.existsSync(CONFIG_FILE)) {
|
|
63
|
+
const config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
|
|
64
|
+
// 强制设置为 legacy
|
|
65
|
+
return withRuntimeConfig(config);
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
catch (error) {
|
|
69
|
+
console.error('读取配置文件失败:', error);
|
|
70
|
+
}
|
|
71
|
+
return null;
|
|
72
|
+
}
|
|
73
|
+
// 检查是否已配置
|
|
74
|
+
export function isConfigured() {
|
|
75
|
+
return fs.existsSync(CONFIG_FILE);
|
|
76
|
+
}
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 自定义错误类型
|
|
3
|
+
*/
|
|
4
|
+
export declare enum ErrorCode {
|
|
5
|
+
AUTH_FAILED = "AUTH_FAILED",
|
|
6
|
+
NETWORK_ERROR = "NETWORK_ERROR",
|
|
7
|
+
NOT_FOUND = "NOT_FOUND",
|
|
8
|
+
INVALID_PARAMS = "INVALID_PARAMS",
|
|
9
|
+
API_ERROR = "API_ERROR",
|
|
10
|
+
CONFIG_ERROR = "CONFIG_ERROR",
|
|
11
|
+
SESSION_EXPIRED = "SESSION_EXPIRED"
|
|
12
|
+
}
|
|
13
|
+
export declare class ZentaoError extends Error {
|
|
14
|
+
code: ErrorCode;
|
|
15
|
+
statusCode?: number | undefined;
|
|
16
|
+
originalError?: any | undefined;
|
|
17
|
+
constructor(code: ErrorCode, message: string, statusCode?: number | undefined, originalError?: any | undefined);
|
|
18
|
+
/**
|
|
19
|
+
* 转换为用户友好的错误消息
|
|
20
|
+
*/
|
|
21
|
+
toUserFriendlyMessage(): string;
|
|
22
|
+
/**
|
|
23
|
+
* 转换为 JSON
|
|
24
|
+
*/
|
|
25
|
+
toJSON(): {
|
|
26
|
+
code: ErrorCode;
|
|
27
|
+
message: string;
|
|
28
|
+
userFriendlyMessage: string;
|
|
29
|
+
statusCode: number | undefined;
|
|
30
|
+
name: string;
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* 创建错误对象
|
|
35
|
+
*/
|
|
36
|
+
export declare function createError(code: ErrorCode, message: string, statusCode?: number, originalError?: any): ZentaoError;
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 自定义错误类型
|
|
3
|
+
*/
|
|
4
|
+
export var ErrorCode;
|
|
5
|
+
(function (ErrorCode) {
|
|
6
|
+
ErrorCode["AUTH_FAILED"] = "AUTH_FAILED";
|
|
7
|
+
ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
|
|
8
|
+
ErrorCode["NOT_FOUND"] = "NOT_FOUND";
|
|
9
|
+
ErrorCode["INVALID_PARAMS"] = "INVALID_PARAMS";
|
|
10
|
+
ErrorCode["API_ERROR"] = "API_ERROR";
|
|
11
|
+
ErrorCode["CONFIG_ERROR"] = "CONFIG_ERROR";
|
|
12
|
+
ErrorCode["SESSION_EXPIRED"] = "SESSION_EXPIRED";
|
|
13
|
+
})(ErrorCode || (ErrorCode = {}));
|
|
14
|
+
export class ZentaoError extends Error {
|
|
15
|
+
constructor(code, message, statusCode, originalError) {
|
|
16
|
+
super(message);
|
|
17
|
+
this.code = code;
|
|
18
|
+
this.statusCode = statusCode;
|
|
19
|
+
this.originalError = originalError;
|
|
20
|
+
this.name = 'ZentaoError';
|
|
21
|
+
Object.setPrototypeOf(this, ZentaoError.prototype);
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* 转换为用户友好的错误消息
|
|
25
|
+
*/
|
|
26
|
+
toUserFriendlyMessage() {
|
|
27
|
+
const messages = {
|
|
28
|
+
[ErrorCode.AUTH_FAILED]: '认证失败,请检查用户名和密码',
|
|
29
|
+
[ErrorCode.NETWORK_ERROR]: '网络连接失败,请检查网络或服务器地址',
|
|
30
|
+
[ErrorCode.NOT_FOUND]: '未找到请求的资源',
|
|
31
|
+
[ErrorCode.INVALID_PARAMS]: '参数错误,请检查输入参数',
|
|
32
|
+
[ErrorCode.API_ERROR]: '禅道 API 返回错误',
|
|
33
|
+
[ErrorCode.CONFIG_ERROR]: '配置错误,请检查配置信息',
|
|
34
|
+
[ErrorCode.SESSION_EXPIRED]: 'Session 已过期,请重新初始化连接'
|
|
35
|
+
};
|
|
36
|
+
return messages[this.code] || this.message;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* 转换为 JSON
|
|
40
|
+
*/
|
|
41
|
+
toJSON() {
|
|
42
|
+
return {
|
|
43
|
+
code: this.code,
|
|
44
|
+
message: this.message,
|
|
45
|
+
userFriendlyMessage: this.toUserFriendlyMessage(),
|
|
46
|
+
statusCode: this.statusCode,
|
|
47
|
+
name: this.name
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* 创建错误对象
|
|
53
|
+
*/
|
|
54
|
+
export function createError(code, message, statusCode, originalError) {
|
|
55
|
+
return new ZentaoError(code, message, statusCode, originalError);
|
|
56
|
+
}
|
package/dist/index.d.ts
ADDED