mcp-advisor 0.1.0__tar.gz

mcp_advisor-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+.DS_Store

mcp_advisor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luca Stucchi
+
+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.

mcp_advisor-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: mcp-advisor
+Version: 0.1.0
+Summary: MCP server to browse, search, and discover MCP servers from the MCP Advisor registry
+Project-URL: Homepage, https://mcpadvisor.stucchi.consulting
+Project-URL: Repository, https://github.com/stucchi/mcp-advisor
+Project-URL: Issues, https://github.com/stucchi/mcp-advisor/issues
+Author-email: Luca Stucchi <luca.stucchi@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: advisor,mcp,model-context-protocol,registry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# MCP Advisor
+
+<!-- mcp-name: io.github.stucchi/mcp-advisor -->
+
+<p align="center">
+  <img src="assets/icon.png" alt="MCP Advisor" width="200">
+</p>
+
+An MCP server that lets your AI assistant browse, search, and discover MCP servers from the [MCP Advisor](https://mcpadvisor.stucchi.consulting) registry.
+
+## Installation
+
+```bash
+pip install mcp-advisor
+```
+
+## Usage
+
+### With Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-advisor": {
+      "command": "mcp-advisor"
+    }
+  }
+}
+```
+
+### With Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-advisor": {
+      "command": "mcp-advisor"
+    }
+  }
+}
+```
+
+### Standalone
+
+```bash
+mcp-advisor                          # stdio transport (default)
+mcp-advisor --transport sse          # SSE transport
+mcp-advisor --api-token YOUR_TOKEN   # authenticated (for starring)
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_servers` | Search MCP servers with filters (query, transport, registry type, tag, sort) |
+| `get_server_details` | Get full details about a specific server |
+| `get_install_instructions` | Get install config for Claude Desktop, Cursor, or generic |
+| `star_server` | Star a server (requires auth token) |
+| `unstar_server` | Remove a star (requires auth token) |
+| `list_starred_servers` | List your starred servers (requires auth token) |
+| `get_trending_servers` | Get trending servers by star count |
+| `get_registry_stats` | Get registry statistics |
+| `browse_tags` | List all tags with server counts |
+
+## License
+
+MIT - Luca Stucchi

mcp_advisor-0.1.0/README.md

@@ -0,0 +1,71 @@
+# MCP Advisor
+
+<!-- mcp-name: io.github.stucchi/mcp-advisor -->
+
+<p align="center">
+  <img src="assets/icon.png" alt="MCP Advisor" width="200">
+</p>
+
+An MCP server that lets your AI assistant browse, search, and discover MCP servers from the [MCP Advisor](https://mcpadvisor.stucchi.consulting) registry.
+
+## Installation
+
+```bash
+pip install mcp-advisor
+```
+
+## Usage
+
+### With Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-advisor": {
+      "command": "mcp-advisor"
+    }
+  }
+}
+```
+
+### With Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-advisor": {
+      "command": "mcp-advisor"
+    }
+  }
+}
+```
+
+### Standalone
+
+```bash
+mcp-advisor                          # stdio transport (default)
+mcp-advisor --transport sse          # SSE transport
+mcp-advisor --api-token YOUR_TOKEN   # authenticated (for starring)
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_servers` | Search MCP servers with filters (query, transport, registry type, tag, sort) |
+| `get_server_details` | Get full details about a specific server |
+| `get_install_instructions` | Get install config for Claude Desktop, Cursor, or generic |
+| `star_server` | Star a server (requires auth token) |
+| `unstar_server` | Remove a star (requires auth token) |
+| `list_starred_servers` | List your starred servers (requires auth token) |
+| `get_trending_servers` | Get trending servers by star count |
+| `get_registry_stats` | Get registry statistics |
+| `browse_tags` | List all tags with server counts |
+
+## License
+
+MIT - Luca Stucchi

mcp_advisor-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "mcp-advisor"
+version = "0.1.0"
+description = "MCP server to browse, search, and discover MCP servers from the MCP Advisor registry"
+requires-python = ">=3.11"
+license = "MIT"
+readme = "README.md"
+authors = [
+    {name = "Luca Stucchi", email = "luca.stucchi@gmail.com"},
+]
+keywords = ["mcp", "model-context-protocol", "registry", "advisor"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://mcpadvisor.stucchi.consulting"
+Repository = "https://github.com/stucchi/mcp-advisor"
+Issues = "https://github.com/stucchi/mcp-advisor/issues"
+
+[project.scripts]
+mcp-advisor = "mcp_advisor.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_advisor"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100

mcp_advisor-0.1.0/server.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.stucchi/mcp-advisor",
+  "title": "MCP Advisor",
+  "description": "Browse, search, and discover MCP servers from your AI assistant",
+  "repository": {
+    "url": "https://github.com/stucchi/mcp-advisor",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "websiteUrl": "https://mcpadvisor.stucchi.consulting",
+  "icons": [
+    {
+      "src": "https://raw.githubusercontent.com/stucchi/mcp-advisor/main/assets/icon.png",
+      "mimeType": "image/png",
+      "sizes": ["1024x1024"]
+    }
+  ],
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "mcp-advisor",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

mcp_advisor-0.1.0/src/mcp_advisor/__init__.py

@@ -0,0 +1,3 @@
+"""MCP Advisor — browse and discover MCP servers from your AI assistant."""
+
+__version__ = "0.1.0"

mcp_advisor-0.1.0/src/mcp_advisor/server.py

@@ -0,0 +1,56 @@
+"""MCP Advisor — browse and discover MCP servers from your AI assistant."""
+import argparse
+
+from mcp.server.fastmcp import FastMCP
+
+from mcp_advisor import tools
+
+
+def build_server(api_url: str, api_token: str | None = None) -> FastMCP:
+    """Create and return a configured FastMCP server instance."""
+    tools.configure(api_url, api_token)
+
+    mcp = FastMCP("MCP Advisor")
+
+    mcp.tool(name="search_servers")(tools.search_servers)
+    mcp.tool(name="get_server_details")(tools.get_server_details)
+    mcp.tool(name="get_install_instructions")(tools.get_install_instructions)
+    mcp.tool(name="star_server")(tools.star_server)
+    mcp.tool(name="unstar_server")(tools.unstar_server)
+    mcp.tool(name="list_starred_servers")(tools.list_starred_servers)
+    mcp.tool(name="get_trending_servers")(tools.get_trending_servers)
+    mcp.tool(name="get_registry_stats")(tools.get_registry_stats)
+    mcp.tool(name="browse_tags")(tools.browse_tags)
+
+    return mcp
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="mcp-advisor",
+        description="MCP server to browse, search, and discover MCP servers",
+    )
+    parser.add_argument(
+        "--api-url",
+        default="https://mcpadvisor.stucchi.consulting",
+        help="Base URL of the MCP Advisor API (default: https://mcpadvisor.stucchi.consulting)",
+    )
+    parser.add_argument(
+        "--api-token",
+        default=None,
+        help="JWT token for authenticated operations (star/unstar)",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse"],
+        default="stdio",
+        help="MCP transport (default: stdio)",
+    )
+    args = parser.parse_args()
+
+    mcp = build_server(args.api_url, args.api_token)
+    mcp.run(transport=args.transport)
+
+
+if __name__ == "__main__":
+    main()

mcp_advisor-0.1.0/src/mcp_advisor/tools.py

@@ -0,0 +1,177 @@
+"""MCP tool implementations — calls the MCP Advisor REST API over HTTP."""
+import httpx
+
+# Configured at startup via `configure()`
+_api_url: str = "https://mcpadvisor.stucchi.consulting"
+_api_token: str | None = None
+
+
+def configure(api_url: str, api_token: str | None = None):
+    global _api_url, _api_token
+    _api_url = api_url.rstrip("/")
+    _api_token = api_token
+
+
+def _headers() -> dict[str, str]:
+    h: dict[str, str] = {}
+    if _api_token:
+        h["Authorization"] = f"Bearer {_api_token}"
+    return h
+
+
+async def _get(path: str, params: dict | None = None) -> dict:
+    async with httpx.AsyncClient(timeout=15.0) as client:
+        resp = await client.get(
+            f"{_api_url}{path}", params=params, headers=_headers()
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def _post(path: str) -> dict:
+    async with httpx.AsyncClient(timeout=15.0) as client:
+        resp = await client.post(f"{_api_url}{path}", headers=_headers())
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def _delete(path: str) -> dict:
+    async with httpx.AsyncClient(timeout=15.0) as client:
+        resp = await client.delete(f"{_api_url}{path}", headers=_headers())
+        resp.raise_for_status()
+        return resp.json()
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+
+async def search_servers(
+    query: str | None = None,
+    transport: str | None = None,
+    registry_type: str | None = None,
+    tag: str | None = None,
+    sort: str = "stars",
+    limit: int = 10,
+) -> dict:
+    """Search for MCP servers with optional filters.
+
+    Args:
+        query: Free-text search query
+        transport: Filter by transport type (stdio, http, sse)
+        registry_type: Filter by package registry (npm, pypi, oci)
+        tag: Filter by tag name
+        sort: Sort by: stars, newest, updated, relevance
+        limit: Max results to return (1-50)
+    """
+    params: dict[str, str] = {"page_size": str(min(max(limit, 1), 50)), "sort": sort}
+    if query:
+        params["q"] = query
+    if transport:
+        params["transport"] = transport
+    if registry_type:
+        params["registry_type"] = registry_type
+    if tag:
+        params["tag"] = tag
+    return await _get("/api/v1/servers", params)
+
+
+async def get_server_details(name: str) -> dict:
+    """Get detailed information about a specific MCP server.
+
+    Args:
+        name: The server name (e.g., 'io.github.org/my-server')
+    """
+    return await _get(f"/api/v1/servers/{name}")
+
+
+async def get_install_instructions(
+    name: str, client: str = "claude-desktop"
+) -> dict:
+    """Get install instructions for an MCP server tailored to a specific client.
+
+    Args:
+        name: The server name
+        client: Target client: claude-desktop, cursor, or generic
+    """
+    detail = await _get(f"/api/v1/servers/{name}")
+
+    instructions = []
+    for pkg in detail.get("packages", []):
+        rt = pkg.get("registry_type", "")
+        tp = pkg.get("transport", "")
+        pkg_name = pkg.get("package_name") or name
+
+        if rt == "npm" and tp == "stdio":
+            config = {"mcpServers": {name: {"command": "npx", "args": ["-y", pkg_name]}}}
+        elif rt == "pypi" and tp == "stdio":
+            config = {"mcpServers": {name: {"command": "uvx", "args": [pkg_name]}}}
+        elif tp in ("http", "sse"):
+            instructions.append({
+                "type": client,
+                "description": f"Remote MCP server ({tp})",
+                "note": "Configure with the server URL provided by the operator",
+            })
+            continue
+        else:
+            continue
+
+        if client == "claude-desktop":
+            instructions.append({
+                "type": "claude-desktop",
+                "description": "Add to ~/Library/Application Support/Claude/claude_desktop_config.json",
+                "config": config,
+            })
+        elif client == "cursor":
+            instructions.append({
+                "type": "cursor",
+                "description": "Add to .cursor/mcp.json in your project root",
+                "config": config,
+            })
+        else:
+            instructions.append({"type": "generic", "config": config})
+
+    return {"server": name, "client": client, "instructions": instructions}
+
+
+async def star_server(name: str) -> dict:
+    """Star an MCP server (requires authentication via --api-token).
+
+    Args:
+        name: The server name to star
+    """
+    return await _post(f"/api/v1/servers/{name}/star")
+
+
+async def unstar_server(name: str) -> dict:
+    """Remove a star from an MCP server.
+
+    Args:
+        name: The server name to unstar
+    """
+    return await _delete(f"/api/v1/servers/{name}/star")
+
+
+async def list_starred_servers() -> dict:
+    """List your starred MCP servers (requires authentication via --api-token)."""
+    return await _get("/api/v1/me/stars")
+
+
+async def get_trending_servers(limit: int = 10) -> dict:
+    """Get trending MCP servers sorted by star count and recent activity.
+
+    Args:
+        limit: Max results (1-50)
+    """
+    return await _get("/api/v1/servers/trending", {"limit": str(min(max(limit, 1), 50))})
+
+
+async def get_registry_stats() -> dict:
+    """Get overall statistics about the MCP server registry."""
+    return await _get("/api/v1/stats")
+
+
+async def browse_tags() -> dict:
+    """List all available tags with their server counts."""
+    return await _get("/api/v1/tags")