Metadata-Version: 2.4
Name: mcp-lookup
Version: 0.5.0
Summary: Lookup MCP servers in the official MCP Registry by name or URL.
Author-email: Sumit Badsara <sumit@unboundsecurity.ai>
License: MIT License
        
        Copyright (c) 2026 Unbound Security
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/websentry-ai/mcp-lookup
Project-URL: Repository, https://github.com/websentry-ai/mcp-lookup
Project-URL: Issues, https://github.com/websentry-ai/mcp-lookup/issues
Keywords: mcp,model-context-protocol,registry,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# mcp-lookup

Lookup MCP servers across the [official MCP Registry](https://registry.modelcontextprotocol.io), [Smithery](https://smithery.ai), and [PulseMCP](https://pulsemcp.com) from one CLI and Python library. Stdlib-only, no runtime dependencies.

## Why

Tools that need to enrich raw MCP server detections — e.g. a security dashboard that catalogs which MCP servers developers are running, an IDE assistant that needs canonical install metadata, or an SBOM pipeline — typically resort to HTML-scraping third-party catalogs because most registries don't expose a clean JSON API.

`mcp-lookup` wraps the three main MCP catalogs (`registry.modelcontextprotocol.io`, `api.smithery.ai`, and `api.pulsemcp.com`) behind a tiny, stable interface. It gives you:

- **Canonical server metadata** by name or repo URL: description, publisher namespace, version, packages (`npm`/`pypi`/`docker`), and remote transports (`stdio`/`sse`/`streamable-http`).
- **Three-source aggregation**: `search` fans out to all three sources **in parallel** and returns merged results, each labeled by `_source`. `get` prefers the registry (canonical), then falls back to Smithery, then PulseMCP.
- **Parallel search for low latency**: search latency is bounded by the slowest source (~1.2s) instead of the sum of all three (~5s). One slow or unavailable source never blocks the others.
- **Authoritative tool lists**: Smithery entries include the server's `tools[]` with input schemas, which the registry does not expose.
- **Community coverage**: PulseMCP adds GitHub star counts, package download counts, and long-tail community servers not (yet) in the official registry.
- **URL → name resolution**: hand it a `https://github.com/owner/repo` (or a vendor domain) and every source tries to find the matching entry.
- **Verified publisher signal for free**: registry namespace prefixes (`io.github.<user>/…`, `<domain>/…`) are cryptographically verified; Smithery entries carry a `verified` flag.
- **Icon derivation**: returns a usable icon URL for every server — Smithery's own `iconUrl` when available, GitHub owner avatars for repo-backed servers, DuckDuckGo favicons for vendor-hosted remotes.
- **Subprocess-friendly**: designed to be called from a backend service to replace fragile HTML scrapers. Outputs stable JSON with `--json`.

Typical callers:

- Dev-tool discovery agents that detect local MCP configs and want enrichment
- Security / DLP platforms classifying MCP servers by publisher and risk
- Registry-aware IDE extensions
- CI jobs validating MCP server manifests

## Install

```bash
pip install mcp-lookup
```

Or from source:

```bash
git clone <repo-url>
cd mcp-lookup
pip install -e .
```

## CLI

```bash
# Search across all three sources (in parallel)
mcp-lookup search github --limit 5
mcp-lookup search https://github.com/owner/repo
mcp-lookup search github --json                     # machine-readable

# Get a single record (registry → Smithery → PulseMCP fallback)
mcp-lookup get app.linear/linear --pretty
mcp-lookup get https://github.com/owner/repo --pretty
mcp-lookup get ai.smithery/<name> --version 1.2.3

# Restrict to one source
mcp-lookup --source registry search linear
mcp-lookup --source smithery get linear --pretty    # includes tools[] with descriptions
mcp-lookup --source pulsemcp search linear

# Icon derivation
mcp-lookup icon app.linear/linear
mcp-lookup get app.linear/linear --with-icon        # injects icon_url into JSON output
```

Exit codes: `0` success, `1` no results, `2` registry/network error.

## Library

```python
from mcp_lookup import (
    Aggregator,
    RegistryClient,
    SmitheryClient,
    PulseMCPClient,
    derive_icon_url,
)

# Combined (default) — parallel across all three sources
agg = Aggregator()
results = agg.search("linear", limit=5)
entry = agg.get("app.linear/linear")                # registry first, Smithery/PulseMCP fallback

# Single source
registry_only = agg.get("app.linear/linear", source="registry")
smithery_only = agg.get("linear", source="smithery")    # includes tools[] list
pulsemcp_only = agg.search("linear", source="pulsemcp")

# Direct clients
RegistryClient().get("app.linear/linear")
SmitheryClient().get("linear")
PulseMCPClient().search("linear", limit=3)

# Icon helper
icon_url = derive_icon_url(entry)
```

## Contributing

Contributions are very welcome — this is an open project and we'd love help from the MCP community.

Good first areas to contribute:

- Additional sources (`mcp.so`, Glama.ai, GitHub topic fallback) behind the existing provider interface
- Live `tools/list` probing so registry-only entries can return authoritative tool lists
- Local caching (SQLite or file-based) with TTL + `--refresh`
- Cross-source deduping by normalized repository URL
- Typed response schemas (Pydantic / JSON Schema) for enterprise consumers
- Tests and CI coverage

To contribute:

1. Fork the repo and create a feature branch.
2. Keep changes small and focused; match the existing stdlib-only style unless a dependency is strongly justified.
3. Open a pull request describing the motivation and include a quick before/after example where relevant.

Issues and feature requests are equally welcome — file them on GitHub.

## License

Released under the [MIT License](./LICENSE). By contributing, you agree that your contributions will be licensed under the same terms.
