tca-mcp-server 2.0.1 → 2.0.2

package/dist/tools/index.js

@@ -4,9 +4,21 @@ import registerJob from './job.js';
 import registerIssueReport from './issue.js';
 import registerSetup from './setup.js';
 export function registerTools(server) {
+    // 支持两种配置方式：
+    // 1. TCA_TOKEN="用户名:Token" （OpenClaw 单输入框模式，推荐）
+    // 2. TCA_TOKEN="Token" + TCA_USER_NAME="用户名" （传统分离模式，向后兼容）
+    const rawToken = process.env.TCA_TOKEN || '';
+    let token = rawToken;
+    let userName = process.env.TCA_USER_NAME || '';
+    if (!userName && rawToken.includes(':')) {
+        // 从 "用户名:Token" 格式中拆分
+        const colonIndex = rawToken.indexOf(':');
+        userName = rawToken.substring(0, colonIndex);
+        token = rawToken.substring(colonIndex + 1);
+    }
     TcaClient.initTcaClient({
-        token: process.env.TCA_TOKEN || '',
-        userName: process.env.TCA_USER_NAME || '',
+        token,
+        userName,
         baseUrl: process.env.TCA_BASE_URL || 'https://tca.tencent.com/',
         env: process.env.TCA_ENV || 'saas',
     });

package/package.json

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

package/skill/tca/SKILL.md

@@ -6,6 +6,7 @@ metadata:
     {
         'openclaw':
             {
+                'requires': { 'env': ['TCA_TOKEN'] },
                 'primaryEnv': 'TCA_TOKEN',
                 'category': 'tencent',
                 'tencentTokenMode': 'custom',
@@ -73,39 +74,88 @@ metadata:
 
 ## ⚙️ 快速配置
 
-在 OpenClaw 中使用时，需要先完成本地安装和注册。
+### 关于 TCA MCP Server
 
-### 环境变量
+TCA MCP Server 是一个发布在 npm 上的包（包名：`tca-mcp-server`），通过 stdio 协议提供 MCP 服务。
 
-使用前需要配置以下环境变量：
+- **npm 包名**：`tca-mcp-server`
+- **启动命令**：`npx -y -p tca-mcp-server@latest tca-mcp-stdio`
+- **传输协议**：stdio（标准输入输出）
+- **运行时要求**：Node.js >= 22
+- **⚠️ 无需全局安装**：不要使用 `npm install -g`，直接通过 `npx` 按需拉取即可
 
-| 变量名          | 说明               | 获取方式                                                             |
-| --------------- | ------------------ | -------------------------------------------------------------------- |
-| `TCA_TOKEN`     | TCA 平台个人 Token | 访问 [个人中心 → 个人Token](https://tca.tencent.com/user/token) 获取 |
-| `TCA_USER_NAME` | TCA 平台用户名     | 访问 [个人中心 → 个人Token](https://tca.tencent.com/user/token) 获取 |
+### 获取 Token
 
-> ⚠️ **如果 `TCA_TOKEN` 或 `TCA_USER_NAME` 为空或未配置**，请先访问 [https://tca.tencent.com/user/token](https://tca.tencent.com/user/token) 获取，否则所有工具调用将返回鉴权失败。
+使用前必须配置 `TCA_TOKEN` 环境变量，否则所有工具调用将返回鉴权失败：
 
-### 安装步骤
+1. 访问 [TCA 个人Token页面](https://tca.tencent.com/user/token)
+2. 登录后复制页面上的 **用户名** 和 **个人 Token**
+3. 在 OpenClaw 中配置环境变量 `TCA_TOKEN`，格式为：`用户名:Token`
 
-1. 运行 `setup.sh` 完成 MCP 服务注册：
+> **📌 Token 格式**：`TCA_TOKEN` 的值为 `用户名:Token`（用英文冒号 `:` 分隔）  
+> 例如：用户名为 `zhangsan`，Token 为 `abc123def456`，则填入 `zhangsan:abc123def456`
+
+| 变量名      | 说明                               | 获取方式                                                             |
+| ----------- | ---------------------------------- | -------------------------------------------------------------------- |
+| `TCA_TOKEN` | TCA 平台凭证，格式：`用户名:Token` | 访问 [个人中心 → 个人Token](https://tca.tencent.com/user/token) 获取 |
+
+> ⚠️ **向后兼容**：如果你同时设置了 `TCA_TOKEN`（纯 Token）和 `TCA_USER_NAME`（用户名）两个环境变量，系统仍然可以正常工作。合并格式 `用户名:Token` 仅在 `TCA_USER_NAME` 未设置时生效。
+
+---
+
+### 方式一：mcporter 注册（OpenClaw 平台推荐）
+
+[mcporter](https://mcporter.pages.oa.com/) 是 OpenClaw 平台提供的 MCP 服务管理 CLI 工具，可统一注册和管理多个 MCP 服务。
+
+**自动注册**（运行 setup.sh）：
 
 ```bash
 bash setup.sh
 ```
 
-> `setup.sh` 会自动将 TCA MCP Server 注册到 mcporter，并验证配置是否成功。
-> 如果未执行 setup，所有工具调用将无法找到 `tca` 服务。
+> `setup.sh` 会自动检测并安装 mcporter（如未安装），然后将 TCA MCP Server 注册为 stdio 类型的 MCP 服务。
 
-2. 验证安装是否成功：
+**手动注册**（如果不想运行 setup.sh，可手动执行以下命令）：
 
 ```bash
-mcporter list | grep tca
+mcporter config add tca \
+    --command "npx" \
+    --arg "-y" \
+    --arg "-p" \
+    --arg "tca-mcp-server@latest" \
+    --arg "tca-mcp-stdio" \
+    --env "TCA_TOKEN=<用户名>:<Token>" \
+    --transport stdio \
+    --scope home
 ```
 
-### MCP 客户端手动配置
+> ⚠️ mcporter 的参数名是 `--arg`（单数，可重复），不是 `--args`。
+
+**注册后验证**：
+
+```bash
+# 查看已注册的服务
+mcporter list tca
+
+# 调用工具测试
+mcporter call tca list_orgs
+```
 
-如果不使用 OpenClaw/mcporter，也可以在 MCP 客户端（如 Cursor、VSCode CodeBuddy 等）的配置文件中直接添加：
+**mcporter 常用命令**：
+
+| 命令                         | 说明                        |
+| ---------------------------- | --------------------------- |
+| `mcporter list`              | 列出所有已注册的 MCP 服务   |
+| `mcporter list tca`          | 查看 tca 服务详情和工具列表 |
+| `mcporter call tca <工具名>` | 调用 tca 的指定工具         |
+| `mcporter config get tca`    | 查看 tca 的配置信息         |
+| `mcporter config remove tca` | 移除 tca 服务注册           |
+
+---
+
+### 方式二：MCP 客户端手动配置
+
+在 MCP 客户端（如 Cursor、CodeBuddy、Claude Desktop、Windsurf 等）的配置文件中添加以下 JSON：
 
 ```json
 {
@@ -114,21 +164,31 @@ mcporter list | grep tca
             "command": "npx",
             "args": ["-y", "-p", "tca-mcp-server@latest", "tca-mcp-stdio"],
             "env": {
-                "TCA_TOKEN": "<你的TCA_TOKEN>",
-                "TCA_USER_NAME": "<你的TCA_USER_NAME>"
+                "TCA_TOKEN": "<用户名>:<Token>"
             }
         }
     }
 }
 ```
 
-### 安装验证
+> 💡 也支持分开配置 `"TCA_TOKEN": "<Token>"` + `"TCA_USER_NAME": "<用户名>"`
 
-配置完成后，可以通过以下方式验证：
+各客户端配置文件路径：
+
+| 客户端         | 配置文件路径                                                               |
+| -------------- | -------------------------------------------------------------------------- |
+| Cursor         | `~/.cursor/mcp.json`                                                       |
+| CodeBuddy      | VS Code 设置中搜索 MCP 或 `~/.codebuddy/mcp.json`                          |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS） |
+| Windsurf       | `~/.windsurf/mcp.json`                                                     |
+
+---
+
+### 安装验证
 
-- **OpenClaw**：运行 `mcporter list | grep tca` 确认服务已注册
-- **MCP 客户端**：在 AI 对话中输入 "列出我的TCA团队"，如果返回团队列表则说明配置成功
-- 如果返回鉴权失败，请检查 `TCA_TOKEN` 和 `TCA_USER_NAME` 是否正确
+- **mcporter 模式**：运行 `mcporter list tca` 确认服务已注册，或运行 `mcporter call tca list_orgs` 测试调用
+- **MCP 客户端模式**：在 AI 对话中输入"列出我的TCA团队"，如果返回团队列表则说明配置成功
+- 如果返回鉴权失败，请检查 `TCA_TOKEN` 格式是否为 `用户名:Token`
 
 ## 🔧 工具列表
 
@@ -235,7 +295,7 @@ mcporter list | grep tca
 
 | 错误信息                                  | 错误类型       | 解决方案                                                                                                                                  |
 | ----------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| **401 Unauthorized**                      | Token 鉴权失败 | 🔑 检查 `TCA_TOKEN` 和 `TCA_USER_NAME` 是否正确配置，可访问 [个人Token页面](https://tca.tencent.com/user/token) 重新获取                  |
+| **401 Unauthorized**                      | Token 鉴权失败 | 🔑 检查 `TCA_TOKEN` 格式是否为 `用户名:Token`，可访问 [个人Token页面](https://tca.tencent.com/user/token) 重新获取                        |
 | **403 Forbidden**                         | 权限不足       | 🔒 确认用户是否有对应团队/项目组的访问权限                                                                                                |
 | **404 Not Found**                         | 资源不存在     | 🔍 检查 `orgSid`、`teamName`、`repoId`、`projectId` 是否正确，可通过 `list_orgs` → `list_teams` → `list_repos` → `list_projects` 重新获取 |
 | **请提供 mcpConfigFile 或 orgSid 等参数** | 参数缺失       | 📝 `start_scan` 等工具需要传入配置文件路径或直接传入 4 个参数（orgSid、teamName、repoId、projectId）                                      |
@@ -244,7 +304,7 @@ mcporter list | grep tca
 
 ### 问题排查步骤
 
-1. **检查环境变量**：确认 `TCA_TOKEN` 和 `TCA_USER_NAME` 已正确配置
+1. **检查环境变量**：确认 `TCA_TOKEN` 已正确配置（格式：`用户名:Token`）
 2. **检查网络连接**：确认能访问 TCA 官网 https://tca.tencent.com
 3. **检查参数**：确认传入工具的参数值正确（如 `orgSid`、`repoId` 等）
 4. **查看工具列表**：确认所调用的工具名称正确

package/skill/tca/setup.sh

@@ -1,9 +1,11 @@
 #!/bin/bash
 # Setup script for 腾讯云代码分析（TCA）MCP Skill
+# 使用 Custom Token 认证
+# TCA_TOKEN 格式：用户名:Token（由 OpenClaw 平台注入）
 
 set -e
 
-echo "🚀 设置腾讯云代码分析（TCA）MCP Server..."
+echo "🚀 设置腾讯云代码分析（TCA）MCP Skill..."
 echo ""
 
 # ───────────────────────────────────────
@@ -11,144 +13,81 @@ echo ""
 # ───────────────────────────────────────
 echo "🔧 检查环境变量配置..."
 
-HAS_ERROR=false
-
 if [ -z "$TCA_TOKEN" ]; then
     echo "⚠️  TCA_TOKEN 环境变量未设置"
-    echo "   请访问 https://tca.tencent.com/user/token 获取 Token"
-    echo "   然后设置环境变量：export TCA_TOKEN=\"你的Token值\""
+    echo "   请访问 https://tca.tencent.com/user/token 获取用户名和 Token"
+    echo "   然后在 OpenClaw 中配置环境变量 TCA_TOKEN，格式：用户名:Token"
     echo ""
-    HAS_ERROR=true
-else
-    echo "✅ TCA_TOKEN 已配置"
+    echo "❌ 请先配置 TCA_TOKEN 环境变量后重试"
+    exit 1
 fi
 
-if [ -z "$TCA_USER_NAME" ]; then
-    echo "⚠️  TCA_USER_NAME 环境变量未设置"
-    echo "   请访问 https://tca.tencent.com/user/token 获取用户名"
-    echo "   然后设置环境变量：export TCA_USER_NAME=\"你的用户名\""
-    echo ""
-    HAS_ERROR=true
+# 支持两种格式：
+# 1. 合并格式：TCA_TOKEN="用户名:Token"（OpenClaw 推荐）
+# 2. 分离格式：TCA_TOKEN="Token" + TCA_USER_NAME="用户名"（向后兼容）
+if [ -z "$TCA_USER_NAME" ] && echo "$TCA_TOKEN" | grep -q ":"; then
+    # 从 "用户名:Token" 格式中拆分
+    TCA_USER_NAME_PARSED=$(echo "$TCA_TOKEN" | cut -d: -f1)
+    TCA_TOKEN_PARSED=$(echo "$TCA_TOKEN" | cut -d: -f2-)
+    echo "✅ TCA_TOKEN 已配置（合并格式，用户名：$TCA_USER_NAME_PARSED）"
 else
-    echo "✅ TCA_USER_NAME 已配置"
-fi
-
-if [ "$HAS_ERROR" = true ]; then
-    echo "❌ 请先配置所有必需的环境变量后重试"
-    exit 1
+    TCA_USER_NAME_PARSED="$TCA_USER_NAME"
+    TCA_TOKEN_PARSED="$TCA_TOKEN"
+    echo "✅ TCA_TOKEN 已配置"
+    if [ -n "$TCA_USER_NAME" ]; then
+        echo "✅ TCA_USER_NAME 已配置"
+    else
+        echo "⚠️  TCA_USER_NAME 未设置，TCA_TOKEN 中也未包含用户名"
+        echo "   TCA_TOKEN 格式应为：用户名:Token"
+        echo "❌ 请修正 TCA_TOKEN 格式后重试"
+        exit 1
+    fi
 fi
 
 # ───────────────────────────────────────
-# 2. 检查 Node.js 版本（mcporter 和 tca-mcp-server 均需要 >= 22）
+# 2. 检查 mcporter
 # ───────────────────────────────────────
-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
+if ! command -v mcporter &> /dev/null; then
+    echo "⚠️  未找到 mcporter，正在安装..."
+    npm install -g mcporter
+    echo "✅ mcporter 安装完成"
 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 模式）
+# 3. 添加 MCP 配置
 # ───────────────────────────────────────
-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 "🔧 配置 mcporter..."
+
+mcporter config add tca \
+    --command "npx" \
+    --arg "-y" \
+    --arg "-p" \
+    --arg "tca-mcp-server@latest" \
+    --arg "tca-mcp-stdio" \
+    --env "TCA_TOKEN=$TCA_USER_NAME_PARSED:$TCA_TOKEN_PARSED" \
+    --transport stdio \
+    --scope home
 
-    # 验证配置
-    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 "✅ 配置完成！"
 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 npm view tca-mcp-server version 2>/dev/null; then
-    echo "✅ TCA MCP Server 包可用，客户端首次启动时会自动下载"
+# ───────────────────────────────────────
+# 4. 验证配置
+# ───────────────────────────────────────
+echo "🧪 验证配置..."
+if mcporter list 2>&1 | grep -q "tca"; then
+    echo "✅ 配置验证成功！"
+    mcporter list | grep -A 1 "tca" || true
 else
-    echo "ℹ️  首次运行时 npx 会自动下载 tca-mcp-server，无需手动安装"
+    echo "⚠️  配置验证失败，请检查网络或 Token 是否正确"
 fi
 
 echo ""
 echo "─────────────────────────────────────"
-echo "🎉 环境检查完成！"
-echo ""
-echo "📖 请将以下配置添加到你的 MCP 客户端配置文件中："
-echo ""
-echo '  {'
-echo '    "mcpServers": {'
-echo '      "tca-mcp-server": {'
-echo '        "command": "npx",'
-echo '        "args": ["-y", "-p", "tca-mcp-server@latest", "tca-mcp-stdio"],'
-echo '        "env": {'
-echo "          \"TCA_TOKEN\": \"$TCA_TOKEN\","
-echo "          \"TCA_USER_NAME\": \"$TCA_USER_NAME\""
-echo '        }'
-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 ""
-echo "🏠 TCA 官网：https://tca.tencent.com"
-echo "📖 使用文档：https://tca.tencent.com/document/zh/guide/"
+echo "📖 使用方法："
+echo "   mcporter call tca list_orgs"
 echo ""
+echo "📖 更多信息请查看 SKILL.md"

package/src/tools/index.ts

@@ -6,9 +6,23 @@ import registerIssueReport from './issue.js';
 import registerSetup from './setup.js';
 
 export function registerTools(server: McpServer) {
+    // 支持两种配置方式：
+    // 1. TCA_TOKEN="用户名:Token" （OpenClaw 单输入框模式，推荐）
+    // 2. TCA_TOKEN="Token" + TCA_USER_NAME="用户名" （传统分离模式，向后兼容）
+    const rawToken = process.env.TCA_TOKEN || '';
+    let token = rawToken;
+    let userName = process.env.TCA_USER_NAME || '';
+
+    if (!userName && rawToken.includes(':')) {
+        // 从 "用户名:Token" 格式中拆分
+        const colonIndex = rawToken.indexOf(':');
+        userName = rawToken.substring(0, colonIndex);
+        token = rawToken.substring(colonIndex + 1);
+    }
+
     TcaClient.initTcaClient({
-        token: process.env.TCA_TOKEN || '',
-        userName: process.env.TCA_USER_NAME || '',
+        token,
+        userName,
         baseUrl: process.env.TCA_BASE_URL || 'https://tca.tencent.com/',
         env: process.env.TCA_ENV || 'saas',
     });