sdcreader 4.0.0__tar.gz → 4.2.0__tar.gz

{sdcreader-4.0.0/src/sdcreader.egg-info → sdcreader-4.2.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: sdcreader
-Version: 4.0.0
-Summary: Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP).
+Version: 4.2.0
+Summary: Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP); MCP server included.
 Author: Axius SDC, Inc.
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/SemanticDataCharter/sdcreader
 Project-URL: Changelog, https://github.com/SemanticDataCharter/sdcreader/blob/main/CHANGELOG.md
-Keywords: sdc,semantic data charter,governed data record,cdif,dcat,dcat-ap,healthdcat-ap,fair
+Keywords: sdc,semantic data charter,governed data record,cdif,dcat,dcat-ap,healthdcat-ap,fair,mcp
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -17,15 +17,16 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: lxml>=5.0
+Requires-Dist: requests>=2.31
 Provides-Extra: fetch
-Requires-Dist: requests>=2.31; extra == "fetch"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: requests>=2.31; extra == "dev"
 Dynamic: license-file
 
 # sdcreader
 
+<!-- mcp-name: io.github.SemanticDataCharter/sdcreader -->
+
 Read a published Semantic Data Charter model's package for projection into other standards.
 
 A projection describes a model's governed data records in another standard's terms: CDIF, DCAT-US 3.0, DCAT-AP
@@ -35,8 +36,7 @@ any projection in it. The four projection writers (`sdc_cdif`, `sdc_dcat3_us`, `
 carried it as identical copies until this package.
 
 ```
-pip install sdcreader            # or, until the PyPI release: pip install "sdcreader @ git+https://github.com/SemanticDataCharter/sdcreader@v4.0.0"
-pip install "sdcreader[fetch]"   # with HTTP, to fetch a package from the public catalog
+pip install sdcreader            # the reader, with HTTP for fetching from the public catalog (since 4.1.0 no extra is needed)
 ```
 
 ```python
@@ -89,6 +89,29 @@ which is complete.
 - Constants: the leaf, numeric and quantified types; the predicate IRIs `IDENTIFIER`, `SOURCE`, `PUBLISHER`, `EXACT`,
   `CLOSE`, `SEE_ALSO`, `HAS_UNIT`; `DC_DEFAULTS`.
 
+## MCP server
+
+`sdcreader` is also an MCP server, registered as `io.github.SemanticDataCharter/sdcreader`, so an assistant can read a
+published model the way `sdcvalidator`, `sdcgovernance` and `sdcreceipt` let it validate, govern and settle a record.
+stdio, no SDK, no account, read-only.
+
+```
+uvx sdcreader                    # or: sdcreader-mcp, or python -m sdcreader.mcp_server
+uvx sdcreader --host https://your-sdcstudio.example   # a sovereign SDCStudio's public catalog
+```
+
+| Tool | Does |
+|---|---|
+| `find_models` | search the public catalog by text, or list a public project's models by name |
+| `describe_model` | one model: title, project, root record, leaf and component counts by type, Dublin Core with SDCStudio's defaults as null, the schema URL pinned to its SHA-256 |
+| `list_leaves` | the leaves in document order with path, type, constraints, code count and identity links, paged |
+| `list_codes` | one component's enumerated values with IRI, definition and code system |
+| `check_package` | the reader's integrity check on a package directory |
+
+Each tool takes a `ct_id` (fetched from the host the server was started with) or a package `directory` on disk.
+No tool takes a URL: the host is fixed at start, so a caller cannot point the server elsewhere. Every tool calls the
+same functions as the library; the two interfaces describe one model the same way.
+
 ## Tests
 
 ```
@@ -104,6 +127,6 @@ The fixture is the NHANES Participant package of the FAIR Data Demo, the record
 The leading 4 is the SDC4 reference model, as with every Semantic Data Charter package. An addition to what the
 reader exposes is a minor version, a fix a patch; the major changes only when the reference model does.
 
-## Licence
+## License
 
 Apache-2.0 (see `LICENSE`, `NOTICE`).

{sdcreader-4.0.0 → sdcreader-4.2.0}/README.md

@@ -1,5 +1,7 @@
 # sdcreader
 
+<!-- mcp-name: io.github.SemanticDataCharter/sdcreader -->
+
 Read a published Semantic Data Charter model's package for projection into other standards.
 
 A projection describes a model's governed data records in another standard's terms: CDIF, DCAT-US 3.0, DCAT-AP
@@ -9,8 +11,7 @@ any projection in it. The four projection writers (`sdc_cdif`, `sdc_dcat3_us`, `
 carried it as identical copies until this package.
 
 ```
-pip install sdcreader            # or, until the PyPI release: pip install "sdcreader @ git+https://github.com/SemanticDataCharter/sdcreader@v4.0.0"
-pip install "sdcreader[fetch]"   # with HTTP, to fetch a package from the public catalog
+pip install sdcreader            # the reader, with HTTP for fetching from the public catalog (since 4.1.0 no extra is needed)
 ```
 
 ```python
@@ -63,6 +64,29 @@ which is complete.
 - Constants: the leaf, numeric and quantified types; the predicate IRIs `IDENTIFIER`, `SOURCE`, `PUBLISHER`, `EXACT`,
   `CLOSE`, `SEE_ALSO`, `HAS_UNIT`; `DC_DEFAULTS`.
 
+## MCP server
+
+`sdcreader` is also an MCP server, registered as `io.github.SemanticDataCharter/sdcreader`, so an assistant can read a
+published model the way `sdcvalidator`, `sdcgovernance` and `sdcreceipt` let it validate, govern and settle a record.
+stdio, no SDK, no account, read-only.
+
+```
+uvx sdcreader                    # or: sdcreader-mcp, or python -m sdcreader.mcp_server
+uvx sdcreader --host https://your-sdcstudio.example   # a sovereign SDCStudio's public catalog
+```
+
+| Tool | Does |
+|---|---|
+| `find_models` | search the public catalog by text, or list a public project's models by name |
+| `describe_model` | one model: title, project, root record, leaf and component counts by type, Dublin Core with SDCStudio's defaults as null, the schema URL pinned to its SHA-256 |
+| `list_leaves` | the leaves in document order with path, type, constraints, code count and identity links, paged |
+| `list_codes` | one component's enumerated values with IRI, definition and code system |
+| `check_package` | the reader's integrity check on a package directory |
+
+Each tool takes a `ct_id` (fetched from the host the server was started with) or a package `directory` on disk.
+No tool takes a URL: the host is fixed at start, so a caller cannot point the server elsewhere. Every tool calls the
+same functions as the library; the two interfaces describe one model the same way.
+
 ## Tests
 
 ```
@@ -78,6 +102,6 @@ The fixture is the NHANES Participant package of the FAIR Data Demo, the record
 The leading 4 is the SDC4 reference model, as with every Semantic Data Charter package. An addition to what the
 reader exposes is a minor version, a fix a patch; the major changes only when the reference model does.
 
-## Licence
+## License
 
 Apache-2.0 (see `LICENSE`, `NOTICE`).

{sdcreader-4.0.0 → sdcreader-4.2.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sdcreader"
-version = "4.0.0"
-description = "Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP)."
+version = "4.2.0"
+description = "Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP); MCP server included."
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "Apache-2.0" }
 authors = [{ name = "Axius SDC, Inc." }]
-keywords = ["sdc", "semantic data charter", "governed data record", "cdif", "dcat", "dcat-ap", "healthdcat-ap", "fair"]
+keywords = ["sdc", "semantic data charter", "governed data record", "cdif", "dcat", "dcat-ap", "healthdcat-ap", "fair", "mcp"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -22,12 +22,21 @@ classifiers = [
 dependencies = [
     # the schema is read for the enumeration definitions and codes and the model's Dublin Core header
     "lxml>=5.0",
+    # fetching a package from SDCStudio's public catalog; a base dependency since 4.1.0 so that `uvx sdcreader`
+    # (the registry's launch) can search and fetch without an extra
+    "requests>=2.31",
 ]
 
 [project.optional-dependencies]
-# Fetching a package from SDCStudio's public catalog needs HTTP; a package already on disk does not.
-fetch = ["requests>=2.31"]
-dev = ["pytest>=8.0", "requests>=2.31"]
+# Kept so `sdcreader[fetch]` keeps installing; HTTP is in the base package since 4.1.0.
+fetch = []
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+# One package, two names over one implementation, matching the other SDC MCP servers: the bare name is what the
+# MCP registry launches (`uvx sdcreader`).
+sdcreader = "sdcreader.mcp_server:main"
+sdcreader-mcp = "sdcreader.mcp_server:main"
 
 [project.urls]
 Homepage = "https://github.com/SemanticDataCharter/sdcreader"

{sdcreader-4.0.0 → sdcreader-4.2.0}/src/sdcreader/__init__.py

@@ -12,7 +12,7 @@ from .model import (CLOSE, DC_DEFAULTS, EXACT, HAS_UNIT, IDENTIFIER, LEAF_TYPES,
                     SOURCE, Code, Component, Leaf, Model, enumeration_iri, read_header, read_model)
 from .package import DEFAULT_HOST, ModelPackage, PackageError, fetch_package, load_package
 
-__version__ = "4.0.0"
+__version__ = "4.2.0"
 __all__ = ["ModelPackage", "PackageError", "DEFAULT_HOST", "load_package", "fetch_package", "read_model", "read_header", "enumeration_iri",
            "Model", "Component", "Leaf", "Code", "LEAF_TYPES", "NUMERIC_TYPES", "QUANTIFIED_TYPES", "DC_DEFAULTS", "IDENTIFIER", "SOURCE",
            "PUBLISHER", "EXACT", "CLOSE", "SEE_ALSO", "HAS_UNIT", "__version__"]

sdcreader-4.2.0/src/sdcreader/mcp.py

@@ -0,0 +1,245 @@
+#
+# Copyright (c) 2026, Axius SDC, Inc.
+# Licensed under the Apache License, Version 2.0.
+#
+"""
+The MCP scaffold the SDC servers share: JSON-RPC 2.0 over stdio, one message
+per line, no SDK.
+
+`sdcvalidator`, `sdcgovernance`, `sdcreceipt` and `sdcreader` each carried this
+by hand. The four projection servers would have made eight copies, so it lives
+here once, as the reader itself does: `sdcreader` is the package every
+projection already depends on.
+
+What a server built on this gets, and must not re-implement:
+
+- `initialize` that negotiates rather than asserts: a client asking for a
+  revision in `SUPPORTED_PROTOCOL_VERSIONS` gets it echoed; anything else gets
+  the newest and decides for itself. 2026-07-28 removes the initialize
+  handshake and is a different architecture, so it is not claimed.
+- Tool failures as `isError` results (SEP-1303), never JSON-RPC errors, so the
+  calling model sees what went wrong and can correct itself. A `ToolError`
+  is the recoverable kind and travels with its message; anything else is a
+  defect and travels without its traceback.
+- `-32600` for a request or `params` that is not an object, `-32602` for
+  `arguments` that is not an object, `-32601` for an unknown method or tool,
+  `-32700` for a line that is not JSON.
+- `PackageCache`: the `ct_id`-or-`directory` source argument every reader-based
+  tool takes, resolved once per process. A published package is immutable, so
+  caching it for the life of the server is safe.
+
+No tool built on this may take a URL as an argument. The catalog host is fixed
+when the server starts, so a caller cannot point a server at an arbitrary host.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+from sdcreader.model import Model, read_model
+from sdcreader.package import DEFAULT_HOST, ModelPackage, PackageError, fetch_package, load_package
+
+JSONRPC_VERSION = "2.0"
+
+#: Newest revision this scaffold implements, and the set it negotiates.
+MCP_PROTOCOL_VERSION = "2025-11-25"
+SUPPORTED_PROTOCOL_VERSIONS = ("2025-06-18", "2025-11-25")
+
+__all__ = [
+    "JSONRPC_VERSION", "MCP_PROTOCOL_VERSION", "SUPPORTED_PROTOCOL_VERSIONS",
+    "ToolError", "Server", "PackageCache", "SOURCE_ARGS", "source_properties", "int_arg", "str_arg",
+]
+
+
+class ToolError(Exception):
+    """A tool failure the calling model can act on: bad input, or a package that does not hold up."""
+
+
+#: The source argument every reader-based tool takes: one model by identifier (fetched from the fixed host) or one
+#: package directory on disk, never both.
+SOURCE_ARGS = {
+    "ct_id": {
+        "type": "string",
+        "description": "The model's identifier (CUID2) in the public catalog; the package is fetched from the host this server was started with.",
+    },
+    "directory": {
+        "type": "string",
+        "description": "A package directory already on disk (dm-<ct>.jsonld and dm-<ct>.xsd, optionally catalog.json and versions.json). Give this or ct_id, not both.",
+    },
+}
+
+
+def source_properties(plural: bool = False) -> dict:
+    """The JSON Schema properties for the source argument; `plural` gives the list forms a multi-model catalog takes."""
+    if not plural:
+        return dict(SOURCE_ARGS)
+    return {
+        "ct_ids": {"type": "array", "items": {"type": "string"}, "minItems": 1,
+                   "description": "Model identifiers (CUID2) in the public catalog, fetched from the host this server was started with."},
+        "directories": {"type": "array", "items": {"type": "string"}, "minItems": 1,
+                        "description": "Package directories on disk. Give ct_ids or directories or both; at least one model."},
+    }
+
+
+def int_arg(args: dict[str, Any], name: str, default: int, lo: int, hi: int) -> int:
+    v = args.get(name, default)
+    if isinstance(v, bool) or not isinstance(v, int):
+        raise ToolError(f"`{name}` must be an integer.")
+    if v < lo or v > hi:
+        raise ToolError(f"`{name}` must be between {lo} and {hi}.")
+    return v
+
+
+def str_arg(args: dict[str, Any], name: str, default: str | None = None, required: bool = False) -> str | None:
+    v = args.get(name, default)
+    if v is None:
+        if required:
+            raise ToolError(f"`{name}` is required.")
+        return None
+    if not isinstance(v, str):
+        raise ToolError(f"`{name}` must be a string.")
+    return v
+
+
+class PackageCache:
+    """Packages fetched or loaded in this process, by source, read once."""
+
+    def __init__(self, host: str = DEFAULT_HOST, storage: dict | None = None, fetcher: Callable | None = None, loader: Callable | None = None):
+        self.host = host.rstrip("/")
+        self.storage: dict[str, tuple[ModelPackage, Model]] = storage if storage is not None else {}
+        # Injectable so a server module can expose `fetch_package` as its own patchable name for tests.
+        self.fetcher = fetcher or (lambda ct_id, host: fetch_package(ct_id, host=host))
+        self.loader = loader or (lambda directory, host: load_package(directory, host=host))
+
+    def get(self, ct_id: str | None = None, directory: str | None = None) -> tuple[ModelPackage, Model]:
+        if bool(ct_id) == bool(directory):
+            raise ToolError("Give exactly one of `ct_id` (fetched from the catalog) or `directory` (a package on disk).")
+        if ct_id is not None and not isinstance(ct_id, str):
+            raise ToolError("`ct_id` must be a string.")
+        if directory is not None and not isinstance(directory, str):
+            raise ToolError("`directory` must be a string path.")
+        key = ct_id or f"dir:{Path(directory).resolve()}"
+        if key in self.storage:
+            return self.storage[key]
+        try:
+            pkg = self.fetcher(ct_id, self.host) if ct_id else self.loader(directory, self.host)
+            model = read_model(pkg)
+        except PackageError as exc:
+            raise ToolError(str(exc)) from exc
+        except OSError as exc:
+            raise ToolError(f"Could not read the package: {exc}") from exc
+        self.storage[key] = (pkg, model)
+        return pkg, model
+
+    def one(self, args: dict[str, Any]) -> tuple[ModelPackage, Model]:
+        """The single source a tool's arguments name."""
+        return self.get(args.get("ct_id"), args.get("directory"))
+
+    def many(self, args: dict[str, Any]) -> list[tuple[ModelPackage, Model]]:
+        """Every source a multi-model tool's arguments name, in the order given, identifiers first."""
+        ct_ids = args.get("ct_ids") or []
+        dirs = args.get("directories") or []
+        if not isinstance(ct_ids, list) or not isinstance(dirs, list) or not all(isinstance(x, str) for x in ct_ids + dirs):
+            raise ToolError("`ct_ids` and `directories` must be arrays of strings.")
+        if not ct_ids and not dirs:
+            raise ToolError("Give at least one model in `ct_ids` or `directories`.")
+        return [self.get(ct_id=c) for c in ct_ids] + [self.get(directory=d) for d in dirs]
+
+
+class Server:
+    """One MCP server: a name, a version, its instructions, its tools and their handlers."""
+
+    def __init__(self, name: str, version: str, instructions: str, tools: list[dict],
+                 handlers: dict[str, Callable[[dict[str, Any]], Any]], issues_url: str):
+        if set(handlers) != {t["name"] for t in tools}:
+            raise ValueError("every tool needs a handler and every handler a tool")
+        self.name, self.version, self.instructions = name, version, instructions
+        self.tools, self.handlers, self.issues_url = tools, handlers, issues_url
+
+    @staticmethod
+    def _response(id: Any, result: Any) -> dict:
+        return {"jsonrpc": JSONRPC_VERSION, "id": id, "result": result}
+
+    @staticmethod
+    def _error(id: Any, code: int, message: str, data: Any = None) -> dict:
+        error = {"code": code, "message": message}
+        if data is not None:
+            error["data"] = data
+        return {"jsonrpc": JSONRPC_VERSION, "id": id, "error": error}
+
+    def _tool_error(self, id: Any, text: str) -> dict:
+        return self._response(id, {"content": [{"type": "text", "text": text}], "isError": True})
+
+    def handle(self, request: Any) -> dict | None:
+        """Handle one JSON-RPC 2.0 request. Returns a response, or None for a notification."""
+        if not isinstance(request, dict):
+            return self._error(None, -32600, "Invalid request: expected a JSON object.")
+        method = request.get("method", "")
+        params = request.get("params", {})
+        req_id = request.get("id")
+        if params is None:
+            params = {}
+        if not isinstance(params, dict):
+            return self._error(req_id, -32600, "Invalid request: `params` must be an object.")
+
+        if method == "initialize":
+            requested = params.get("protocolVersion")
+            negotiated = requested if requested in SUPPORTED_PROTOCOL_VERSIONS else MCP_PROTOCOL_VERSION
+            return self._response(req_id, {
+                "protocolVersion": negotiated,
+                "capabilities": {"tools": {"listChanged": False}},
+                "serverInfo": {"name": self.name, "version": self.version},
+                "instructions": self.instructions,
+            })
+        if method == "notifications/initialized":
+            return None
+        if method == "tools/list":
+            return self._response(req_id, {"tools": self.tools})
+        if method == "tools/call":
+            tool_name = params.get("name", "")
+            tool_args = params.get("arguments", {})
+            if tool_args is None:
+                tool_args = {}
+            if not isinstance(tool_args, dict):
+                return self._error(req_id, -32602, "Invalid params: `arguments` must be an object.")
+            handler = self.handlers.get(tool_name)
+            if handler is None:
+                return self._error(req_id, -32601, f"Unknown tool: {tool_name}")
+            try:
+                result = handler(tool_args)
+            except ToolError as exc:
+                return self._tool_error(req_id, f"Tool execution error: {exc}")
+            except Exception as exc:  # a defect in the server, reported without its traceback
+                return self._tool_error(req_id, (
+                    f"Tool execution error: the server could not process this input ({type(exc).__name__}). "
+                    f"This is a defect worth reporting at {self.issues_url}"))
+            if isinstance(result, str):
+                text = result
+            else:
+                text = json.dumps(result, default=str)
+            return self._response(req_id, {"content": [{"type": "text", "text": text}]})
+        if method == "ping":
+            return self._response(req_id, {})
+        if req_id is not None:
+            return self._error(req_id, -32601, f"Method not found: {method}")
+        return None
+
+    def run_stdio(self) -> None:
+        """One JSON-RPC message per line on stdin, one response per line on stdout."""
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                request = json.loads(line)
+            except json.JSONDecodeError as exc:
+                sys.stdout.write(json.dumps(self._error(None, -32700, f"Parse error: {exc}")) + "\n")
+                sys.stdout.flush()
+                continue
+            response = self.handle(request)
+            if response is not None:
+                sys.stdout.write(json.dumps(response) + "\n")
+                sys.stdout.flush()

sdcreader-4.2.0/src/sdcreader/mcp_server.py

@@ -0,0 +1,325 @@
+#
+# Copyright (c) 2026, Axius SDC, Inc.
+# Licensed under the Apache License, Version 2.0.
+#
+"""
+MCP stdio server for `sdcreader`.
+
+`sdcvalidator`, `sdcgovernance` and `sdcreceipt` are registered MCP servers, so
+an agent can validate a record, evaluate governance over it and settle it. It
+could not read the model those acts are about. This closes that gap: find a
+published model in the public catalog, read its record structure, its
+enumerated values with their codes and definitions, its Dublin Core as the
+modeler wrote it, and the pinned schema URL, with no account anywhere.
+
+**Five tools, read-only.** `find_models` searches the public catalog.
+`describe_model` summarizes one model. `list_leaves` walks its leaves in
+document order, paged, because a model can have more than a thousand.
+`list_codes` gives one component's enumerated values. `check_package` runs the
+reader's integrity check on a package directory.
+
+**No tool takes a URL.** The catalog host is fixed when the server starts
+(`--host`, default SDCStudio's public catalog), so a caller cannot point this
+server at an arbitrary host. A tool takes either a model identifier, fetched
+from that host, or a package directory already on disk.
+
+**A default is never reported as a fact.** Dublin Core comes through
+`Model.dc()`, so SDCStudio's field defaults ("Universal" coverage, "None"
+relation) come back as null rather than as what the modeler said.
+
+The protocol handling lives in `sdcreader.mcp`, shared with the projection
+servers. Reuse, do not reimplement: every tool calls the same functions the
+library exposes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdcreader import __version__
+from sdcreader.mcp import (MCP_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, PackageCache, Server, ToolError,
+                           int_arg, source_properties)
+from sdcreader.model import EXACT, IDENTIFIER, PUBLISHER, SEE_ALSO, SOURCE
+from sdcreader.package import DEFAULT_HOST, fetch_package  # noqa: F401  (fetch_package is patched by tests)
+
+__all__ = ["TOOLS", "TOOL_HANDLERS", "MCP_PROTOCOL_VERSION", "SUPPORTED_PROTOCOL_VERSIONS", "main", "run_stdio"]
+
+SERVER_NAME = "sdcreader"
+SERVER_VERSION = __version__
+ISSUES = "https://github.com/SemanticDataCharter/sdcreader/issues"
+
+#: Set once by `main()`, never from tool arguments.
+_HOST: str = DEFAULT_HOST
+#: The process-wide package cache's storage; a published package is immutable.
+_CACHE: dict = {}
+
+DEFAULT_PAGE = 50
+MAX_PAGE = 200
+DEFAULT_FIND = 20
+MAX_FIND = 100
+
+ReaderToolError = ToolError
+
+TOOLS = [
+    {
+        "name": "find_models",
+        "description": (
+            "Search SDCStudio's public catalog of published models by text, or list "
+            "the models of one public project by name. Needs no account. Returns "
+            "identifiers, titles and projects; pass an identifier to describe_model."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "search": {"type": "string", "description": "Text matched against title and description."},
+                "project": {"type": "string", "description": "A public project's exact name, for example NIH_CDE."},
+                "page": {"type": "integer", "minimum": 1, "default": 1},
+                "page_size": {"type": "integer", "minimum": 1, "maximum": MAX_FIND, "default": DEFAULT_FIND},
+            },
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "describe_model",
+        "description": (
+            "Describe one published model: title, description, project, the root "
+            "record, how many leaves and components it has and of which types, its "
+            "Dublin Core as the modeler wrote it (defaults reported as null), its "
+            "semantic links, and the schema URL pinned to the SHA-256 of the bytes "
+            "every record is validated against."
+        ),
+        "inputSchema": {"type": "object", "properties": source_properties(), "additionalProperties": False},
+    },
+    {
+        "name": "list_leaves",
+        "description": (
+            "The model's leaves in document order, each with its path of clusters, "
+            "its SDC4 type, its constraints, how many enumerated values it has and "
+            "its identity links. Paged: a model can have more than a thousand leaves."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                **source_properties(),
+                "offset": {"type": "integer", "minimum": 0, "default": 0},
+                "limit": {"type": "integer", "minimum": 1, "maximum": MAX_PAGE, "default": DEFAULT_PAGE},
+            },
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "list_codes",
+        "description": (
+            "The enumerated values of one component in a model: each value with the "
+            "IRI, definition and code system the published schema annotates it with."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                **source_properties(),
+                "component": {"type": "string", "description": "The component's identifier (ct_id), as list_leaves reports it."},
+            },
+            "required": ["component"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "check_package",
+        "description": (
+            "Run the reader's integrity check on a package directory: the JSON-LD "
+            "names the directory's model, it has components, the schema is an XML "
+            "Schema, and its bytes are the published current version when "
+            "versions.json is present. Returns the SHA-256 and the pinned schema URL."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {"directory": source_properties()["directory"]},
+            "required": ["directory"],
+            "additionalProperties": False,
+        },
+    },
+]
+
+
+def _cache() -> PackageCache:
+    # Built per call so a test that swaps `_HOST` or patches `fetch_package` on this module is honored; the storage
+    # dict is shared, so a package is still read once per process.
+    import sdcreader.mcp_server as me
+
+    return PackageCache(host=_HOST, storage=_CACHE, fetcher=lambda ct_id, host: me.fetch_package(ct_id, host=host))
+
+
+def _links(component) -> dict[str, list[str]]:
+    names = {IDENTIFIER: "identifier", SOURCE: "source", PUBLISHER: "publisher", EXACT: "exactMatch", SEE_ALSO: "seeAlso"}
+    return {short: list(component.links[pred]) for pred, short in names.items() if component.links.get(pred)}
+
+
+def _handle_find_models(args: dict[str, Any]) -> Any:
+    import requests
+
+    search = args.get("search", "")
+    project = args.get("project", "")
+    if not isinstance(search, str) or not isinstance(project, str):
+        raise ToolError("`search` and `project` must be strings.")
+    page = int_arg(args, "page", 1, 1, 10_000)
+    page_size = int_arg(args, "page_size", DEFAULT_FIND, 1, MAX_FIND)
+    params = {"format": "json", "page": page, "page_size": page_size}
+    if search:
+        params["search"] = search
+    if project:
+        params["project"] = project
+    try:
+        r = requests.get(f"{_HOST}/api/v1/catalog/dms/", params=params, timeout=60)
+    except requests.RequestException as exc:
+        raise ToolError(f"The catalog could not be reached: {exc}") from exc
+    if r.status_code != 200:
+        raise ToolError(f"The catalog answered HTTP {r.status_code}.")
+    data = r.json()
+    return {
+        "host": _HOST,
+        "count": data.get("count"),
+        "page": page,
+        "page_size": page_size,
+        "models": [
+            {"ct_id": m.get("ct_id"), "title": m.get("title"), "project": m.get("project_name"),
+             "description": (m.get("description") or "")[:300], "updated": m.get("updated")}
+            for m in data.get("results", [])
+        ],
+        "hint": "Pass a ct_id to describe_model. Models are listed only from public projects.",
+    }
+
+
+def _handle_describe_model(args: dict[str, Any]) -> Any:
+    pkg, model = _cache().one(args)
+    by_type: dict[str, int] = {}
+    for leaf in model.leaves:
+        by_type[leaf.component.sdc_type] = by_type.get(leaf.component.sdc_type, 0) + 1
+    dc_names = ("creator", "publisher", "date", "language", "coverage", "relation", "source", "type", "format", "identifier")
+    dublin_core = {name: model.dc(name) for name in dc_names}
+    dublin_core["contributors"] = model.contributors
+    dublin_core["subjects"] = model.subjects
+    dublin_core["rights_url"] = model.rights_url or None
+    dublin_core["rights_statement"] = model.rights_statement or None
+    return {
+        "ct_id": model.ct_id,
+        "title": model.title,
+        "description": model.description,
+        "project": pkg.catalog.get("project_name"),
+        "catalog_url": pkg.catalog_url,
+        "schema_url": pkg.schema_url,
+        "schema_sha256": pkg.sha256,
+        "schema_url_pinned": pkg.schema_url_pinned,
+        "schema_is_current": (pkg.versions.get("current_sha256") in (None, pkg.sha256)),
+        "root": {"ct_id": model.root.ct_id, "label": model.root.label, "description": model.root.description, "links": _links(model.root)},
+        "components": len(model.components),
+        "leaves": len(model.leaves),
+        "leaves_by_type": dict(sorted(by_type.items())),
+        "enumerated_components": sum(1 for v in model.codes.values() if v),
+        "dublin_core": dublin_core,
+        "hint": "Dublin Core values are what the modeler wrote; SDCStudio's defaults are reported as null, never as facts.",
+    }
+
+
+def _handle_list_leaves(args: dict[str, Any]) -> Any:
+    pkg, model = _cache().one(args)
+    offset = int_arg(args, "offset", 0, 0, 10_000_000)
+    limit = int_arg(args, "limit", DEFAULT_PAGE, 1, MAX_PAGE)
+    page = model.leaves[offset : offset + limit]
+    leaves = [
+        {
+            "position": leaf.position, "slug": leaf.slug, "ct_id": leaf.component.ct_id, "label": leaf.component.label,
+            "sdc_type": leaf.component.sdc_type, "data_type": leaf.component.data_type, "path": [p.label for p in leaf.path],
+            "description": leaf.component.description, "constraints": leaf.component.constraints,
+            "codes": len(model.codes.get(leaf.component.ct_id, [])), "links": _links(leaf.component),
+        }
+        for leaf in page
+    ]
+    return {
+        "ct_id": model.ct_id, "title": model.title, "total": len(model.leaves), "offset": offset, "limit": limit,
+        "returned": len(leaves), "next_offset": offset + limit if offset + limit < len(model.leaves) else None, "leaves": leaves,
+    }
+
+
+def _handle_list_codes(args: dict[str, Any]) -> Any:
+    pkg, model = _cache().one(args)
+    comp_id = args.get("component")
+    if not isinstance(comp_id, str) or not comp_id:
+        raise ToolError("`component` must be a component identifier (ct_id).")
+    comp = model.components.get(comp_id)
+    if comp is None:
+        raise ToolError(f"No component {comp_id!r} in model {model.ct_id}. list_leaves reports the identifiers.")
+    codes = model.codes.get(comp_id, [])
+    return {
+        "ct_id": model.ct_id,
+        "component": {"ct_id": comp.ct_id, "label": comp.label, "sdc_type": comp.sdc_type, "links": _links(comp)},
+        "count": len(codes),
+        "codes": [{"value": k.value, "iri": k.iri, "definition": k.definition, "defined_by": k.defined_by} for k in codes],
+        "hint": None if codes else "This component has no enumerated values in the published schema.",
+    }
+
+
+def _handle_check_package(args: dict[str, Any]) -> Any:
+    from sdcreader.package import PackageError, load_package
+
+    directory = args.get("directory")
+    if not isinstance(directory, str) or not directory:
+        raise ToolError("`directory` must be a string path.")
+    try:
+        pkg = load_package(directory, host=_HOST)
+    except PackageError as exc:
+        return {"ok": False, "directory": directory, "error": str(exc)}
+    except OSError as exc:
+        raise ToolError(f"Could not read the package: {exc}") from exc
+    return {
+        "ok": True, "directory": directory, "ct_id": pkg.ct_id, "schema_sha256": pkg.sha256,
+        "schema_url_pinned": pkg.schema_url_pinned, "published_current_sha256": pkg.versions.get("current_sha256"),
+        "versions_present": bool(pkg.versions), "catalog_present": bool(pkg.catalog),
+    }
+
+
+TOOL_HANDLERS = {
+    "find_models": _handle_find_models,
+    "describe_model": _handle_describe_model,
+    "list_leaves": _handle_list_leaves,
+    "list_codes": _handle_list_codes,
+    "check_package": _handle_check_package,
+}
+
+
+def _server() -> Server:
+    return Server(
+        name=SERVER_NAME, version=SERVER_VERSION, tools=TOOLS, handlers=TOOL_HANDLERS, issues_url=ISSUES,
+        instructions=(
+            "Read published Semantic Data Charter models. `find_models` searches "
+            f"the public catalog at {_HOST}; `describe_model`, `list_leaves` and "
+            "`list_codes` read one model by its ct_id from that host or from a "
+            "package directory on disk; `check_package` verifies a directory. "
+            "All tools are read-only and need no account. No tool takes a URL."
+        ),
+    )
+
+
+def _handle_request(request: Any) -> dict | None:
+    return _server().handle(request)
+
+
+def run_stdio() -> None:
+    _server().run_stdio()
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point for `sdcreader` and `sdcreader-mcp`."""
+    import argparse
+
+    global _HOST
+
+    parser = argparse.ArgumentParser(prog="sdcreader-mcp", description="MCP stdio server for reading published Semantic Data Charter models.")
+    parser.add_argument("--host", default=DEFAULT_HOST,
+                        help=f"The SDCStudio host whose public catalog is read, fixed here so a caller cannot redirect the server. Default {DEFAULT_HOST}.")
+    args = parser.parse_args(argv)
+    _HOST = args.host.rstrip("/")
+    run_stdio()
+
+
+if __name__ == "__main__":
+    main()

{sdcreader-4.0.0 → sdcreader-4.2.0/src/sdcreader.egg-info}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: sdcreader
-Version: 4.0.0
-Summary: Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP).
+Version: 4.2.0
+Summary: Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP); MCP server included.
 Author: Axius SDC, Inc.
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/SemanticDataCharter/sdcreader
 Project-URL: Changelog, https://github.com/SemanticDataCharter/sdcreader/blob/main/CHANGELOG.md
-Keywords: sdc,semantic data charter,governed data record,cdif,dcat,dcat-ap,healthdcat-ap,fair
+Keywords: sdc,semantic data charter,governed data record,cdif,dcat,dcat-ap,healthdcat-ap,fair,mcp
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -17,15 +17,16 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: lxml>=5.0
+Requires-Dist: requests>=2.31
 Provides-Extra: fetch
-Requires-Dist: requests>=2.31; extra == "fetch"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: requests>=2.31; extra == "dev"
 Dynamic: license-file
 
 # sdcreader
 
+<!-- mcp-name: io.github.SemanticDataCharter/sdcreader -->
+
 Read a published Semantic Data Charter model's package for projection into other standards.
 
 A projection describes a model's governed data records in another standard's terms: CDIF, DCAT-US 3.0, DCAT-AP
@@ -35,8 +36,7 @@ any projection in it. The four projection writers (`sdc_cdif`, `sdc_dcat3_us`, `
 carried it as identical copies until this package.
 
 ```
-pip install sdcreader            # or, until the PyPI release: pip install "sdcreader @ git+https://github.com/SemanticDataCharter/sdcreader@v4.0.0"
-pip install "sdcreader[fetch]"   # with HTTP, to fetch a package from the public catalog
+pip install sdcreader            # the reader, with HTTP for fetching from the public catalog (since 4.1.0 no extra is needed)
 ```
 
 ```python
@@ -89,6 +89,29 @@ which is complete.
 - Constants: the leaf, numeric and quantified types; the predicate IRIs `IDENTIFIER`, `SOURCE`, `PUBLISHER`, `EXACT`,
   `CLOSE`, `SEE_ALSO`, `HAS_UNIT`; `DC_DEFAULTS`.
 
+## MCP server
+
+`sdcreader` is also an MCP server, registered as `io.github.SemanticDataCharter/sdcreader`, so an assistant can read a
+published model the way `sdcvalidator`, `sdcgovernance` and `sdcreceipt` let it validate, govern and settle a record.
+stdio, no SDK, no account, read-only.
+
+```
+uvx sdcreader                    # or: sdcreader-mcp, or python -m sdcreader.mcp_server
+uvx sdcreader --host https://your-sdcstudio.example   # a sovereign SDCStudio's public catalog
+```
+
+| Tool | Does |
+|---|---|
+| `find_models` | search the public catalog by text, or list a public project's models by name |
+| `describe_model` | one model: title, project, root record, leaf and component counts by type, Dublin Core with SDCStudio's defaults as null, the schema URL pinned to its SHA-256 |
+| `list_leaves` | the leaves in document order with path, type, constraints, code count and identity links, paged |
+| `list_codes` | one component's enumerated values with IRI, definition and code system |
+| `check_package` | the reader's integrity check on a package directory |
+
+Each tool takes a `ct_id` (fetched from the host the server was started with) or a package `directory` on disk.
+No tool takes a URL: the host is fixed at start, so a caller cannot point the server elsewhere. Every tool calls the
+same functions as the library; the two interfaces describe one model the same way.
+
 ## Tests
 
 ```
@@ -104,6 +127,6 @@ The fixture is the NHANES Participant package of the FAIR Data Demo, the record
 The leading 4 is the SDC4 reference model, as with every Semantic Data Charter package. An addition to what the
 reader exposes is a minor version, a fix a patch; the major changes only when the reference model does.
 
-## Licence
+## License
 
 Apache-2.0 (see `LICENSE`, `NOTICE`).

{sdcreader-4.0.0 → sdcreader-4.2.0}/src/sdcreader.egg-info/SOURCES.txt

@@ -3,11 +3,16 @@ NOTICE
 README.md
 pyproject.toml
 src/sdcreader/__init__.py
+src/sdcreader/mcp.py
+src/sdcreader/mcp_server.py
 src/sdcreader/model.py
 src/sdcreader/package.py
 src/sdcreader.egg-info/PKG-INFO
 src/sdcreader.egg-info/SOURCES.txt
 src/sdcreader.egg-info/dependency_links.txt
+src/sdcreader.egg-info/entry_points.txt
 src/sdcreader.egg-info/requires.txt
 src/sdcreader.egg-info/top_level.txt
+tests/test_mcp_scaffold.py
+tests/test_mcp_server.py
 tests/test_reader.py

sdcreader-4.2.0/src/sdcreader.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+sdcreader = sdcreader.mcp_server:main
+sdcreader-mcp = sdcreader.mcp_server:main

{sdcreader-4.0.0 → sdcreader-4.2.0}/src/sdcreader.egg-info/requires.txt

@@ -1,8 +1,7 @@
 lxml>=5.0
+requests>=2.31
 
 [dev]
 pytest>=8.0
-requests>=2.31
 
 [fetch]
-requests>=2.31

sdcreader-4.2.0/tests/test_mcp_scaffold.py

@@ -0,0 +1,88 @@
+"""The shared MCP scaffold in sdcreader.mcp: protocol handling, tool errors, and the package cache."""
+from pathlib import Path
+
+import pytest
+
+from sdcreader.mcp import PackageCache, Server, ToolError, int_arg, source_properties, str_arg
+
+SAMPLE = Path(__file__).resolve().parents[1] / "samples" / "nhanes-participant"
+CT = "xy8upneajsb8vdcmnve01g6g"
+
+
+def make():
+    tools = [{"name": "echo", "description": "echo", "inputSchema": {"type": "object"}},
+             {"name": "boom", "description": "boom", "inputSchema": {"type": "object"}},
+             {"name": "defect", "description": "defect", "inputSchema": {"type": "object"}}]
+    handlers = {"echo": lambda a: {"got": a}, "boom": lambda a: (_ for _ in ()).throw(ToolError("bad input")),
+                "defect": lambda a: 1 / 0}
+    return Server("t", "0.0", "do things", tools, handlers, "https://example.org/issues")
+
+
+def test_a_server_needs_a_handler_per_tool_and_vice_versa():
+    with pytest.raises(ValueError):
+        Server("t", "0", "i", [{"name": "a", "description": "", "inputSchema": {}}], {}, "u")
+
+
+def test_initialize_negotiates_and_lists_tools():
+    s = make()
+    r = s.handle({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}})["result"]
+    assert r["protocolVersion"] == "2025-06-18" and r["serverInfo"] == {"name": "t", "version": "0.0"} and r["instructions"] == "do things"
+    r = s.handle({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "1999-01-01"}})["result"]
+    assert r["protocolVersion"] == "2025-11-25"
+    assert [t["name"] for t in s.handle({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})["result"]["tools"]] == ["echo", "boom", "defect"]
+    assert s.handle({"jsonrpc": "2.0", "method": "notifications/initialized"}) is None
+    assert s.handle({"jsonrpc": "2.0", "id": 3, "method": "ping"})["result"] == {}
+
+
+def test_tool_results_errors_and_defects():
+    s = make()
+    call = lambda n, a: s.handle({"jsonrpc": "2.0", "id": 9, "method": "tools/call", "params": {"name": n, "arguments": a}})["result"]
+    ok = call("echo", {"x": 1})
+    assert "isError" not in ok and ok["content"][0]["text"] == '{"got": {"x": 1}}'
+    bad = call("boom", {})
+    assert bad["isError"] is True and "bad input" in bad["content"][0]["text"]
+    defect = call("defect", {})
+    assert defect["isError"] is True and "ZeroDivisionError" in defect["content"][0]["text"] and "example.org/issues" in defect["content"][0]["text"]
+    assert "Traceback" not in defect["content"][0]["text"]
+
+
+def test_request_guards():
+    s = make()
+    assert s.handle(["x"])["error"]["code"] == -32600
+    assert s.handle({"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": "x"})["error"]["code"] == -32600
+    assert s.handle({"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "echo", "arguments": []}})["error"]["code"] == -32602
+    assert s.handle({"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "nope"}})["error"]["code"] == -32601
+    assert s.handle({"jsonrpc": "2.0", "id": 1, "method": "no/such"})["error"]["code"] == -32601
+    assert s.handle({"jsonrpc": "2.0", "method": "no/such"}) is None
+
+
+def test_package_cache_reads_once_and_resolves_singular_and_plural():
+    seen = []
+    cache = PackageCache(host="https://h.example", loader=lambda d, h: seen.append(d) or __import__("sdcreader").load_package(d, host=h))
+    pkg, model = cache.one({"directory": str(SAMPLE)})
+    assert model.ct_id == CT and pkg.host == "https://h.example"
+    cache.one({"directory": str(SAMPLE)})
+    assert len(seen) == 1 and len(cache.storage) == 1
+    both = cache.many({"directories": [str(SAMPLE)]})
+    assert len(both) == 1 and both[0][1].ct_id == CT
+    with pytest.raises(ToolError):
+        cache.one({})
+    with pytest.raises(ToolError):
+        cache.one({"ct_id": CT, "directory": str(SAMPLE)})
+    with pytest.raises(ToolError):
+        cache.many({})
+    with pytest.raises(ToolError):
+        cache.many({"ct_ids": "x"})
+
+
+def test_argument_helpers_and_source_schemas():
+    assert int_arg({"n": 3}, "n", 1, 1, 5) == 3 and int_arg({}, "n", 1, 1, 5) == 1
+    for bad in ({"n": "3"}, {"n": True}, {"n": 9}):
+        with pytest.raises(ToolError):
+            int_arg(bad, "n", 1, 1, 5)
+    assert str_arg({"s": "x"}, "s") == "x" and str_arg({}, "s") is None
+    with pytest.raises(ToolError):
+        str_arg({}, "s", required=True)
+    with pytest.raises(ToolError):
+        str_arg({"s": 1}, "s")
+    assert set(source_properties()) == {"ct_id", "directory"} and set(source_properties(plural=True)) == {"ct_ids", "directories"}

sdcreader-4.2.0/tests/test_mcp_server.py

@@ -0,0 +1,176 @@
+"""The MCP server: JSON-RPC 2.0 handling and the five read-only tools, offline against the NHANES fixture."""
+import json
+from pathlib import Path
+
+import pytest
+
+import sdcreader.mcp_server as srv
+from sdcreader.mcp_server import TOOLS, TOOL_HANDLERS, _handle_request
+
+SAMPLE = Path(__file__).resolve().parents[1] / "samples" / "nhanes-participant"
+CT = "xy8upneajsb8vdcmnve01g6g"
+
+
+def rpc(method, params=None, id=1):
+    req = {"jsonrpc": "2.0", "id": id, "method": method}
+    if params is not None:
+        req["params"] = params
+    return _handle_request(req)
+
+
+def call(name, arguments):
+    resp = rpc("tools/call", {"name": name, "arguments": arguments})
+    assert "result" in resp, resp
+    content = resp["result"]["content"]
+    assert len(content) == 1 and content[0]["type"] == "text"
+    return resp["result"], content[0]["text"]
+
+
+def call_ok(name, arguments):
+    result, text = call(name, arguments)
+    assert not result.get("isError"), text
+    return json.loads(text)
+
+
+def call_err(name, arguments):
+    result, text = call(name, arguments)
+    assert result.get("isError") is True, text
+    return text
+
+
+@pytest.fixture(autouse=True)
+def clear_cache():
+    srv._CACHE.clear()
+    yield
+    srv._CACHE.clear()
+
+
+class TestProtocol:
+    def test_initialize_negotiates_a_supported_revision(self):
+        r = rpc("initialize", {"protocolVersion": "2025-06-18"})["result"]
+        assert r["protocolVersion"] == "2025-06-18"
+        assert r["serverInfo"]["name"] == "sdcreader"
+        assert "tools" in r["capabilities"]
+        assert "No tool takes a URL" in r["instructions"]
+
+    def test_initialize_answers_newest_for_an_unknown_revision(self):
+        r = rpc("initialize", {"protocolVersion": "2024-11-05"})["result"]
+        assert r["protocolVersion"] == srv.MCP_PROTOCOL_VERSION
+
+    def test_initialized_notification_has_no_response(self):
+        assert _handle_request({"jsonrpc": "2.0", "method": "notifications/initialized"}) is None
+
+    def test_tools_list_names_the_five_tools_with_schemas(self):
+        tools = rpc("tools/list", {})["result"]["tools"]
+        assert {t["name"] for t in tools} == {"find_models", "describe_model", "list_leaves", "list_codes", "check_package"}
+        assert set(TOOL_HANDLERS) == {t["name"] for t in TOOLS}
+        for t in tools:
+            assert t["inputSchema"]["type"] == "object"
+            assert t["description"]
+
+    def test_unknown_tool_and_method_are_protocol_errors(self):
+        assert rpc("tools/call", {"name": "nope", "arguments": {}})["error"]["code"] == -32601
+        assert rpc("no/such", {})["error"]["code"] == -32601
+        assert _handle_request({"jsonrpc": "2.0", "method": "no/such"}) is None
+
+    def test_non_object_request_and_params_are_invalid_requests(self):
+        assert _handle_request(["not", "an", "object"])["error"]["code"] == -32600
+        assert rpc("tools/list", "x")["error"]["code"] == -32600
+        assert rpc("tools/call", {"name": "describe_model", "arguments": "x"})["error"]["code"] == -32602
+
+    def test_ping(self):
+        assert rpc("ping", {})["result"] == {}
+
+
+class TestTools:
+    def test_describe_model_from_a_directory(self):
+        d = call_ok("describe_model", {"directory": str(SAMPLE)})
+        assert d["ct_id"] == CT
+        assert d["title"] == "NHANES Participant"
+        assert d["leaves"] == 153 and d["components"] > d["leaves"]
+        assert d["schema_url_pinned"].startswith(f"https://sdcstudio.axius-sdc.com/dmlib/dm-{CT}.xsd?sha256=")
+        assert d["schema_is_current"] is True
+        assert sum(d["leaves_by_type"].values()) == 153
+        assert d["root"]["ct_id"] and d["root"]["label"]
+        # defaults are null, never facts
+        assert d["dublin_core"]["coverage"] is None or d["dublin_core"]["coverage"] != "Universal"
+        assert d["dublin_core"]["relation"] is None or d["dublin_core"]["relation"] != "None"
+
+    def test_list_leaves_pages_in_document_order(self):
+        first = call_ok("list_leaves", {"directory": str(SAMPLE), "limit": 10})
+        assert first["total"] == 153 and first["returned"] == 10 and first["next_offset"] == 10
+        assert [l["position"] for l in first["leaves"]] == list(range(10))
+        last = call_ok("list_leaves", {"directory": str(SAMPLE), "offset": 150, "limit": 10})
+        assert last["returned"] == 3 and last["next_offset"] is None
+        leaf = first["leaves"][0]
+        from sdcreader import LEAF_TYPES
+        assert leaf["slug"] and leaf["path"] and leaf["sdc_type"] in LEAF_TYPES
+        assert isinstance(leaf["codes"], int) and isinstance(leaf["links"], dict)
+
+    def test_list_codes_for_an_enumerated_component(self):
+        leaves = call_ok("list_leaves", {"directory": str(SAMPLE), "limit": 200})["leaves"]
+        coded = next(l for l in leaves if l["codes"] > 0)
+        c = call_ok("list_codes", {"directory": str(SAMPLE), "component": coded["ct_id"]})
+        assert c["count"] == coded["codes"] and c["component"]["ct_id"] == coded["ct_id"]
+        assert all(k["value"] and k["iri"].startswith("http") for k in c["codes"])
+
+    def test_list_codes_unknown_component_is_a_tool_error(self):
+        text = call_err("list_codes", {"directory": str(SAMPLE), "component": "nope"})
+        assert "No component" in text
+
+    def test_source_argument_rules(self):
+        assert "exactly one" in call_err("describe_model", {})
+        assert "exactly one" in call_err("describe_model", {"ct_id": CT, "directory": str(SAMPLE)})
+        assert "integer" in call_err("list_leaves", {"directory": str(SAMPLE), "limit": "ten"})
+        assert "between" in call_err("list_leaves", {"directory": str(SAMPLE), "limit": 10_000})
+
+    def test_check_package_ok_and_refusals(self, tmp_path):
+        ok = call_ok("check_package", {"directory": str(SAMPLE)})
+        assert ok["ok"] is True and ok["ct_id"] == CT and ok["versions_present"] is True
+        bad = call_ok("check_package", {"directory": str(tmp_path)})
+        assert bad["ok"] is False and "expected one dm-<ct>.xsd" in bad["error"]
+
+    def test_a_package_is_read_once_per_process(self):
+        call_ok("describe_model", {"directory": str(SAMPLE)})
+        call_ok("list_leaves", {"directory": str(SAMPLE)})
+        assert len(srv._CACHE) == 1
+
+    def test_find_models_queries_the_fixed_host(self, monkeypatch):
+        import requests
+
+        seen = {}
+
+        class R:
+            status_code = 200
+
+            def json(self):
+                return {"count": 1, "results": [{"ct_id": CT, "title": "NHANES Participant", "project_name": "FAIR Data Demo", "description": "x", "updated": "2026-01-01"}]}
+
+        def fake_get(url, params=None, timeout=None):
+            seen["url"], seen["params"] = url, params
+            return R()
+
+        monkeypatch.setattr(requests, "get", fake_get)
+        r = call_ok("find_models", {"search": "NHANES", "project": "FAIR Data Demo", "page_size": 5})
+        assert seen["url"] == f"{srv._HOST}/api/v1/catalog/dms/"
+        assert seen["params"]["search"] == "NHANES" and seen["params"]["project"] == "FAIR Data Demo" and seen["params"]["page_size"] == 5
+        assert r["count"] == 1 and r["models"][0]["ct_id"] == CT and r["models"][0]["project"] == "FAIR Data Demo"
+
+    def test_describe_model_by_ct_id_uses_fetch_package(self, monkeypatch):
+        from sdcreader import package as pkgmod
+
+        calls = []
+
+        def fake_fetch(ct_id, host=None, **kw):
+            calls.append((ct_id, host))
+            return pkgmod.load_package(SAMPLE, host=host)
+
+        monkeypatch.setattr(srv, "fetch_package", fake_fetch)
+        d = call_ok("describe_model", {"ct_id": CT})
+        assert d["ct_id"] == CT and calls == [(CT, srv._HOST)]
+
+
+@pytest.mark.network
+def test_find_models_against_production():
+    r = call_ok("find_models", {"project": "FAIR Data Demo", "page_size": 3})
+    assert r["count"] >= 1 and r["models"][0]["project"] == "FAIR Data Demo"