oitvoip-mcp

用于 Oitvoip（托管 VoIP/UCaaS 转售平台，基于 NetSapiens 构建 — API 主机模式为 {tenant-pbx-host}/ns-api/）的 MCP 服务器。将 NetSapiens ns-api 的域名、经销商、设备、用户和 CDR 方法作为 MCP 工具公开。

命名说明：MSPbots 自身的集成注册为“Oitvoip”（subjectCode=NS — 即 NetSapiens 的缩写）；底层 API 和所有官方文档均引用“NetSapiens”/“ns-api”。此 MCP 恰好涵盖 MSPbots 自身配置的 5 个方法。

概述

• 无状态 HTTP 服务。不持久化任何凭据 — 每个请求通过请求头提供自己的凭据，仅在该单个请求的生命周期内使用。

• 支持并发请求；每个请求的凭据隔离通过 Python contextvars 实现，而非全局/共享客户端实例。

• 入口点：POST /mcp（MCP 协议）和 GET /health（健康检查）。

• 默认端口：8080（可通过 MCP_HTTP_PORT 配置）。

Related MCP server: whmcs-mcp-server

身份验证

NetSapiens 使用标准的 OAuth2 密码授权：

POST https://{site}/ns-api/oauth2/token/
  grant_type=password&client_id=...&client_secret=...&username=...&password=...
-> {"access_token": "...", "expires_in": 3600, "token_type": "Bearer", ...}

生成的 access_token 有效期为 1 小时，但此服务器在每次工具调用时都会重新进行全新身份验证，而不是在 MCP 请求之间缓存 — 不缓存或持久化任何内容。然后，每个真实的 ns-api 调用都会发送 Authorization: Bearer <access_token>。

HEADER 授权参数说明

缺少任何标头均返回 401：

{
  "error": "Missing credentials",
  "message": "This server requires the X-Oitvoip-Site, X-Oitvoip-Client-Id, X-Oitvoip-Client-Secret, X-Oitvoip-Username, X-Oitvoip-Password headers",
  "required_headers": ["X-Oitvoip-Site", "X-Oitvoip-Client-Id", "X-Oitvoip-Client-Secret", "X-Oitvoip-Username", "X-Oitvoip-Password"],
  "optional_headers": []
}

无效凭据或已通过身份验证但作用域不足的订阅者账户会以工具级 unauthorized 错误信封的形式出现（消息包含供应商自身的详细信息，例如 Invalid Scope [APP001]），而不是来自此服务器的 HTTP 级错误 — 请参阅已知差距。

环境变量

MCP 端点

• POST /mcp — MCP 协议（可流式 HTTP 传输）

• GET /health — 健康检查，返回 {"status": "ok"}（纯本地探测，不调用供应商 API）

工具列表

响应是供应商的 JSON（根据方法不同，可能是数组或对象），以紧凑方式序列化（无缩进，ensure_ascii=False）。如果响应超过约 20,000 个字符，则截断最大的列表字段，结果包含 truncated: true 以及原始计数，而不是返回无界 blob。所有 5 个工具均为只读（readOnlyHint）— 此服务中没有写入/删除工具。

出错时，工具返回结构化的 JSON 错误信封，而不是引发异常：

{"error": {"code": "unauthorized", "message": "...", "retryable": false}}

code 是 not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error 之一；retryable 指示代理是否可以安全重试（对于 rate_limited 和 upstream_error 为 true）。

测试示例

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Oitvoip-Site: pbx.example.com" \
  -H "X-Oitvoip-Client-Id: 58900.mspbot" \
  -H "X-Oitvoip-Client-Secret: <your-client-secret>" \
  -H "X-Oitvoip-Username: 1000@example" \
  -H "X-Oitvoip-Password: <your-password>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "oitvoip_get_subscribers",
      "arguments": {"domain": "example.58900.service"}
    }
  }'

实时验证（2026-07-30）针对真实租户，所有 5 个工具均通过此运行中的服务器端到端调用：oitvoip_get_subscribers 返回真实的订阅者/分机记录；oitvoip_get_devices 返回已注册的 SIP 设备（Polycom 端点，实时注册状态）；oitvoip_get_cdr2 返回给定日期范围的真实通话详单。oitvoip_get_domains 和 oitvoip_get_resellers 正确访问 API，并出现干净、预期的 401 Invalid Scope [APP001] 工具级错误 — 提供的测试凭据是订阅者级账户（scope: "Office Manager"），在此特定 NetSapiens 部署中不具有域/经销商管理员权限；请参阅已知差距。

API 参考

• 公开，无需登录：https://api.ucaasnetwork.com/ns-api/apidoc/（完整的 ns-api 参考，包括 OAuth2、域、经销商、设备、订阅者和 CDR 对象）

已知差距

• 范围恰好是 MSPbots 配置的 5 个端点，而不是供应商的完整 API 表面 — ns-api 还涵盖 Callqueue、Agent、Phonenumber、Dialplan、Contacts、Presence、Call Queue Report/Stat、实时呼叫控制等（根据公共文档自身的对象列表）；这些不在范围内。

• oitvoip_get_domains 和 oitvoip_get_resellers 无法使用真实数据完全实时验证 — 提供的测试账户成功进行身份验证（证明 OAuth2 流程和此实现正确），但作用域为订阅者级“Office Manager”角色，NetSapiens 拒绝这两个管理级对象，返回 401 Invalid Scope [APP001]。这是特定测试账户的凭据权限限制，而不是此服务器的错误 — oitvoip_get_subscribers、oitvoip_get_devices 和 oitvoip_get_cdr2 都使用相同登录的相同访问令牌成功返回真实数据。

• CDR 日期范围字段（start_date/end_date）是未经验证的字符串 — 按原样以 YYYY-MM-DD HH:MM:SS 格式传递给供应商，与 MSPbots 自身存储的用法匹配；不执行客户端日期解析。