@aiservicer/mcp-server

AIServicer 的 Model Context Protocol (MCP) Server 独立包 —— 通过 stdio 协议向 AI 客户端（Cursor、Claude Desktop 等）暴露 AIServicer 平台的 66 个工具：Bot / 项目 / 知识库 / 渠道 / 对话 / 交易 / Agent 管理 / API Key / AgentX / Admin / LightRAG / 全局分析 / Function Calling chat。

• 传输协议：stdio（不需要开放任何网络端口）
• 协议版本：MCP 2024-11-05
• 认证：AISERVICER_API_KEY（X-API-Key Header）

安装与使用

1. 从 npm 安装（推荐）

# 全局安装（任意目录可直接调用）
npm i -g @aiservicer/mcp-server

# 或使用 npx（不安装）
npx @aiservicer/mcp-server

2. 配置 AI 客户端

Cursor — 在项目目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "aiservicer": {
      "command": "aiservicer-mcp-server",
      "env": {
        "AISERVICER_BASE_URL": "https://aiservicer.0xainet.top",
        "AISERVICER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop — 编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "aiservicer": {
      "command": "aiservicer-mcp-server",
      "args": [],
      "env": {
        "AISERVICER_BASE_URL": "https://aiservicer.0xainet.top",
        "AISERVICER_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. 环境变量

| 变量 | 必填 | 默认值 | 说明 | |------|------|--------|------| | AISERVICER_BASE_URL | 是 | http://localhost:3800 | Gateway API 根地址（工具内部已含 /api/v1 前缀）。生产环境填 https://aiservicer.0xainet.top | | AISERVICER_API_KEY | 是 | - | API Key 认证（X-API-Key Header） | | AISERVICER_SERVER_BASE_URL | 否 | 同 AISERVICER_BASE_URL | Server API 地址（auth/agentx/chat/admin 端点）。生产环境填 https://aiservicer.0xainet.top（server 域与 gateway 同域名） | | AISERVICER_ADMIN_TOKEN | 否 | - | 平台管理员 JWT。配置后启用 admin_* 工具 |

对话与 BYOK 要求（重要）

MCP Server 始终以 API Key（集成方） 身份调用平台，因此：

• 平台 LLM 不向 API Key 开放：API Key 调用的对话请求若 Bot 未配置自有 LLM，返回 400 byok_required
• chat_with_agent 工具调用前，目标 Bot 必须已配置 LLM Provider（BYOK）——即商户自己的 OpenAI 兼容 endpoint + Key + Model

配置 BYOK 两种方式：

1. 平台后台：项目 → Bot → LLM Provider 配置
2. Merchant API：

curl -X PATCH http://localhost:5189/api/merchant/projects/<projectId>/bots/<botId>/llm-config \
  -H "Authorization: Bearer <merchant JWT>" -H "Content-Type: application/json" \
  -d '{
    "provider": "custom",
    "endpoint": "https://api.openai.com/v1",
    "apiKey": "sk-...",
    "model": "gpt-4o"
  }'

平台登录用户（JWT）不受此限制，走平台默认 LLM（按套餐 token 配额计费）。

发布流程（维护者）

版本号约定

| 项 | 值 | 说明 | |----|----|----| | 当前版本 | 0.8.2 | npm 远端 latest 为 0.8.1，按小版本递增（BYOK 规则文档/提示同步） | | 依赖 @aiservicer/sdk | ^0.8.2 | 必须跟随 SDK 发布进度升级；SDK 新增资源（orchestration / scheduledTasks）时同步在本包补工具 | | 依赖 @modelcontextprotocol/sdk | ^1.0.0 | MCP 官方 SDK | | 依赖 zod | ^3.23.0 | 工具参数 schema 校验 |

版本对齐规则：@aiservicer/mcp-server 与 @aiservicer/sdk 各自独立发版，但 MCP 包的 @aiservicer/sdk 依赖始终指向已发布的最新版（^0.8.2 起）。涉及 SDK API 变更时必须先发 SDK 再发 MCP 包。

发布步骤

cd mcp-server

# 1. 升级版本号（不自动打 tag，tag 由仓库统一管理）
npm version 0.8.2 --no-git-tag-version

# 2. 校验依赖版本（发布前确认 sdk 依赖为最新已发布版）
grep '"@aiservicer/sdk"' package.json   # 应为 ^0.8.2

# 3. 安装依赖并构建
npm install
npm run build                            # tsc → dist/index.js
node dist/index.js --help 2>&1 | head    # 冒烟测试（缺 env 应报错退出）

# 4. 发布（需要 @aiservicer 组织权限，token 在 ~/.npmrc）
npm publish

# 5. 验证远端 latest
npm dist-tag ls @aiservicer/mcp-server   # 期望 latest = 0.8.2

# 6. 提交版本号变更
cd ..
git add mcp-server/package.json mcp-server/package-lock.json
git commit -m "chore(mcp-server): 发布 @aiservicer/[email protected]"

发布依赖 npm 凭证：NPM_TOKEN 写入 ~/.npmrc（//registry.npmjs.org/:_authToken=...），发布账号需属于 @aiservicer 组织。

变更检查清单

• [ ] SDK 依赖已升级到最新已发布版（npm dist-tag ls @aiservicer/sdk）
• [ ] npm run build 通过，dist/index.js 存在
• [ ] npm publish 后 npm dist-tag ls 确认 latest 更新
• [ ] 仓库内 package.json / package-lock.json 已提交

完整工具清单

见仓库根目录 docs/MCP.md。