mcp-repo-catalog
MCP server for discovering and exploring repositories across multiple git platforms. Supports Azure DevOps and GitHub simultaneously, with results aggregated from all configured providers.
Architecture
flowchart LR
Client["MCP Client<br/>(e.g. Claude Code)"]
subgraph Server["mcp-repo-catalog (stdio)"]
Tools["Tool handlers<br/>list, search, view,<br/>read, clone, sync, ..."]
Registry["Provider Registry"]
Cache[("In-memory cache<br/>TTL 5 min")]
Store[("Catalog store<br/>~/.config/.../catalog.json")]
Locator["Local repo locator"]
end
subgraph Providers["Provider implementations"]
ADO["Azure DevOps<br/>REST v7.1"]
GH["GitHub<br/>REST v3"]
end
subgraph External["External / filesystem"]
ADOAPI[("dev.azure.com")]
GHAPI[("api.github.com")]
LocalRepos[("Local clones<br/>$AZURE_DEVOPS_REPOS_PATH<br/>$GITHUB_REPOS_PATH")]
RemoteCat[("Optional remote catalog<br/>$CATALOG_REMOTE_REPO")]
end
Client <-->|JSON-RPC| Tools
Tools --> Registry
Tools --> Cache
Tools --> Store
Tools --> Locator
Registry --> ADO
Registry --> GH
ADO --> ADOAPI
GH --> GHAPI
Locator --> LocalRepos
Store -.->|sync_remote| RemoteCat
Request flow (example: read_from_repo)
sequenceDiagram
participant C as Client
participant H as read_from_repo handler
participant S as Catalog store
participant L as Local FS
participant P as Provider API
C->>H: {repo, path}
H->>S: Search(repo)
S-->>H: matched entry
alt entry has LocalPath
H->>L: read file from clone
L-->>H: content (source: local)
else not cloned
H->>P: GetFileContent(project, repo, path)
P-->>H: content (source: api)
end
H-->>C: file content + source
Tools
Always available:
| Tool | Description |
|---|
list_projects | List all projects/organizations across configured providers |
search_repositories | Search repositories by name, with local clone path when available |
get_repo_details | Detailed metadata for a repo (README, last commit, size) |
view_catalog | Show the local catalog grouped by provider |
read_from_repo | Read a file from any cloned repo (cross-repo lookup) |
clone_repository | Clone a repo into the configured local directory |
Mode-dependent:
| Tool | Mode | Description |
|---|
sync_remote | Remote | Pull a central catalog repo and map local paths |
sync_catalog | Local | Sync the catalog by querying provider APIs |
update_catalog_entry | Local | Edit a catalog entry locally |
The mode is determined by the CATALOG_REMOTE_REPO env var: when set, the server runs in remote mode (read-only catalog from a shared repo); otherwise it runs in local mode.
Installation
This repository ships in two layers: the MCP server (a Go binary) and a Claude Code plugin that bundles the server registration plus the enrich-catalog skill. You can install either independently.
Option 1 — Plugin (recommended for Claude Code users)
The plugin gives you the MCP server registration and the enrich-catalog skill in one install. You still need the binary on your $PATH (the plugin doesn't ship multi-platform binaries — see "Why no bundled binary" below).
Step 1. Install the binary.
go install github.com/heidiks/mcp-repo-catalog/cmd@latest
# or download a pre-built binary from https://github.com/heidiks/mcp-repo-catalog/releases
# and move it into a directory on $PATH (e.g. /usr/local/bin/)
Verify: mcp-repo-catalog --version should print the version.
Step 2. Add the marketplace and install the plugin.
In Claude Code:
/plugin marketplace add heidiks/mcp-repo-catalog
/plugin install mcp-repo-catalog@mcp-repo-catalog
Step 3. Set the credentials in your shell (the plugin's .mcp.json reads them from environment variables):
# ~/.zshrc or ~/.bashrc
export AZURE_DEVOPS_ORG=your-org
export AZURE_DEVOPS_TOKEN=...
export GITHUB_TOKEN=...
# optional
export AZURE_DEVOPS_REPOS_PATH=~/path/to/azure/repos
export GITHUB_REPOS_PATH=~/path/to/github/repos
Why no bundled binary: shipping pre-compiled binaries for linux/darwin/windows × amd64/arm64 inside the plugin would inflate the repo by ~40 MB per release and couple binary updates to the plugin release cadence. Goreleaser already publishes clean per-platform binaries via GitHub Releases, so the plugin defers to your $PATH. This is the same pattern used by language server plugins.
Option 2 — Standalone MCP server (no plugin)
If you don't use Claude Code or want to register the MCP yourself:
go install github.com/heidiks/mcp-repo-catalog/cmd@latest
Or build from source: