内容
# @primate-intelligence/mcp
[](https://www.npmjs.com/package/@primate-intelligence/mcp)
[](./LICENSE)
MCP（模型上下文协议）服务器，用于 **[Primate Vision API](https://primateintelligence.ai/docs)**，由 [Primate Intelligence](https://primateintelligence.ai) 提供。
为 AI 代理提供 **视频场景理解** 功能：注册视频，以纯英文提出问题，获取带有置信度分数和剪辑时间戳的确定性答案。无虚构描述 — 答案为 `yes` / `no` / `indeterminate`，并附有证据。
## 免费试用
免费测试密钥无需电子邮件、信用卡或注册：
```bash
curl -X POST https://api.primateintelligence.ai/v1/sandbox
```
您的 AI 代理可以直接执行此操作 — 从 Claude 开始。指向
[primateintelligence.ai/llms.txt](https://primateintelligence.ai/llms.txt)，它可以
自行发现、配置、集成和验证，无需人工干预。
## 连接方式
### 1. 远程服务器（推荐）— OAuth，无需安装
可流式的 HTTP 端点，支持完整的 OAuth 2.1 + 动态客户端注册 + PKCE：
```
https://api.primateintelligence.ai/mcp
```
在 Claude.ai / Claude Desktop 中：**设置 → 连接器 → 添加自定义连接器**，粘贴 URL，登录。无需处理 API 密钥 — OAuth 流程为您颁发和轮换令牌。
### 2. 本地_stdio_服务器
```jsonc
// 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`） | — |
| `get_analysis` | 获取分析状态/结果（`GET /v1/analyses/{id}`） | ✓ |
| `wait_for_analysis` | 轮询直到终端状态，返回最终分析 | ✓ |
| `list_models` | 列出可用模型（`GET /v1/models`） | ✓ |
| `get_usage` | 信用余额 + 周期计量（`GET /v1/usage`） | ✓ |
| `get_test_fixture` | 用于集成自我验证的稳定装置（`GET /v1/test-fixture`） | ✓ |
每个工具都带有 MCP 注解（`title`、`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`）。无工具删除数据。工具描述和模式映射到 OpenAPI 文档中的 [`GET /v1/openapi.json`](https://api.primateintelligence.ai/v1/openapi.json) — 该规范是事实的来源。
## 典型代理流程
1. `get_test_fixture` → 验证集成有效（测试密钥返回确定性结果，无配额消耗）
2. `create_video_from_url`，附带视频 URL
3. `create_analysis`，附带问题 — *"视频中有人吗？"*
4. `wait_for_analysis` → `result.answer` (`yes` | `no` | `indeterminate`) + `result.confidence` + `result.clips`
5. 在 `insufficient_credits` 时：调用 `get_usage`，报告余额，指向人类进行计费
## 安全合约
API 密钥仅从 `PRIMATE_API_KEY` **环境变量** 读取。**无工具接受密钥、令牌或机密作为参数** — 因此凭证不会出现在代理记录、工具调用日志或模型上下文中。这由单元测试强制执行，如果任何工具模式增长出凭证形参数，则测试失败。
错误会显示机器可读的错误 `code`、`docs_url` 和 `request_id`，以便代理在无需人工干预的情况下自我纠正。
## 配置
| 变量 | 必需 | 默认值 |
|---|---|---|
| `PRIMATE_API_KEY` | 是 | — |
| `PRIMATE_BASE_URL` | 否 | `https://api.primateintelligence.ai` |
## 开发
```bash
npm install
npm test # vitest — 工具表面、安全合约、轮询、错误形状
npm run build # tsc → dist/
```
## 链接
- [AI 代理快速入门](https://primateintelligence.ai/docs/agents) — 零人工干预集成路径
- [API 文档](https://primateintelligence.ai/docs)
- [OpenAPI 3.1 规范](https://api.primateintelligence.ai/v1/openapi.json)
- [错误注册表](https://primateintelligence.ai/docs/errors)
- [llms.txt](https://primateintelligence.ai/llms.txt) — 机器可读索引，用于代理
- [隐私政策](https://primateintelligence.ai/privacy) · [条款](https://primateintelligence.ai/terms)
## 许可证
MIT © Primate AI, Inc.
