@zzp123/mcp-zentao 1.18.7 → 1.18.8

package/README.md

@@ -279,6 +279,70 @@ docker run -d \
 }
 ```
 
+## 🚦 传输方式：STDIO 与 HTTP 双支持
+
+默认使用 STDIO 传输（适合本地/CLI 场景）。如果需要通过 URL 与 MCP 客户端通信，可启用 HTTP 传输。两种配置方式任选其一：
+
+**方式 1：环境变量**
+- `MCP_TRANSPORT=http` 启用 HTTP（默认 `stdio`）
+- `MCP_HTTP_PORT`（或 `MCP_PORT`）：端口，默认 3000
+- `MCP_HTTP_HOST`（或 `MCP_HOST`）：监听地址，默认 `0.0.0.0`
+- `MCP_HTTP_PATH`：路由前缀，默认 `/mcp`
+- 安全可选：`MCP_ALLOWED_HOSTS`、`MCP_ALLOWED_ORIGINS`（逗号分隔），`MCP_DNS_PROTECTION=true`
+
+示例：
+```bash
+MCP_TRANSPORT=http MCP_HTTP_PORT=3000 MCP_HTTP_PATH=/mcp zentao --config "{\"url\":\"http://your-zentao\",\"username\":\"u\",\"password\":\"p\",\"apiVersion\":\"v1\"}"
+```
+
+**方式 2：CLI 参数**
+- `--transport http`
+- `--http-port 3000`（或 `--port`）
+- `--http-host 0.0.0.0`（或 `--host`）
+- `--http-path /mcp`
+- 安全可选：`--allowed-hosts host1,host2`，`--allowed-origins http://a,http://b`，`--dns-protection true`
+
+示例：
+```bash
+zentao --transport http --http-port 3000 --http-path /mcp --config "{\"url\":\"http://your-zentao\",\"username\":\"u\",\"password\":\"p\",\"apiVersion\":\"v1\"}"
+```
+
+HTTP 模式下客户端需要连接到 `http://<host>:<port><path>`（默认 `http://localhost:3000/mcp`）。
+
+**方式 3：交互式初始化（最便捷）**
+
+运行一次交互式向导，选择 STDIO/HTTP 并保存到 `~/.zentao/transport.json`，后续无需再带参数：
+```bash
+zentao --init-transport
+# 或 zentao-dev / zentao-pm / zentao-qa 均可
+```
+
+交互式示例：
+```
+=== MCP 传输方式初始化 ===
+选择传输方式 (1) stdio (2) http [1]: 2
+HTTP 端口 [3000]: 4000
+HTTP 路径前缀 (如 /mcp) [/mcp]: /zentao
+监听地址 [0.0.0.0]: 127.0.0.1
+允许的 Host 列表(逗号分隔，可留空): localhost:4000
+允许的 Origin 列表(逗号分隔，可留空): https://example.com
+启用 DNS Rebinding 防护? (y/N): y
+```
+
+最终配置会写入 `~/.zentao/transport.json`，示例：
+```json
+{
+  "transport": "http",
+  "host": "127.0.0.1",
+  "port": 4000,
+  "path": "/zentao",
+  "allowedHosts": ["localhost:4000"],
+  "allowedOrigins": ["https://example.com"],
+  "dnsProtection": true
+}
+```
+该文件优先级低于环境变量/CLI 参数，因此仍可通过临时参数覆盖。
+
 ## 基本使用
 
 ```typescript

package/dist/index-dev.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ZentaoAPI } from './api/zentaoApi.js';
 import { loadConfig, saveConfig } from './config.js';
+import { interactiveInitTransport, startServerTransport } from './serverTransport.js';
 // 解析命令行参数
 const args = process.argv.slice(2);
 let configData = null;
+if (await interactiveInitTransport({ args })) {
+    process.exit(0);
+}
 // 查找 --config 参数
 const configIndex = args.indexOf('--config');
 if (configIndex !== -1 && configIndex + 1 < args.length) {
@@ -783,9 +786,7 @@ server.tool("deleteComment", "删除评论 - 只能删除自己的评论，管
             }]
     };
 });
-// Start receiving messages on stdin and sending messages on stdout
-const transport = new StdioServerTransport();
-await server.connect(transport).catch(err => {
+await startServerTransport(server, { args }).catch(err => {
     process.stderr.write('[FATAL] MCP server failed: ' + String(err) + '\n');
     process.exit(1);
 });

package/dist/index-pm.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ZentaoAPI } from './api/zentaoApi.js';
 import { loadConfig, saveConfig } from './config.js';
+import { interactiveInitTransport, startServerTransport } from './serverTransport.js';
 // 解析命令行参数
 const args = process.argv.slice(2);
 let configData = null;
+if (await interactiveInitTransport({ args })) {
+    process.exit(0);
+}
 // 查找 --config 参数
 const configIndex = args.indexOf('--config');
 if (configIndex !== -1 && configIndex + 1 < args.length) {
@@ -908,9 +911,7 @@ server.tool("deleteComment", "删除评论 - 只能删除自己的评论，管
             }]
     };
 });
-// Start receiving messages on stdin and sending messages on stdout
-const transport = new StdioServerTransport();
-await server.connect(transport).catch(err => {
+await startServerTransport(server, { args }).catch(err => {
     process.stderr.write('[FATAL] MCP server failed: ' + String(err) + '\n');
     process.exit(1);
 });

package/dist/index-qa.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ZentaoAPI } from './api/zentaoApi.js';
 import { loadConfig, saveConfig } from './config.js';
+import { interactiveInitTransport, startServerTransport } from './serverTransport.js';
 // 解析命令行参数
 const args = process.argv.slice(2);
 let configData = null;
+if (await interactiveInitTransport({ args })) {
+    process.exit(0);
+}
 // 查找 --config 参数
 const configIndex = args.indexOf('--config');
 if (configIndex !== -1 && configIndex + 1 < args.length) {
@@ -720,6 +723,7 @@ server.tool("deleteComment", "删除评论 - 只能删除自己的评论，管
             }]
     };
 });
-// Start receiving messages on stdin and sending messages on stdout
-const transport = new StdioServerTransport();
-await server.connect(transport).catch(err => { process.stderr.write('[FATAL] MCP server failed: ' + String(err) + '\n'); process.exit(1); });
+await startServerTransport(server, { args }).catch(err => {
+    process.stderr.write('[FATAL] MCP server failed: ' + String(err) + '\n');
+    process.exit(1);
+});

package/dist/index.js

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ZentaoAPI } from './api/zentaoApi.js';
 import { loadConfig, saveConfig } from './config.js';
 import { withApi } from './mcpHelpers.js';
+import { interactiveInitTransport, startServerTransport } from './serverTransport.js';
 // 解析命令行参数
 const args = process.argv.slice(2);
 let configData = null;
+if (await interactiveInitTransport({ args })) {
+    process.exit(0);
+}
 // 查找 --config 参数
 const configIndex = args.indexOf('--config');
 if (configIndex !== -1 && configIndex + 1 < args.length) {
@@ -1540,9 +1543,7 @@ server.tool("deleteComment", "删除评论 - 只能删除自己的评论，管
             }]
     };
 });
-// Start receiving messages on stdin and sending messages on stdout
-const transport = new StdioServerTransport();
-await server.connect(transport).catch(err => {
+await startServerTransport(server, { args }).catch(err => {
     process.stderr.write('[FATAL] MCP server failed: ' + String(err) + '\n');
     process.exit(1);
 });

package/dist/serverTransport.d.ts

@@ -0,0 +1,20 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+interface TransportLogger {
+    info?: (message: string) => void;
+    error?: (message: string) => void;
+}
+export interface StartTransportOptions {
+    args?: string[];
+    logger?: TransportLogger;
+}
+export interface InteractiveInitOptions {
+    args?: string[];
+    logger?: TransportLogger;
+}
+export declare function startServerTransport(server: McpServer, options?: StartTransportOptions): Promise<void>;
+/**
+ * 交互式初始化：让用户选择 STDIO / HTTP 及 HTTP 参数，并将结果写入 ~/.zentao/transport.json
+ * 返回 true 表示已处理（应在入口处直接 exit）
+ */
+export declare function interactiveInitTransport(options?: InteractiveInitOptions): Promise<boolean>;
+export {};

package/dist/serverTransport.js

@@ -0,0 +1,151 @@
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import readline from 'node:readline';
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { loadTransportConfig, saveTransportConfig } from './transportConfig.js';
+const DEFAULT_HTTP_PORT = 3000;
+const DEFAULT_HTTP_PATH = '/mcp';
+const getArgValue = (args, flag) => {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === flag) {
+            return args[i + 1];
+        }
+        if (arg.startsWith(`${flag}=`)) {
+            return arg.substring(flag.length + 1);
+        }
+    }
+    return undefined;
+};
+const parsePort = (value) => {
+    if (!value)
+        return undefined;
+    const parsed = Number(value);
+    if (Number.isFinite(parsed) && parsed > 0 && parsed <= 65535) {
+        return parsed;
+    }
+    return undefined;
+};
+export async function startServerTransport(server, options = {}) {
+    const args = options.args ?? [];
+    const logger = options.logger ?? {
+        info: (msg) => process.stdout.write(msg + '\n'),
+        error: (msg) => process.stderr.write(msg + '\n')
+    };
+    const fileConfig = loadTransportConfig();
+    const mode = (process.env.MCP_TRANSPORT || getArgValue(args, '--transport') || fileConfig?.transport || 'stdio').toLowerCase();
+    if (mode !== 'http') {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        return;
+    }
+    const portStr = process.env.MCP_HTTP_PORT
+        || process.env.MCP_PORT
+        || getArgValue(args, '--http-port')
+        || getArgValue(args, '--port')
+        || (fileConfig?.port ? String(fileConfig.port) : undefined);
+    const host = process.env.MCP_HTTP_HOST
+        || process.env.MCP_HOST
+        || getArgValue(args, '--http-host')
+        || getArgValue(args, '--host')
+        || fileConfig?.host
+        || '0.0.0.0';
+    const pathSetting = process.env.MCP_HTTP_PATH
+        || getArgValue(args, '--http-path')
+        || fileConfig?.path
+        || DEFAULT_HTTP_PATH;
+    const port = parsePort(portStr) ?? DEFAULT_HTTP_PORT;
+    const normalizedPath = pathSetting.startsWith('/') ? pathSetting : `/${pathSetting}`;
+    const allowedHosts = (process.env.MCP_ALLOWED_HOSTS || getArgValue(args, '--allowed-hosts'))?.split(',').map(h => h.trim()).filter(Boolean)
+        || fileConfig?.allowedHosts;
+    const allowedOrigins = (process.env.MCP_ALLOWED_ORIGINS || getArgValue(args, '--allowed-origins'))?.split(',').map(o => o.trim()).filter(Boolean)
+        || fileConfig?.allowedOrigins;
+    const enableDnsProtection = (process.env.MCP_DNS_PROTECTION || getArgValue(args, '--dns-protection')) === 'true'
+        || Boolean(fileConfig?.dnsProtection);
+    const httpTransport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        enableJsonResponse: true,
+        allowedHosts,
+        allowedOrigins,
+        enableDnsRebindingProtection: enableDnsProtection
+    });
+    await server.connect(httpTransport);
+    const httpServer = createServer(async (req, res) => {
+        const reqPath = new URL(req.url || '/', 'http://localhost').pathname;
+        if (reqPath !== normalizedPath) {
+            res.writeHead(404).end('Not Found');
+            return;
+        }
+        try {
+            await httpTransport.handleRequest(req, res);
+        }
+        catch (error) {
+            logger.error?.(`[ERROR] HTTP transport request failed: ${String(error)}`);
+            res.writeHead(500).end('Internal Server Error');
+        }
+    });
+    httpServer.listen(port, host, () => {
+        const displayHost = host === '0.0.0.0' ? 'localhost' : host;
+        logger.info?.(`[INFO] MCP HTTP server listening at http://${displayHost}:${port}${normalizedPath}`);
+    });
+    httpServer.on('error', (err) => {
+        logger.error?.(`[ERROR] HTTP server error: ${String(err)}`);
+    });
+}
+/**
+ * 交互式初始化：让用户选择 STDIO / HTTP 及 HTTP 参数，并将结果写入 ~/.zentao/transport.json
+ * 返回 true 表示已处理（应在入口处直接 exit）
+ */
+export async function interactiveInitTransport(options = {}) {
+    const args = options.args ?? [];
+    const logger = options.logger ?? {
+        info: (msg) => process.stdout.write(msg + '\n'),
+        error: (msg) => process.stderr.write(msg + '\n')
+    };
+    if (!args.includes('--init-transport')) {
+        return false;
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const ask = (query) => new Promise(resolve => rl.question(query, resolve));
+    try {
+        logger.info?.('=== MCP 传输方式初始化 ===');
+        const modeInput = await ask('选择传输方式 (1) stdio (2) http [1]: ');
+        const chosenMode = modeInput.trim() === '2' ? 'http' : 'stdio';
+        if (chosenMode === 'stdio') {
+            saveTransportConfig({ transport: 'stdio' });
+            logger.info?.('已保存：使用 STDIO 传输');
+            return true;
+        }
+        const portInput = await ask('HTTP 端口 [3000]: ');
+        const pathInput = await ask('HTTP 路径前缀 (如 /mcp) [/mcp]: ');
+        const hostInput = await ask('监听地址 [0.0.0.0]: ');
+        const allowedHostsInput = await ask('允许的 Host 列表(逗号分隔，可留空): ');
+        const allowedOriginsInput = await ask('允许的 Origin 列表(逗号分隔，可留空): ');
+        const dnsInput = await ask('启用 DNS Rebinding 防护? (y/N): ');
+        const port = parsePort(portInput?.trim()) ?? DEFAULT_HTTP_PORT;
+        const pathSetting = pathInput?.trim() || '/mcp';
+        const host = hostInput?.trim() || '0.0.0.0';
+        const allowedHosts = allowedHostsInput.split(',').map(s => s.trim()).filter(Boolean);
+        const allowedOrigins = allowedOriginsInput.split(',').map(s => s.trim()).filter(Boolean);
+        const dnsProtection = dnsInput.trim().toLowerCase() === 'y';
+        const config = {
+            transport: 'http',
+            host,
+            port,
+            path: pathSetting.startsWith('/') ? pathSetting : `/${pathSetting}`,
+            allowedHosts: allowedHosts.length ? allowedHosts : undefined,
+            allowedOrigins: allowedOrigins.length ? allowedOrigins : undefined,
+            dnsProtection
+        };
+        saveTransportConfig(config);
+        logger.info?.(`已保存：HTTP 模式 http://${host}:${port}${config.path}`);
+        return true;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/transportConfig.d.ts

@@ -0,0 +1,12 @@
+export type TransportMode = 'stdio' | 'http';
+export interface TransportConfig {
+    transport: TransportMode;
+    host?: string;
+    port?: number;
+    path?: string;
+    allowedHosts?: string[];
+    allowedOrigins?: string[];
+    dnsProtection?: boolean;
+}
+export declare function saveTransportConfig(config: TransportConfig): void;
+export declare function loadTransportConfig(): TransportConfig | null;

package/dist/transportConfig.js

@@ -0,0 +1,23 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+const CONFIG_DIR = path.join(os.homedir(), '.zentao');
+const TRANSPORT_FILE = path.join(CONFIG_DIR, 'transport.json');
+export function saveTransportConfig(config) {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    fs.writeFileSync(TRANSPORT_FILE, JSON.stringify(config, null, 2));
+}
+export function loadTransportConfig() {
+    try {
+        if (fs.existsSync(TRANSPORT_FILE)) {
+            const config = JSON.parse(fs.readFileSync(TRANSPORT_FILE, 'utf-8'));
+            return config;
+        }
+    }
+    catch {
+        // ignore parse errors, return null
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zzp123/mcp-zentao",
-    "version": "1.18.7",
+    "version": "1.18.8",
     "description": "禅道项目管理系统的高级API集成包 - 完整版，包含所有94个工具。另有产品经理、测试工程师、开发工程师专用精简版本可选",
     "main": "dist/index.js",
     "type": "module",