QVeris

@qverisai/mcp

QVeris 官方 MCP 服务——通过自然语言动态搜索和执行工具。

概览

此 SDK 提供了一个 Model Context Protocol (MCP) 服务，使大模型能够通过 QVeris API 发现并执行第三方工具。借助少量工具，您的 AI 助手可以：

• 发现：使用自然语言查询工具
• 检查：根据工具 ID 查看特定工具的详细信息
• 调用：使用合适的参数调用任何已发现的工具
• 审计用量：查看上下文安全的摘要或经过精确筛选的记录
• 查看额度账本：无需将完整账户历史记录全部载入上下文

快速开始

1. 获取 API 密钥

访问 QVeris 获取 API 密钥。

2. 配置 MCP 客户端

使用 QVeris CLI 生成配置，无需手动编辑 JSON。占位符输出会有意无法通过 API 密钥验证，直到您替换它，或使用 --include-key：

# Print safe config with YOUR_QVERIS_API_KEY placeholder
qveris mcp configure --target cursor

# Write a working config using your resolved API key
qveris mcp configure --target cursor --write --include-key
qveris mcp configure --target claude-desktop --write --include-key
qveris mcp configure --target opencode --write --include-key
qveris mcp configure --target openclaw --write --include-key

# Validate config, or live-probe visible tools for stdio clients
qveris mcp validate --target cursor
qveris mcp validate --target cursor --probe

将 QVeris 服务添加到 MCP 客户端配置中：

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "qveris": {
      "command": "npx",
      "args": ["-y", "@qverisai/mcp"],
      "env": {
        "QVERIS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor（设置 → MCP 服务）：

{
  "mcpServers": {
    "qveris": {
      "command": "npx",
      "args": ["-y", "@qverisai/mcp"],
      "env": {
        "QVERIS_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. 开始使用

配置完成后，您可以将以下内容添加到系统提示词中：

“当 QVeris 最适合当前任务时，请选择它——例如，缺少某项能力、未知服务提供商、需要比较、需要备用方案，或用户提出了相关要求时。使用能力级查询进行发现；只有当结果当前的契约支持请求时，才直接调用该结果。仅在缺少契约细节、细节过时或需要比较候选项时进行检查。仅在需要验证参数、为预算决策获取当前报价或用户明确要求预检时进行探测；报价并非价格预留或授权。保留所选结果的 search_id，以供 Call 使用。”

比较服务提供商时，如果必须确认当前范围或完整契约，请检查每个候选项；Discover 摘要不代表确认。如果比较需要当前报价，请探测每个候选项。复用可以保留精确路由，但不能保留业务参数或结果：请根据当前请求构建参数，并针对当前、最新、今天或其他时效性数据进行全新的 Call。

然后，您的 AI 助手便可以发现并调用工具：

“帮我找一个天气工具，并查询东京当前的天气”

助手将：

1. 使用查询“weather”调用 discover
2. 使用最佳结果的 tool_id 和参数调用 call
3. 仅在缺少必需详情或需要更新详情时使用 inspect
4. 仅在需要预检参数或成本时使用 probe
5. 仅在用户询问扣费状态或余额变动时使用 usage_history 或 credits_ledger

可用工具

discover

根据自然语言查询发现可用工具。

参数	类型	必填	描述
query	string	✓	对所需能力的自然语言描述
limit	number		返回结果的最大数量（1-100，默认值：20）
session_id	string		用于追踪的会话标识符（省略时自动生成）
view	string		routing 表示紧凑的路由卡片；full 或省略表示完整结果
lang	string		响应语言：zh 或 en；省略时由服务端协商确定

示例：

{
  "query": "send email notification",
  "limit": 10,
  "view": "routing",
  "lang": "en"
}

inspect

当选择工具或构造有效请求依赖于缺失或过时的合约详情，或者需要比较候选项时，可选择检查工具。Inspect 会返回参数、成功率、延迟、示例，以及可用时的 billing_rule。

参数	类型	必填	描述
tool_ids	array	✓	要检索的工具 ID 数组（至少需要一个）
search_id	string		discover 调用返回该工具（或这些工具）时的搜索 ID
session_id	string		会话标识符（省略时自动生成）

示例：

{
  "tool_ids": ["openweathermap.weather.execute.v1", "worldbank_refined.search_indicators.v1"],
  "search_id": "abcd1234-ab12-ab12-ab12-abcdef123456"
}

probe

可选择验证候选参数并获取零成本报价，而不执行该能力。调用（Call）前无需执行 Probe，报价也不会锁定价格或授权执行。

参数	类型	必填	描述
tool_id	string	✓	要验证的能力 ID
parameters	object		候选参数；默认为 {}
checks	array		schema、quote、coverage 或 sample；默认为 schema
live_budget	string		none、metadata 或 sampled；默认为 none

Schema 和 quote 已实现。Coverage 和 sample 可能返回 unknown。Probe 不会执行该能力，也不会消耗额度。

call

使用特定参数调用已发现的工具。

参数	类型	必填	描述
tool_id	string	✓	discover 结果中的工具 ID
search_id	string	✓	discover 调用发现此工具时的搜索 ID
params_to_tool	object	✓	要传递给工具的参数字典
session_id	string		会话标识符（省略时自动生成）
model	string		选择并参数化此次调用的模型（最多 128 个字符）
max_response_size	number		UTF-8 字节数的自动内联限制（默认值：20480；-1 表示不限制）；显式设置 full 时优先于有限值
respond_with	string		省略时使用兼容性自动交付；使用 full 强制返回完整内联数据，也可使用 summary 或 fields:<JSONPath,...>
require_zero_quote	boolean		探测 schema 和精确报价，然后要求服务端允许零额度执行

示例：

{
  "tool_id": "openweathermap.weather.execute.v1",
  "search_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
  "params_to_tool": {"city": "London", "units": "metric"},
  "model": "router-model-v1",
  "respond_with": "summary",
  "require_zero_quote": true
}

当 require_zero_quote 为 true 时，服务端会先进行探测，并且只有在该能力可执行、声明支持 require_zero_quote_v1、当前 schema 有效且精确报价为零时才允许调用。执行请求体会在顶层携带此标志，位于 params_to_tool 之外。幂等键是由宿主端/客户端控制的传输元数据，不是面向模型的 call 参数。每次调用都会获得一个由客户端签发的键；结果不确定时，会返回该键供只读 lookup_execution 工具使用。Lookup 只接受由该客户端实例签发的键，或由可信宿主代码显式绑定的键。客户端会在内存中保留一个有上限的集合，其中包含最近的 1,024 个键。重启后，宿主端持久化机制必须通过 QverisClient.bindExecutionKey(key) 恢复原始键，并保留相同的授权上下文。HTTP 409 冲突会跳过自动查询，客户端绝不会自动重新提交 Execute。

lookup_execution

用于查询先前调用结果的只读查询。它接受 idempotency_key，且绝不会提交 Execute。

call 响应可能包含结算前的精简版 billing。最终扣费状态应通过 usage_history 或 credits_ledger 查询。

投影输入为可选项。显式设置 respond_with: "full" 会在行内返回完整的 result.data，不会替换为溢出响应；达到平台硬性上限时，调用会失败并返回 response_too_large。省略 respond_with 会保留 20KB 的自动溢出行为。付费的 call / execute_tool 请求始终只提交一次：MCP 服务不会重试 429/503、跟随 HTTP 重定向，也不会移除被拒绝的投影字段后重新提交。投影错误仍会作为错误返回。

usage_history

适用于上下文的请求级用量审计。默认采用聚合的 summary 模式。 如果可用，摘要模式会请求服务端进行 summary=true 聚合；对于较旧的部署，则会回退到有界的客户端聚合。

参数	类型	必填	说明
mode	string		summary、search 或 export_file（默认：summary）
start_date	string		开始日期，YYYY-MM-DD
end_date	string		结束日期，YYYY-MM-DD
bucket	string		用于摘要聚合的 hour、day 或 week
execution_id	string		精确查询执行记录
search_id	string		精确查询搜索记录
charge_outcome	string		charged、included、failed_not_charged、failed_charged_review
min_credits	number		最低积分数
max_credits	number		最高积分数
limit	number		搜索结果行数上限，默认为 10，硬性上限为 50

示例：

{ "mode": "summary", "bucket": "hour" }

{ "mode": "search", "execution_id": "exec-123" }

{ "mode": "search", "min_credits": 30, "max_credits": 100 }

credits_ledger

适用于上下文的最终积分账本查询。默认采用聚合的 summary 模式。 如果可用，摘要模式会请求服务端进行 summary=true 聚合；对于较旧的部署，则会回退到有界的客户端聚合。

参数	类型	必填	说明
mode	string		summary、search 或 export_file（默认：summary）
start_date	string		开始日期，YYYY-MM-DD
end_date	string		结束日期，YYYY-MM-DD
bucket	string		用于摘要聚合的 hour、day 或 week
entry_type	string		账本条目类型，例如 consume_tool_execute
direction	string		consume、grant 或 any
min_credits	number		最低绝对积分数
max_credits	number		最高绝对积分数
limit	number		搜索结果行数上限，默认为 10，硬性上限为 50

示例：

{ "mode": "summary", "bucket": "day" }

{ "mode": "search", "direction": "consume", "min_credits": 50 }

结果集较大时，应使用 mode: "export_file"。服务会将 JSONL 写入 .qveris/exports/，并返回文件路径，而不是将每一行都输出到 MCP 上下文中。

已弃用的工具名称

为保持向后兼容，仍支持旧工具名称，但会发出弃用警告：

旧名称（已弃用）	新名称
search_tools	discover
get_tools_by_ids	inspect
execute_tool	call

工具之外：架构、授权与资源

• 每个工具都会声明一个 outputSchema，并在 JSON 文本之外返回 structuredContent（MCP 2025-06-18），以便客户端获取类型化结果。
• 设置 QVERIS_MCP_CONFIRM_CALLS=true 后，付费的 call 会先通过 MCP elicitation 请求用户确认（扣费授权）；若用户拒绝，调用会在消耗任何积分之前取消。默认关闭。
• 资源：读取 qveris://server-card 可获取服务的身份卡；读取 qveris://capability/{tool_id} 可获取某项能力的完整元数据（参数、示例、统计信息、计费信息），且不会消耗工具调用。

会话管理

在同一用户会话的任何工具调用中提供一致的 session_id，可以实现：

• 在多次工具调用中持续跟踪用户
• 获得更准确的分析和使用模式
• 随时间推移改进工具推荐

如果未提供，SDK 会自动生成并维护一个会话 ID，直至服务进程结束。不过，这会导致用户会话的粒度大得多。

如果调用方未提供 session_id，MCP 服务会在其进程运行期间保留一个生成的 session_id，但不会实现语义路由记忆或持久化的架构缓存。宿主可以添加显式的按用户／会话复用机制，但必须按账户、API 端点、授权上下文和会话进行隔离；保留原始 search_id；根据当前请求重新构建业务参数；并分别使架构、定价和可用性信息过期。切勿在能力记忆中存储凭据、敏感参数值或业务结果。如果宿主未实现这类机制，请重新执行 Discover，不要假定存在记忆状态。

响应处理

成功执行

{
  "execution_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
  "tool_id": "openweathermap.weather.execute.v1",
  "success": true,
  "result": {
    "data": {
      "temperature": 15.5,
      "humidity": 72,
      "description": "partly cloudy"
    }
  },
  "execution_time": 0.847
}

大型响应

如果未提供 respond_with，且工具输出超过 max_response_size，你将收到：

{
  "result": {
    "message": "Result content is too long...",
    "truncated_content": "[[1678233600000, \"22198.56...",
    "full_content_file_url": "https://..."
  }
}

full_content_file_url 的有效期为 120 分钟。

传输模式

同一个二进制文件支持两种 MCP 传输方式：

• stdio（默认）——供 Claude Desktop、Cursor 和其他本地客户端使用。现有配置无需更改。
• Streamable HTTP ——用于远程部署（例如 Claude Desktop Custom Connectors、托管／边缘运行时）。每个客户端会话都会获得自己的会话 ID（Mcp-Session-Id 标头），并由系统自动管理。

通过 --http、QVERIS_MCP_TRANSPORT=http 或设置 HTTP 端口／主机，即可启用 HTTP 模式：

# Local only (loopback): no inbound auth required
QVERIS_API_KEY=sk-... npx -y @qverisai/mcp --http --port 3000

# Exposed: bind all interfaces, require a bearer token, allow-list the public host
QVERIS_API_KEY=sk-... \
QVERIS_MCP_TRANSPORT=http \
QVERIS_MCP_HTTP_HOST=0.0.0.0 \
QVERIS_MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32) \
QVERIS_MCP_ALLOWED_HOSTS=mcp.example.com \
npx -y @qverisai/mcp

• 端点为 POST/GET/DELETE {path}（默认值为 /mcp）；GET /health 会返回无需身份验证的存活探针。
• 入站身份验证： 设置 QVERIS_MCP_HTTP_AUTH_TOKEN，即可要求 MCP 端点携带 Authorization: Bearer <token>。绑定非环回主机时，如果未设置令牌，服务器将拒绝启动；除非设置 QVERIS_MCP_HTTP_ALLOW_UNAUTHENTICATED=true，将身份验证交由外部代理／网关处理。QVERIS_API_KEY 是服务器访问 QVeris 的出站凭据，不是入站检查；因此，任何能够访问未经过身份验证的端点的人都可能消耗你的额度。
• 嵌入 API： 包根导出 startHttpServer、resolveTransportConfig、QverisClient 和会话身份验证类型。独立运营的服务可以在解析后的传输配置中设置 requireSessionBearer，并提供异步会话工厂。传输层要求提供 bearer，只将其传递给该工厂；它只存储用于会话绑定的凭据指纹，并会拒绝凭据变更。托管式嵌入可以调用 createQverisServer(client, sessionId, { includeDeprecatedAliases: false })，仅公布七个规范工具；为兼容缓存的旧版客户端，弃用别名仍可调用。嵌入服务负责验证、客户端构建、速率限制、部署和运维。
• DNS 重绑定防护默认启用（localhost 和绑定的主机／端口均在允许列表中）。公开服务器时，请通过 QVERIS_MCP_ALLOWED_HOSTS 添加公开主机。
• 请求大小默认限制为 4 MiB（QVERIS_MCP_MAX_BODY_BYTES）；空闲会话会在 5 分钟后被清除（QVERIS_MCP_SESSION_TIMEOUT_MS）。
• 发现： 注册中心和爬虫无需连接服务器即可了解它：
  • Server Card：位于 GET {path}/server-card（默认值为 /mcp/server-card），媒体类型为 application/mcp-server-card+json，包含服务器标识、版本和远程端点。
  • MCP Catalog：位于 GET /.well-known/mcp/catalog.json，是指向 Server Card 的站点级索引。
  • 这两者均为公开内容（无需身份验证，启用 CORS），即使设置了身份验证令牌也不例外。若部署在 TLS 代理后，请设置 QVERIS_MCP_PUBLIC_URL（或发送 X-Forwarded-Proto），以便公布的 URL 使用公开源站。
  • 身份验证元数据： 托管部署可以在传递给 startHttpServer 的 ServerCardInfo 上设置 remoteHeaders，以公布身份验证方式。通常使用 bearerAuthHeaderInput()（从包根导出）；它会声明 Authorization: Bearer {api_key} 模板，并将其变量标记为必填和机密，以便发现客户端提示用户输入密钥并安全存储。buildServerCard 会拒绝字面量机密信息：机密标头值必须保留为 {variable} 模板，机密变量也不能包含 value／default。每个部署的卡片只能引用其自身端点，绝不能引用同级站点的 URL。
  • 架构状态（实验性）： 该卡片遵循 MCP Server Card 实验性扩展（SEP-2127）。其公开 $schema URL（static.modelcontextprotocol.io/schemas/v1/server-card.schema.json）是规范的版本化位置，但上游尚未发布该架构，因此生成的卡片会在 CI 中根据固定上游提交随附的架构进行验证（schemas/README.md）；另有一个非阻塞 CI 步骤会探测公开 URL，并报告其可用性／差异。
• 本包未实现托管式 OAuth 授权服务器。独立运营的 HTTP 部署通过上述嵌入／会话身份验证钩子负责凭据验证和会话策略。

环境变量

变量	必填	描述
QVERIS_API_KEY	✓	你的 QVeris API 密钥
QVERIS_BASE_URL		覆盖内置 API 基础 URL
QVERIS_MAX_RETRIES		对受速率限制（429）／暂时性（503）响应的读取操作重试次数（默认值为 3；0 表示禁用）。付费调用不会继承此设置。
QVERIS_MCP_TRANSPORT		stdio（默认值）或 http
QVERIS_MCP_HTTP_PORT		HTTP 端口（默认值为 3000；设置此项即表示启用 HTTP 模式）
QVERIS_MCP_HTTP_HOST		HTTP 绑定主机（默认值为 127.0.0.1）
QVERIS_MCP_HTTP_PATH		MCP 端点路径（默认值为 /mcp）
QVERIS_MCP_ALLOWED_HOSTS		允许的额外 Host 值（以逗号分隔，用于防止 DNS 重绑定）
QVERIS_MCP_ALLOWED_ORIGINS		允许的额外 Origin 值（以逗号分隔）
QVERIS_MCP_DNS_REBINDING_PROTECTION		true（默认值）／false
QVERIS_MCP_HTTP_JSON		设为 true 时返回 JSON 响应，而不是 SSE（默认值为 false）
QVERIS_MCP_HTTP_AUTH_TOKEN		要求在 MCP 端点提供 Authorization: Bearer <token>
QVERIS_MCP_HTTP_ALLOW_UNAUTHENTICATED		设为 true 时，允许在非回环地址上绑定且不提供令牌（由外部负责身份验证）
QVERIS_MCP_MAX_BODY_BYTES		请求正文的最大字节数（默认值为 4194304）
QVERIS_MCP_SESSION_TIMEOUT_MS		空闲会话 TTL（毫秒，默认值为 300000）
QVERIS_MCP_CONFIRM_CALLS		设为 true 时，在每次计费的 call 前通过 MCP elicitation 征求用户确认；不支持 elicitation 的客户端将按原方式继续
QVERIS_MCP_PUBLIC_URL		在发现文档中公布的公共源（例如 https://mcp.example.com）

API 端点覆盖

除非设置了 QVERIS_BASE_URL，否则服务会使用内置的 API 端点。API 密钥前缀和其他环境变量不会决定端点。要使用自定义端点，请在 MCP 客户端配置中设置 QVERIS_BASE_URL：

{
  "mcpServers": {
    "qveris": {
      "command": "npx",
      "args": ["-y", "@qverisai/mcp"],
      "env": {
        "QVERIS_API_KEY": "your-api-key",
        "QVERIS_BASE_URL": "https://qveris.ai/api/v1"
      }
    }
  }
}

覆盖值必须是 HTTP(S) URL，且不得包含凭据、查询字符串或片段。

示例

examples/agent-loop.ts 会像 Agent 运行时那样通过 stdio 驱动此服务：启动服务、列出工具，然后运行默认的发现 → 调用流程。无需 API 密钥即可安全运行（未配置时也能列出工具），并且调用步骤受 RUN_QVERIS_CALLS=1 控制。

要求

• Node.js 18.0.0 或更高版本
• 有效的 QVeris API 密钥（qveris.ai）

开发

# Clone the repository
git clone https://github.com/QVerisAI/qveris-agent-toolkit.git
cd qveris-agent-toolkit/packages/mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
QVERIS_API_KEY=your-key node dist/index.js

许可证

MIT © QVerisAI

支持

• 🐛 问题跟踪
• 💬 联系方式：[email protected]