AtlasRepo MCP
AtlasRepo MCP is a public, read-only connector that answers repository-selection questions from the AtlasRepo catalog — three bounded, schema-validated tools, no writes and no code execution.
atlasrepo_recommend— Describe a concrete engineering or content-production problem (query, 3–1000 chars, required) and optionally cap results withlimit(1–20, default 8) to get evidence-backed repository and workflow recommendations.atlasrepo_search_tools— Search the approved catalog of normalized open-source tools by free text (q, ≤300 chars),kind/category (≤100 chars) andminQuality(0–1); all filters optional.atlasrepo_get_repository— Fetch the AtlasRepo decision record and linked evidence for one GitHub repository by requiredownerandname(each 1–100 chars,^[A-Za-z0-9_.-]+$).Connect two ways — locally over stdio, or remotely via hosted Streamable HTTP at
https://mcp.atlasrepo.com/mcp(health:/readyz,/livez); one-command Codex plugin install is supported.Safety guarantees — every input is Zod-validated, upstream calls are timeout-bounded and responses truncated, host/origin allowlisting applies, and stdout stays protocol-clean.
Out of scope — no catalog ingestion, scoring, moderation, accounts, billing, database access, arbitrary URL fetching or repository execution.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AtlasRepo MCP Find evidence-backed projects for optimizing CI build times."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
Related MCP server: capalith
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 --> APITools
Tool | Input | Result |
| A bounded problem/use-case query | Evidence-backed repository recommendations |
| Search text and bounded filters | Matching tools from the approved catalog |
| 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
Install the AtlasRepo plugin for Codex with the same command shown in the AtlasRepo account:
codex plugin marketplace add Arnon-hs/atlasrepo-mcp && codex plugin add atlasrepo@atlasrepoThe plugin connects to the hosted Streamable HTTP service at https://mcp.atlasrepo.com/mcp. The public catalog tools are read-only; account quota and connected OAuth clients are shown in the AtlasRepo API connections panel.
Local development
npm ci
npm run check
npm test
npm run build
npm run readiness:store
node dist/index.jsHTTP service
PORT=8080 MCP_ALLOWED_HOSTS=localhost npm run start:httpVariable | Purpose |
| Upstream public API origin |
| Optional upstream key; keep secret |
| Bounded upstream timeout |
| HTTP listener port |
| Comma/space/semicolon-separated Host allowlist |
Use .env.example as the non-secret template. Never remove immutable or inherited Zeabur variables.
Verification, deployment and publishing
Every pull request runs secret-free hosted quality gates. After merge, the
trusted main workflow runs on one ephemeral JIT runner and performs:
Build and test - typecheck, tests, package smoke and dependency audit.
Image verification - build and inspect the production Docker image.
This repository does not deploy, migrate or probe production from its main
workflow. Production releases are owned by the pinned contract in
Arnon-hs/atlasrepo-schema/.github/workflows/release.yml,
which deploys services sequentially and verifies the release. 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 buildandnpm run smokepass.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.
The main JIT workflow built and inspected the MCP container image.
Any production release was initiated only from the Schema release contract.
License
MIT. See LICENSE.
Available Tools
3 toolsatlasrepo_get_repositoryGet AtlasRepo repository evidenceA
Load the AtlasRepo decision record and linked evidence for one GitHub repository.
Inputs: name (required), owner (required).
atlasrepo_recommendRecommend open-source solutionsA
Find evidence-backed repositories and workflows for a concrete engineering or content-production problem.
Inputs: query (required), limit.
atlasrepo_search_toolsSearch AtlasRepo toolsB
Search normalized open-source tools by text, kind, and quality threshold.
Inputs: q, kind, minQuality.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The tools are mostly distinct: atlasrepo_recommend is problem-driven, atlasrepo_search_tools is structured query-based, and atlasrepo_get_repository is a targeted detail fetch. However, recommend and search_tools could both return repositories/tools, so an agent might occasionally be unsure which path to use for discovery.
All tools share the atlasrepo_ prefix and use a verb-first style. atlasrepo_search_tools and atlasrepo_get_repository follow a clear verb_noun pattern, but atlasrepo_recommend lacks an object, creating a minor inconsistency.
Three tools is well-scoped for this domain: one for problem-level recommendation, one for structured search, and one for inspecting a specific repository record. Each tool covers a distinct part of the workflow without redundancy.
The read-only decision-record workflow is well covered: discover by problem, search by criteria, and load detailed evidence for a repository. Minor gaps include no explicit list-all/browse capability or a dedicated workflow-detail fetch, but these are workable through the existing tools.
Related MCP Connectors
Read-only CodeAtlas service catalog: list, get and search services. No authentication.
Read-only AgentiScript concept search, catalog, authenticity, license, and approved asset discovery.
Search and read the articles, videos, podcasts, PDFs and notes you saved in Recall. Read-only.
Read-only catalog of app-building materials: fonts, APIs, MCP servers, libraries, templates, data.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA deterministic, read-only MCP server that lets coding agents search Git-backed architecture decision records and retrieve decisions governing specific files. It includes rejected and superseded decisions, with no model, network, or write access.25Apache 2.0
- AlicenseBqualityCmaintenanceEnables read-only access to a local-first catalog of portable agent skills, exposing tools to discover ranked matches, inspect stored artifacts, traverse declared relationships, and view configuration.5MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to read-only query a self-hosted repository knowledge base, searching documents, source code, and symbols across GitHub and GitLab imports while retrieving source and dependency traces by commit and path.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables read-only access to generated technical documentation across one or multiple documented repositories, exposing tools to search code and docs, inspect modules and symbols, list gaps, review architecture, and check freshness with file#line citations.MIT