serverdex 0.1.0__py3-none-any.whl

serverdex/__init__.py

@@ -0,0 +1,100 @@
+"""Serverdex — a tiny Python client for the Serverdex directory of MCP servers.
+
+Serverdex (https://serverdex.io) indexes the official Model Context Protocol
+registry: 60,000+ MCP servers, searchable, with install configs, GitHub signals
+and category rankings. This client wraps the public JSON API — no API key, no
+dependencies (standard library only).
+
+    import serverdex
+    serverdex.search("postgres", limit=5)
+    serverdex.get("io-github-ccxt-ccxt-mcp")
+    serverdex.categories()
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Optional
+
+__all__ = ["Client", "ServerdexError", "search", "get", "categories", "__version__"]
+__version__ = "0.1.0"
+
+_BASE = "https://serverdex.io/api/v1"
+_UA = f"serverdex-python/{__version__} (+https://serverdex.io)"
+
+
+class ServerdexError(RuntimeError):
+    """Raised when the Serverdex API returns an error or is unreachable."""
+
+
+class Client:
+    """Client for the Serverdex public API (https://serverdex.io).
+
+    All methods return plain Python dicts/lists parsed from the JSON API.
+    """
+
+    def __init__(self, base_url: str = _BASE, timeout: float = 20.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _get(self, path: str, params: Optional[dict] = None) -> Any:
+        url = self.base_url + path
+        if params:
+            clean = {k: v for k, v in params.items() if v is not None}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean)
+        req = urllib.request.Request(url, headers={"User-Agent": _UA, "Accept": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:  # pragma: no cover - network
+            raise ServerdexError(f"Serverdex API returned HTTP {exc.code} for {url}") from exc
+        except urllib.error.URLError as exc:  # pragma: no cover - network
+            raise ServerdexError(f"Could not reach the Serverdex API: {exc.reason}") from exc
+
+    def search(
+        self,
+        query: Optional[str] = None,
+        *,
+        category: Optional[str] = None,
+        sort: Optional[str] = None,
+        limit: int = 10,
+        page: int = 1,
+    ) -> list:
+        """Search MCP servers. Returns a list of server dicts.
+
+        query: words to search for (omit to browse). category: a category slug
+        (see categories()). sort: "new" (default), "name" or "stars".
+        """
+        data = self._get("/servers", {"q": query, "category": category, "sort": sort, "limit": limit, "page": page})
+        return data.get("data", [])
+
+    def get(self, slug: str) -> dict:
+        """Get everything about one server by slug (from a serverdex.io/server/<slug> URL)."""
+        data = self._get("/servers/" + urllib.parse.quote(slug, safe=""))
+        return data.get("data", {})
+
+    def categories(self) -> list:
+        """List the directory's categories with live server counts."""
+        data = self._get("/categories")
+        return data.get("data", [])
+
+
+_default = Client()
+
+
+def search(query: Optional[str] = None, **kwargs) -> list:
+    """Module-level shortcut for Client().search()."""
+    return _default.search(query, **kwargs)
+
+
+def get(slug: str) -> dict:
+    """Module-level shortcut for Client().get()."""
+    return _default.get(slug)
+
+
+def categories() -> list:
+    """Module-level shortcut for Client().categories()."""
+    return _default.categories()

serverdex-0.1.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: serverdex
+Version: 0.1.0
+Summary: Tiny Python client for Serverdex — search 60,000+ MCP servers from the official registry.
+Project-URL: Homepage, https://serverdex.io
+Project-URL: Documentation, https://serverdex.io/developers
+Project-URL: Source, https://github.com/hellolistifyai/serverdex-py
+Author-email: Serverdex <hello@serverdex.io>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,claude,cursor,directory,llm,mcp,model-context-protocol,serverdex
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# serverdex
+
+A tiny Python client for [Serverdex](https://serverdex.io) — the directory of Model Context Protocol (MCP) servers. Serverdex indexes 60,000+ MCP servers from the official registry, with install configs, GitHub signals and category rankings.
+
+No API key, no dependencies (standard library only).
+
+## Install
+
+```bash
+pip install serverdex
+```
+
+## Use
+
+```python
+import serverdex
+
+# Search the directory
+for s in serverdex.search("postgres", limit=5):
+    print(s["name"], "—", s["url"])
+
+# Filter by category and sort by stars
+serverdex.search(category="databases", sort="stars", limit=10)
+
+# Get one server by slug (from a serverdex.io/server/<slug> URL)
+server = serverdex.get("io-github-ccxt-ccxt-mcp")
+print(server["description"], server["repository_url"])
+
+# List categories with live server counts
+for c in serverdex.categories():
+    print(c["name"], c["servers"])
+```
+
+Or with an explicit client:
+
+```python
+from serverdex import Client
+
+client = Client()
+results = client.search("calendar", sort="new", limit=20)
+```
+
+## API
+
+- `search(query=None, *, category=None, sort=None, limit=10, page=1)` — list of server dicts.
+- `get(slug)` — one server's full details.
+- `categories()` — categories with live counts.
+
+Backed by the public Serverdex API at `https://serverdex.io/api/v1`. Browse the directory at [serverdex.io](https://serverdex.io).
+
+## License
+
+MIT

serverdex-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+serverdex/__init__.py,sha256=R02oeMsjrJcjiIMGZiE5P3mewWF4rhFvRmAgrOPD1wI,3592
+serverdex-0.1.0.dist-info/METADATA,sha256=u8YP3OO9iBiTdUpkt78EWsl4EYYxZPZw98IEUtNGS54,2253
+serverdex-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+serverdex-0.1.0.dist-info/licenses/LICENSE,sha256=lUUZ0nQirMVGhVZXoV5atVCJgtKwQ_g7Wp99HilGKlw,1066
+serverdex-0.1.0.dist-info/RECORD,,

serverdex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

serverdex-0.1.0.dist-info/licenses/LICENSE

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