Context Repo MCP stdio Bridge

context-repo-mcp is a stateless, network-dependent transport adapter for the hosted Context Repo MCP. It lets MCP clients that require a local stdio command or API-key authentication use the hosted service.

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

This package does not implement or register Context Repo tools locally. The hosted MCP owns its tools, prompts, resources, schemas, business behavior, errors, and result shapes. The bridge frames stdio messages, authenticates requests, validates hosted responses, and relays accepted JSON-RPC response text without reserializing it.

Choose the right connection

Remote MCP with OAuth

If your client supports remote MCP servers and OAuth, connect directly to the hosted MCP:

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

Client configuration locations and property names vary. Consult your MCP client's documentation when adapting this generic example.

The npm bridge does not implement OAuth, open a browser, store OAuth tokens, or expose a callback port.

Local stdio with an API key

If your client requires a local command or API-key setup, launch the npm bridge:

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

Generate an API key in Context Repo settings. Keep it in your MCP client's secret or environment configuration. Never commit it to source control.

CONTEXTREPO_API_KEY is the canonical environment variable. Its value must be a non-empty string beginning with gm_.

CONTEXT_REPO_API_KEY remains available as a deprecated compatibility alias and emits one warning to stderr. If both names are configured, their values must match. The alias still emits its deprecation warning when both values are present.

Requirements

• Node.js 18 or later
• Network access to the configured hosted MCP endpoint
• A Context Repo API key for the npm/stdio connection path

Installation

MCP clients can run the package without installing it:

npx -y context-repo-mcp

Or install it globally:

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

The command is normally launched and controlled by an MCP client. It reads JSON-RPC messages from stdin and writes responses to stdout rather than providing an interactive shell interface.

Agent skill

This repository also distributes SKILL.md, reusable guidance that teaches compatible agents when and how to use Context Repo. It covers:

• item-level search across prompts, documents, and collections;
• hierarchical search and navigation within document content;
• cited, best-effort answers over stored documents with reason;
• revision-safe document updates and restores with required expectedRevision; and
• the distinction between direct OAuth connections and the API-key stdio bridge.

The skill is installed from this GitHub repository by the Skills CLI. It is not bundled in the npm package, and running npx context-repo-mcp does not install it.

Install the skill globally for supported agents:

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

Update an existing installation after a skill change is merged:

npx skills update context-repo-mcp

Installing the skill does not connect an MCP client, provide credentials, or add tools by itself. Configure either the direct hosted connection or the stdio bridge separately, as described above. Start a new agent session if an updated skill is not yet visible.

Capability ownership and discovery

The npm package deliberately contains no static tool inventory. After MCP initialization, use the protocol's listing methods, including tools/list, prompts/list, and resources/list, to discover the capabilities currently provided by the hosted server.

Hosted capabilities and business behavior can evolve without a new npm package release. Pinning this package pins the bridge implementation, not the hosted tool surface.

Runtime contract

Input framing and dispatch

• Stdin is UTF-8 with one JSON-RPC payload per non-empty line.
• LF and CRLF line endings are accepted. A final line does not require a trailing newline.
• Empty lines are ignored.
• Malformed JSON produces a local JSON-RPC parse error with code -32700 and id: null; later input lines continue to be processed.
• Successfully parsed lines are dispatched independently. Multiple requests may be in flight, so responses can arrive out of input order and must be correlated by JSON-RPC ID.
• On normal stdin EOF, the process waits for all in-flight requests to finish.

Hosted request

Each successfully parsed input line is sent exactly once as the body of an HTTP POST to the configured MCP endpoint with:

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

The bridge applies a 90-second timeout to reason tool calls and a 30-second timeout to other hosted responses. It does not follow redirects and does not retry failed POST requests.

Hosted response validation

A non-empty hosted response is accepted only when all of the following are true:

• Its media type is application/json or an application/*+json type.
• Its body is a single line with no literal carriage return or newline.
• Its body parses as a JSON-RPC 2.0 response object or a non-empty batch of valid JSON-RPC 2.0 response objects.
• Every response has a string, number, or null ID and exactly one of result or error. Error objects require an integer code and string message.

HTTP status alone does not determine success. A valid JSON-RPC result or error is relayed even when the HTTP status is non-2xx.

After validation, the original hosted response text is written to stdout without reserializing it; the bridge appends only the terminating LF required by the stdio line protocol. This preserves fields such as content, structuredContent, _meta, numeric text, escaping, whitespace, and unknown future fields.

An empty successful response is accepted only for a JSON-RPC notification, which is an object without an id. It produces no stdout message.

Bridge failures

Timeouts, redirects, network failures, empty request responses, unsupported content types, SSE, multiline bodies, malformed JSON, and invalid JSON-RPC responses all fail closed.

• For a request, the bridge writes one JSON-RPC error using the original valid ID (or null), code -32000, and this stable message: Context Repo bridge could not reach the hosted MCP server.
• For a notification, the bridge writes no JSON-RPC response and emits the same stable message to stderr.
• Raw network errors, upstream bodies, credentials, payloads, stack traces, and local filesystem paths are not copied into these diagnostics.

Stdout remains JSON-RPC-only. Configuration warnings and failure diagnostics go to stderr.

Development endpoint override

CONTEXTREPO_MCP_URL overrides https://contextrepo.com/mcp for development and tests. The value must be an absolute URL:

• HTTPS is required for non-loopback hosts.
• Plain HTTP is allowed only for localhost, 127.0.0.1, or [::1].
• Embedded usernames, passwords, and URL fragments are rejected.

The bridge sends the configured API key to this endpoint. Only use an override you control and trust. Prefer a disposable test key when the endpoint is not the production Context Repo service.

The removed v2 variable CONTEXTREPO_API_URL points to the REST API and is not supported by this bridge.

Troubleshooting

The process exits immediately

The bridge validates configuration before reading stdin. Confirm CONTEXTREPO_API_KEY is present, begins with gm_, and does not conflict with the deprecated alias.

The client reports a bridge failure

The stable bridge-failure message intentionally hides raw upstream details. It can indicate a network failure, timeout, redirect, empty request response, unsupported content type, multiline or malformed body, or invalid JSON-RPC response.

Valid hosted JSON-RPC errors, including authentication and business errors, are relayed unchanged. Follow the error returned by the hosted MCP when one is available.

Check Context Repo status when hosted calls are unavailable. The package has no local or offline fallback.

The client shows a deprecation warning

Replace CONTEXT_REPO_API_KEY with CONTEXTREPO_API_KEY. If both variables are inherited from your environment, remove the deprecated alias after confirming the canonical variable is configured.

Development

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

The project uses ES modules and the built-in node:test runner. It has no runtime or development dependencies. Automated tests use injected fetch implementations or loopback HTTP servers and do not require a real API key or contact contextrepo.com.

Source layout:

• src/config.js validates environment configuration.
• src/index.js frames stdio input, dispatches work, and writes output.
• src/bridge.js sends each hosted request and validates its response.
• test/ covers configuration, transport, process behavior, and the packed npm artifact.

Migrating from v2

Version 3 replaced the duplicated local MCP implementation with this hosted stdio bridge. It therefore requires network access, and its MCP capabilities come from the hosted server.

• Rename CONTEXT_REPO_API_KEY to CONTEXTREPO_API_KEY.
• Replace the removed REST override CONTEXTREPO_API_URL with CONTEXTREPO_MCP_URL only for development or testing.
• Prefer the direct hosted OAuth connection when your MCP client supports it.

If you need a temporary v2 fallback while migrating, pin the last v2 release explicitly:

npx -y [email protected]

Links

• Context Repo
• Context Repo MCP documentation
• npm package
• Service status
• Model Context Protocol
• GitHub repository
• Issue tracker
• Support

License

MIT, see LICENSE.