Quelvio

@quelvio/mcp-server

Quelvio MCP 服务——可通过任何支持 Model Context Protocol 的 AI 工具搜索公司已连接的知识库。

端点：https://mcp.quelvio.com/http（Streamable HTTP，MCP 规范 2025-03-26） 源码：Quelvio/quelvio-mcp-server 许可证：MIT

工具

工具	用途	知识令牌
query_knowledge	在租户已连接的来源（Drive、SharePoint、Confluence、Slack、Notion）中进行主要搜索。模式：fast、standard（默认）、deep。	1,500 kT（fast）/ 12,500 kT（standard）/ 25,000 kT（deep）
list_domains	发现——列出带有覆盖级别的分类域。在发起计费查询前，可用它判断知识库是否包含相关知识。	0 kT
get_source_detail	查看之前查询中每个分块的来源信息：文档路径、生命周期状态、嵌入时间戳、贡献者、上次更新时间。传入之前 query_knowledge 响应中的 query_id。	0 kT

权限模型

每个 MCP 查询都限定在单个员工身份范围内，而不仅仅是租户范围。服务会应用与控制面板相同的三层访问模型：

1. 租户隔离——Qdrant 集合按租户划分；从结构上无法访问其他租户的内容。
2. 基于角色的功能访问——Owner / Admin / Member 决定哪些工具可调用。
3. 来源权限筛选——每个分块上的 permission_emails 都会在摄取时根据来源系统的 ACL（Google Drive 共享、SharePoint 群组、Confluence 空间限制）进行解析。MCP 查询只能看到你的个人账号在这些来源系统中能访问的内容。

来源权限筛选始终生效——没有任何标志、环境变量或控制面板开关可以将其关闭。MCP 服务会记录每次查询对应的员工身份，因此，通过 get_source_detail 跨员工检查来源信息会被拒绝并返回 404（只有 Owner/Admin 才能查看其他成员的查询）。

登录

无需配置 API 密钥。首次通过任何客户端使用 Quelvio MCP 时，系统会将你重定向到组织的登录页面（由 Clerk 托管，与控制面板使用相同的页面）。登录后，客户端会自动恢复操作。后续查询会重复使用 OAuth 令牌，直到令牌过期（约 30 天）或你在 enterprise.quelvio.com 撤销令牌。

如果 AI 助手提示你在 JSON 配置中填写“Bearer token”或“API key”标头，说明配置已过时——删除 headers 块，让客户端管理 OAuth。迁移会自动完成：下次调用工具时，客户端会打开浏览器标签页供你登录。

安装

Claude Desktop（和 Claude Web）

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "quelvio": {
      "url": "https://mcp.quelvio.com/http"
    }
  }
}

重启 Claude Desktop。首次使用时，Claude 会打开一个浏览器标签页，跳转到 Clerk 托管的登录页面；完成登录后，Claude 会自动恢复操作。

Cursor

将以下内容添加到项目根目录中的 .cursor/mcp.json（或全局配置文件 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "quelvio": {
      "url": "https://mcp.quelvio.com/http"
    }
  }
}

Cursor 会像 Claude 一样处理 OAuth 往返流程。

Claude Code

claude mcp add quelvio --transport http https://mcp.quelvio.com/http

VS Code（Copilot）

将以下内容添加到 .vscode/mcp.json：

{
  "servers": {
    "quelvio": {
      "type": "http",
      "url": "https://mcp.quelvio.com/http"
    }
  }
}

stdio 桥接程序（较旧的客户端）

对于尚不支持 Streamable HTTP 的 MCP 客户端，请安装 npm 包：

npm install -g @quelvio/mcp-server

然后将客户端指向该二进制文件：

{
  "mcpServers": {
    "quelvio": {
      "command": "quelvio-mcp"
    }
  }
}

该二进制文件会在随机的 127.0.0.1 端口上打开本地 OAuth 监听器，并将之后所有 JSON-RPC 请求代理到 https://mcp.quelvio.com/http。

OAuth 流程

MCP 服务是受 OAuth 2.1 + PKCE（S256）保护的资源。Bearer 令牌是不透明的，由 KV 提供支持，并使用 AES-GCM 加密后静态存储。已接入 RFC 9728 + RFC 8414 发现机制：

• GET /.well-known/oauth-protected-resource — 资源元数据
• GET /.well-known/oauth-authorization-server — 授权服务器元数据
• GET /oauth/authorize — 重定向（302）至 Clerk 托管的登录页面（PKCE 状态暂存于 KV 中）
• GET /oauth/callback — Clerk 会话 JWT → POST /v1/auth/sso-bridge 铸造每位员工专属的临时密钥 → 重定向（302）回客户端的 redirect_uri
• POST /oauth/token — auth_code 或 refresh_token 授权类型
• POST /oauth/revoke — 使令牌失效

现代 MCP 客户端收到带有 WWW-Authenticate: Bearer ... resource_metadata=... 挑战的 401 响应时，会自动启动该流程。Cursor 和 Claude Desktop 会透明地完成此操作。

v0.8.8 基础设施移除： 旧版粘贴 API 密钥表单路径（在表单正文中通过 POST /oauth/authorize 提交 qlv_ent_* 密钥）已移除。使用粘贴密钥方式接入 MCP 的客户首次使用时必须完成 OAuth/Clerk 往返流程；迁移会自动进行——下次调用工具时，客户端只会打开一个浏览器标签页。

示例

1. query_knowledge — 查找带引文的答案

ask Claude: "What's our deployment process for the payments service?"

Claude calls: query_knowledge(query="deployment process payments service")

Response: synthesized answer with [n] citations + structured metadata block including
query_id, coverage level, retrieval execution state, latency, and tokens consumed.
(Default mode is `standard` — synthesis is built in. Use `mode="deep"` for complex
analytical questions, `mode="fast"` for keyword-style retrieval with no synthesis.)

2. list_domains — 查询前查看已索引的内容

ask Claude: "What taxonomy domains does our company have indexed?"

Claude calls: list_domains()

Response: list of every domain with document count, expert count, coverage level
(expert | partial | none), top contributor by authority, and the single_expert risk
flag where applicable.

3. get_source_detail — 验证引文

After a query_knowledge call returned [3] citations, ask Claude:
"Show me the actual source for citation [3]."

Claude calls: get_source_detail(query_id="<uuid from prior query>")

Response: per-chunk provenance — document path, lifecycle state (live | stale |
superseded | user_deleted), embedding timestamp + model, contributor name + department,
authority score, taxonomy domain.

定价

每次工具调用消耗的 Knowledge Token（v0.9 固定常量）：

• query_knowledge 使用 mode=fast ：1,500 kT （仅检索，不做综合）
• query_knowledge 使用 mode=standard ：12,500 kT（默认；包含综合）
• query_knowledge 使用 mode=deep ：25,000 kT（更广泛的检索 + 高级综合）
• list_domains ：0 kT
• get_source_detail ：0 kT

这些费用在 v0.9 合约锁定时固定。控制面板的账单页面（/billing）会显示实时的每租户每日 Knowledge Token 额度，以及预计的下一张发票金额。

自托管 / 开发

cd mcp-server
pnpm install

# Local dev
pnpm dev

# Deploy to Cloudflare Workers
wrangler secret put TOKEN_ENCRYPTION_KEY    # 32 bytes hex (openssl rand -hex 32)
wrangler secret put CLERK_SIGN_IN_URL       # Clerk hosted sign-in URL
pnpm deploy

Worker 是无状态的——所有 OAuth 产物（授权码、访问令牌、刷新令牌）都存放在绑定的 KV 命名空间中。无需 Durable Objects。

协议

• 传输方式： Streamable HTTP（MCP 规范 2025-03-26）
• 端点： POST /http，Content-Type: application/json
• 健康检查： GET / 或 GET /http 返回服务信息
• 方法： initialize、tools/list、tools/call、ping
• 流式传输： 当 tools/call query_knowledge 携带 Accept: text/event-stream，且 mode 为 standard|deep（v0.9 中会执行综合的两个档位）时，服务会代理后端的 SSE 流程。fast 模式不会进行流式传输（没有可逐步生成的综合正文）。MCP 响应仍为单个 JSON 正文——待规范添加原生输出增量后，MCP 客户端才能接收逐令牌流式输出。
• 响应上限： 服务端会强制执行 Claude Connectors 的每个工具结果 25,000 个令牌上限。截断顺序：先丢弃超过 200 个字符的摘录，再丢弃排名最低的来源（至少保留 3 个），最后截断综合正文。截断情况会通过结构化元数据块中的 truncated: true 标示，以便 Agent 使用更小的 max_sources 重新发起请求。

发布流程

发布通过 npm Trusted Publishing（OIDC），经由 .github/workflows/publish.yml 进行。此仓库和 GitHub Actions 密钥中均不存放长期有效的 NPM_TOKEN。

发布新版本：

# 1. Bump version + commit
npm version patch   # or minor / major
git push origin main

# 2. Push the matching tag — this triggers the publish workflow
git push origin v$(node -p "require('./package.json').version")

工作流会验证标签是否与 package.json 一致，执行类型检查和构建，并运行 npm publish --provenance --access public。每次发布都会附加 SLSA 来源证明。

在 npmjs.com 上的一次性初始设置（操作者步骤）：

• 包：@quelvio/mcp-server → Settings → Trusted Publishers → Add
• 仓库所有者：Quelvio
• 仓库名称：quelvio-mcp-server
• 工作流文件名：publish.yml

更新日志

参见 CHANGELOG.md。