serverdex 0.1.0__tar.gz

serverdex-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+# Publishes the package to PyPI when you cut a GitHub Release.
+# Uses PyPI Trusted Publishing (OIDC) — no API token/secret needed.
+# One-time setup on PyPI: pypi.org -> your account -> Publishing ->
+# "Add a pending publisher": project "serverdex", owner "hellolistifyai",
+# repo "serverdex-py", workflow "publish.yml", environment "pypi".
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

serverdex-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc

serverdex-0.1.0/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.

serverdex-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,53 @@
+# 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/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "serverdex"
+version = "0.1.0"
+description = "Tiny Python client for Serverdex — search 60,000+ MCP servers from the official registry."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Serverdex", email = "hello@serverdex.io" }]
+keywords = ["mcp", "model-context-protocol", "serverdex", "directory", "ai", "llm", "claude", "cursor", "agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://serverdex.io"
+Documentation = "https://serverdex.io/developers"
+Source = "https://github.com/hellolistifyai/serverdex-py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/serverdex"]

serverdex-0.1.0/src/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()