py-code-org 0.1.0__tar.gz

py_code_org-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+data/
+dist/
+__pycache__/
+*.pyc
+.deploy.env

py_code_org-0.1.0/LICENSE

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

py_code_org-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: py-code-org
+Version: 0.1.0
+Summary: Find which PyPI packages use a module, function or class, from the command line or as an MCP server.
+Project-URL: Homepage, https://py-code.org
+Project-URL: Source, https://github.com/pypi-data/py-code
+Project-URL: Issues, https://github.com/pypi-data/py-code/issues
+Project-URL: Dataset, https://huggingface.co/datasets/pypi-data/py-code
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dependencies,mcp,pypi,reverse dependencies,static analysis,who uses
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# py-code-org
+
+Find which PyPI packages use a module, function or class, from the command line or from an AI
+coding tool. It reads the index behind [py-code.org](https://py-code.org), which covers the latest
+release of more than 335,000 PyPI projects (every project released in the last year, plus the
+most downloaded ones) and records every name their code imports or reaches by attribute.
+
+Use it before you rename or remove something in a library, to see who calls it and where.
+
+```
+$ uvx py-code-org who-uses httpx.AsyncClient --limit 3
+26,709 packages use httpx.AsyncClient (index built 2026-11-13)
+
+#  Package                  Version  Downloads/mo  Files  First use
+1  google-genai             3.2.0          124.9M      8  google/genai/_api_client.py:735
+2  google-cloud-aiplatform  2.9.0           70.8M      3  agentplatform/_genai/_runtimes_utils.py:1810
+3  sentry-sdk               2.75.0          66.7M      1  sentry_sdk/integrations/httpx.py:28
+
+Showing 3 of 26,709. --limit 0 shows the 2,000 most downloaded.
+
+Narrower names: httpx.AsyncClient.send (179), httpx.AsyncClient.__init__ (57), ...
+```
+
+It has no dependencies and needs Python 3.9 or newer.
+
+## Install
+
+```sh
+pipx install py-code-org     # or: uv tool install py-code-org
+```
+
+Or run it without installing: `uvx py-code-org who-uses requests.Session`.
+
+## Commands
+
+| Command | What it shows |
+|---|---|
+| `py-code who-uses NAME` | Packages that import or call `NAME`, most downloaded first, with the file and line of the first uses |
+| `py-code project NAME` | What a PyPI project imports, the modules it provides, and how many packages import it |
+| `py-code names MODULE` | Every indexed name under a top-level module and how many packages use each |
+| `py-code mcp` | Run as an MCP server over stdio |
+
+Options:
+
+- `who-uses --min-downloads N`: only packages with at least N downloads in the last 30 days.
+- `who-uses --limit N`, `names --limit N`: rows to show; `0` shows all.
+- `names --prefix numpy.linalg`: only names that start with the prefix.
+- `--json` on every lookup command prints JSON for scripts.
+
+Names are case-sensitive and written as the code imports them: `requests.Session`,
+`numpy.linalg.norm`, `PIL.Image`. When a name is not found, the tool suggests the closest
+indexed spelling. The exit code is 0 when found, 1 when not found and 2 when the index could not be
+reached.
+
+## Use it from an AI coding tool (MCP)
+
+The `mcp` command gives AI coding tools three read-only tools:
+
+- `who_uses(name, min_downloads, limit)`
+- `project_imports(project)`
+- `module_names(module, prefix, limit)`
+
+Claude Code:
+
+```sh
+claude mcp add py-code -- uvx py-code-org mcp
+```
+
+Cursor, Claude Desktop and other tools that read an `mcpServers` JSON file:
+
+```json
+{
+  "mcpServers": {
+    "py-code": { "command": "uvx", "args": ["py-code-org", "mcp"] }
+  }
+}
+```
+
+Then ask, for example: "Which popular packages call `requests.Session.merge_environment_settings`?"
+
+## Where the data comes from
+
+Every lookup is two small requests to the static JSON files at `https://data.py-code.org/api`: a
+manifest, then the shard that holds the name. Nothing is sent except the name you look up. The
+index is rebuilt monthly. Set `PY_CODE_API` to read a copy hosted elsewhere.
+
+What it misses: older releases, dynamic imports (`importlib.import_module`, `getattr`), names
+passed through variables, and files that do not parse as current Python. For bulk queries, the
+full tables are on Hugging Face as Parquet:
+[pypi-data/py-code](https://huggingface.co/datasets/pypi-data/py-code).
+
+The scanner that builds the index is in the same repository:
+[pypi-data/py-code](https://github.com/pypi-data/py-code).
+
+## Licence
+
+MIT.

py_code_org-0.1.0/README.md

@@ -0,0 +1,97 @@
+# py-code-org
+
+Find which PyPI packages use a module, function or class, from the command line or from an AI
+coding tool. It reads the index behind [py-code.org](https://py-code.org), which covers the latest
+release of more than 335,000 PyPI projects (every project released in the last year, plus the
+most downloaded ones) and records every name their code imports or reaches by attribute.
+
+Use it before you rename or remove something in a library, to see who calls it and where.
+
+```
+$ uvx py-code-org who-uses httpx.AsyncClient --limit 3
+26,709 packages use httpx.AsyncClient (index built 2026-11-13)
+
+#  Package                  Version  Downloads/mo  Files  First use
+1  google-genai             3.2.0          124.9M      8  google/genai/_api_client.py:735
+2  google-cloud-aiplatform  2.9.0           70.8M      3  agentplatform/_genai/_runtimes_utils.py:1810
+3  sentry-sdk               2.75.0          66.7M      1  sentry_sdk/integrations/httpx.py:28
+
+Showing 3 of 26,709. --limit 0 shows the 2,000 most downloaded.
+
+Narrower names: httpx.AsyncClient.send (179), httpx.AsyncClient.__init__ (57), ...
+```
+
+It has no dependencies and needs Python 3.9 or newer.
+
+## Install
+
+```sh
+pipx install py-code-org     # or: uv tool install py-code-org
+```
+
+Or run it without installing: `uvx py-code-org who-uses requests.Session`.
+
+## Commands
+
+| Command | What it shows |
+|---|---|
+| `py-code who-uses NAME` | Packages that import or call `NAME`, most downloaded first, with the file and line of the first uses |
+| `py-code project NAME` | What a PyPI project imports, the modules it provides, and how many packages import it |
+| `py-code names MODULE` | Every indexed name under a top-level module and how many packages use each |
+| `py-code mcp` | Run as an MCP server over stdio |
+
+Options:
+
+- `who-uses --min-downloads N`: only packages with at least N downloads in the last 30 days.
+- `who-uses --limit N`, `names --limit N`: rows to show; `0` shows all.
+- `names --prefix numpy.linalg`: only names that start with the prefix.
+- `--json` on every lookup command prints JSON for scripts.
+
+Names are case-sensitive and written as the code imports them: `requests.Session`,
+`numpy.linalg.norm`, `PIL.Image`. When a name is not found, the tool suggests the closest
+indexed spelling. The exit code is 0 when found, 1 when not found and 2 when the index could not be
+reached.
+
+## Use it from an AI coding tool (MCP)
+
+The `mcp` command gives AI coding tools three read-only tools:
+
+- `who_uses(name, min_downloads, limit)`
+- `project_imports(project)`
+- `module_names(module, prefix, limit)`
+
+Claude Code:
+
+```sh
+claude mcp add py-code -- uvx py-code-org mcp
+```
+
+Cursor, Claude Desktop and other tools that read an `mcpServers` JSON file:
+
+```json
+{
+  "mcpServers": {
+    "py-code": { "command": "uvx", "args": ["py-code-org", "mcp"] }
+  }
+}
+```
+
+Then ask, for example: "Which popular packages call `requests.Session.merge_environment_settings`?"
+
+## Where the data comes from
+
+Every lookup is two small requests to the static JSON files at `https://data.py-code.org/api`: a
+manifest, then the shard that holds the name. Nothing is sent except the name you look up. The
+index is rebuilt monthly. Set `PY_CODE_API` to read a copy hosted elsewhere.
+
+What it misses: older releases, dynamic imports (`importlib.import_module`, `getattr`), names
+passed through variables, and files that do not parse as current Python. For bulk queries, the
+full tables are on Hugging Face as Parquet:
+[pypi-data/py-code](https://huggingface.co/datasets/pypi-data/py-code).
+
+The scanner that builds the index is in the same repository:
+[pypi-data/py-code](https://github.com/pypi-data/py-code).
+
+## Licence
+
+MIT.

py_code_org-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "py-code-org"
+dynamic = ["version"]
+description = "Find which PyPI packages use a module, function or class, from the command line or as an MCP server."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["pypi", "dependencies", "reverse dependencies", "who uses", "mcp", "static analysis"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.urls]
+Homepage = "https://py-code.org"
+Source = "https://github.com/pypi-data/py-code"
+Issues = "https://github.com/pypi-data/py-code/issues"
+Dataset = "https://huggingface.co/datasets/pypi-data/py-code"
+
+[project.scripts]
+py-code = "py_code_org.cli:main"
+
+[tool.hatch.version]
+path = "src/py_code_org/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/py_code_org"]

py_code_org-0.1.0/src/py_code_org/__init__.py

@@ -0,0 +1,2 @@
+"""Command-line tool and MCP server for py-code.org: which PyPI packages use a module, function or class."""
+__version__ = "0.1.0"

py_code_org-0.1.0/src/py_code_org/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

py_code_org-0.1.0/src/py_code_org/api.py

@@ -0,0 +1,93 @@
+"""Read the static py-code.org index from data.py-code.org.
+
+The index is a set of JSON files sharded by CRC32 (zlib) of a name, so a lookup is two small
+GET requests: the manifest, then the shard that holds the name.
+"""
+import json
+import os
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+import zlib
+
+from . import __version__
+
+BASE = os.environ.get("PY_CODE_API", "https://data.py-code.org/api").rstrip("/")
+USER_AGENT = f"py-code-org/{__version__} (+https://py-code.org)"
+
+
+class ApiError(Exception):
+    pass
+
+
+class Index:
+    def __init__(self, base=BASE, timeout=30):
+        self.base = base
+        self.timeout = timeout
+        self._cache = {}
+
+    def get(self, path):
+        """Fetch one JSON file. Returns None when it does not exist."""
+        if path in self._cache:
+            return self._cache[path]
+        req = urllib.request.Request(self.base + path, headers={"User-Agent": USER_AGENT, "Accept": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                data = json.load(r)
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                data = None
+            else:
+                raise ApiError(f"{self.base}{path}: HTTP {e.code}") from e
+        except (urllib.error.URLError, OSError) as e:
+            raise ApiError(f"could not reach {self.base}: {getattr(e, 'reason', e)}") from e
+        self._cache[path] = data
+        return data
+
+    @property
+    def manifest(self):
+        m = self.get("/manifest.json")
+        if not m:
+            raise ApiError(f"{self.base}/manifest.json is missing")
+        return m
+
+    def name_shard(self, name):
+        """Path of the shard file that holds a dotted name such as requests.Session."""
+        m, top = self.manifest, name.split(".")[0]
+        if top in m["big"]:
+            return f"/big/{urllib.parse.quote(top)}/{crc32(name) % m['big'][top]}.json"
+        return f"/idx/{crc32(top) % m['idx_shards']:03x}.json"
+
+    def who_uses(self, name):
+        """{'total': int, 'rows': [[project, version, downloads_30d, files, [path:line, ...]], ...]} or None.
+
+        rows hold at most manifest['row_cap'] projects, sorted by downloads; total is the true count.
+        """
+        top = name.split(".")[0]
+        d = self.get(self.name_shard(name)) or {}
+        return d.get(name) if top in self.manifest["big"] else (d.get(top) or {}).get(name)
+
+    def names(self, module):
+        """[[name, projects], ...] for every indexed name under a top-level module, most used first."""
+        m = self.manifest
+        d = self.get(f"/names/{crc32(module) % m['idx_shards']:03x}.json") or {}
+        return d.get(module) or []
+
+    def project(self, name):
+        """One project's document: version, summary, downloads, imports, own modules, users. None if not indexed."""
+        k = norm(name)
+        d = self.get(f"/project/{crc32(k) % self.manifest['project_shards']:04x}.json") or {}
+        return d.get(k)
+
+    def status(self):
+        return self.get("/status.json") or {}
+
+
+def crc32(s):
+    return zlib.crc32(s.encode("utf-8"))
+
+
+def norm(name):
+    """PEP 503 normalized project name."""
+    return re.sub(r"[-_.]+", "-", name).lower()

py_code_org-0.1.0/src/py_code_org/cli.py

@@ -0,0 +1,146 @@
+"""py-code: which PyPI packages use a module, function or class.
+
+  py-code who-uses requests.Session
+  py-code project fastapi
+  py-code names httpx
+  py-code mcp            run as an MCP server over stdio
+"""
+import argparse
+import json
+import sys
+
+from . import __version__
+from .api import ApiError, Index
+from .queries import NotFound, module_names, project_imports, who_uses
+
+
+def human(n):
+    for size, unit in ((1e9, "B"), (1e6, "M"), (1e3, "K")):
+        if n >= size:
+            return f"{n / size:.1f}{unit}"
+    return str(n)
+
+
+def table(header, rows, right=()):
+    widths = [max(len(str(x)) for x in col) for col in zip(header, *rows)]
+    fmt = lambda row: "  ".join(  # noqa: E731
+        str(x).rjust(w) if i in right else str(x).ljust(w) for i, (x, w) in enumerate(zip(row, widths))
+    ).rstrip()
+    return "\n".join([fmt(header)] + [fmt(r) for r in rows])
+
+
+def print_who_uses(r):
+    n = r["total"]
+    print(f"{n:,} package{'s' if n != 1 else ''} use {r['name']}" + (f" (index built {r['index_built'][:10]})" if r["index_built"] else ""))
+    if r["min_downloads"]:
+        at_least = "" if r["matching_exact"] else "At least "
+        print(f"{at_least}{r['matching']:,} of them have {human(r['min_downloads'])} or more downloads a month")
+    if r["packages"]:
+        print()
+        rows = [
+            (i, p["project"], p["version"], human(p["downloads_30d"]), p["files"], p["locations"][0] if p["locations"] else "")
+            for i, p in enumerate(r["packages"], 1)
+        ]
+        print(table(("#", "Package", "Version", "Downloads/mo", "Files", "First use"), rows, right=(0, 3, 4)))
+    of = r["matching"] if r["min_downloads"] and r["matching_exact"] else r["total"]
+    if len(r["packages"]) < r["matching"]:
+        print(f"\nShowing {len(r['packages']):,} of {of:,}. --limit 0 shows " + (
+            f"all {r['matching']:,}." if r["matching"] == of else f"the {r['matching']:,} most downloaded."))
+    elif len(r["packages"]) < of:
+        print(f"\nThe index lists the {r['listed']:,} most downloaded of the {r['total']:,}.")
+    if r["narrower_names"]:
+        print("\nNarrower names: " + ", ".join(f"{x['name']} ({x['projects']:,})" for x in r["narrower_names"]))
+    print(f"\n{r['url']}")
+
+
+def print_project(p):
+    print(f"{p['project']} {p['version']}" + (f": {p['summary']}" if p["summary"] else ""))
+    lines = [
+        ("Downloads", f"{human(p['downloads_30d'])} in the last 30 days"),
+        ("Released", p["released"] or "unknown"),
+        ("Requires Python", p["requires_python"] or "not set"),
+        ("Indexed file", f"{p['file']} ({p['py_files']} .py files" + (f", {p['py_failed']} did not parse)" if p["py_failed"] else ")")),
+        ("Its modules", ", ".join(p["own_modules"]) or "none"),
+        ("Used by", ", ".join(f"{n:,} packages import {m}" for m, n in p["used_by"].items()) or "no indexed package"),
+        ("Third-party imports", ", ".join(p["third_party_imports"]) or "none"),
+        ("Stdlib imports", ", ".join(p["stdlib_imports"]) or "none"),
+    ]
+    if p["removed_or_deprecated_names"]:
+        lines.append(("Removed or deprecated", ", ".join(p["removed_or_deprecated_names"])))
+    if p["pth_files_with_import"]:
+        lines.append((".pth with import", ", ".join(p["pth_files_with_import"])))
+    w = max(len(k) for k, _ in lines)
+    print()
+    for k, v in lines:
+        print(f"{k.ljust(w)}  {v}")
+    print(f"\n{p['url']}")
+
+
+def print_names(r):
+    capped = " (the index keeps the 5,000 most used names per module)" if r["count"] >= 5000 and not r["prefix"] else ""
+    print(f"{r['count']:,} indexed names under {r['prefix'] or r['module']}{capped}\n")
+    print(table(("Name", "Packages"), [(x["name"], f"{x['projects']:,}") for x in r["names"]], right=(1,)))
+    if r["count"] > len(r["names"]):
+        print(f"\n{r['count'] - len(r['names']):,} more. Use --limit 0 to list all.")
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="py-code",
+        description="Which PyPI packages use a module, function or class. Data from https://py-code.org.",
+    )
+    ap.add_argument("--version", action="version", version=f"py-code-org {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True, metavar="command")
+
+    p = sub.add_parser("who-uses", help="packages that import or call a name, e.g. requests.Session")
+    p.add_argument("name", help="dotted name, case-sensitive: a module, function or class")
+    p.add_argument("--min-downloads", type=int, default=0, metavar="N", help="only packages with at least N downloads a month")
+    p.add_argument("--limit", type=int, default=20, help="rows to show, 0 for all (default 20)")
+    p.add_argument("--json", action="store_true", help="print JSON")
+
+    p = sub.add_parser("project", help="what a PyPI project imports and who uses it")
+    p.add_argument("name", help="PyPI project name")
+    p.add_argument("--json", action="store_true", help="print JSON")
+
+    p = sub.add_parser("names", help="indexed names under a top-level module, most used first")
+    p.add_argument("module", help="top-level module, e.g. numpy")
+    p.add_argument("--prefix", default="", help="only names that start with this, e.g. numpy.linalg")
+    p.add_argument("--limit", type=int, default=50, help="rows to show, 0 for all (default 50)")
+    p.add_argument("--json", action="store_true", help="print JSON")
+
+    sub.add_parser("mcp", help="run an MCP server over stdio for AI coding tools")
+
+    a = ap.parse_args(argv)
+    if a.cmd == "mcp":
+        from .mcp import serve
+
+        return serve()
+
+    index = Index()
+    try:
+        if a.cmd == "who-uses":
+            r, show = who_uses(index, a.name, a.min_downloads, a.limit), print_who_uses
+        elif a.cmd == "project":
+            r, show = project_imports(index, a.name), print_project
+        else:
+            r, show = module_names(index, a.module, a.prefix, a.limit), print_names
+    except NotFound as e:
+        if a.json:
+            print(json.dumps({"error": str(e), "did_you_mean": e.suggestions}, indent=2))
+        else:
+            print(e, file=sys.stderr)
+            if e.suggestions:
+                print("Did you mean: " + ", ".join(e.suggestions), file=sys.stderr)
+        return 1
+    except ApiError as e:
+        print(f"py-code: {e}", file=sys.stderr)
+        return 2
+    if a.json:
+        print(json.dumps(r, indent=2))
+    else:
+        show(r)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

py_code_org-0.1.0/src/py_code_org/mcp.py

@@ -0,0 +1,144 @@
+"""A minimal MCP server over stdio (newline-delimited JSON-RPC 2.0), with no dependencies.
+
+Tools: who_uses, project_imports, module_names. Each result is JSON text, plus structuredContent.
+"""
+import json
+import sys
+
+from . import __version__
+from .api import ApiError, Index
+from .queries import NotFound, module_names, project_imports, who_uses
+
+PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"]
+
+INSTRUCTIONS = (
+    "py-code.org indexes the code inside the latest release of every PyPI project released in the last "
+    "year (about 335,000 projects) and records which modules, functions and classes each one imports or "
+    "reaches by attribute. Use who_uses before changing or removing a public name in a library, to see "
+    "which packages call it and where. Names are case-sensitive and fully qualified as imported, e.g. "
+    "requests.Session or numpy.linalg.norm. If a name is not found, use module_names to find the exact spelling."
+)
+
+TOOLS = [
+    {
+        "name": "who_uses",
+        "title": "Who uses this name on PyPI",
+        "description": (
+            "List the PyPI packages whose latest release imports or calls a module, function or class, "
+            "most downloaded first, with the file and line of the first uses. Returns the true total, "
+            "names one level deeper, and suggestions when the name is not indexed."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Dotted name as imported, case-sensitive, e.g. requests.Session"},
+                "min_downloads": {"type": "integer", "minimum": 0, "default": 0, "description": "Only packages with at least this many downloads in 30 days"},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 20, "description": "Packages to return"},
+            },
+            "required": ["name"],
+        },
+        "annotations": {"readOnlyHint": True, "openWorldHint": True},
+    },
+    {
+        "name": "project_imports",
+        "title": "What a PyPI project imports",
+        "description": (
+            "For one PyPI project: its latest release, Requires-Python, downloads, the top-level modules it "
+            "provides, the third-party and standard-library modules it imports, how many indexed packages "
+            "import it, and names it uses that recent Python or NumPy versions removed or deprecated."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {"project": {"type": "string", "description": "PyPI project name, e.g. fastapi"}},
+            "required": ["project"],
+        },
+        "annotations": {"readOnlyHint": True, "openWorldHint": True},
+    },
+    {
+        "name": "module_names",
+        "title": "Names used under a module",
+        "description": (
+            "List the indexed names under a top-level module with the number of packages that use each, "
+            "most used first. Use it to find the exact spelling for who_uses or to see which parts of a "
+            "library people actually call."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "module": {"type": "string", "description": "Top-level import name, e.g. numpy"},
+                "prefix": {"type": "string", "default": "", "description": "Only names starting with this, e.g. numpy.linalg"},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 50},
+            },
+            "required": ["module"],
+        },
+        "annotations": {"readOnlyHint": True, "openWorldHint": True},
+    },
+]
+
+
+def call_tool(index, name, args):
+    if name == "who_uses":
+        return who_uses(index, args["name"], int(args.get("min_downloads") or 0), min(int(args.get("limit") or 20), 500))
+    if name == "project_imports":
+        return project_imports(index, args["project"])
+    if name == "module_names":
+        return module_names(index, args["module"], args.get("prefix") or "", min(int(args.get("limit") or 50), 1000))
+    raise KeyError(name)
+
+
+def tool_result(data, error=False):
+    return {"content": [{"type": "text", "text": json.dumps(data, indent=1)}], "structuredContent": data, "isError": error}
+
+
+def handle(index, msg):
+    """Return the response for one JSON-RPC message, or None for notifications."""
+    method, mid, params = msg.get("method"), msg.get("id"), msg.get("params") or {}
+    if mid is None:
+        return None
+    ok = lambda result: {"jsonrpc": "2.0", "id": mid, "result": result}  # noqa: E731
+    err = lambda code, text: {"jsonrpc": "2.0", "id": mid, "error": {"code": code, "message": text}}  # noqa: E731
+
+    if method == "initialize":
+        asked = params.get("protocolVersion")
+        return ok({
+            "protocolVersion": asked if asked in PROTOCOL_VERSIONS else PROTOCOL_VERSIONS[0],
+            "capabilities": {"tools": {"listChanged": False}},
+            "serverInfo": {"name": "py-code", "title": "py-code.org", "version": __version__},
+            "instructions": INSTRUCTIONS,
+        })
+    if method == "ping":
+        return ok({})
+    if method == "tools/list":
+        return ok({"tools": TOOLS})
+    if method == "tools/call":
+        name, args = params.get("name"), params.get("arguments") or {}
+        if name not in {t["name"] for t in TOOLS}:
+            return err(-32602, f"Unknown tool: {name}")
+        try:
+            return ok(tool_result(call_tool(index, name, args)))
+        except NotFound as e:
+            return ok(tool_result({"error": str(e), "did_you_mean": e.suggestions}, error=True))
+        except (KeyError, TypeError, ValueError) as e:
+            return ok(tool_result({"error": f"Missing or bad argument: {e}"}, error=True))
+        except ApiError as e:
+            return ok(tool_result({"error": str(e)}, error=True))
+    return err(-32601, f"Method not found: {method}")
+
+
+def serve(stdin=sys.stdin, stdout=sys.stdout):
+    index = Index()
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except ValueError:
+            resp = {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "Parse error"}}
+        else:
+            resp = handle(index, msg) if isinstance(msg, dict) else {
+                "jsonrpc": "2.0", "id": None, "error": {"code": -32600, "message": "Invalid request"}}
+        if resp is not None:
+            stdout.write(json.dumps(resp) + "\n")
+            stdout.flush()
+    return 0

py_code_org-0.1.0/src/py_code_org/queries.py

@@ -0,0 +1,112 @@
+"""Lookups shared by the command-line tool and the MCP server. Each returns plain JSON-ready dicts."""
+import difflib
+from urllib.parse import quote
+
+from .api import Index
+
+
+class NotFound(Exception):
+    def __init__(self, message, suggestions=()):
+        super().__init__(message)
+        self.suggestions = list(suggestions)
+
+
+def who_uses(index: Index, name, min_downloads=0, limit=20):
+    name = name.strip()
+    hit = index.who_uses(name)
+    if not hit:
+        raise NotFound(
+            f"No indexed package references {name}. Names are matched exactly and are case-sensitive.",
+            suggest_names(index, name),
+        )
+    rows = [r for r in hit["rows"] if r[2] >= min_downloads]
+    shown = rows if not limit else rows[:limit]
+    return {
+        "name": name,
+        "total": hit["total"],
+        "listed": len(hit["rows"]),
+        "matching": len(rows),
+        # rows are capped and sorted by downloads, so the count is exact when the cap was not hit
+        # or the last listed package is already below the threshold
+        "matching_exact": hit["total"] == len(hit["rows"]) or (bool(hit["rows"]) and hit["rows"][-1][2] < min_downloads),
+        "min_downloads": min_downloads,
+        "packages": [
+            {"project": r[0], "version": r[1], "downloads_30d": r[2], "files": r[3], "locations": r[4]}
+            for r in shown
+        ],
+        "narrower_names": narrower(index, name),
+        "url": f"https://py-code.org/search/?q={quote(name)}",
+        "index_built": index.status().get("built"),
+    }
+
+
+def project_imports(index: Index, name):
+    p = index.project(name.strip())
+    if not p:
+        raise NotFound(
+            f"{name} is not in the index. It covers the latest release of PyPI projects released in the last year."
+        )
+    return {
+        "project": p["name"],
+        "version": p["version"],
+        "summary": p.get("summary") or "",
+        "released": (p.get("upload_time") or "")[:10],
+        "requires_python": p.get("requires_python"),
+        "downloads_30d": p.get("downloads", 0),
+        "file": p.get("file"),
+        "py_files": p.get("py_files", 0),
+        "py_failed": p.get("py_failed", 0),
+        "own_modules": p.get("own_modules", []),
+        "third_party_imports": p.get("imports", {}).get("third_party", []),
+        "stdlib_imports": p.get("imports", {}).get("stdlib", []),
+        "used_by": p.get("used_by_module", {}),
+        "removed_or_deprecated_names": p.get("upgrade_hits", []),
+        "pth_files_with_import": p.get("pth_with_import", []),
+        "url": f"https://py-code.org/projects/view/?name={quote(p['key'])}",
+    }
+
+
+def module_names(index: Index, module, prefix="", limit=50):
+    module = module.strip().split(".")[0]
+    rows = [r for r in index.names(module) if not prefix or r[0].startswith(prefix)]
+    if not rows:
+        raise NotFound(f"No indexed package imports the module {module}.", suggest_modules(index, module))
+    shown = rows if not limit else rows[:limit]
+    return {"module": module, "prefix": prefix, "count": len(rows),
+            "names": [{"name": n, "projects": c} for n, c in shown]}
+
+
+def narrower(index, name, limit=15):
+    """Names one level below `name`, e.g. requests.Session.get under requests.Session."""
+    depth = name.count(".") + 1
+    return [
+        {"name": n, "projects": c}
+        for n, c in index.names(name.split(".")[0])
+        if n.startswith(name + ".") and n.count(".") == depth
+    ][:limit]
+
+
+def suggest_names(index, name, limit=5):
+    """Indexed names that match ignoring case, else the closest spellings under the same module."""
+    top = name.split(".")[0]
+    names = [n for n, _ in index.names(top)]
+    if not names:
+        rest = name[len(top):]
+        return [m + rest for m in suggest_modules(index, top) if index.who_uses(m + rest)] or suggest_modules(index, top)
+    low = name.lower()
+    same = [n for n in names if n.lower() == low]
+    if same:
+        return same[:limit]
+    by_lower = {}
+    for n in names:
+        by_lower.setdefault(n.lower(), n)
+    return [by_lower[n] for n in difflib.get_close_matches(low, list(by_lower), n=limit, cutoff=0.6)]
+
+
+def suggest_modules(index, module):
+    """Try common case variants of a top-level module name (Django vs django, PIL vs pil)."""
+    out = []
+    for v in dict.fromkeys([module.lower(), module.upper(), module.capitalize()]):
+        if v != module and index.names(v):
+            out.append(v)
+    return out

py_code_org-0.1.0/tests/test_client.py

@@ -0,0 +1,144 @@
+"""Offline tests: a fake index served from memory, laid out like data.py-code.org/api."""
+import io
+import json
+import sys
+import unittest
+import zlib
+from contextlib import redirect_stdout
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from py_code_org import api, cli, mcp, queries  # noqa: E402
+
+IDX, PROJ = 16, 32
+
+
+def crc(s):
+    return zlib.crc32(s.encode())
+
+
+def fake_files():
+    rows = [["big-user", "1.0", 5000, 2, ["a.py:1"]], ["small-user", "2.0", 10, 1, ["b.py:3"]]]
+    files = {
+        "/manifest.json": {"idx_shards": IDX, "project_shards": PROJ, "big": {"bigmod": 2}, "row_cap": 2},
+        "/status.json": {"built": "2026-11-13T13:11+00:00"},
+        f"/idx/{crc('requests') % IDX:03x}.json": {"requests": {
+            "requests.Session": {"total": 3, "rows": rows},
+        }},
+        f"/names/{crc('requests') % IDX:03x}.json": {"requests": [
+            ["requests", 10], ["requests.Session", 3], ["requests.Session.get", 2], ["requests.Session.get.x", 1]]},
+        f"/big/bigmod/{crc('bigmod.thing') % 2}.json": {"bigmod.thing": {"total": 1, "rows": rows[:1]}},
+        f"/project/{crc('my-pkg') % PROJ:04x}.json": {"my-pkg": {
+            "key": "my-pkg", "name": "My_Pkg", "version": "1.2", "summary": "s", "downloads": 7,
+            "file": "my_pkg-1.2.whl", "upload_time": "2026-01-02T00:00:00Z", "requires_python": ">=3.9",
+            "py_files": 3, "py_failed": 0, "own_modules": ["my_pkg"], "pth_with_import": [],
+            "imports": {"stdlib": ["os"], "third_party": ["requests"]}, "upgrade_hits": [],
+            "used_by_module": {"my_pkg": 4}, "primary_module": "my_pkg", "used_by": 4}},
+    }
+    return files
+
+
+class FakeIndex(api.Index):
+    def __init__(self):
+        super().__init__(base="https://example.invalid/api")
+        self.files = fake_files()
+
+    def get(self, path):
+        return self.files.get(path)
+
+
+class Lookups(unittest.TestCase):
+    def setUp(self):
+        self.index = FakeIndex()
+
+    def test_crc_matches_the_site(self):
+        # Values computed by the crc32 function in the site's app.js.
+        self.assertEqual(api.crc32("requests"), 2072368721)
+        self.assertEqual(api.crc32("numpy.linalg.norm"), 2828900854)
+        self.assertEqual(api.crc32("café.Ünïcode"), 3598506173)
+        self.assertEqual(api.norm("My_Pkg.Name"), "my-pkg-name")
+
+    def test_who_uses_small_module(self):
+        r = queries.who_uses(self.index, "requests.Session")
+        self.assertEqual(r["total"], 3)
+        self.assertEqual([p["project"] for p in r["packages"]], ["big-user", "small-user"])
+        self.assertEqual(r["narrower_names"], [{"name": "requests.Session.get", "projects": 2}])
+
+    def test_who_uses_big_module(self):
+        self.assertEqual(queries.who_uses(self.index, "bigmod.thing")["total"], 1)
+
+    def test_min_downloads_and_exactness(self):
+        r = queries.who_uses(self.index, "requests.Session", min_downloads=100)
+        self.assertEqual(r["matching"], 1)
+        self.assertTrue(r["matching_exact"])  # last listed row is below the threshold
+        r = queries.who_uses(self.index, "requests.Session", min_downloads=1)
+        self.assertFalse(r["matching_exact"])  # capped list, every row above the threshold
+
+    def test_not_found_suggests_case(self):
+        with self.assertRaises(queries.NotFound) as cm:
+            queries.who_uses(self.index, "requests.session")
+        self.assertIn("requests.Session", cm.exception.suggestions)
+
+    def test_project_by_any_spelling(self):
+        self.assertEqual(queries.project_imports(self.index, "MY.pkg")["project"], "My_Pkg")
+        with self.assertRaises(queries.NotFound):
+            queries.project_imports(self.index, "nope")
+
+
+class Cli(unittest.TestCase):
+    def run_cli(self, *argv):
+        out = io.StringIO()
+        orig = cli.Index
+        cli.Index = FakeIndex
+        try:
+            with redirect_stdout(out):
+                code = cli.main(list(argv))
+        finally:
+            cli.Index = orig
+        return code, out.getvalue()
+
+    def test_table_and_json(self):
+        code, out = self.run_cli("who-uses", "requests.Session", "--limit", "1")
+        self.assertEqual(code, 0)
+        self.assertIn("3 packages use requests.Session", out)
+        self.assertIn("Showing 1 of 3", out)
+        code, out = self.run_cli("project", "my-pkg", "--json")
+        self.assertEqual(json.loads(out)["third_party_imports"], ["requests"])
+
+    def test_not_found_exit_code(self):
+        code, out = self.run_cli("who-uses", "requests.session", "--json")
+        self.assertEqual(code, 1)
+        self.assertEqual(json.loads(out)["did_you_mean"], ["requests.Session"])
+
+
+class Mcp(unittest.TestCase):
+    def talk(self, *msgs):
+        orig = mcp.Index
+        mcp.Index = FakeIndex
+        out = io.StringIO()
+        try:
+            mcp.serve(io.StringIO("\n".join(json.dumps(m) for m in msgs) + "\n"), out)
+        finally:
+            mcp.Index = orig
+        return [json.loads(line) for line in out.getvalue().splitlines()]
+
+    def test_session(self):
+        replies = self.talk(
+            {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}},
+            {"jsonrpc": "2.0", "method": "notifications/initialized"},
+            {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
+            {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "who_uses", "arguments": {"name": "requests.Session"}}},
+            {"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "project_imports", "arguments": {"project": "zzz"}}},
+            {"jsonrpc": "2.0", "id": 5, "method": "unknown"},
+        )
+        self.assertEqual([r["id"] for r in replies], [1, 2, 3, 4, 5])
+        self.assertEqual(replies[0]["result"]["protocolVersion"], "2025-06-18")
+        self.assertEqual({t["name"] for t in replies[1]["result"]["tools"]}, {"who_uses", "project_imports", "module_names"})
+        self.assertEqual(replies[2]["result"]["structuredContent"]["total"], 3)
+        self.assertTrue(replies[3]["result"]["isError"])
+        self.assertEqual(replies[4]["error"]["code"], -32601)
+
+
+if __name__ == "__main__":
+    unittest.main()