AtlasRepo MCP

<div align="center"> <img src="docs/images/atlasrepo-mark.svg" width="72" alt="AtlasRepo" /> <h1>AtlasRepo MCP</h1> <p><strong>A public, read-only MCP connector for evidence-backed repository decisions.</strong></p> <p><code>POST /mcp</code> · <a href="https://mcp.atlasrepo.com/readyz">Readiness</a> · <a href="https://mcp.atlasrepo.com/livez">Liveness</a> · <a href="README.ru.md">Русский</a></p> <a href="https://github.com/Arnon-hs/atlasrepo-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Arnon-hs/atlasrepo-mcp/actions/workflows/ci.yml/badge.svg" /></a> <a href="https://github.com/Arnon-hs/atlasrepo-mcp/actions/workflows/publish.yml"><img alt="Publish" src="https://github.com/Arnon-hs/atlasrepo-mcp/actions/workflows/publish.yml/badge.svg" /></a> <a href="https://www.npmjs.com/package/atlasrepo-mcp"><img alt="npm" src="https://img.shields.io/npm/v/atlasrepo-mcp" /></a> </div>

Purpose

AtlasRepo MCP adapts the public AtlasRepo catalog contract to Model Context Protocol clients. It supports local stdio and hosted Streamable HTTP, exposes three bounded read-only tools, and contains no private scoring, account or billing logic.

Owns	Does not own
MCP protocol, schemas and tool descriptions	Catalog ingestion, scoring or moderation
Bounded API client, timeouts and result truncation	Authentication, accounts or payments
stdio executable and Streamable HTTP endpoint	Web/Admin UI or database access
Origin/host validation and health endpoints	Arbitrary URL fetching or code execution

Architecture

flowchart LR
  Client["MCP client"] -->|"stdio"| Server["AtlasRepo MCP"]
  Remote["Remote MCP client"] -->|"Streamable HTTP /mcp"| Server
  Server --> Validate["Zod input validation"]
  Validate --> Tools{"Read-only tools"}
  Tools --> Recommend["atlasrepo_recommend"]
  Tools --> Search["atlasrepo_search_tools"]
  Tools --> Repo["atlasrepo_get_repository"]
  Recommend --> API["Public AtlasRepo API"]
  Search --> API
  Repo --> API

Tools

Tool	Input	Result
atlasrepo_recommend	A bounded problem/use-case query	Evidence-backed repository recommendations
atlasrepo_search_tools	Search text and bounded filters	Matching tools from the approved catalog
atlasrepo_get_repository	Repository owner and name	One repository evidence record

All inputs are schema-validated. Upstream calls have a timeout and responses are truncated to a safe maximum. The connector never executes discovered repositories.

Technology

Area	Choice
Language/runtime	TypeScript, Node.js 20+
Protocol	Model Context Protocol SDK
HTTP	Express 5, Streamable HTTP
Validation	Zod 4
Distribution	npm executable and Docker/Zeabur service

Install in one command

The public tools work through the anonymous free fallback. ATLASREPO_API_KEY is optional and should only be added through the client's environment when account limits or private features are needed.

Codex:

codex mcp add atlasrepo -- npx -y atlasrepo-mcp

Claude Code:

claude mcp add atlasrepo -- npx -y atlasrepo-mcp

Other stdio MCP clients can launch the published package with npx -y atlasrepo-mcp and the hosted Streamable HTTP endpoint is https://mcp.atlasrepo.com/mcp.

Full Codex plugin

The repository also ships a validated Codex plugin bundle. Add its marketplace once, then install the plugin:

codex plugin marketplace add Arnon-hs/atlasrepo-mcp && codex plugin add atlasrepo@atlasrepo

The plugin uses the same published npm executable. The first command is no longer needed after the AtlasRepo marketplace has been configured.

Generic MCP client configuration

{
  "mcpServers": {
    "atlasrepo": {
      "command": "npx",
      "args": ["-y", "atlasrepo-mcp"]
    }
  }
}

Local development

npm ci
npm run check
npm test
npm run build
node dist/index.js

HTTP service

PORT=8080 MCP_ALLOWED_HOSTS=localhost npm run start:http

Variable	Purpose
ATLASREPO_API_BASE_URL	Upstream public API origin
ATLASREPO_API_KEY	Optional upstream key; keep secret
ATLASREPO_REQUEST_TIMEOUT_MS	Bounded upstream timeout
PORT	HTTP listener port
MCP_ALLOWED_HOSTS	Comma/space/semicolon-separated Host allowlist

Use .env.example as the non-secret template. Never remove immutable or inherited Zeabur variables.

Deployment and publishing

Every pull request runs one five-stage service release:

1. Build — typecheck, tests, package smoke and Docker build.
2. Deploy — auto-merge after checks; Zeabur observes one main commit.
3. Migrations — explicit no-op; MCP owns no database schema.
4. Tests — /livez, /readyz, /mcp transport and read-only tool smoke.
5. Cache cleanup — targeted build/package cache cleanup.

Do not manually deploy the same merged commit. npm publication is separate: create a reviewed semantic-version tag and let the trusted-publishing workflow publish the package.

Engineering rules

• Preserve read-only behavior and bounded inputs, timeouts and result sizes.
• Keep stdout protocol-clean in stdio mode; diagnostics go to stderr without secrets.
• Never log API keys, authorization headers or full upstream payloads.
• Add schemas and tests with every tool/contract change.
• Conventional Commits: feat(mcp): ..., fix(http): ..., docs(mcp): ....

Pull request checklist

• [ ] npm run check, npm test, npm run build and npm run smoke pass.
• [ ] stdio stdout contains protocol messages only.
• [ ] HTTP host/origin protections and health contracts remain intact.
• [ ] No private Platform/Scout logic or write operation was added.
• [ ] One merge created one MCP service deployment.

License

MIT. See LICENSE.