@hupan56/wlkj 2.7.12 → 3.0.0

package/templates/qoder/scripts/{zentao_mcp_server.py → mcp/zentao_mcp_server.py}

@@ -1,424 +1,384 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-"""ZenTao (禅道) MCP Server - 对接禅道项目管理, 替代本地 task。
-
-禅道自建内网开源版 REST API。
-/wl-task 的底层从本地 task.json 切换到禅道。
-
-工具:
-  - list_products:        列产品(找到需求的归属)
-  - list_stories:         列需求(PRD→禅道需求)
-  - create_story:         创建需求(PRD发布→自动建禅道需求)
-  - list_execution_tasks: 列执行的任务(谁在做什么)
-  - get_story_detail:     查需求详情
-
-认证: 用户名密码 → token (config.yaml zentao 段配, 团队共享)
-"""
-import os
-import sys
-import json
-import socket
-
-try:
-    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
-    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
-except Exception:
-    pass
-
-# 配置 (从环境变量或 config.yaml)
-ZENTAO_URL = os.environ.get('ZENTAO_URL', 'http://10.89.2.91/zentao')
-ZENTAO_USER = os.environ.get('ZENTAO_USER', 'hupan')
-ZENTAO_PASSWORD = os.environ.get('ZENTAO_PASSWORD', 'Aa123456')
-PING_HOST = ZENTAO_URL.replace('http://', '').replace('https://', '').split('/')[0]
-PING_PORT = 80 if '://' not in ZENTAO_URL or ':80' in ZENTAO_URL else (
-    int(ZENTAO_URL.split(':')[2].split('/')[0]) if ZENTAO_URL.count(':') >= 2 else 80
-)
-
-_real_stdout = sys.stdout
-sys.stdout = sys.stderr
-
-try:
-    import requests
-except ImportError:
-    sys.stdout = _real_stdout
-    print('[zentao-mcp] requests 未装, 跑 pip install requests')
-    sys.exit(1)
-
-_TOKEN = None
-_SESSION = None
-
-
-def check_intranet():
-    """内网连通性校验。"""
-    try:
-        host = PING_HOST
-        port = PING_PORT
-        with socket.create_connection((host, port), timeout=3):
-            return True, ''
-    except Exception as e:
-        return False, '无法连接禅道 (%s): %s。请确认已连接内网。' % (ZENTAO_URL, str(e)[:60])
-
-
-def _get_token():
-    """登录拿 token (缓存)。"""
-    global _TOKEN
-    if _TOKEN:
-        return _TOKEN
-    r = requests.post(
-        ZENTAO_URL.rstrip('/') + '/api.php/v1/tokens',
-        json={'account': ZENTAO_USER, 'password': ZENTAO_PASSWORD},
-        timeout=10
-    )
-    if r.status_code in (200, 201):
-        _TOKEN = r.json().get('token')
-        return _TOKEN
-    raise RuntimeError('禅道登录失败: %s %s' % (r.status_code, r.text[:100]))
-
-
-def _api(method, path, data=None):
-    """调禅道 API。"""
-    token = _get_token()
-    url = ZENTAO_URL.rstrip('/') + '/api.php/v1' + path
-    r = requests.request(method, url, headers={'Token': token},
-                         json=data if method in ('POST', 'PUT') else None,
-                         params=data if method == 'GET' else None,
-                         timeout=15)
-    if r.status_code == 401:
-        global _TOKEN
-        _TOKEN = None
-        token = _get_token()
-        r = requests.request(method, url, headers={'Token': token},
-                             json=data if method in ('POST', 'PUT') else None,
-                             params=data if method == 'GET' else None,
-                             timeout=15)
-    return r
-
-
-TOOLS = [
-    {
-        "name": "list_products",
-        "description": "列禅道产品(找到需求归属)。例: list_products()",
-        "inputSchema": {"type": "object", "properties": {}},
-    },
-    {
-        "name": "list_stories",
-        "description": "查某产品的需求列表。例: list_stories(product_id=1, limit=10)",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "product_id": {"type": "integer", "description": "产品ID"},
-                "limit": {"type": "integer", "description": "返回数量(默认20)"},
-            },
-            "required": ["product_id"],
-        },
-    },
-    {
-        "name": "create_story",
-        "description": "在禅道创建需求(PRD发布→禅道需求)。权限不足会返回友好提示不报错。例: create_story(product_id=1, title='品质案件催办', spec='需求详情', pri=3, module=104)",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "product_id": {"type": "integer", "description": "产品ID"},
-                "title": {"type": "string", "description": "需求标题"},
-                "spec": {"type": "string", "description": "需求描述"},
-                "pri": {"type": "integer", "description": "优先级 1-4(1最高, 默认3)"},
-                "module": {"type": "integer", "description": "模块ID(可选)"},
-                "category": {"type": "string", "description": "类别(feature/interface/optimization, 默认feature)"},
-            },
-            "required": ["product_id", "title", "spec"],
-        },
-    },
-    {
-        "name": "list_plans",
-        "description": "查某产品的计划/迭代列表(让用户选归属)。例: list_plans(product_id=1)",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "product_id": {"type": "integer", "description": "产品ID"},
-            },
-            "required": ["product_id"],
-        },
-    },
-    {
-        "name": "list_executions",
-        "description": "查活跃的执行/迭代(按周划分的后端/前端/移动端)。例: list_executions(limit=5)",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "limit": {"type": "integer", "description": "返回数量(默认10)"},
-            },
-        },
-    },
-    {
-        "name": "link_story_to_execution",
-        "description": "把需求关联到执行/迭代(让开发能看到)。权限不足返回提示不报错。例: link_story_to_execution(story_id=761, execution_id=73)",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "story_id": {"type": "integer", "description": "需求ID"},
-                "execution_id": {"type": "integer", "description": "执行ID"},
-            },
-            "required": ["story_id", "execution_id"],
-        },
-    },
-    {
-        "name": "assign_story",
-        "description": "指派需求给某人(设负责人)。权限不足返回提示不报错。例: assign_story(story_id=761, account='hupan')",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "story_id": {"type": "integer", "description": "需求ID"},
-                "account": {"type": "string", "description": "禅道账号"},
-            },
-            "required": ["story_id", "account"],
-        },
-    },
-    {
-        "name": "change_story_status",
-        "description": "变更需求状态(draft→reviewing→active→closed)。权限不足返回提示不报错。例: change_story_status(story_id=761, status='active')",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "story_id": {"type": "integer", "description": "需求ID"},
-                "status": {"type": "string", "description": "目标状态(draft/reviewing/active/closed)"},
-            },
-            "required": ["story_id", "status"],
-        },
-    },
-    {
-        "name": "list_execution_tasks",
-        "description": "查某执行的任务列表(谁在做什么)。例: list_execution_tasks(execution_id=73)",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "execution_id": {"type": "integer", "description": "执行ID"},
-                "limit": {"type": "integer", "description": "返回数量"},
-            },
-            "required": ["execution_id"],
-        },
-    },
-    {
-        "name": "get_story_detail",
-        "description": "查需求详情(完整描述+状态+关联)。例: get_story_detail(story_id=761)",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "story_id": {"type": "integer", "description": "需求ID"},
-            },
-            "required": ["story_id"],
-        },
-    },
-]
-
-
-def _execute_tool(name, args):
-    args = args or {}
-    ok, msg = check_intranet()
-    if not ok:
-        return msg
-
-    if name == 'list_products':
-        r = _api('GET', '/products')
-        if r.status_code != 200:
-            return '查询失败: %s' % r.text[:100]
-        products = r.json().get('products', [])
-        lines = ['禅道产品 (%d 个):' % len(products)]
-        for p in products:
-            lines.append('  [%s] %s' % (p.get('id'), p.get('name', '')[:20]))
-        return '\n'.join(lines)
-
-    if name == 'list_stories':
-        pid = args.get('product_id', 1)
-        limit = args.get('limit', 20)
-        r = _api('GET', '/products/%s/stories' % pid, {'limit': limit})
-        if r.status_code not in (200, 201):
-            return '查询失败: %s' % r.text[:100]
-        stories = r.json().get('stories', [])
-        lines = ['产品 %s 的需求 (%d 个):' % (pid, len(stories))]
-        for s in stories[:limit]:
-            lines.append('  [#%s] %s (pri=%s status=%s)' % (
-                s.get('id'), s.get('title', '')[:30], s.get('pri'), s.get('status')))
-        return '\n'.join(lines)
-
-    if name == 'create_story':
-        pid = args.get('product_id', 1)
-        payload = {
-            'title': args.get('title', ''),
-            'spec': args.get('spec', ''),
-            'category': args.get('category', 'feature'),
-            'pri': args.get('pri', 3),
-        }
-        if args.get('module'):
-            payload['module'] = args['module']
-        r = _api('POST', '/products/%s/stories' % pid, payload)
-        if r.status_code in (200, 201):
-            d = r.json()
-            sid = d.get('id', '?')
-            return '✅ 需求已创建! ID=%s\n禅道地址: %s/story-view-%s.html' % (
-                sid, ZENTAO_URL.rstrip('/'), sid)
-        # 权限不足或字段错误, 友好返回不崩
-        try:
-            err = r.json().get('error', r.text[:100])
-        except Exception:
-            err = r.text[:100]
-        return '⚠️ 需求创建失败: %s\n(可能权限不足或字段缺失, 不影响其它操作)' % err
-
-    if name == 'list_plans':
-        pid = args.get('product_id', 1)
-        r = _api('GET', '/products/%s/plans' % pid)
-        if r.status_code != 200:
-            return '查询计划失败: %s' % r.text[:100]
-        plans = r.json().get('plans', [])
-        if not plans:
-            return '产品 %s 暂无计划。可在禅道里创建计划/迭代。' % pid
-        lines = ['产品 %s 的计划 (%d 个):' % (pid, len(plans))]
-        for p in plans:
-            lines.append('  [%s] %s (%s~%s)' % (
-                p.get('id'), str(p.get('title', ''))[:20], p.get('begin', ''), p.get('end', '')))
-        return '\n'.join(lines)
-
-    if name == 'list_executions':
-        limit = args.get('limit', 10)
-        r = _api('GET', '/executions', {'limit': limit})
-        if r.status_code != 200:
-            return '查询执行失败: %s' % r.text[:100]
-        execs = r.json().get('executions', [])
-        lines = ['活跃执行/迭代 (%d 个):' % len(execs)]
-        for ex in execs[:limit]:
-            lines.append('  [%s] %s (%s~%s project=%s)' % (
-                ex.get('id'), str(ex.get('name', ''))[:15],
-                ex.get('begin', ''), ex.get('end', ''), ex.get('project', '')))
-        return '\n'.join(lines)
-
-    if name == 'link_story_to_execution':
-        sid = args.get('story_id', 0)
-        eid = args.get('execution_id', 0)
-        r = _api('POST', '/executions/%s/stories' % eid, {'stories': [sid]})
-        if r.status_code in (200, 201):
-            return '✅ 需求 #%s 已关联到执行 #%s' % (sid, eid)
-        try:
-            err = r.json().get('error', r.text[:100])
-        except Exception:
-            err = r.text[:100]
-        return '⚠️ 关联失败: %s\n(可能权限不足, 需在禅道手动关联)' % err
-
-    if name == 'assign_story':
-        sid = args.get('story_id', 0)
-        account = args.get('account', '')
-        r = _api('POST', '/stories/%s/assign' % sid, {'assignedTo': account})
-        if r.status_code in (200, 201):
-            return '✅ 需求 #%s 已指派给 %s' % (sid, account)
-        try:
-            err = r.json().get('error', r.text[:100])
-        except Exception:
-            err = r.text[:100]
-        return '⚠️ 指派失败: %s\n(可能权限不足, 需在禅道手动指派)' % err
-
-    if name == 'change_story_status':
-        sid = args.get('story_id', 0)
-        status = args.get('status', '')
-        r = _api('POST', '/stories/%s/change' % sid, {'status': status})
-        if r.status_code in (200, 201):
-            return '✅ 需求 #%s 状态变更为 %s' % (sid, status)
-        try:
-            err = r.json().get('error', r.text[:100])
-        except Exception:
-            err = r.text[:100]
-        return '⚠️ 状态变更失败: %s\n(可能权限不足或状态转换不合法)' % err
-
-    if name == 'list_execution_tasks':
-        eid = args.get('execution_id', 1)
-        r = _api('GET', '/executions/%s/tasks' % eid)
-        if r.status_code != 200:
-            return '查询失败: %s' % r.text[:100]
-        tasks = r.json().get('tasks', [])
-        lines = ['执行 %s 的任务 (%d 个):' % (eid, len(tasks))]
-        for t in tasks[:20]:
-            if isinstance(t, dict):
-                lines.append('  [#%s] %s (assignedTo=%s status=%s)' % (
-                    t.get('id'), str(t.get('name', ''))[:25],
-                    t.get('assignedTo', ''), t.get('status', '')))
-        return '\n'.join(lines)
-
-    if name == 'get_story_detail':
-        sid = args.get('story_id', 0)
-        r = _api('GET', '/stories/%s' % sid)
-        if r.status_code != 200:
-            return '查询失败: %s' % r.text[:100]
-        s = r.json()
-        return '需求 #%s: %s\n状态: %s\n优先级: %s\n描述: %s' % (
-            sid, s.get('title', ''), s.get('status', ''),
-            s.get('pri', ''), str(s.get('spec', ''))[:200])
-
-    return '未知工具: %s' % name
-
-
-# ── MCP Stdio Protocol ──
-def _send(msg):
-    _real_stdout.write(json.dumps(msg, ensure_ascii=False) + '\n')
-    _real_stdout.flush()
-
-
-async def _handle(req):
-    method = req.get('method', '')
-    req_id = req.get('id')
-    params = req.get('params', {})
-
-    if method == 'initialize':
-        ok, msg = check_intranet()
-        info = {"name": "qoder-zentao", "version": "1.0.0"}
-        if not ok:
-            info['warning'] = msg
-        _send({"jsonrpc": "2.0", "id": req_id, "result": {
-            "protocolVersion": "2024-11-05",
-            "capabilities": {"tools": {}}, "serverInfo": info}})
-    elif method == 'notifications/initialized':
-        pass
-    elif method == 'tools/list':
-        _send({"jsonrpc": "2.0", "id": req_id, "result": {"tools": TOOLS}})
-    elif method == 'tools/call':
-        import asyncio
-        try:
-            result = await asyncio.get_event_loop().run_in_executor(
-                None, _execute_tool, params.get('name', ''), params.get('arguments', {}))
-            _send({"jsonrpc": "2.0", "id": req_id, "result": {
-                "content": [{"type": "text", "text": result}], "isError": False}})
-        except Exception as e:
-            _send({"jsonrpc": "2.0", "id": req_id, "result": {
-                "content": [{"type": "text", "text": "[error] %s" % str(e)[:200]}],
-                "isError": True}})
-    elif method == 'ping':
-        _send({"jsonrpc": "2.0", "id": req_id, "result": {}})
-    elif req_id is not None:
-        _send({"jsonrpc": "2.0", "id": req_id,
-               "error": {"code": -32601, "message": "Method not found"}})
-
-
-def main():
-    import asyncio
-    while True:
-        try:
-            line = sys.stdin.buffer.readline()
-        except (EOFError, OSError):
-            break
-        if not line:
-            break
-        line = line.strip()
-        if not line:
-            continue
-        try:
-            req = json.loads(line.decode('utf-8'))
-            loop = asyncio.new_event_loop()
-            loop.run_until_complete(_handle(req))
-            loop.close()
-        except json.JSONDecodeError:
-            pass
-        except Exception as e:
-            print('[zentao-mcp] error: %s' % str(e)[:80])
-
-
-if __name__ == '__main__':
-    try:
-        main()
-    except KeyboardInterrupt:
-        pass
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_cp = _o.path.join(_o.path.dirname(_o.path.dirname(_o.path.abspath(__file__))), 'common')
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
+"""ZenTao (禅道) MCP Server - 对接禅道项目管理, 替代本地 task。
+
+禅道自建内网开源版 REST API。
+/wl-task 的底层从本地 task.json 切换到禅道。
+
+工具:
+  - list_products:        列产品(找到需求的归属)
+  - list_stories:         列需求(PRD→禅道需求)
+  - create_story:         创建需求(PRD发布→自动建禅道需求)
+  - list_execution_tasks: 列执行的任务(谁在做什么)
+  - get_story_detail:     查需求详情
+
+认证: 用户名密码 → token (config.yaml zentao 段配, 团队共享)
+"""
+import os
+import sys
+import json
+import socket
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+# 配置 (从环境变量或 config.yaml)
+ZENTAO_URL = os.environ.get('ZENTAO_URL', 'http://10.89.2.91/zentao')
+ZENTAO_USER = os.environ.get('ZENTAO_USER', 'hupan')
+ZENTAO_PASSWORD = os.environ.get('ZENTAO_PASSWORD', 'Aa123456')
+PING_HOST = ZENTAO_URL.replace('http://', '').replace('https://', '').split('/')[0]
+PING_PORT = 80 if '://' not in ZENTAO_URL or ':80' in ZENTAO_URL else (
+    int(ZENTAO_URL.split(':')[2].split('/')[0]) if ZENTAO_URL.count(':') >= 2 else 80
+)
+
+# stdout 重定向 + 协议层由 BaseMCPServer 接管 (v3.0 重构)
+# 注意: requests 在 run() 内才需要 (延迟 import, 避免没装时启动即崩)
+
+_TOKEN = None
+_SESSION = None
+
+
+def check_intranet():
+    """内网连通性校验。"""
+    try:
+        host = PING_HOST
+        port = PING_PORT
+        with socket.create_connection((host, port), timeout=3):
+            return True, ''
+    except Exception as e:
+        return False, '无法连接禅道 (%s): %s。请确认已连接内网。' % (ZENTAO_URL, str(e)[:60])
+
+
+def _get_token():
+    """登录拿 token (缓存)。"""
+    global _TOKEN
+    if _TOKEN:
+        return _TOKEN
+    r = requests.post(
+        ZENTAO_URL.rstrip('/') + '/api.php/v1/tokens',
+        json={'account': ZENTAO_USER, 'password': ZENTAO_PASSWORD},
+        timeout=10
+    )
+    if r.status_code in (200, 201):
+        _TOKEN = r.json().get('token')
+        return _TOKEN
+    raise RuntimeError('禅道登录失败: %s %s' % (r.status_code, r.text[:100]))
+
+
+def _api(method, path, data=None):
+    """调禅道 API。"""
+    token = _get_token()
+    url = ZENTAO_URL.rstrip('/') + '/api.php/v1' + path
+    r = requests.request(method, url, headers={'Token': token},
+                         json=data if method in ('POST', 'PUT') else None,
+                         params=data if method == 'GET' else None,
+                         timeout=15)
+    if r.status_code == 401:
+        global _TOKEN
+        _TOKEN = None
+        token = _get_token()
+        r = requests.request(method, url, headers={'Token': token},
+                             json=data if method in ('POST', 'PUT') else None,
+                             params=data if method == 'GET' else None,
+                             timeout=15)
+    return r
+
+
+TOOLS = [
+    {
+        "name": "list_products",
+        "description": "列禅道产品(找到需求归属)。例: list_products()",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "list_stories",
+        "description": "查某产品的需求列表。例: list_stories(product_id=1, limit=10)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "product_id": {"type": "integer", "description": "产品ID"},
+                "limit": {"type": "integer", "description": "返回数量(默认20)"},
+            },
+            "required": ["product_id"],
+        },
+    },
+    {
+        "name": "create_story",
+        "description": "在禅道创建需求(PRD发布→禅道需求)。权限不足会返回友好提示不报错。例: create_story(product_id=1, title='品质案件催办', spec='需求详情', pri=3, module=104)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "product_id": {"type": "integer", "description": "产品ID"},
+                "title": {"type": "string", "description": "需求标题"},
+                "spec": {"type": "string", "description": "需求描述"},
+                "pri": {"type": "integer", "description": "优先级 1-4(1最高, 默认3)"},
+                "module": {"type": "integer", "description": "模块ID(可选)"},
+                "category": {"type": "string", "description": "类别(feature/interface/optimization, 默认feature)"},
+            },
+            "required": ["product_id", "title", "spec"],
+        },
+    },
+    {
+        "name": "list_plans",
+        "description": "查某产品的计划/迭代列表(让用户选归属)。例: list_plans(product_id=1)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "product_id": {"type": "integer", "description": "产品ID"},
+            },
+            "required": ["product_id"],
+        },
+    },
+    {
+        "name": "list_executions",
+        "description": "查活跃的执行/迭代(按周划分的后端/前端/移动端)。例: list_executions(limit=5)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "limit": {"type": "integer", "description": "返回数量(默认10)"},
+            },
+        },
+    },
+    {
+        "name": "link_story_to_execution",
+        "description": "把需求关联到执行/迭代(让开发能看到)。权限不足返回提示不报错。例: link_story_to_execution(story_id=761, execution_id=73)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "story_id": {"type": "integer", "description": "需求ID"},
+                "execution_id": {"type": "integer", "description": "执行ID"},
+            },
+            "required": ["story_id", "execution_id"],
+        },
+    },
+    {
+        "name": "assign_story",
+        "description": "指派需求给某人(设负责人)。权限不足返回提示不报错。例: assign_story(story_id=761, account='hupan')",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "story_id": {"type": "integer", "description": "需求ID"},
+                "account": {"type": "string", "description": "禅道账号"},
+            },
+            "required": ["story_id", "account"],
+        },
+    },
+    {
+        "name": "change_story_status",
+        "description": "变更需求状态(draft→reviewing→active→closed)。权限不足返回提示不报错。例: change_story_status(story_id=761, status='active')",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "story_id": {"type": "integer", "description": "需求ID"},
+                "status": {"type": "string", "description": "目标状态(draft/reviewing/active/closed)"},
+            },
+            "required": ["story_id", "status"],
+        },
+    },
+    {
+        "name": "list_execution_tasks",
+        "description": "查某执行的任务列表(谁在做什么)。例: list_execution_tasks(execution_id=73)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "execution_id": {"type": "integer", "description": "执行ID"},
+                "limit": {"type": "integer", "description": "返回数量"},
+            },
+            "required": ["execution_id"],
+        },
+    },
+    {
+        "name": "get_story_detail",
+        "description": "查需求详情(完整描述+状态+关联)。例: get_story_detail(story_id=761)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "story_id": {"type": "integer", "description": "需求ID"},
+            },
+            "required": ["story_id"],
+        },
+    },
+]
+
+
+def _execute_tool(name, args):
+    args = args or {}
+    ok, msg = check_intranet()
+    if not ok:
+        return msg
+
+    if name == 'list_products':
+        r = _api('GET', '/products')
+        if r.status_code != 200:
+            return '查询失败: %s' % r.text[:100]
+        products = r.json().get('products', [])
+        lines = ['禅道产品 (%d 个):' % len(products)]
+        for p in products:
+            lines.append('  [%s] %s' % (p.get('id'), p.get('name', '')[:20]))
+        return '\n'.join(lines)
+
+    if name == 'list_stories':
+        pid = args.get('product_id', 1)
+        limit = args.get('limit', 20)
+        r = _api('GET', '/products/%s/stories' % pid, {'limit': limit})
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % r.text[:100]
+        stories = r.json().get('stories', [])
+        lines = ['产品 %s 的需求 (%d 个):' % (pid, len(stories))]
+        for s in stories[:limit]:
+            lines.append('  [#%s] %s (pri=%s status=%s)' % (
+                s.get('id'), s.get('title', '')[:30], s.get('pri'), s.get('status')))
+        return '\n'.join(lines)
+
+    if name == 'create_story':
+        pid = args.get('product_id', 1)
+        payload = {
+            'title': args.get('title', ''),
+            'spec': args.get('spec', ''),
+            'category': args.get('category', 'feature'),
+            'pri': args.get('pri', 3),
+        }
+        if args.get('module'):
+            payload['module'] = args['module']
+        r = _api('POST', '/products/%s/stories' % pid, payload)
+        if r.status_code in (200, 201):
+            d = r.json()
+            sid = d.get('id', '?')
+            return '✅ 需求已创建! ID=%s\n禅道地址: %s/story-view-%s.html' % (
+                sid, ZENTAO_URL.rstrip('/'), sid)
+        # 权限不足或字段错误, 友好返回不崩
+        try:
+            err = r.json().get('error', r.text[:100])
+        except Exception:
+            err = r.text[:100]
+        return '⚠️ 需求创建失败: %s\n(可能权限不足或字段缺失, 不影响其它操作)' % err
+
+    if name == 'list_plans':
+        pid = args.get('product_id', 1)
+        r = _api('GET', '/products/%s/plans' % pid)
+        if r.status_code != 200:
+            return '查询计划失败: %s' % r.text[:100]
+        plans = r.json().get('plans', [])
+        if not plans:
+            return '产品 %s 暂无计划。可在禅道里创建计划/迭代。' % pid
+        lines = ['产品 %s 的计划 (%d 个):' % (pid, len(plans))]
+        for p in plans:
+            lines.append('  [%s] %s (%s~%s)' % (
+                p.get('id'), str(p.get('title', ''))[:20], p.get('begin', ''), p.get('end', '')))
+        return '\n'.join(lines)
+
+    if name == 'list_executions':
+        limit = args.get('limit', 10)
+        r = _api('GET', '/executions', {'limit': limit})
+        if r.status_code != 200:
+            return '查询执行失败: %s' % r.text[:100]
+        execs = r.json().get('executions', [])
+        lines = ['活跃执行/迭代 (%d 个):' % len(execs)]
+        for ex in execs[:limit]:
+            lines.append('  [%s] %s (%s~%s project=%s)' % (
+                ex.get('id'), str(ex.get('name', ''))[:15],
+                ex.get('begin', ''), ex.get('end', ''), ex.get('project', '')))
+        return '\n'.join(lines)
+
+    if name == 'link_story_to_execution':
+        sid = args.get('story_id', 0)
+        eid = args.get('execution_id', 0)
+        r = _api('POST', '/executions/%s/stories' % eid, {'stories': [sid]})
+        if r.status_code in (200, 201):
+            return '✅ 需求 #%s 已关联到执行 #%s' % (sid, eid)
+        try:
+            err = r.json().get('error', r.text[:100])
+        except Exception:
+            err = r.text[:100]
+        return '⚠️ 关联失败: %s\n(可能权限不足, 需在禅道手动关联)' % err
+
+    if name == 'assign_story':
+        sid = args.get('story_id', 0)
+        account = args.get('account', '')
+        r = _api('POST', '/stories/%s/assign' % sid, {'assignedTo': account})
+        if r.status_code in (200, 201):
+            return '✅ 需求 #%s 已指派给 %s' % (sid, account)
+        try:
+            err = r.json().get('error', r.text[:100])
+        except Exception:
+            err = r.text[:100]
+        return '⚠️ 指派失败: %s\n(可能权限不足, 需在禅道手动指派)' % err
+
+    if name == 'change_story_status':
+        sid = args.get('story_id', 0)
+        status = args.get('status', '')
+        r = _api('POST', '/stories/%s/change' % sid, {'status': status})
+        if r.status_code in (200, 201):
+            return '✅ 需求 #%s 状态变更为 %s' % (sid, status)
+        try:
+            err = r.json().get('error', r.text[:100])
+        except Exception:
+            err = r.text[:100]
+        return '⚠️ 状态变更失败: %s\n(可能权限不足或状态转换不合法)' % err
+
+    if name == 'list_execution_tasks':
+        eid = args.get('execution_id', 1)
+        r = _api('GET', '/executions/%s/tasks' % eid)
+        if r.status_code != 200:
+            return '查询失败: %s' % r.text[:100]
+        tasks = r.json().get('tasks', [])
+        lines = ['执行 %s 的任务 (%d 个):' % (eid, len(tasks))]
+        for t in tasks[:20]:
+            if isinstance(t, dict):
+                lines.append('  [#%s] %s (assignedTo=%s status=%s)' % (
+                    t.get('id'), str(t.get('name', ''))[:25],
+                    t.get('assignedTo', ''), t.get('status', '')))
+        return '\n'.join(lines)
+
+    if name == 'get_story_detail':
+        sid = args.get('story_id', 0)
+        r = _api('GET', '/stories/%s' % sid)
+        if r.status_code != 200:
+            return '查询失败: %s' % r.text[:100]
+        s = r.json()
+        return '需求 #%s: %s\n状态: %s\n优先级: %s\n描述: %s' % (
+            sid, s.get('title', ''), s.get('status', ''),
+            s.get('pri', ''), str(s.get('spec', ''))[:200])
+
+    return '未知工具: %s' % name
+
+
+# ── MCP Server (继承 BaseMCPServer, 协议层由基类接管) ──────────────────
+# v3.0 重构: 删除 _send/_handle/main 三段逐字复制代码 (~69行),
+# 改为继承 BaseMCPServer (Template Method), 只填差异点。
+
+def _bootstrap_base():
+    """延迟 import BaseMCPServer (scripts/ 在 sys.path)。"""
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    from common.mcp_base import BaseMCPServer
+    return BaseMCPServer
+
+
+class ZentaoMCPServer(_bootstrap_base()):
+    """禅道 MCP Server。继承基类协议层, 只填工具逻辑。"""
+
+    SERVER_NAME = "qoder-zentao"
+    SERVER_VERSION = "1.0.0"
+    TOOLS = TOOLS  # 引用上方模块级 TOOLS
+
+    def handle_tool(self, name, args):
+        return _execute_tool(name, args)
+
+    def on_initialize_hook(self, info):
+        # 启动时内网校验, 不通塞 warning (与旧版行为一致)
+        ok, msg = check_intranet()
+        if not ok:
+            info['warning'] = msg
+
+
+if __name__ == '__main__':
+    ZentaoMCPServer().run()