Skip to content

Registry

registry

registry.py — Query the official MCP Registry at registry.modelcontextprotocol.io

search_servers 

search_servers(query=None, limit=20)

Search the official MCP Registry. Returns list of unwrapped server dicts.

Source code in src/crux_cli/registry.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
def search_servers(query: str | None = None, limit: int = 20) -> list[dict[str, Any]]:
    """Search the official MCP Registry. Returns list of unwrapped server dicts."""
    params = {"limit": str(limit)}
    if query:
        params["q"] = query
    url = f"{REGISTRY_BASE}/servers?" + urllib.parse.urlencode(params)
    req = urllib.request.Request(url, headers={"Accept": "application/json", "User-Agent": "crux-cli/1.0"})  # noqa: S310
    try:
        with urllib.request.urlopen(req, timeout=10) as resp:  # noqa: S310
            data = json.loads(resp.read().decode())
            return [item["server"] for item in data.get("servers", []) if "server" in item]
    except urllib.error.URLError as e:
        raise RuntimeError(f"Registry unavailable: {e}") from e

get_server 

get_server(server_id)

Fetch full details for a specific server by ID.

Source code in src/crux_cli/registry.py 
29
30
31
32
33
34
35
36
37
38
def get_server(server_id: str) -> dict[str, Any]:
    """Fetch full details for a specific server by ID."""
    url = f"{REGISTRY_BASE}/servers/{urllib.parse.quote(server_id, safe='')}"
    req = urllib.request.Request(url, headers={"Accept": "application/json", "User-Agent": "crux-cli/1.0"})  # noqa: S310
    try:
        with urllib.request.urlopen(req, timeout=10) as resp:  # noqa: S310
            data = json.loads(resp.read().decode())
            return data.get("server", data)
    except urllib.error.URLError as e:
        raise RuntimeError(f"Registry unavailable: {e}") from e

display_name 

display_name(server)

Return the best human-readable name for display.

Source code in src/crux_cli/registry.py 
41
42
43
def display_name(server: dict[str, Any]) -> str:
    """Return the best human-readable name for display."""
    return server.get("title") or server.get("name") or ""

github_slug 

github_slug(server)

Extract 'owner/repo' from a server's repository URL, or None.

Source code in src/crux_cli/registry.py 
46
47
48
49
50
51
52
53
54
55
def github_slug(server: dict[str, Any]) -> str | None:
    """Extract 'owner/repo' from a server's repository URL, or None."""
    url = (server.get("repository") or {}).get("url", "")
    if "github.com/" in url:
        parts = url.rstrip("/").split("github.com/", 1)
        if len(parts) == 2:
            slug = parts[1].rstrip(".git")
            if slug.count("/") >= 1:
                return "/".join(slug.split("/")[:2])
    return None

best_package 

best_package(server)

Return (registry_name, package_name) for the most useful package, or (None, None).

Source code in src/crux_cli/registry.py 
58
59
60
61
62
63
64
65
66
67
68
def best_package(server: dict[str, Any]) -> tuple[str | None, str | None]:
    """Return (registry_name, package_name) for the most useful package, or (None, None)."""
    packages = server.get("packages") or []
    for preferred in ("npm", "pypi"):
        for pkg in packages:
            if pkg.get("registry_name") == preferred and pkg.get("name"):
                return preferred, pkg["name"]
    for pkg in packages:
        if pkg.get("name"):
            return pkg.get("registry_name", ""), pkg["name"]
    return None, None

remote_url 

remote_url(server)

Return the primary hosted remote URL, if any.

Source code in src/crux_cli/registry.py 
71
72
73
74
75
76
77
def remote_url(server: dict[str, Any]) -> str | None:
    """Return the primary hosted remote URL, if any."""
    remotes = server.get("remotes") or []
    for r in remotes:
        if r.get("url"):
            return r["url"]
    return None

suggest_crux_add 

suggest_crux_add(safe_name, server)

Return the best crux mcp add command string for a registry server, or None.

Source code in src/crux_cli/registry.py 
80
81
82
83
84
85
86
87
88
def suggest_crux_add(safe_name: str, server: dict[str, Any]) -> str | None:
    """Return the best `crux mcp add` command string for a registry server, or None."""
    reg, pkg = best_package(server)
    if reg == "npm":
        return f"crux mcp add {safe_name} --npx {pkg}"
    slug = github_slug(server)
    if slug:
        return f"crux mcp add {safe_name} --github {slug}"
    return None