mcp-tool-contract 0.1.0__tar.gz

mcp_tool_contract-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: mcp-tool-contract
+Version: 0.1.0
+Summary: Shared taxonomies and decorator for MCP tools to self-declare ADR 0016 Layer-1 facts (risk, content trust, idempotency, lifecycle).
+Project-URL: Repository, https://github.com/vinicius-ssantos/mcp-tool-contract
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.3.0; extra == "dev"
+Requires-Dist: ruff<1.0.0,>=0.11.0; extra == "dev"
+
+# mcp-tool-contract
+
+Shared taxonomies and a `@tool` decorator that let an MCP tool self-declare
+the facts about itself that only its author knows for certain: risk level,
+content trustworthiness, idempotency, and lifecycle (version/deprecation).
+
+This implements Layer 1 ("Facts") of
+[ADR 0016](https://github.com/vinicius-ssantos/central-mcp-gateway/blob/main/docs/adr/0016-upstream-declared-tool-contract.md)
+in `central-mcp-gateway`. Every upstream MCP service the gateway aggregates is
+owned by the same team, so instead of the gateway guessing these facts from a
+tool's name/description (or requiring them to be re-declared by hand in a
+separate catalog file), the tool's own definition is the single source of
+truth and the gateway reads it from `tools/list`.
+
+## Install
+
+```bash
+pip install mcp-tool-contract
+```
+
+or with `uv`:
+
+```bash
+uv add mcp-tool-contract
+```
+
+## Usage
+
+```python
+from mcp_tool_contract import tool, tool_annotations
+
+@tool(
+    risk="external-publication",   # one of RISK_LEVELS
+    content_trust="trusted",       # one of CONTENT_TRUST_LEVELS
+    idempotent=False,
+    version="2.1.0",
+)
+def post_update(...):
+    ...
+```
+
+When your MCP server framework builds the `tools/list` response for a tool,
+merge `tool_annotations(post_update)` into that tool's `annotations` dict
+alongside its real `inputSchema` and `description` (which this package does
+not touch — your framework already derives those from the function
+signature/docstring).
+
+`tool_annotations()` returns `{}` for an undeclared function, so adoption can
+be incremental: undecorated tools simply fall back to the gateway's existing
+name/description heuristic, exactly as before.
+
+## Taxonomies
+
+- `RISK_LEVELS` / `RISK_LEVEL_ORDER` — `read-only` < `low-risk-write` <
+  `high-risk-write` < `external-publication` < `paid-operation` <
+  `destructive`.
+- `CONTENT_TRUST_LEVELS` — `trusted`, `untrusted`, `sensitive`,
+  `prompt-injection-prone`. Orthogonal to risk: a read-only tool can still
+  return untrusted or adversarial content.
+
+An unrecognised value for either field raises `ValueError` at decoration
+time — a typo in the upstream fails that upstream's own CI, instead of
+silently falling back to the gateway's heuristic.
+
+## Trust boundary
+
+The gateway remains the single point of control (ADR 0001). A declared fact
+is the *default*; the gateway's static catalog may still veto or override any
+tool's effective risk, content-trust, or schema (ADR 0016 Layer 3), and an
+anti-downgrade check flags any tool whose effective risk or content-trust
+weakens between discovery cycles without a recorded catalog override.
+
+## Release
+
+Bump `version` in `pyproject.toml`, then tag and push:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+`.github/workflows/publish.yml` builds and publishes the tagged version to
+PyPI.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+```

mcp_tool_contract-0.1.0/README.md

@@ -0,0 +1,91 @@
+# mcp-tool-contract
+
+Shared taxonomies and a `@tool` decorator that let an MCP tool self-declare
+the facts about itself that only its author knows for certain: risk level,
+content trustworthiness, idempotency, and lifecycle (version/deprecation).
+
+This implements Layer 1 ("Facts") of
+[ADR 0016](https://github.com/vinicius-ssantos/central-mcp-gateway/blob/main/docs/adr/0016-upstream-declared-tool-contract.md)
+in `central-mcp-gateway`. Every upstream MCP service the gateway aggregates is
+owned by the same team, so instead of the gateway guessing these facts from a
+tool's name/description (or requiring them to be re-declared by hand in a
+separate catalog file), the tool's own definition is the single source of
+truth and the gateway reads it from `tools/list`.
+
+## Install
+
+```bash
+pip install mcp-tool-contract
+```
+
+or with `uv`:
+
+```bash
+uv add mcp-tool-contract
+```
+
+## Usage
+
+```python
+from mcp_tool_contract import tool, tool_annotations
+
+@tool(
+    risk="external-publication",   # one of RISK_LEVELS
+    content_trust="trusted",       # one of CONTENT_TRUST_LEVELS
+    idempotent=False,
+    version="2.1.0",
+)
+def post_update(...):
+    ...
+```
+
+When your MCP server framework builds the `tools/list` response for a tool,
+merge `tool_annotations(post_update)` into that tool's `annotations` dict
+alongside its real `inputSchema` and `description` (which this package does
+not touch — your framework already derives those from the function
+signature/docstring).
+
+`tool_annotations()` returns `{}` for an undeclared function, so adoption can
+be incremental: undecorated tools simply fall back to the gateway's existing
+name/description heuristic, exactly as before.
+
+## Taxonomies
+
+- `RISK_LEVELS` / `RISK_LEVEL_ORDER` — `read-only` < `low-risk-write` <
+  `high-risk-write` < `external-publication` < `paid-operation` <
+  `destructive`.
+- `CONTENT_TRUST_LEVELS` — `trusted`, `untrusted`, `sensitive`,
+  `prompt-injection-prone`. Orthogonal to risk: a read-only tool can still
+  return untrusted or adversarial content.
+
+An unrecognised value for either field raises `ValueError` at decoration
+time — a typo in the upstream fails that upstream's own CI, instead of
+silently falling back to the gateway's heuristic.
+
+## Trust boundary
+
+The gateway remains the single point of control (ADR 0001). A declared fact
+is the *default*; the gateway's static catalog may still veto or override any
+tool's effective risk, content-trust, or schema (ADR 0016 Layer 3), and an
+anti-downgrade check flags any tool whose effective risk or content-trust
+weakens between discovery cycles without a recorded catalog override.
+
+## Release
+
+Bump `version` in `pyproject.toml`, then tag and push:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+`.github/workflows/publish.yml` builds and publishes the tagged version to
+PyPI.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+```

mcp_tool_contract-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=80.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-tool-contract"
+version = "0.1.0"
+description = "Shared taxonomies and decorator for MCP tools to self-declare ADR 0016 Layer-1 facts (risk, content trust, idempotency, lifecycle)."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/vinicius-ssantos/mcp-tool-contract"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3.0,<9.0.0",
+  "ruff>=0.11.0,<1.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

mcp_tool_contract-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_tool_contract-0.1.0/src/mcp_tool_contract/__init__.py

@@ -0,0 +1,176 @@
+"""Shared tool-contract taxonomies and decorator (ADR 0016).
+
+central-mcp-gateway aggregates tools from several upstream MCP services that we
+own. Facts about what a tool *is* and *does* — risk level, content
+trustworthiness, idempotency, version — are known with certainty by the
+upstream that implements the tool, yet historically the gateway either
+guessed them from the tool's name/description or required them to be
+re-declared by hand in a separate catalog file. That duplication drifts.
+
+This package lets an upstream tool self-declare those facts once, at the
+point where the tool is defined, via the ``@tool`` decorator. The facts are
+exposed as ``tools/list`` annotations that central-mcp-gateway reads as the
+default value for each field, falling back to its own heuristics only for
+tools that declare nothing.
+
+Usage in an upstream MCP server::
+
+    from mcp_tool_contract import tool, tool_annotations
+
+    @tool(risk="external-publication", content_trust="trusted", idempotent=False)
+    def post_update(...): ...
+
+    # When building the tools/list response for this tool:
+    annotations = tool_annotations(post_update)
+
+See docs/adr/0016-upstream-declared-tool-contract.md in central-mcp-gateway
+for the full design (the gateway remains the trust boundary: it may always
+veto or override a declared fact via its static catalog — ADR 0016 Layer 3).
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "RISK_LEVELS",
+    "RISK_LEVEL_ORDER",
+    "CONTENT_TRUST_LEVELS",
+    "ToolContract",
+    "tool",
+    "get_contract",
+    "tool_annotations",
+]
+
+# Valid risk levels, in ascending order of side-effect impact. Mirrors
+# central_mcp_gateway.tools.RISK_LEVELS — the two must not diverge; this
+# package is the canonical source once the gateway migrates to import it.
+RISK_LEVELS = frozenset(
+    {
+        "read-only",
+        "low-risk-write",
+        "high-risk-write",
+        "external-publication",
+        "paid-operation",
+        "destructive",
+    }
+)
+
+RISK_LEVEL_ORDER = (
+    "read-only",
+    "low-risk-write",
+    "high-risk-write",
+    "external-publication",
+    "paid-operation",
+    "destructive",
+)
+
+# Trustworthiness of a tool's *response* content. Orthogonal to risk_level: a
+# read-only tool can still return untrusted or adversarial content (e.g. a
+# tool that fetches a web page).
+CONTENT_TRUST_LEVELS = frozenset(
+    {
+        "trusted",
+        "untrusted",
+        "sensitive",
+        "prompt-injection-prone",
+    }
+)
+
+# Annotation keys central-mcp-gateway's discovery reads from tools/list, in
+# addition to the three standard MCP hints (readOnlyHint, destructiveHint,
+# idempotentHint), which cannot alone express a 6-level risk taxonomy or a
+# 4-level content-trust taxonomy.
+ANNOTATION_RISK_LEVEL = "risk_level"
+ANNOTATION_CONTENT_TRUST_RISK = "content_trust_risk"
+ANNOTATION_VERSION = "version"
+ANNOTATION_DEPRECATED_SINCE = "deprecated_since"
+ANNOTATION_ALIASES = "aliases"
+
+_CONTRACT_ATTR = "__mcp_tool_contract__"
+
+
+@dataclass(frozen=True)
+class ToolContract:
+    """A tool's self-declared Layer-1 facts (ADR 0016)."""
+
+    risk: str
+    content_trust: str = "trusted"
+    idempotent: bool = False
+    version: str = "1.0.0"
+    deprecated_since: str | None = None
+    aliases: tuple[str, ...] = field(default_factory=tuple)
+
+    def __post_init__(self) -> None:
+        if self.risk not in RISK_LEVELS:
+            raise ValueError(
+                f"Unknown risk level {self.risk!r}; must be one of {sorted(RISK_LEVELS)}"
+            )
+        if self.content_trust not in CONTENT_TRUST_LEVELS:
+            raise ValueError(
+                f"Unknown content_trust {self.content_trust!r}; "
+                f"must be one of {sorted(CONTENT_TRUST_LEVELS)}"
+            )
+
+    def to_annotations(self) -> dict[str, Any]:
+        """Render this contract as MCP tools/list annotation fields."""
+        annotations: dict[str, Any] = {
+            "readOnlyHint": self.risk == "read-only",
+            "destructiveHint": self.risk == "destructive",
+            "idempotentHint": self.idempotent,
+            ANNOTATION_RISK_LEVEL: self.risk,
+            ANNOTATION_CONTENT_TRUST_RISK: self.content_trust,
+            ANNOTATION_VERSION: self.version,
+        }
+        if self.deprecated_since is not None:
+            annotations[ANNOTATION_DEPRECATED_SINCE] = self.deprecated_since
+        if self.aliases:
+            annotations[ANNOTATION_ALIASES] = list(self.aliases)
+        return annotations
+
+
+def tool(
+    *,
+    risk: str,
+    content_trust: str = "trusted",
+    idempotent: bool = False,
+    version: str = "1.0.0",
+    deprecated_since: str | None = None,
+    aliases: Sequence[str] = (),
+):
+    """Decorator: self-declare a tool's Layer-1 facts.
+
+    Raises ValueError immediately (at import time, not at gateway-discovery
+    time) if ``risk`` or ``content_trust`` is not a recognised taxonomy value
+    — a typo here must fail the upstream's own CI, not silently fall back to
+    the gateway's heuristic.
+    """
+    contract = ToolContract(
+        risk=risk,
+        content_trust=content_trust,
+        idempotent=idempotent,
+        version=version,
+        deprecated_since=deprecated_since,
+        aliases=tuple(aliases),
+    )
+
+    def decorator(func):
+        setattr(func, _CONTRACT_ATTR, contract)
+        return func
+
+    return decorator
+
+
+def get_contract(func: Any) -> ToolContract | None:
+    """Return the ToolContract attached to func by @tool, or None if undeclared."""
+    return getattr(func, _CONTRACT_ATTR, None)
+
+
+def tool_annotations(func: Any) -> dict[str, Any]:
+    """Return the tools/list annotation fields for func, or {} if undeclared.
+
+    Merge this into whatever annotations dict the upstream's MCP framework
+    builds for the tool, alongside its real inputSchema and description.
+    """
+    contract = get_contract(func)
+    return contract.to_annotations() if contract is not None else {}

mcp_tool_contract-0.1.0/src/mcp_tool_contract.egg-info/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: mcp-tool-contract
+Version: 0.1.0
+Summary: Shared taxonomies and decorator for MCP tools to self-declare ADR 0016 Layer-1 facts (risk, content trust, idempotency, lifecycle).
+Project-URL: Repository, https://github.com/vinicius-ssantos/mcp-tool-contract
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.3.0; extra == "dev"
+Requires-Dist: ruff<1.0.0,>=0.11.0; extra == "dev"
+
+# mcp-tool-contract
+
+Shared taxonomies and a `@tool` decorator that let an MCP tool self-declare
+the facts about itself that only its author knows for certain: risk level,
+content trustworthiness, idempotency, and lifecycle (version/deprecation).
+
+This implements Layer 1 ("Facts") of
+[ADR 0016](https://github.com/vinicius-ssantos/central-mcp-gateway/blob/main/docs/adr/0016-upstream-declared-tool-contract.md)
+in `central-mcp-gateway`. Every upstream MCP service the gateway aggregates is
+owned by the same team, so instead of the gateway guessing these facts from a
+tool's name/description (or requiring them to be re-declared by hand in a
+separate catalog file), the tool's own definition is the single source of
+truth and the gateway reads it from `tools/list`.
+
+## Install
+
+```bash
+pip install mcp-tool-contract
+```
+
+or with `uv`:
+
+```bash
+uv add mcp-tool-contract
+```
+
+## Usage
+
+```python
+from mcp_tool_contract import tool, tool_annotations
+
+@tool(
+    risk="external-publication",   # one of RISK_LEVELS
+    content_trust="trusted",       # one of CONTENT_TRUST_LEVELS
+    idempotent=False,
+    version="2.1.0",
+)
+def post_update(...):
+    ...
+```
+
+When your MCP server framework builds the `tools/list` response for a tool,
+merge `tool_annotations(post_update)` into that tool's `annotations` dict
+alongside its real `inputSchema` and `description` (which this package does
+not touch — your framework already derives those from the function
+signature/docstring).
+
+`tool_annotations()` returns `{}` for an undeclared function, so adoption can
+be incremental: undecorated tools simply fall back to the gateway's existing
+name/description heuristic, exactly as before.
+
+## Taxonomies
+
+- `RISK_LEVELS` / `RISK_LEVEL_ORDER` — `read-only` < `low-risk-write` <
+  `high-risk-write` < `external-publication` < `paid-operation` <
+  `destructive`.
+- `CONTENT_TRUST_LEVELS` — `trusted`, `untrusted`, `sensitive`,
+  `prompt-injection-prone`. Orthogonal to risk: a read-only tool can still
+  return untrusted or adversarial content.
+
+An unrecognised value for either field raises `ValueError` at decoration
+time — a typo in the upstream fails that upstream's own CI, instead of
+silently falling back to the gateway's heuristic.
+
+## Trust boundary
+
+The gateway remains the single point of control (ADR 0001). A declared fact
+is the *default*; the gateway's static catalog may still veto or override any
+tool's effective risk, content-trust, or schema (ADR 0016 Layer 3), and an
+anti-downgrade check flags any tool whose effective risk or content-trust
+weakens between discovery cycles without a recorded catalog override.
+
+## Release
+
+Bump `version` in `pyproject.toml`, then tag and push:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+`.github/workflows/publish.yml` builds and publishes the tagged version to
+PyPI.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+```

mcp_tool_contract-0.1.0/src/mcp_tool_contract.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/mcp_tool_contract/__init__.py
+src/mcp_tool_contract.egg-info/PKG-INFO
+src/mcp_tool_contract.egg-info/SOURCES.txt
+src/mcp_tool_contract.egg-info/dependency_links.txt
+src/mcp_tool_contract.egg-info/requires.txt
+src/mcp_tool_contract.egg-info/top_level.txt
+tests/test_contract.py

mcp_tool_contract-0.1.0/src/mcp_tool_contract.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mcp_tool_contract-0.1.0/src/mcp_tool_contract.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest<9.0.0,>=8.3.0
+ruff<1.0.0,>=0.11.0

mcp_tool_contract-0.1.0/src/mcp_tool_contract.egg-info/top_level.txt

@@ -0,0 +1 @@
+mcp_tool_contract

mcp_tool_contract-0.1.0/tests/test_contract.py

@@ -0,0 +1,103 @@
+import pytest
+
+from mcp_tool_contract import (
+    CONTENT_TRUST_LEVELS,
+    RISK_LEVELS,
+    ToolContract,
+    get_contract,
+    tool,
+    tool_annotations,
+)
+
+
+def test_tool_decorator_attaches_contract_without_changing_callable() -> None:
+    @tool(risk="external-publication", content_trust="trusted", idempotent=False)
+    def publish(): ...
+
+    assert publish() is None
+    contract = get_contract(publish)
+    assert contract is not None
+    assert contract.risk == "external-publication"
+    assert contract.content_trust == "trusted"
+    assert contract.idempotent is False
+
+
+def test_get_contract_returns_none_for_undeclared_function() -> None:
+    def plain(): ...
+
+    assert get_contract(plain) is None
+
+
+def test_tool_annotations_empty_for_undeclared_function() -> None:
+    def plain(): ...
+
+    assert tool_annotations(plain) == {}
+
+
+def test_tool_annotations_includes_standard_mcp_hints() -> None:
+    @tool(risk="destructive", idempotent=True)
+    def delete_everything(): ...
+
+    annotations = tool_annotations(delete_everything)
+    assert annotations["readOnlyHint"] is False
+    assert annotations["destructiveHint"] is True
+    assert annotations["idempotentHint"] is True
+    assert annotations["risk_level"] == "destructive"
+    assert annotations["content_trust_risk"] == "trusted"
+
+
+def test_tool_annotations_read_only_hints() -> None:
+    @tool(risk="read-only")
+    def get_status(): ...
+
+    annotations = tool_annotations(get_status)
+    assert annotations["readOnlyHint"] is True
+    assert annotations["destructiveHint"] is False
+
+
+def test_tool_annotations_omits_optional_fields_when_unset() -> None:
+    @tool(risk="read-only")
+    def get_status(): ...
+
+    annotations = tool_annotations(get_status)
+    assert "deprecated_since" not in annotations
+    assert "aliases" not in annotations
+
+
+def test_tool_annotations_includes_deprecated_since_and_aliases_when_set() -> None:
+    @tool(risk="read-only", version="2.0.0", deprecated_since="2026-01-01", aliases=["old.name"])
+    def get_status(): ...
+
+    annotations = tool_annotations(get_status)
+    assert annotations["version"] == "2.0.0"
+    assert annotations["deprecated_since"] == "2026-01-01"
+    assert annotations["aliases"] == ["old.name"]
+
+
+def test_invalid_risk_level_rejected_at_decoration_time() -> None:
+    with pytest.raises(ValueError, match="risk level"):
+
+        @tool(risk="totally-fine-trust-me")
+        def shady(): ...
+
+
+def test_invalid_content_trust_rejected_at_decoration_time() -> None:
+    with pytest.raises(ValueError, match="content_trust"):
+
+        @tool(risk="read-only", content_trust="not-a-real-level")
+        def shady(): ...
+
+
+def test_tool_contract_dataclass_validates_directly() -> None:
+    with pytest.raises(ValueError):
+        ToolContract(risk="not-a-risk-level")
+
+
+@pytest.mark.parametrize("risk", sorted(RISK_LEVELS))
+def test_every_risk_level_accepted(risk: str) -> None:
+    ToolContract(risk=risk)
+
+
+@pytest.mark.parametrize("content_trust", sorted(CONTENT_TRUST_LEVELS))
+def test_every_content_trust_level_accepted(content_trust: str) -> None:
+    ToolContract(risk="read-only", content_trust=content_trust)