内容
# OCP 图形查询 API 的 MCP 服务器
适用于 [Open Collective GraphQL API v2](https://api.opencollective.com/graphql/v2) 的 MCP 服务器。它为 AI 助手提供了三种工具，以便在不暴露任何写入操作的情况下，**学习模式、搜索文档和运行只读查询** Open Collective。
## 安全地与 AI 一起使用
Open Collective 数据包括个人可识别信息（姓名、电子邮件、付款详情、地址）。此服务器是一个 **通用只读 GraphQL 代理** — `graphql_query` 工具可以选择底层令牌允许读取的任何字段，因此防止泄露 PII 的防护措施在 *提示级别*，而不在代码中强制执行。
- 优先在 **本地** 运行（下面的 stdio 传输），以便您的数据和令牌永远不会离开您的机器。
- 当您只需要公共数据时，优先使用 **匿名模式**（无令牌）— 您只能看到公共 API 公开的内容。
此服务器从不记录或保留令牌。有关完整的 PII 状况和安全的字段选择指南，请参阅 **[docs/using-with-ai-safely.md](docs/using-with-ai-safely.md)**。
## 安装 — Claude Code 插件（最简单）
对于 Claude Code，安装插件而不是手动配置。它附带了 MCP 服务器（stdio，通过 `uvx`）、查询技能和 `opencollective-analyst` 代理 — 所有这些都固定到发布的版本：
```bash
/plugin marketplace add opensourceeurope/mcp-for-ocp-graphql
/plugin install oc-platform-api@ose-ai
```
在您的环境中设置 `OC_PERSONAL_TOKEN` 以进行身份验证访问（可选 — 忽略以获取匿名公共数据）。如果您使用 Claude Code，请优先使用此方法而不是下面的手动 stdio 设置。
## 两种运行方式
### 本地 — stdio（推荐）
完全在您的机器上通过 MCP stdio 传输运行。令牌是 **可选的**：如果没有令牌，服务器将匿名运行以获取公共数据；如果有令牌，它可以读取该令牌授权的任何内容。发布到 [PyPI](https://pypi.org/project/mcp-for-ocp-graphql/) 并使用 `uvx` 运行。
```bash
# 匿名（仅公共数据）
uvx mcp-for-ocp-graphql
# 身份验证 — 在 https://opencollective.com/dashboard/personal-tokens 获取令牌
OC_PERSONAL_TOKEN=oc_xxx uvx mcp-for-ocp-graphql
```
通用 MCP 客户端配置：
```json
{
"mcpServers": {
"mcp-for-ocp-graphql": {
"command": "uvx",
"args": ["mcp-for-ocp-graphql"],
"env": { "OC_PERSONAL_TOKEN": "oc_xxx" }
}
}
}
```
Claude 代码：
```bash
claude mcp add mcp-for-ocp-graphql -e OC_PERSONAL_TOKEN=oc_xxx -- uvx mcp-for-ocp-graphql
```
（省略 `-e OC_PERSONAL_TOKEN=...` 以匿名运行。）
### 主机 — 可流式 HTTP + OAuth
**只要客户端支持，优先使用stdio（上面）** — 它更简单，您的数据和令牌永远不会离开您的机器。只有当您的工具通过 HTTP 讲话 MCP 并且无法启动本地 stdio 子进程时，才使用 HTTP 传输 — 通常是基于 Web/托管的助手，如 claude.ai 自定义连接器或 ChatGPT 连接器。桌面代理（Claude Code、Cursor、Windsurf、Zed、VS Code、LM Studio、Goose、Cherry Studio）都支持 stdio — 使用它。
每个用户都使用自己的 Open Collective 个人令牌通过 OAuth 2.1 / PKCE 直通（/oc-login 处的浏览器表单）进行身份验证；服务器不会创建自己的令牌，也不会存储共享的凭据。
为社区在欧盟（Scaleway，`pl-waw`）托管了一个 **社区实例**。指向它的是一个仅限 HTTP 的 MCP 客户端：
```bash
claude mcp add --transport http mcp-for-ocp-graphql \
https://opensourceeuropeb9a9bb69-oc-graphql-mcp.functions.fnc.pl-waw.scw.cloud/mcp
```
首次使用时，客户端会打开一个浏览器进行 OAuth；粘贴您自己的 Open Collective 个人令牌。每个用户都独立进行身份验证 — 服务器上没有共享令牌。
> ⚠️ **请勿过度使用社区实例。** 它是一个小型、成本共担的社区部署，在空闲时扩展到零 — 提供给工具无法进行 stdio 的人使用，而不是用于重负载或自动负载。如果您查询很多，需要保证可用性，或者想要控制区域，**请在本地运行stdio（上面）** 或 **[自行托管](docs/self-hosting.md)**。
要运行您自己的 HTTP 实例，请参阅 **[docs/self-hosting.md](docs/self-hosting.md)**（Docker + 配置参考）。
## 三种工具
预期的流程是 **学习，然后执行**：
1. **`search_docs(query, top_k=5)`** — 对 Open Collective GraphQL 指南的精选语料库和顶级查询字段的精选映射进行关键词（BM25）搜索。使用此 **首先** 来确定您需要的查询和字段。每个命中结果都带有 `source_url`，链接回其源 — 深入链接到指南块的精确部分（`#anchor`）。
2. **`schema_lookup(name)`** — GraphQL 类型或查询字段的精确定义：其描述、字段和参数（名称、类型、必填、默认值）。子字符串匹配返回候选名称。
3. **`graphql_query(query, variables=None)`** — 执行只读 GraphQL 查询并返回 JSON 结果。**拒绝突变和订阅**：文档中的每个操作都被解析，并且必须是 `query`。
## 进一步阅读
- **[安全地与 AI 一起使用](docs/using-with-ai-safely.md)** — PII 状况和安全的字段选择指南。
- **[自行托管](docs/self-hosting.md)** — 通过 Docker 运行您自己的托管 HTTP 服务器，以及完整的配置参考。
- **[Scaleway 部署](docs/scaleway-deployment.md)** — Scaleway 上托管的 HTTP 服务器的逐步演练。
- **[开发](docs/development.md)** — 本地开发设置、文档语料库管道和发布过程。
- 本地 stdio 设置端到端：**[与 Ollama](docs/local-agent-with-ollama.md)** · **[与 UI](docs/local-agent-with-ui.md)**。
## 堆栈和致谢
- [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk) （FastMCP）
- [graphql-core](https://github.com/graphql-python/graphql-core) — 只读查询解析/验证
- [httpx](https://www.python-httpx.org/) — GraphQL 传输
- Pure-Python BM25（`search.py`）— 文档搜索，无模型或向量 DB
- OpenCrane CLI（`uvx opencrane`）— 构建时文档语料库管道（`fetch` / `llms` / `chunk`;精简的 `docs.json` 由该项目自己的 `docs_bake.py` 生成）
- [Open Collective GraphQL API v2](https://developers.opencollective.com/access)
MIT 许可。
