Claude / Cursor 接入

本文介绍如何将 TestNet 作为 MCP (Model Context Protocol) 服务端接入 Claude Code、OpenCode 或 Cursor IDE（其他支持 SSE / streamable MCP 的客户端可参照同样的配置方式接入）。

前提条件

1. TestNet 后端服务已部署并正常运行（默认端口 8081）
2. 拥有 TestNet 访问凭证：
   • 推荐方式：使用静态 MCP API Key（TESTNET_MCP_API_KEY，开发环境默认 default-mcp-api-key-for-dev-environment，永不过期，专为 Agent 优化）
   • 用户方式：使用平台用户账号登录获取的 JWT Token（需具备 mcp:view 和 mcp:execute 权限）

---

快速配置

1. Claude Code 集成

方式 A：CLI 命令行一键接入（推荐）

在终端中直接运行以下命令注册 MCP 服务：

# 使用静态 API Key（推荐）
claude mcp add --transport sse testnet http://localhost:8081/mcp/v1 --header "Authorization: Bearer default-mcp-api-key-for-dev-environment"

方式 B：项目级配置文件

在项目根目录新建或直接使用预置的 .mcp.json 或 .claude/settings.json：

{
  "mcpServers": {
    "testnet": {
      "url": "http://localhost:8081/mcp/v1",
      "headers": {
        "Authorization": "Bearer default-mcp-api-key-for-dev-environment"
      }
    }
  }
}

---

2. OpenCode 集成

在项目根目录下创建 opencode.json：

{
  "$schema": "https://opencode.ai/config.schema.json",
  "mcp": {
    "servers": [
      {
        "name": "testnet",
        "type": "sse",
        "url": "http://localhost:8081/mcp/v1/sse",
        "headers": {
          "Authorization": "Bearer default-mcp-api-key-for-dev-environment"
        }
      }
    ]
  }
}

启动 OpenCode 后，工具箱中将自动出现 testnet_* 开头的 14 个核心门面工具（每个工具通过 action 参数覆盖一个完整业务域）。

---

3. Cursor IDE 集成

1. 打开 Cursor 设置（Ctrl + , 或 Cmd + ,）
2. 导航至「Features」➔「MCP」
3. 点击「+ Add New MCP Server」：
   • Name: testnet
   • Type: url
   • URL: http://localhost:8081/mcp/v1
4. 添加 Headers：
   • Key: Authorization
   • Value: Bearer default-mcp-api-key-for-dev-environment
5. 点击「Save」保存。

---

错误自愈协议

TestNet MCP 服务在工具执行失败时，不仅返回错误原因，还会附带结构化的 remediation（自愈修复引导）：

{
  "isError": true,
  "error": "target 未在项目 [proj-1] 资产库中找到: example.com (DOMAIN)",
  "remediation": {
    "suggestion": "工作流需要先有种子资产在库中归档。请先调用 testnet_asset(action='create') 录入目标。",
    "recommendedTool": "testnet_asset",
    "exampleArguments": {
      "action": "create",
      "projectId": "proj-1",
      "assetType": "DOMAIN",
      "data": { "domain": "example.com" }
    }
  }
}

外部 AI Agent（如 Claude Code、OpenCode）捕获该结构后，能直接根据 recommendedTool 和 exampleArguments 完成自愈闭环，无需重新规划长链思考。

---

Agent 工具调用最佳实践

1. 项目上下文优先：所有操作依赖 projectId，优先调用具备幂等保护的 testnet_project(action="create", projectName="...")。
2. 严禁循环短轮询：派发批量任务后，必须使用 testnet_task(action="await") 服务端挂起等待；轻量单工具可使用 testnet_task(action="run", wait_timeout_seconds=20) 同步直返。
3. 先搜后跑：触发任何扫描或工作流前，先用 testnet_search_tools 检索可用工具与参数规范，严禁臆测工具名称。
4. 上下文经济性：查询资产开启 compact: true，单页数量限制 limit <= 50。
5. 底层日志排查：任务报错时调用 testnet_task(action="logs", taskId="...", limit=200) 查看真实 stdout/stderr。

---

相关文档

• MCP 概述 — 14 个核心门面工具总览与资源/提示词
• AI 技能中心 — 为 Agent 注入技能知识卡
• AI 记忆管理 — Agent 的跨会话持久记忆