tca-mcp-server 2.0.0 → 2.0.1

package/dist/stdio.js

@@ -13,4 +13,5 @@ process.env.TCA_ENV = env;
 registerTools(server);
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.log('Server started');
+// 注意：stdio 模式下必须使用 stderr 输出日志，stdout 专用于 MCP 协议通信
+console.error('TCA MCP Server started');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tca-mcp-server",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "",
   "main": "./dist/stdio.js",
   "scripts": {

package/skill/install.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# install.sh — 将 tca 技能目录软链到各 AI 客户端的 skills 目录
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_DIR="$SCRIPT_DIR/tca"
+
+if [ ! -d "$SKILL_DIR" ]; then
+    echo "❌ 未找到技能目录: $SKILL_DIR"
+    exit 1
+fi
+
+# 定义各客户端 skills 目录
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+TARGETS=(
+    "$CODEX_HOME/skills"
+    "$HOME/.claude/skills"
+    "$HOME/.cursor/skills"
+    "$HOME/.codebuddy/skills"
+)
+
+INSTALLED=0
+
+for SKILLS_DIR in "${TARGETS[@]}"; do
+    TARGET="$SKILLS_DIR/tca"
+
+    # 如果 skills 父目录不存在（客户端未安装），跳过
+    PARENT_DIR="$(dirname "$SKILLS_DIR")"
+    if [ ! -d "$PARENT_DIR" ]; then
+        echo "⏭  跳过 $SKILLS_DIR（客户端目录不存在）"
+        continue
+    fi
+
+    # 创建 skills 目录（如果不存在）
+    mkdir -p "$SKILLS_DIR"
+
+    # 如果目标已存在且不是软链，跳过
+    if [ -e "$TARGET" ] && [ ! -L "$TARGET" ]; then
+        echo "⏭  跳过 $TARGET（已存在且非软链）"
+        continue
+    fi
+
+    # 创建或更新软链
+    ln -sfn "$SKILL_DIR" "$TARGET"
+    echo "✅ 已链接 $TARGET → $SKILL_DIR"
+    INSTALLED=$((INSTALLED + 1))
+done
+
+echo ""
+if [ $INSTALLED -gt 0 ]; then
+    echo "🎉 安装完成！已链接到 $INSTALLED 个客户端。"
+    echo "   如果客户端正在运行，请重启以加载技能。"
+else
+    echo "⚠️  未安装到任何客户端。请确认至少安装了一个支持的 AI 客户端。"
+fi

package/skill/pack.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# pack.sh — 打包 tca 技能目录为 zip 文件
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_DIR="$SCRIPT_DIR/tca"
+OUTPUT="${1:-$SCRIPT_DIR/releases/tca.zip}"
+
+if [ ! -d "$SKILL_DIR" ]; then
+    echo "❌ 未找到技能目录: $SKILL_DIR"
+    exit 1
+fi
+
+# 确保输出目录存在
+OUTPUT_DIR="$(dirname "$OUTPUT")"
+mkdir -p "$OUTPUT_DIR"
+
+# 删除旧的输出文件
+rm -f "$OUTPUT"
+
+# 打包（排除 .gitignore 中的常见条目和 .DS_Store）
+cd "$SCRIPT_DIR"
+zip -r "$OUTPUT" tca/ \
+    -x "*.DS_Store" \
+    -x "*__MACOSX*" \
+    -x "*.git*" \
+    -x "*node_modules*" \
+    -x "*.env*"
+
+echo ""
+echo "✅ 打包完成: $OUTPUT"
+echo "   大小: $(du -h "$OUTPUT" | cut -f1)"

package/skill/tca/README.md

@@ -0,0 +1,70 @@
+# tca-skill
+
+供 AI 助手（Cursor、Claude、CodeBuddy、Codex）使用的腾讯云代码分析（TCA）技能包。安装后，Agent 可按照技能说明调用 TCA MCP Server 进行代码质量扫描、问题排查与修复等场景。
+
+## 技能内容概览
+
+- **调用方式**：MCP 协议，通过 `npx -y -p tca-mcp-server@latest tca-mcp-stdio` 启动
+- **凭证**：需配置 `TCA_TOKEN` 和 `TCA_USER_NAME`，访问 [个人 Token 页面](https://tca.tencent.com/user/token) 获取
+- **核心能力**：项目配置管理（17 个工具）、全量/增量代码扫描、问题分级查看与自动修复、任务监控与报告
+- 详见 `tca/SKILL.md`
+
+## CodeBuddy 中使用
+
+从 Knot 下载技能的 zip 包，在 CodeBuddy 中安装即可使用。
+
+## 手动安装（可以给其他智能体使用）
+
+克隆或下载本项目后，在项目根目录执行：
+
+```bash
+./install.sh
+```
+
+脚本会在以下目录创建指向 `tca` 的软链（若目录存在且目标非软链则跳过）：
+
+| 客户端    | 技能目录                                       |
+| --------- | ---------------------------------------------- |
+| Codex     | `$CODEX_HOME/skills`（默认 `~/.codex/skills`） |
+| Claude    | `~/.claude/skills`                             |
+| Cursor    | `~/.cursor/skills`                             |
+| CodeBuddy | `~/.codebuddy/skills`                          |
+
+安装后若客户端已运行，可重启以加载技能。
+
+## 打包
+
+生成仅含 `tca` 目录的 zip（排除 `.gitignore` 中的条目）：
+
+```bash
+./pack.sh
+# 输出默认: releases/tca.zip
+
+./pack.sh releases/tca-1.0.zip  # 指定输出路径
+```
+
+## 项目结构
+
+```
+.
+├── README.md           # 本文件
+├── install.sh          # 安装脚本（软链到各客户端 skills）
+├── pack.sh             # 打包脚本
+├── tca/                # 技能目录
+│   ├── SKILL.md        # 技能主文档（名称、描述、调用规则、凭证、工作流）
+│   ├── setup.sh        # 环境检查与配置验证脚本
+│   └── references/     # 参考文档
+│       ├── api_references.md   # 全部 17 个工具的完整 API 文档
+│       ├── tca-setup.md        # 场景：项目初始化配置
+│       ├── tca-code-scan.md    # 场景：代码扫描分析
+│       ├── tca-issue-fix.md    # 场景：问题排查与修复
+│       └── tca-job-monitor.md  # 场景：任务状态监控
+└── releases/           # 打包输出（已在 .gitignore）
+```
+
+## 相关链接
+
+- 🏠 **TCA 官网**：https://tca.tencent.com
+- 📖 **使用文档**：https://tca.tencent.com/document/zh/guide/
+- 🔑 **获取 Token**：https://tca.tencent.com/user/token
+- 📦 **npm 包**：https://www.npmjs.com/package/tca-mcp-server

package/skill/tca/{skill.md → SKILL.md}

@@ -1,8 +1,18 @@
 ---
-name: tca-mcp-server
+name: tca
 description: 腾讯云代码分析（TCA），提供完整的代码分析操作能力。当用户需要进行代码质量检查、安全扫描、代码规范检查时使用此skill，包括：(1) 配置和管理TCA分析项目 (2) 启动全量/增量代码扫描 (3) 查看和修复代码问题 (4) 监控扫描任务状态 (5) 获取分析报告。
 homepage: https://tca.tencent.com
-metadata: { 'openclaw': { 'primaryEnv': 'TCA_TOKEN', 'category': 'tencent', 'emoji': '🔍' } }
+metadata:
+    {
+        'openclaw':
+            {
+                'primaryEnv': 'TCA_TOKEN',
+                'category': 'tencent',
+                'tencentTokenMode': 'custom',
+                'tokenUrl': 'https://tca.tencent.com/user/token',
+                'emoji': '🔍',
+            },
+    }
 ---
 
 # 腾讯云代码分析（TCA）MCP 使用指南
@@ -48,10 +58,23 @@ metadata: { 'openclaw': { 'primaryEnv': 'TCA_TOKEN', 'category': 'tencent', 'emo
 
 ## API详细参考文档
 
-阅读文件 `references/api_references.md` 查看所有工具的完整 API 说明，该文件包含所有工具的参数说明、返回值说明及枚举值说明。
+首先需要阅读文件 `references/api_references.md` 查看所有工具的完整 API 说明，该文件包含所有工具的参数说明、返回值说明及枚举值说明。
+
+### 🎯 场景化文档指引
+
+根据您的具体任务场景，选择相应的参考文档进行查阅：
+
+| 任务场景                                               | 推荐参考文档                             | 主要用途                           |
+| ------------------------------------------------------ | ---------------------------------------- | ---------------------------------- |
+| **首次配置** - 初始化 TCA 项目、接入仓库、创建分析项目 | 阅读文件 `references/tca-setup.md`       | 交互式引导完成项目配置的完整工作流 |
+| **代码扫描** - 启动全量/增量扫描、获取扫描结果         | 阅读文件 `references/tca-code-scan.md`   | 从启动扫描到获取分析报告的完整流程 |
+| **问题修复** - 查看代码问题、分析根因、修复代码        | 阅读文件 `references/tca-issue-fix.md`   | 问题排查、根因分析与自动修复工作流 |
+| **任务监控** - 查看任务状态、历史记录、分析报告        | 阅读文件 `references/tca-job-monitor.md` | 任务状态监控与历史记录查询工作流   |
 
 ## ⚙️ 快速配置
 
+在 OpenClaw 中使用时，需要先完成本地安装和注册。
+
 ### 环境变量
 
 使用前需要配置以下环境变量：
@@ -61,9 +84,28 @@ metadata: { 'openclaw': { 'primaryEnv': 'TCA_TOKEN', 'category': 'tencent', 'emo
 | `TCA_TOKEN`     | TCA 平台个人 Token | 访问 [个人中心 → 个人Token](https://tca.tencent.com/user/token) 获取 |
 | `TCA_USER_NAME` | TCA 平台用户名     | 访问 [个人中心 → 个人Token](https://tca.tencent.com/user/token) 获取 |
 
-### MCP 客户端配置
+> ⚠️ **如果 `TCA_TOKEN` 或 `TCA_USER_NAME` 为空或未配置**，请先访问 [https://tca.tencent.com/user/token](https://tca.tencent.com/user/token) 获取，否则所有工具调用将返回鉴权失败。
+
+### 安装步骤
+
+1. 运行 `setup.sh` 完成 MCP 服务注册：
+
+```bash
+bash setup.sh
+```
+
+> `setup.sh` 会自动将 TCA MCP Server 注册到 mcporter，并验证配置是否成功。
+> 如果未执行 setup，所有工具调用将无法找到 `tca` 服务。
+
+2. 验证安装是否成功：
+
+```bash
+mcporter list | grep tca
+```
+
+### MCP 客户端手动配置
 
-在 MCP 客户端（如 Cursor、VSCode CodeBuddy 等）的配置文件中添加：
+如果不使用 OpenClaw/mcporter，也可以在 MCP 客户端（如 Cursor、VSCode CodeBuddy 等）的配置文件中直接添加：
 
 ```json
 {
@@ -82,9 +124,10 @@ metadata: { 'openclaw': { 'primaryEnv': 'TCA_TOKEN', 'category': 'tencent', 'emo
 
 ### 安装验证
 
-配置完成后，MCP 客户端会自动启动 TCA MCP Server。可以通过以下方式验证：
+配置完成后，可以通过以下方式验证：
 
-- 在 AI 对话中输入 "列出我的TCA团队"，如果返回团队列表则说明配置成功
+- **OpenClaw**：运行 `mcporter list | grep tca` 确认服务已注册
+- **MCP 客户端**：在 AI 对话中输入 "列出我的TCA团队"，如果返回团队列表则说明配置成功
 - 如果返回鉴权失败，请检查 `TCA_TOKEN` 和 `TCA_USER_NAME` 是否正确
 
 ## 🔧 工具列表

package/skill/tca/setup.sh

@@ -1,37 +1,18 @@
 #!/bin/bash
-# Setup script for 腾讯云代码分析（TCA）MCP Server
+# Setup script for 腾讯云代码分析（TCA）MCP Skill
 
 set -e
 
 echo "🚀 设置腾讯云代码分析（TCA）MCP Server..."
 echo ""
 
-# 检查 Node.js 环境
-if ! command -v node &> /dev/null; then
-    echo "❌ 未找到 Node.js，请先安装 Node.js >= 22.0.0"
-    echo "   推荐使用 nvm 安装：https://github.com/nvm-sh/nvm"
-    exit 1
-fi
-
-NODE_VERSION=$(node -v | cut -d'v' -f2 | cut -d'.' -f1)
-if [ "$NODE_VERSION" -lt 22 ]; then
-    echo "⚠️  Node.js 版本过低（当前：$(node -v)），需要 >= 22.0.0"
-    echo "   请升级 Node.js 版本"
-    exit 1
-fi
-echo "✅ Node.js 版本检查通过：$(node -v)"
-
-# 检查 npx
-if ! command -v npx &> /dev/null; then
-    echo "❌ 未找到 npx，请确保 npm 已正确安装"
-    exit 1
-fi
-echo "✅ npx 可用"
-
-# 检查环境变量
-echo ""
+# ───────────────────────────────────────
+# 1. 检查环境变量
+# ───────────────────────────────────────
 echo "🔧 检查环境变量配置..."
 
+HAS_ERROR=false
+
 if [ -z "$TCA_TOKEN" ]; then
     echo "⚠️  TCA_TOKEN 环境变量未设置"
     echo "   请访问 https://tca.tencent.com/user/token 获取 Token"
@@ -57,20 +38,97 @@ if [ "$HAS_ERROR" = true ]; then
     exit 1
 fi
 
-# 验证 MCP Server 是否可以正常启动
+# ───────────────────────────────────────
+# 2. 检查 Node.js 版本（mcporter 和 tca-mcp-server 均需要 >= 22）
+# ───────────────────────────────────────
+if ! command -v node &> /dev/null; then
+    echo "❌ 未找到 Node.js，请先安装 Node.js >= 22.0.0"
+    echo "   推荐使用 nvm 安装：https://github.com/nvm-sh/nvm"
+    exit 1
+fi
+
+NODE_VERSION=$(node -v | cut -d'v' -f2 | cut -d'.' -f1)
+if [ "$NODE_VERSION" -lt 22 ]; then
+    echo "❌ Node.js 版本过低（当前：$(node -v)），mcporter 和 tca-mcp-server 均需要 >= 22.0.0"
+    echo "   请升级：nvm install 22 && nvm use 22"
+    exit 1
+fi
+echo "✅ Node.js 版本检查通过：$(node -v)"
+
+# ───────────────────────────────────────
+# 3. 检查 mcporter（OpenClaw 模式）
+# ───────────────────────────────────────
+if command -v mcporter &> /dev/null; then
+    echo ""
+    echo "📦 检测到 mcporter，使用 OpenClaw 模式注册 MCP 服务..."
+    echo ""
+
+    # 注册 TCA MCP Server 到 mcporter（stdio 传输模式）
+    mcporter config add tca \
+        --command "npx" \
+        --arg "-y" \
+        --arg "-p" \
+        --arg "tca-mcp-server@latest" \
+        --arg "tca-mcp-stdio" \
+        --env "TCA_TOKEN=$TCA_TOKEN" \
+        --env "TCA_USER_NAME=$TCA_USER_NAME" \
+        --transport stdio \
+        --scope home
+
+    echo ""
+    echo "✅ mcporter 注册完成！"
+    echo ""
+
+    # 验证配置
+    echo "🧪 验证配置..."
+    if mcporter list 2>&1 | grep -q "tca"; then
+        echo "✅ 配置验证成功！"
+        echo ""
+        mcporter list | grep -A 1 "tca" || true
+    else
+        echo "⚠️  配置验证失败，请检查环境变量是否正确"
+    fi
+
+    echo ""
+    echo "─────────────────────────────────────"
+    echo "🎉 设置完成！"
+    echo ""
+    echo "📖 使用方法："
+    echo "   mcporter call tca list_orgs"
+    echo ""
+    echo "🏠 TCA 官网：https://tca.tencent.com"
+    echo ""
+    exit 0
+fi
+
+# ───────────────────────────────────────
+# 4. 非 mcporter 模式：输出 MCP 客户端配置
+# ───────────────────────────────────────
+echo ""
+echo "📦 mcporter 未安装，使用 MCP 客户端直接配置模式..."
+echo ""
+
+# 检查 npx
+if ! command -v npx &> /dev/null; then
+    echo "❌ 未找到 npx，请确保 npm 已正确安装"
+    exit 1
+fi
+echo "✅ npx 可用"
+
+# 预下载 MCP Server 包（不启动进程）
 echo ""
-echo "🧪 验证 TCA MCP Server..."
-if npx -y -p tca-mcp-server@latest tca-mcp-stdio --version 2>/dev/null; then
-    echo "✅ TCA MCP Server 安装验证成功"
+echo "🧪 预下载 TCA MCP Server..."
+if npm view tca-mcp-server version 2>/dev/null; then
+    echo "✅ TCA MCP Server 包可用，客户端首次启动时会自动下载"
 else
     echo "ℹ️  首次运行时 npx 会自动下载 tca-mcp-server，无需手动安装"
 fi
 
 echo ""
 echo "─────────────────────────────────────"
-echo "🎉 设置完成！"
+echo "🎉 环境检查完成！"
 echo ""
-echo "📖 MCP 客户端配置示例（添加到 MCP 配置文件中）："
+echo "📖 请将以下配置添加到你的 MCP 客户端配置文件中："
 echo ""
 echo '  {'
 echo '    "mcpServers": {'
@@ -85,6 +143,12 @@ echo '      }'
 echo '    }'
 echo '  }'
 echo ""
+echo "📁 各客户端配置文件路径："
+echo "   Cursor:         ~/.cursor/mcp.json"
+echo "   CodeBuddy:      VS Code 设置中搜索 MCP 或 ~/.codebuddy/mcp.json"
+echo "   Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)"
+echo "   Windsurf:       ~/.windsurf/mcp.json"
+echo ""
 echo "🏠 TCA 官网：https://tca.tencent.com"
 echo "📖 使用文档：https://tca.tencent.com/document/zh/guide/"
 echo ""

package/src/stdio.ts

@@ -17,4 +17,5 @@ process.env.TCA_ENV = env;
 registerTools(server);
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.log('Server started');
+// 注意：stdio 模式下必须使用 stderr 输出日志，stdout 专用于 MCP 协议通信
+console.error('TCA MCP Server started');