mcp-repo-catalog

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: