# MCP Capability Matchmaker

MCP Capability Matchmaker is an MCP gateway and an offline catalog CLI. The
gateway reads a trusted catalog, starts or connects to the configured upstream
MCP servers, discovers their live tools, and exposes those tools through one
stdio MCP endpoint. The CLI remains useful for importing, inspecting, and
ranking catalog metadata without connecting to any upstream.

## Gateway quick start

Install and build once:

```bash
npm install
npm run build
```

Configure an MCP client with the gateway entry point:

```json
{
  "mcpServers": {
    "capability-gateway": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-capability-matchmaker/dist/mcp-server.js",
        "--catalog",
        "/absolute/path/to/catalog.json"
      ]
    }
  }
}
```

The package also installs the equivalent executable alias
`mcp-capability-gateway` (the historical `mcp-capability-matchmaker` alias is
retained). For local development:

```bash
npm run dev:mcp -- --catalog examples/catalog.json
```

The gateway connects all configured upstreams in parallel. A healthy upstream
is still available when another one fails. Discovered tools are published as
`server__tool`; names are normalized and made unique when necessary. Calls to
those tools are forwarded to the original upstream tool with its JSON Schema,
annotations, output schema, and result content preserved.

When a connected upstream closes, the gateway removes its stale routes
immediately and reconnects with exponential backoff (1 second initially,
capped at 30 seconds). A successful reconnect republishes the live tools and
notifies downstream clients. Reconnect attempts and the next delay are visible
through `gateway__inspect_catalog`.

The gateway also exposes two built-in read-only tools:

| MCP tool | Purpose |
| --- | --- |
| `gateway__recommend_tools` | Recommend a small, explainable set from currently connected tools |
| `gateway__inspect_catalog` | Report configured upstreams, connection state, live tool counts, and metadata gaps |

The gateway uses stdio for its downstream interface. Upstreams may use either
stdio or Streamable HTTP. HTTP authentication belongs in `headers`. Every
`env` or `headers` value must be a complete `${ENV_VAR}` placeholder resolved
from the gateway process environment. Missing variables disable only the
affected upstream and are never returned in status or error messages.

## Catalog format

Catalog files use `version: 1`. `tools` is optional in the gateway workflow and
defaults to an empty array: live `tools/list` results are authoritative. Static
tools are still useful to the offline CLI for ranking and metadata review.

```json
{
  "version": 1,
  "servers": [
    {
      "name": "linear",
      "description": "Read and update Linear issues.",
      "transport": {
        "command": "npx",
        "args": ["-y", "@example/linear-mcp"],
        "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
      },
      "tools": []
    },
    {
      "name": "slack",
      "transport": {
        "url": "https://mcp.example.com/slack",
        "headers": { "Authorization": "${SLACK_AUTHORIZATION}" }
      },
      "tools": []
    }
  ]
}
```

Each transport is either stdio (`command`, optional `args` and `env`) or
Streamable HTTP (`url`, optional `headers`). Treat a catalog as executable
configuration: starting the gateway can execute local commands and make
network requests.

## Offline CLI

The `mcp-match` CLI never starts, connects to, or executes an MCP server. It
normalizes registry exports, checks metadata quality, and produces an
explainable tool recommendation.

```bash
node dist/cli.js index examples/registry-export.json --output catalog.json
node dist/cli.js inspect --catalog catalog.json
node dist/cli.js recommend \
  "Read Linear issue ENG-42, modify the GitHub repository, then notify Slack" \
  --catalog catalog.json
```

Commands:

| Command | Purpose |
| --- | --- |
| `mcp-match index <input>` | Normalize JSON/YAML catalog data from a file or URL |
| `mcp-match inspect -c <catalog>` | Report catalog size and metadata quality |
| `mcp-match recommend <task> -c <catalog>` | Select and explain a minimal tool set |

Output formats are `markdown`, `json`, `claude`, `cursor`, and `codex`.

## Runtime boundaries

- Only Tools are proxied in this release; Resources, Prompts, Sampling,
  Elicitation, and task-based execution are not gateway features.
- Gateway-level reconnect handles closed upstream connections. Initial startup
  failures remain isolated and require a gateway restart after configuration or
  credential fixes.
- The gateway downstream transport is stdio only; HTTP gateway serving,
  production authentication, auditing, and rate limiting are out of scope.
- A failed upstream is isolated and reported by the inspection tool. A failed
  refresh keeps its last known tool snapshot until the connection closes.

## Development

```bash
npm install
npm run check
```

MIT licensed. See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).