Cursor 与 Claude Desktop 本地实时接入指南 (Client Integration Guide)

将 BitzOrcas.Modern 的业务切片通过 MCP 暴露后，开发者可以直接在日常使用的 AI 客户端（如 Cursor IDE 的 Agent 模式，或 Anthropic 官方的 Claude Desktop）中以自然语言对话的形式，实时查看数据、发起审批流并执行复杂的业务写操作。

本指南将指导你在 5 分钟内完成本地环境的客户端挂载与联调。

1. 启动 BitzOrcas 本地宿主

首先确保通过 .NET Aspire 或独立命令行启动 BitzOrcas.Api 实例：

# 启动 API 宿主，默认监听于 http://127.0.0.1:5000
dotnet run --project src/Hosts/BitzOrcas.Api

验证 MCP 传输端点是否健康：

curl -I http://127.0.0.1:5000/mcp
# 期望返回 HTTP/1.1 200 OK 或 401/403（若启用了严格身份挑战）

2. 配置 Cursor IDE (Agent Mode)

Cursor 支持通过项目根目录下的 .cursor/mcp.json 或全局设置接入标准 MCP 服务器。

在当前工作区根目录下创建或编辑 .cursor/mcp.json：

{
  "mcpServers": {
    "bitzorcas-local": {
      "url": "http://127.0.0.1:5000/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer dev_token_administrator_seed",
        "X-Tenant-Id": "1000001"
      }
    }
  }
}

保存后，打开 Cursor 的 Settings -> Features -> MCP 界面：

确认 bitzorcas-local 状态显示为绿色圆点（Connected）；
展开工具列表，确认能够看到 create_litigation_case、get_case_by_id 等业务工具名称及对应的参数 Schema。

3. 配置 Claude Desktop

对于使用 Anthropic 官方客户端的用户，编辑 Claude Desktop 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

写入如下服务器接入配置：

{
  "mcpServers": {
    "bitzorcas": {
      "url": "http://127.0.0.1:5000/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer dev_token_administrator_seed",
        "X-Tenant-Id": "1000001"
      }
    }
  }
}

保存文件并重启 Claude Desktop。在聊天输入框右下角会亮起“小锤子（Tools）”图标，点击即可查看已挂载的 BitzOrcas 企业业务工具集。

4. 实时交互对话实战体验

在 Cursor 或 Claude 对话框中，直接使用自然语言发布指令：

开发者提问： “请帮我在租户 1000001 下创建一个诉讼案件：标的是 500,000 元，被告是‘远东建设工程有限公司’，案由是‘商业工程款项拖欠与违约赔偿’，案件类型设为 CommercialArbitration。”

智能体自主调用过程

模型推理与工具匹配： LLM 发现系统注册的 create_litigation_case 工具与意图精准匹配；

生成工具入参：

{
  "CaseTitle": "商业工程款项拖欠与违约赔偿",
  "CaseType": "CommercialArbitration",
  "ClaimAmount": 500000,
  "DefendantName": "远东建设工程有限公司"
}

安全管线执行与反馈： MCP 服务接收参数，穿越 ValidationPipelineBehavior 校验金额大于零，穿越 SqlSugarUnitOfWork 提交数据库，自动生成雪花案号 ARB-20260923-0012；
模型总结回复：
“案件已成功为您创建！
- 案号：ARB-20260923-0012
- 案件名称：商业工程款项拖欠与违约赔偿
- 标的金额：¥500,000.00
- 被告方：远东建设工程有限公司
- 承办状态：已绑定初始主办律师席位，立案审批流已自动就绪。”

5. 常见问题排查 (Troubleshooting)

故障现象	根因排查	解决方案
客户端显示 Disconnected	本地 API 宿主未启动或防火墙阻断了 5000 端口	检查 `dotnet run` 控制台输出，确认监听地址为 `http://127.0.0.1:5000`
返回 401 Unauthorized	请求头缺失有效的 Bearer Token 凭据	在 `headers` 中配置开发期有效 Token，生产环境应配置专用 Service Account 凭据
返回 403 Forbidden	租户上下文缺失或未分配 `mcp.access` 权限	在 `headers` 中补充 `X-Tenant-Id`，并确认该租户开启了 MCP 智能体访问 Feature
工具调用超时 (Timeout)	复杂业务查询没有在合理时间内完成	优化后端数据库索引，或在客户端配置中增大 `timeoutMs: 30000` 超时窗口