feat: add project-level Codex MCP configuration (#1398)

Add project MCP configuration, launchers, local configuration templates, and offline regression tests for TAPD, Playwright, and DBHub.

Author: fit2cloud-chenyw

.codex/README.md

@@ -0,0 +1,45 @@
+# SQLBot 开发用 MCP
+
+项目级 MCP 布局，提供 TAPD、Playwright 和 DBHub 启动器。
+这里服务于 Codex 开发任务，与 SQLBot 产品对外提供的 MCP 接口无关。
+
+## 配置与启用
+
+[Codex 官方 MCP 文档](https://developers.openai.com/codex/mcp)支持受信任项目使用 `.codex/config.toml`。
+本仓库三个服务配置为 `enabled = true`。首次使用前需完成本地配置；暂不使用的服务应设为 `enabled = false`，避免缺少配置时启动失败。
+
+1. 在本机安装需要的 MCP 服务，记录其入口文件位置；启动器不会自动安装依赖。
+2. 将相应目录的 `.env.example` 复制为同目录 `.env.local`，填写自己的入口、解释器和项目配置。
+3. 在 `.codex/config.toml` 中确认需要的服务为 `enabled = true`，其余设为 `false`；从 SQLBot 仓库根启动新的 Codex 会话，并检查 MCP 连接状态。
+
+配置中的启动脚本路径相对于仓库根。不要从子目录启动这些相对路径命令。
+`.env.local` 使用 `KEY="value"` 格式，值必须是 JSON 字符串；不支持 shell 展开、单引号或行尾注释。
+未知字段、重复字段和缺失必填值会导致启动失败，错误消息不回显配置值。
+本地配置、浏览器资料及输出已被 Git 忽略；建议将 `.env.local` 权限设为 `600`。
+不要复制其他项目的凭据、项目 ID 或浏览器会话。
+
+## 服务约定
+
+- **TAPD**：填写 SQLBot 对应的 `TAPD_WORKSPACE_ID`、个人用户名、令牌和入口。配置保留参考项目的 Node/Python 两种实现的读取工具白名单，不开放写入工具。Python `mcp-server-tapd` 调用仍须显式传本项目 `workspace_id`；启动器不会自动注入每次调用。不要使用会另行加载其他个人凭据的包装入口。
+- **Playwright**：使用支持 Chrome、`--user-data-dir` 和 `--output-dir` 参数的 `@playwright/mcp` 入口，并准备本机 Chrome。浏览器资料位于 `playwright_mcp/browser-profile/`，截图等产物位于 `playwright_mcp/output/`。`TEST_BASE_URL` 是本机示例，需按实际测试环境调整；`TEST_*` 仅供执行测试时按需使用，启动器不会自动登录。
+- **DBHub**：沿用参考项目针对 `@bytebase/dbhub@1.3.1` 的配置格式，入口须支持 `--config`。示例 DSN 已改为 PostgreSQL/sqlbot，仅用于展示格式。DSN 通过环境变量传递，`dbhub.toml` 为 `execute_sql` 设置 `readonly = true` 和最多 1000 行；数据库账号本身也必须只读。只在任务授权的测试环境使用，不用生产或共享业务库做配置验证。
+
+## 运行时
+
+外层启动器需要 PATH 中的 Python 3.9+。`mcp_runtime.py` 统一处理配置和入口解析：
+
+- `MCP_RUNTIME="auto"` 根据 `.js/.cjs/.mjs`、`.py` 或 Node/Python shebang 识别运行时，也可明确指定 `node` 或 `python`。
+- MCP 入口须为已存在的绝对路径；`NODE_BIN` / `PYTHON_BIN` 可为绝对路径或 PATH 命令名。桌面应用 PATH 可能与终端不同，推荐在本地配置中填写解释器绝对路径。
+- Python MCP 使用其安装环境的解释器。Python TAPD 将 `TAPD_API_TOKEN` 映射为 `TAPD_ACCESS_TOKEN`，将用户名映射为 `CURRENT_USER_NICK`，并使用 stdio。
+- 运行时识别不保证不同 MCP 实现的命令行参数和工具 API 兼容。Playwright、DBHub 模板面向上述 Node 实现。
+
+## 验证
+
+从仓库根运行：
+
+```bash
+python3 -B backend/tests/test_codex_mcp_runtime.py
+```
+
+离线测试覆盖配置校验、解释器选择和启动参数/环境变量传递，不连接外部服务。
+配置解析或离线测试通过不代表真实 MCP 握手、工具调用或数据库只读权限已经验证。

.codex/config.toml

@@ -0,0 +1,22 @@
+# 填写对应 .env.local 后，按需将 enabled 改为 true。
+[mcp_servers.tapd]
+command = "python3"
+args = [".codex/tapd_mcp/launch.py"]
+enabled = true
+startup_timeout_sec = 20
+tool_timeout_sec = 60
+enabled_tools = ["tapd_get_current_user", "tapd_parse_url", "tapd_get_story", "tapd_list_stories", "tapd_get_task", "tapd_list_tasks", "tapd_get_bug", "tapd_list_bugs", "tapd_get_iteration", "tapd_list_iterations", "tapd_list_comments", "tapd_get_story_related_bugs", "tapd_get_story_changes", "tapd_list_workspace_users", "get_stories_or_tasks", "get_story_or_task_count", "get_bug", "get_bug_count", "get_comments", "get_iterations", "get_related_bugs", "get_workspace_users", "get_entity_custom_fields", "get_entity_attachments", "get_image", "get_workflows_status_map", "get_workitem_types"]
+
+[mcp_servers.playwright]
+command = "python3"
+args = [".codex/playwright_mcp/launch.py"]
+enabled = true
+startup_timeout_sec = 30
+tool_timeout_sec = 120
+
+[mcp_servers.dbhub]
+command = "python3"
+args = [".codex/dbhub_mcp/launch.py"]
+enabled = true
+startup_timeout_sec = 30
+tool_timeout_sec = 120

.codex/dbhub_mcp/.env.example

@@ -0,0 +1,8 @@
+DBHUB_DSN="postgres://readonly_user:password@127.0.0.1:5432/sqlbot"
+DBHUB_MCP_ENTRY="/absolute/path/to/@bytebase/dbhub/dist/index.js"
+NODE_BIN="node"
+
+# auto 根据扩展名或 shebang 判断；也可指定 node / python
+MCP_RUNTIME="auto"
+# Python 入口请使用安装该 MCP 的虚拟环境解释器
+PYTHON_BIN="python3"

.codex/dbhub_mcp/dbhub.toml

@@ -0,0 +1,13 @@
+[[sources]]
+id = "sqlbot"
+dsn = "${DSN}"
+
+[[tools]]
+name = "execute_sql"
+source = "sqlbot"
+readonly = true
+max_rows = 1000
+
+[[tools]]
+name = "search_objects"
+source = "sqlbot"

.codex/dbhub_mcp/launch.py

@@ -0,0 +1,19 @@
+"""Launch DBHub using the existing read-only configuration."""
+import os
+import sys
+from pathlib import Path
+
+sys.dont_write_bytecode = True
+base = Path(__file__).resolve().parent
+sys.path.insert(0, str(base.parent))
+from mcp_runtime import execute, load_config, resolve_command
+
+try:
+    local = load_config(base, {'DBHUB_DSN', 'DBHUB_MCP_ENTRY'}, {'DBHUB_DSN', 'DBHUB_MCP_ENTRY'})
+    _, command = resolve_command(local, 'DBHUB_MCP_ENTRY')
+    env = os.environ.copy()
+    env['DSN'] = local['DBHUB_DSN']
+    command.extend(['--config', str(base / 'dbhub.toml')])
+    execute(command, env)
+except (OSError, ValueError, KeyError, TypeError):
+    sys.exit('DBHub MCP 启动失败；请检查 .codex/dbhub_mcp/.env.local 的字段、入口及解释器')

.codex/mcp_runtime.py

@@ -0,0 +1,62 @@
+"""Shared local MCP configuration and runtime resolution (Python 3.9+)."""
+import json
+import os
+import shutil
+from pathlib import Path
+
+RUNTIME_KEYS = {'MCP_RUNTIME', 'NODE_BIN', 'PYTHON_BIN'}
+
+
+def load_config(base, allowed, required):
+    local = {}
+    for number, raw in enumerate((base / '.env.local').read_text().splitlines(), 1):
+        line = raw.strip()
+        if not line or line.startswith('#'):
+            continue
+        key, sep, value = line.partition('=')
+        key = key.strip()
+        if not sep or key not in allowed | RUNTIME_KEYS or key in local:
+            raise ValueError(f'配置第 {number} 行存在未知或重复字段')
+        try:
+            parsed = json.loads(value.strip())
+        except ValueError:
+            raise ValueError(f'配置第 {number} 行必须使用 JSON 字符串') from None
+        if not isinstance(parsed, str):
+            raise ValueError(f'配置第 {number} 行必须使用字符串')
+        local[key] = parsed
+    for key in required:
+        if not local.get(key):
+            raise ValueError(f'缺少配置字段 {key}')
+    return local
+
+
+def resolve_command(local, entry_key):
+    entry = Path(local[entry_key]).expanduser()
+    if not entry.is_absolute() or not entry.is_file():
+        raise ValueError(f'{entry_key} 必须是存在的文件绝对路径')
+    runtime = local.get('MCP_RUNTIME') or 'auto'
+    if runtime == 'auto':
+        if entry.suffix in {'.js', '.cjs', '.mjs'}:
+            runtime = 'node'
+        elif entry.suffix == '.py':
+            runtime = 'python'
+        else:
+            with entry.open('rb') as stream:
+                shebang = stream.readline(512)
+            if shebang.startswith(b'#!') and b'python' in shebang:
+                runtime = 'python'
+            elif shebang.startswith(b'#!') and b'node' in shebang:
+                runtime = 'node'
+            else:
+                raise ValueError('无法判断入口类型，请明确设置 MCP_RUNTIME')
+    if runtime not in {'node', 'python'}:
+        raise ValueError('MCP_RUNTIME 仅支持 auto、node、python')
+    key, fallback = ('NODE_BIN', 'node') if runtime == 'node' else ('PYTHON_BIN', 'python3')
+    binary = shutil.which(str(Path(local.get(key) or fallback).expanduser()))
+    if not binary:
+        raise ValueError(f'{key} 不是可执行文件，请指定实际解释器路径')
+    return runtime, [binary, str(entry)]
+
+
+def execute(command, env):
+    os.execvpe(command[0], command, env)

.codex/playwright_mcp/.env.example

@@ -0,0 +1,10 @@
+PLAYWRIGHT_MCP_ENTRY="/absolute/path/to/@playwright/mcp/cli.js"
+NODE_BIN="node"
+TEST_BASE_URL="http://127.0.0.1:8000"
+TEST_USERNAME=""
+TEST_PASSWORD=""
+
+# auto 根据扩展名或 shebang 判断；也可指定 node / python
+MCP_RUNTIME="auto"
+# Python 入口请使用安装该 MCP 的虚拟环境解释器
+PYTHON_BIN="python3"

.codex/playwright_mcp/launch.py

@@ -0,0 +1,22 @@
+"""Launch Playwright MCP with project-local browser storage."""
+import os
+import sys
+from pathlib import Path
+
+sys.dont_write_bytecode = True
+base = Path(__file__).resolve().parent
+sys.path.insert(0, str(base.parent))
+from mcp_runtime import execute, load_config, resolve_command
+
+try:
+    local = load_config(base, {'PLAYWRIGHT_MCP_ENTRY', 'TEST_BASE_URL', 'TEST_USERNAME', 'TEST_PASSWORD'},
+                        {'PLAYWRIGHT_MCP_ENTRY'})
+    _, command = resolve_command(local, 'PLAYWRIGHT_MCP_ENTRY')
+    profile = base / 'browser-profile'
+    output = base / 'output'
+    profile.mkdir(exist_ok=True, mode=0o700)
+    output.mkdir(exist_ok=True, mode=0o700)
+    command.extend(['--browser', 'chrome', '--user-data-dir', str(profile), '--output-dir', str(output)])
+    execute(command, os.environ.copy())
+except (OSError, ValueError, KeyError, TypeError):
+    sys.exit('Playwright MCP 启动失败；请检查 .codex/playwright_mcp/.env.local 的字段、入口及解释器')

.codex/tapd_mcp/.env.example

@@ -0,0 +1,15 @@
+TAPD_WORKSPACE_ID=""
+TAPD_CURRENT_USER=""
+TAPD_API_TOKEN=""
+TAPD_MCP_ENTRY="/absolute/path/to/tapd-mcp/dist/index.js"
+NODE_BIN="node"
+
+# auto 根据扩展名或 shebang 判断；也可指定 node / python
+MCP_RUNTIME="auto"
+# Python 入口请使用安装该 MCP 的虚拟环境解释器
+PYTHON_BIN="python3"
+
+# Python mcp-server-tapd：入口填写虚拟环境 bin/mcp-server-tapd
+# PYTHON_BIN 填写同一虚拟环境 bin/python，令牌仍填写 TAPD_API_TOKEN
+TAPD_API_BASE_URL="https://api.tapd.cn"
+TAPD_BASE_URL="https://www.tapd.cn"

.codex/tapd_mcp/launch.py

@@ -0,0 +1,34 @@
+"""Launch Node or Python TAPD MCP using only project-local credentials."""
+import os
+import sys
+from pathlib import Path
+
+sys.dont_write_bytecode = True
+base = Path(__file__).resolve().parent
+sys.path.insert(0, str(base.parent))
+from mcp_runtime import execute, load_config, resolve_command
+
+try:
+    keys = {'TAPD_WORKSPACE_ID', 'TAPD_CURRENT_USER', 'TAPD_API_TOKEN',
+            'TAPD_MCP_ENTRY', 'TAPD_API_BASE_URL', 'TAPD_BASE_URL'}
+    local = load_config(base, keys, {'TAPD_WORKSPACE_ID', 'TAPD_CURRENT_USER',
+                                    'TAPD_API_TOKEN', 'TAPD_MCP_ENTRY'})
+    runtime, command = resolve_command(local, 'TAPD_MCP_ENTRY')
+    env = os.environ.copy()
+    for key in ('TAPD_API_USER', 'TAPD_API_PASSWORD', 'TAPD_ACCESS_TOKEN',
+                'TAPD_API_BASE_URL', 'TAPD_BASE_URL', 'CURRENT_USER_NICK'):
+        env.pop(key, None)
+    env.update({key: local[key] for key in ('TAPD_WORKSPACE_ID', 'TAPD_CURRENT_USER', 'TAPD_API_TOKEN')})
+    if runtime == 'python':
+        env['TAPD_ACCESS_TOKEN'] = local['TAPD_API_TOKEN']
+        env['CURRENT_USER_NICK'] = local['TAPD_CURRENT_USER']
+        env['TAPD_API_BASE_URL'] = local.get('TAPD_API_BASE_URL') or 'https://api.tapd.cn'
+        env['TAPD_BASE_URL'] = local.get('TAPD_BASE_URL') or 'https://www.tapd.cn'
+        command.extend(['--mode', 'stdio'])
+    else:
+        for key in ('TAPD_API_BASE_URL', 'TAPD_BASE_URL'):
+            if local.get(key):
+                env[key] = local[key]
+    execute(command, env)
+except (OSError, ValueError, KeyError, TypeError):
+    sys.exit('TAPD MCP 启动失败；请检查 .codex/tapd_mcp/.env.local 的字段、入口及解释器')