primateintelligence

@primate-intelligence/mcp

用于 Primate Vision 视频分析 API 的 MCP（Model Context Protocol）服务——这是由 Primate Intelligence 提供的视频理解 API（文档 · llms.txt）。

为 AI Agent 提供视频场景理解工具：注册视频，用通俗英语提问，即可获得确定性答案，以及置信度分数和片段时间戳。不会产生幻觉式描述——答案为 yes / no / indeterminate，并附有证据。

免费试用

免费测试密钥无需邮箱、银行卡或注册：

curl -X POST https://api.primateintelligence.ai/v1/sandbox

AI Agent 可以直接在 Claude 中为你完成这些操作。让它访问 primateintelligence.ai/llms.txt，它就能 自行发现、配置、集成并验证，全程无需人工操作。

两种连接方式

1. 远程服务（推荐）——OAuth，无需安装

支持完整 OAuth 2.1 + Dynamic Client Registration + PKCE 的 Streamable HTTP 端点：

https://api.primateintelligence.ai/mcp

在 Claude.ai / Claude Desktop 中：选择 Settings → Connectors → Add custom connector，粘贴 URL，然后登录。无需管理 API 密钥——OAuth 流程会为你签发并轮换令牌。

2. 本地 stdio 服务

// claude_desktop_config.json · .mcp.json · mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "primate-intelligence": {
      "command": "npx",
      "args": ["-y", "@primate-intelligence/mcp"],
      "env": { "PRIMATE_API_KEY": "pv_live_…" }
    }
  }
}

工具

工具	功能	只读
create_video_from_url	从公开的 https URL 注册视频（POST /v1/videos）	—
create_analysis	针对视频提问（POST /v1/analyses）	—
validate_analysis	试运行提示词：评估可分析性 + 估算成本，不消耗额度（validate_only: true）	✓
create_analysis_batch	针对同一视频提出 2–10 个提示词；第一个之后的每个提示词按 50% 计费（POST /v1/analyses/batch）	—
get_analysis	获取分析状态/结果（GET /v1/analyses/{id}）	✓
wait_for_analysis	轮询直至进入终态；返回 { analysis, retry }	✓
list_models	列出可用模型（GET /v1/models）	✓
get_usage	额度余额 + 周期用量统计（GET /v1/usage）	✓
get_credits	余额 + 按分析记录的交易明细（GET /v1/credits）	✓
get_test_fixture	用于集成自验证的稳定测试样例（GET /v1/test-fixture）	✓

每个工具都带有 MCP 注解（title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint），声明了 outputSchema，并返回符合该架构的 structuredContent。没有工具会删除数据。工具描述和架构与 GET /v1/openapi.json 中的 OpenAPI 文档一致——该规范是唯一事实来源。

典型的 Agent 工作流

1. get_test_fixture → 验证集成是否正常（测试密钥会返回确定性结果，且不消耗额度）
2. 使用视频 URL 调用 create_video_from_url
3. validate_analysis → 确认可分析该提示词 + 预览 estimated_cost_usd（免费）
4. 使用问题调用 create_analysis——“视频中有一个人吗？”——也可以用 create_analysis_batch 批量提问
5. wait_for_analysis → result.answer（yes | no | indeterminate）+ result.confidence + result.clips + result.detected_count（计数查询）+ result.indeterminate_reason
6. 遇到 insufficient_credits 时：调用 get_credits，报告余额和最近的扣款记录，并指引用户前往账单页面

安全契约

API 密钥仅从 PRIMATE_API_KEY 环境变量读取。没有任何工具会将密钥、令牌或机密作为参数接受——因此凭据不会进入 Agent 对话记录、工具调用日志或模型上下文。此要求由单元测试强制执行：如果任何工具架构新增了类似凭据的参数，测试就会导致构建失败。

错误会提供机器可读的错误 code、docs_url 和 request_id，让 Agent 无需人工介入即可自行纠正。

配置

变量	必填	默认值
PRIMATE_API_KEY	是	—
PRIMATE_BASE_URL	否	https://api.primateintelligence.ai

开发

npm install
npm test        # vitest — tool surface, security contract, polling, error shape
npm run build   # tsc → dist/

链接

• AI Agent 快速入门 — 无需人工干预的集成路径
• API 文档
• OpenAPI 3.1 规范
• 错误注册表
• llms.txt — 面向 Agent 的机器可读索引
• 隐私政策 · 条款

许可证

MIT © Primate AI, Inc.