sdcreader 4.0.0__tar.gz → 4.1.0__tar.gz

{sdcreader-4.0.0/src/sdcreader.egg-info → sdcreader-4.1.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.1.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.1.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.1.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.1.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.1.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.1.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.1.0/src/sdcreader/mcp_server.py

@@ -0,0 +1,496 @@
+#
+# 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.
+
+Reuse, do not reimplement: every tool calls the same functions the library
+exposes. If the two interfaces ever describe one model differently, the
+product is broken.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from sdcreader import __version__
+from sdcreader.model import EXACT, IDENTIFIER, PUBLISHER, SEE_ALSO, SOURCE, Model, read_model
+from sdcreader.package import DEFAULT_HOST, ModelPackage, PackageError, fetch_package, load_package
+
+JSONRPC_VERSION = "2.0"
+
+#: Newest revision this server implements. `initialize` negotiates rather than
+#: asserting, so a client on an older supported revision is honored. The
+#: 2026-07-28 revision removes the initialize handshake and is not claimed.
+MCP_PROTOCOL_VERSION = "2025-11-25"
+SUPPORTED_PROTOCOL_VERSIONS = ("2025-06-18", "2025-11-25")
+
+SERVER_NAME = "sdcreader"
+SERVER_VERSION = __version__
+
+#: Set once by `main()`, never from tool arguments.
+_HOST: str = DEFAULT_HOST
+
+#: Packages fetched or loaded in this process, by model identifier. A model's
+#: package is immutable once published, so caching it for the life of the
+#: server is safe and keeps a paged walk from re-fetching four files per page.
+_CACHE: dict[str, tuple[ModelPackage, Model]] = {}
+
+DEFAULT_PAGE = 50
+MAX_PAGE = 200
+DEFAULT_FIND = 20
+MAX_FIND = 100
+
+
+class ReaderToolError(Exception):
+    """A tool failure the calling model can act on: bad input, or a package that does not hold up."""
+
+
+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.",
+    },
+}
+
+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": dict(SOURCE_ARGS), "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_ARGS,
+                "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_ARGS,
+                "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_ARGS["directory"]},
+            "required": ["directory"],
+            "additionalProperties": False,
+        },
+    },
+]
+
+
+def _package(args: dict[str, Any]) -> tuple[ModelPackage, Model]:
+    ct_id = args.get("ct_id")
+    directory = args.get("directory")
+    if bool(ct_id) == bool(directory):
+        raise ReaderToolError("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 ReaderToolError("`ct_id` must be a string.")
+    if directory is not None and not isinstance(directory, str):
+        raise ReaderToolError("`directory` must be a string path.")
+    key = ct_id or f"dir:{Path(directory).resolve()}"
+    if key in _CACHE:
+        return _CACHE[key]
+    try:
+        pkg = fetch_package(ct_id, host=_HOST) if ct_id else load_package(directory, host=_HOST)
+        model = read_model(pkg)
+    except PackageError as exc:
+        raise ReaderToolError(str(exc)) from exc
+    except OSError as exc:
+        raise ReaderToolError(f"Could not read the package: {exc}") from exc
+    _CACHE[key] = (pkg, model)
+    return pkg, model
+
+
+def _int(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 ReaderToolError(f"`{name}` must be an integer.")
+    if v < lo or v > hi:
+        raise ReaderToolError(f"`{name}` must be between {lo} and {hi}.")
+    return v
+
+
+def _links(component) -> dict[str, list[str]]:
+    """The component's semantic links by short predicate name, only those present."""
+    names = {IDENTIFIER: "identifier", SOURCE: "source", PUBLISHER: "publisher", EXACT: "exactMatch", SEE_ALSO: "seeAlso"}
+    out = {}
+    for pred, short in names.items():
+        if component.links.get(pred):
+            out[short] = list(component.links[pred])
+    return out
+
+
+def _handle_find_models(args: dict[str, Any]) -> Any:
+    import requests  # a base dependency since 4.1.0, so the registry's `uvx sdcreader` can search
+
+    search = args.get("search", "")
+    project = args.get("project", "")
+    if not isinstance(search, str) or not isinstance(project, str):
+        raise ReaderToolError("`search` and `project` must be strings.")
+    page = _int(args, "page", 1, 1, 10_000)
+    page_size = _int(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 ReaderToolError(f"The catalog could not be reached: {exc}") from exc
+    if r.status_code != 200:
+        raise ReaderToolError(f"The catalog answered HTTP {r.status_code}.")
+    data = r.json()
+    results = [
+        {
+            "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", [])
+    ]
+    return {
+        "host": _HOST,
+        "count": data.get("count"),
+        "page": page,
+        "page_size": page_size,
+        "models": 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 = _package(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 = _package(args)
+    offset = _int(args, "offset", 0, 0, 10_000_000)
+    limit = _int(args, "limit", DEFAULT_PAGE, 1, MAX_PAGE)
+    page = model.leaves[offset : offset + limit]
+    leaves = []
+    for leaf in page:
+        c = leaf.component
+        leaves.append(
+            {
+                "position": leaf.position,
+                "slug": leaf.slug,
+                "ct_id": c.ct_id,
+                "label": c.label,
+                "sdc_type": c.sdc_type,
+                "data_type": c.data_type,
+                "path": [p.label for p in leaf.path],
+                "description": c.description,
+                "constraints": c.constraints,
+                "codes": len(model.codes.get(c.ct_id, [])),
+                "links": _links(c),
+            }
+        )
+    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 = _package(args)
+    comp_id = args.get("component")
+    if not isinstance(comp_id, str) or not comp_id:
+        raise ReaderToolError("`component` must be a component identifier (ct_id).")
+    comp = model.components.get(comp_id)
+    if comp is None:
+        raise ReaderToolError(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:
+    directory = args.get("directory")
+    if not isinstance(directory, str) or not directory:
+        raise ReaderToolError("`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 ReaderToolError(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 _jsonrpc_response(id: Any, result: Any) -> dict:
+    return {"jsonrpc": JSONRPC_VERSION, "id": id, "result": result}
+
+
+def _jsonrpc_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 _handle_request(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 _jsonrpc_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 _jsonrpc_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 _jsonrpc_response(
+            req_id,
+            {
+                "protocolVersion": negotiated,
+                "capabilities": {"tools": {"listChanged": False}},
+                "serverInfo": {"name": SERVER_NAME, "version": SERVER_VERSION},
+                "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."
+                ),
+            },
+        )
+
+    elif method == "notifications/initialized":
+        return None
+
+    elif method == "tools/list":
+        return _jsonrpc_response(req_id, {"tools": TOOLS})
+
+    elif 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 _jsonrpc_error(req_id, -32602, "Invalid params: `arguments` must be an object.")
+        handler = TOOL_HANDLERS.get(tool_name)
+        if handler is None:
+            return _jsonrpc_error(req_id, -32601, f"Unknown tool: {tool_name}")
+        try:
+            result = handler(tool_args)
+            return _jsonrpc_response(req_id, {"content": [{"type": "text", "text": json.dumps(result, default=str)}]})
+        except ReaderToolError as exc:
+            # SEP-1303: a failure the model can correct is a tool error in the
+            # result, not a protocol error it would never see.
+            return _jsonrpc_response(req_id, {"content": [{"type": "text", "text": f"Tool execution error: {exc}"}], "isError": True})
+        except Exception as exc:
+            return _jsonrpc_response(
+                req_id,
+                {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": (
+                                "Tool execution error: the server could not process this input "
+                                f"({type(exc).__name__}). This is a defect worth reporting at "
+                                "https://github.com/SemanticDataCharter/sdcreader/issues"
+                            ),
+                        }
+                    ],
+                    "isError": True,
+                },
+            )
+
+    elif method == "ping":
+        return _jsonrpc_response(req_id, {})
+
+    else:
+        if req_id is not None:
+            return _jsonrpc_error(req_id, -32601, f"Method not found: {method}")
+        return None
+
+
+def run_stdio() -> None:
+    """One JSON-RPC message per line on stdin, one response per line on stdout. stdio and no SDK."""
+    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(_jsonrpc_error(None, -32700, f"Parse error: {exc}")) + "\n")
+            sys.stdout.flush()
+            continue
+        response = _handle_request(request)
+        if response is not None:
+            sys.stdout.write(json.dumps(response) + "\n")
+            sys.stdout.flush()
+
+
+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=(
+            "The SDCStudio host whose public catalog is read, fixed here so a caller "
+            f"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.1.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.1.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.1.0}/src/sdcreader.egg-info/SOURCES.txt

@@ -3,11 +3,14 @@ NOTICE
 README.md
 pyproject.toml
 src/sdcreader/__init__.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_server.py
 tests/test_reader.py

sdcreader-4.1.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.1.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.1.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"