Context Repo Mcp Server

Context Repo MCP stdio 桥接器

context-repo-mcp 是一个无状态、依赖网络的传输适配器，用于连接托管的 Context Repo MCP。它让需要本地 stdio 命令或 API 密钥身份验证的 MCP 客户端能够使用托管服务。

stdio MCP client
  -> context-repo-mcp
  -> HTTPS POST https://contextrepo.com/mcp
  -> hosted Context Repo MCP

此软件包不会在本地实现或注册 Context Repo 工具。托管 MCP 负责其工具、提示词、资源、架构、业务行为、错误和结果格式。桥接器负责封装 stdio 消息、验证请求、校验托管服务的响应，并转发已接受的 JSON-RPC 响应文本，而不会重新序列化。

选择合适的连接方式

使用 OAuth 连接远程 MCP

如果你的客户端支持远程 MCP 服务和 OAuth，请直接连接托管的 MCP：

{
  "mcpServers": {
    "context-repo": {
      "url": "https://contextrepo.com/mcp"
    }
  }
}

客户端的配置位置和属性名称各不相同。调整此通用示例时，请参考 MCP 客户端的文档。

npm 桥接器不实现 OAuth、不打开浏览器、不存储 OAuth 令牌，也不公开回调端口。

使用 API 密钥连接本地 stdio

如果你的客户端需要本地命令或 API 密钥设置，请启动 npm 桥接器：

{
  "mcpServers": {
    "context-repo": {
      "command": "npx",
      "args": ["-y", "context-repo-mcp"],
      "env": {
        "CONTEXTREPO_API_KEY": "gm_your_api_key"
      }
    }
  }
}

在 Context Repo 设置中生成 API 密钥。将其保存在 MCP 客户端的机密或环境配置中。切勿将其提交到源代码管理中。

CONTEXTREPO_API_KEY 是规范的环境变量。其值必须是以 gm_ 开头的非空字符串。

CONTEXT_REPO_API_KEY 仍作为已弃用的兼容别名提供，并会向 stderr 输出一条警告。如果同时配置了这两个名称，其值必须一致。即使两个名称同时存在，该别名仍会输出弃用警告。

要求

• Node.js 18 或更高版本
• 能够访问配置的托管 MCP 端点
• 使用 npm/stdio 连接方式时，需要 Context Repo API 密钥

安装

MCP 客户端可以运行此软件包，无需安装：

npx -y context-repo-mcp

也可以全局安装：

npm install --global context-repo-mcp
context-repo-mcp

通常由 MCP 客户端启动和控制此命令。它从 stdin 读取 JSON-RPC 消息并将响应写入 stdout，而不提供交互式 Shell 界面。

Agent 技能

此仓库还分发了 SKILL.md，其中包含可复用的指导，说明兼容的 Agent 何时以及如何使用 Context Repo。内容包括：

• 搜索提示词、文档和集合中的单个条目；
• 在文档内容中进行分层搜索和导航；
• 使用 reason 对存储的文档提供附带引用、尽力而为的回答；
• 使用必需的 expectedRevision 安全地更新和恢复文档版本；以及
• 区分直接 OAuth 连接和 API 密钥 stdio 桥接器。

可通过 Skills CLI 从此 GitHub 仓库安装该技能。它不会打包在 npm 软件包中，运行 npx context-repo-mcp 也不会安装它。

为受支持的 Agent 全局安装该技能：

npx skills add Gitmaxd/context-repo-mcp --global

技能更新合并后，更新现有安装：

npx skills update context-repo-mcp

安装技能本身不会连接 MCP 客户端、提供凭据或添加工具。请按照上文说明，另外配置直接连接托管服务或使用 stdio 桥接器。如果更新后的技能尚未显示，请启动新的 Agent 会话。

能力归属与发现

npm 软件包刻意不包含静态工具清单。MCP 初始化后，请使用协议的列表方法（包括 tools/list、prompts/list 和 resources/list）来发现托管服务当前提供的能力。

托管能力和业务行为可能会不断演进，而无需发布新版 npm 软件包。固定此软件包的版本，固定的是桥接器实现，而不是托管工具集。

运行时约定

输入帧处理与分发

• 标准输入采用 UTF-8 编码，每个非空行包含一个 JSON-RPC 负载。
• 接受 LF 和 CRLF 换行符。最后一行无需以换行符结尾。
• 空行会被忽略。
• JSON 格式错误时，会返回本地 JSON-RPC 解析错误，代码为 -32700，且 id: null；后续输入行仍会继续处理。
• 成功解析的行会独立分发。多个请求可能同时在处理中，因此响应可能与输入顺序不同，必须根据 JSON-RPC ID 进行关联。
• 标准输入正常 EOF 时，进程会等待所有正在处理的请求完成。

托管请求

每个成功解析的输入行都会作为 HTTP POST 的请求体，恰好发送一次到已配置的 MCP 端点：

Authorization: API-Key <configured key>
Content-Type: application/json
Accept: application/json
User-Agent: context-repo-mcp

对于 reason 工具调用，桥接程序会设置 90 秒超时；对于其他托管响应，则设置 30 秒超时。桥接程序不会跟随重定向，也不会重试失败的 POST 请求。

托管响应验证

只有满足以下所有条件，非空托管响应才会被接受：

• 媒体类型为 application/json 或 application/*+json 类型。
• 响应体只有一行，不含字面的回车符或换行符。
• 响应体可解析为 JSON-RPC 2.0 响应对象，或由多个有效 JSON-RPC 2.0 响应对象组成的非空批次。
• 每个响应都具有字符串、数字或 null 类型的 ID，并且恰有 result 和 error 之一。错误对象必须包含整数 code 和字符串 message。

HTTP 状态码本身并不能决定请求是否成功。即使 HTTP 状态码不是 2xx，仍会转发有效的 JSON-RPC 结果或错误。

验证通过后，原始托管响应文本会写入标准输出，不会重新序列化；桥接程序只会追加标准输入输出行协议所需的结尾 LF。这样可以保留 content、structuredContent、_meta、数字文本、转义字符、空白以及未来新增的未知字段。

只有 JSON-RPC 通知（即不含 id 的对象）才接受空的成功响应。此类响应不会产生标准输出消息。

桥接程序故障

超时、重定向、网络故障、空请求响应、不受支持的内容类型、SSE、多行响应体、格式错误的 JSON 以及无效的 JSON-RPC 响应都会导致请求失败。

• 对于请求，桥接程序会写入一条 JSON-RPC 错误，使用原始有效 ID（或 null），代码为 -32000，并采用以下固定消息： Context Repo bridge could not reach the hosted MCP server
• 对于通知，桥接程序不会写入 JSON-RPC 响应，而是将相同的固定消息输出到标准错误。
• 原始网络错误、上游响应体、凭据、负载、堆栈跟踪和本地文件系统路径不会被复制到这些诊断信息中。

标准输出仅包含 JSON-RPC 内容。配置警告和故障诊断信息会输出到标准错误。

开发端点覆盖

CONTEXTREPO_MCP_URL 可在开发和测试时覆盖 https://contextrepo.com/mcp。其值必须是绝对 URL：

• 非环回主机必须使用 HTTPS。
• 仅 localhost、127.0.0.1 或 [::1] 允许使用纯 HTTP。
• 不接受包含用户名、密码或 URL 片段的地址。

桥接程序会将已配置的 API 密钥发送到此端点。只能使用由你控制并信任的覆盖端点。如果该端点不是生产环境的 Context Repo 服务，建议使用一次性测试密钥。

已移除的 v2 变量 CONTEXTREPO_API_URL 指向 REST API，本桥接程序不支持该变量。

故障排除

进程立即退出

桥接程序会在读取标准输入之前验证配置。请确认 CONTEXTREPO_API_KEY 已设置、以 gm_ 开头，且未与已弃用的别名冲突。

客户端报告桥接失败

稳定的桥接失败消息会有意隐藏上游原始详情。这可能表示网络故障、超时、重定向、请求响应为空、内容类型不受支持、正文包含多行或格式错误，或 JSON-RPC 响应无效。

有效的托管 JSON-RPC 错误（包括身份验证错误和业务错误）会原样转发。如果托管 MCP 返回了错误，请以该错误为准。

如果无法进行托管调用，请查看 Context Repo 服务状态。该软件包没有本地或离线备用方案。

客户端显示弃用警告

请将 CONTEXT_REPO_API_KEY 替换为 CONTEXTREPO_API_KEY。如果环境中同时继承了这两个变量，请确认规范变量已配置，然后移除已弃用的别名。

开发

npm ci
npm test
npm ls --all
npm pack --dry-run

该项目使用 ES 模块和内置的 node:test 测试运行器。它没有运行时或开发依赖项。自动化测试使用注入的 fetch 实现或环回 HTTP 服务器，无需真实的 API 密钥，也不会连接 contextrepo.com。

源代码布局：

• src/config.js 验证环境配置。
• src/index.js 处理标准输入流的分帧、分发任务并写入输出。
• src/bridge.js 发送每个托管请求并验证响应。
• test/ 覆盖配置、传输、进程行为和打包后的 npm 构件。

从 v2 迁移

版本 3 将重复的本地 MCP 实现替换为此托管标准输入输出桥接。因此，它需要网络访问，其 MCP 功能由托管服务提供。

• 将 CONTEXT_REPO_API_KEY 重命名为 CONTEXTREPO_API_KEY。
• 仅在开发或测试时，将已移除的 REST 覆盖项 CONTEXTREPO_API_URL 替换为 CONTEXTREPO_MCP_URL。
• 如果你的 MCP 客户端支持直接连接托管 OAuth，请优先使用此方式。

如果迁移期间需要临时回退到 v2，请明确指定最后一个 v2 版本：

npx -y [email protected]

链接

• Context Repo
• Context Repo MCP 文档
• npm 软件包
• 服务状态
• Model Context Protocol
• GitHub 仓库
• 问题跟踪
• 支持

许可证

MIT，详见 LICENSE。