# MCP Registry Navigator

Read-only MCP server for discovering, comparing, and auditing public servers
from the official Model Context Protocol Registry.

Serveur MCP en lecture seule pour decouvrir, comparer et auditer les serveurs
publics du registre officiel Model Context Protocol.

## Overview

MCP Registry Navigator helps agents and developers answer practical questions
before installing or publishing an MCP server:

- Which MCP server fits a task best?
- What package registry, transport, and install command does it use?
- Is a `server.json` file ready for registry publication?
- What checklist should be followed before publishing a PyPI, npm, or OCI MCP
  server?

The server does not edit user files. It returns structured reports, generated
configuration snippets, and review checklists that callers can inspect and apply
manually.

## Vue d'ensemble

MCP Registry Navigator aide les agents et les developpeurs a prendre de bonnes
decisions avant d'installer ou de publier un serveur MCP :

- Quel serveur MCP convient le mieux a une tache donnee ?
- Quel registre de package, transport et commande d'installation utilise-t-il ?
- Un fichier `server.json` est-il pret pour une publication dans le registre ?
- Quelle checklist suivre avant de publier un serveur MCP via PyPI, npm ou OCI ?

Le serveur ne modifie aucun fichier utilisateur. Il retourne des rapports
structures, des snippets de configuration et des checklists que l'appelant peut
relire puis appliquer manuellement.

## Features / Fonctionnalites

- Search latest servers from `https://registry.modelcontextprotocol.io`.
- Fetch a specific server by registry name and version.
- Compare server package types, transports, and descriptions.
- Validate `server.json` metadata before publication.
- Generate MCP client install snippets for PyPI, npm, and OCI packages.
- Prepare publication checklists for PyPI, npm, and OCI registry flows.
- Expose MCP tools, resources, and prompts through the official Python SDK v2.
- Use a local TTL JSON cache and deterministic test fixtures.

## MCP Primitives

### Tools

- `search_servers`
- `get_server`
- `compare_servers`
- `validate_server_json`
- `generate_install_config`
- `prepare_publish_checklist`

### Resources

- `registry://servers/{name}`
- `registry://latest`
- `registry://cache/status`

### Prompts

- `choose_mcp_server`
- `audit_mcp_metadata`
- `prepare_mcp_release`

## Requirements / Prerequis

- Python 3.12 or newer.
- [`uv`](https://docs.astral.sh/uv/) for local Python dependency management.
- Node.js 22.19.0 or newer only when using the MCP Inspector.

## Installation

From a local checkout:

```bash
uv sync
uv run mcp-registry-navigator --version
```

Depuis un clone local :

```bash
uv sync
uv run mcp-registry-navigator --version
```

## Usage

Run over stdio, the default transport for local MCP clients:

```bash
uv run mcp-registry-navigator
```

Lancer le serveur en stdio, le transport par defaut pour les clients MCP locaux :

```bash
uv run mcp-registry-navigator
```

Run as Streamable HTTP for local testing:

```bash
uv run mcp-registry-navigator --transport streamable-http --host 127.0.0.1 --port 8000
```

Lancer le serveur en Streamable HTTP pour les tests locaux :

```bash
uv run mcp-registry-navigator --transport streamable-http --host 127.0.0.1 --port 8000
```

Run the MCP Inspector:

```bash
npm install
npm run inspect
```

Lancer le MCP Inspector :

```bash
npm install
npm run inspect
```

This repository includes `.node-version` and `package.json` so local inspection
uses `@modelcontextprotocol/inspector` v2 instead of the deprecated v1 launcher
used by some `mcp dev` environments.

Ce depot inclut `.node-version` et `package.json` afin que l'inspection locale
utilise `@modelcontextprotocol/inspector` v2 au lieu de l'ancien lanceur v1
utilise par certains environnements `mcp dev`.

## Example Client Config

For a local checkout:

```json
{
  "mcpServers": {
    "mcp-registry-navigator": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-registry-navigator",
        "run",
        "mcp-registry-navigator"
      ]
    }
  }
}
```

After publishing to PyPI, the command can be simplified:

```json
{
  "mcpServers": {
    "mcp-registry-navigator": {
      "command": "uvx",
      "args": ["mcp-registry-navigator"]
    }
  }
}
```

## Development / Developpement

```bash
uv run python -m pytest -q
uv run ruff check .
uv run mypy
uv build
npm run inspect
```

The test suite uses fake registry responses for deterministic offline coverage.
The MCP integration tests use the SDK in-memory client and do not open ports.

La suite de tests utilise de fausses reponses du registre pour rester
deterministe et fonctionner hors ligne. Les tests d'integration MCP utilisent le
client en memoire du SDK et n'ouvrent pas de port reseau.

## Cache

The default cache file is:

```text
~/.cache/mcp-registry-navigator/registry-cache.json
```

Set `XDG_CACHE_HOME` to change the cache root. Use `NullCache` in tests or
embedding code when no disk writes are desired.

Le fichier de cache par defaut est :

```text
~/.cache/mcp-registry-navigator/registry-cache.json
```

Definissez `XDG_CACHE_HOME` pour changer la racine du cache. Utilisez
`NullCache` dans les tests ou dans du code embarque si aucune ecriture disque ne
doit etre effectuee.

## Repository Status / Etat du depot

This project is currently alpha software. APIs and generated recommendations may
change while the MCP Registry and Python SDK continue to evolve.

Ce projet est actuellement en phase alpha. Les APIs et les recommandations
generees peuvent changer pendant que le registre MCP et le SDK Python evoluent.

## Release Notes / Notes de publication

Before publishing to PyPI, add `[project.urls]` in `pyproject.toml` with the
real GitHub repository URL and issue tracker.

Avant une publication sur PyPI, ajoutez `[project.urls]` dans `pyproject.toml`
avec l'URL reelle du depot GitHub et le lien vers le suivi des issues.

If later publishing this server to the official MCP Registry as a PyPI package,
add the registry verification marker to this README:

```html
<!-- mcp-name: io.github.YOUR_GITHUB_USERNAME/mcp-registry-navigator -->
```

Si ce serveur est ensuite publie dans le registre MCP officiel comme package
PyPI, ajoutez le marqueur de verification ci-dessus dans ce README.

## License / Licence

MIT. See `LICENSE`.