nutria-plugin 0.3.0__tar.gz → 0.3.2__tar.gz

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.2
+
+- Add transport-neutral MCP result normalization for FastMCP scalar JSON envelopes.
+- Add declared-output projection and cardinality conformance helpers for plugin and host tests.
+- Document protocol-level validation in addition to static manifest validation.
+
+## 0.3.1
+
+- Create missing parent directories for explicit plugin package output paths.
+
 ## 0.3.0
 
 - Replace adapter-specific prepared actions with one portable exact-preview protocol.

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nutria-plugin
-Version: 0.3.0
+Version: 0.3.2
 Summary: SDK for building, validating, signing, and packaging Nutria plugins
 Project-URL: Homepage, https://github.com/AlRos14/nutria-plugin-sdk
 Project-URL: Repository, https://github.com/AlRos14/nutria-plugin-sdk
@@ -21,7 +21,7 @@ Description-Content-Type: text/markdown
 
 SDK for building, validating, signing, and packaging Nutria plugins.
 
-Release `0.3.0` is intentionally breaking. It accepts only manifest schema
+Release `0.3.2` uses the intentionally breaking schema introduced in 0.3.0. It accepts only manifest schema
 `3.0`, requires typed capabilities and world providers, and makes authority,
 audience, task-context requirements, and exposure explicit. There is no runtime
 migration for schema 2.0/2.1 manifests and no compatibility/model-callability
@@ -34,7 +34,7 @@ and exact delivery of an approved snapshot.
 ## Install
 
 ```bash
-uv add nutria-plugin==0.3.0
+uv add nutria-plugin==0.3.2
 ```
 
 ## Scaffold and validate
@@ -119,6 +119,26 @@ errors = validate_plugin_dir(Path("."))
 archive = pack_plugin(Path("."), Path("dist/plugin.zip"))
 ```
 
+### Validate MCP results against declared outputs
+
+Manifest validation checks the descriptor itself. Protocol-level plugin tests
+must also validate the payload Nutria receives after MCP transport:
+
+```python
+from nutria_plugin import validate_capability_result
+
+payload = validate_capability_result(
+    capability,
+    structured_content=call_result.structuredContent,
+    text_content=call_result.content[0].text,
+)
+```
+
+This normalizes FastMCP's scalar JSON envelope and raises
+`MCPResultContractError` when a declared path such as `.items` does not
+materialize. It does not execute the tool and should be used in a bounded,
+fixture-backed or read-only MCP integration test.
+
 The package exports the strict manifest, capability, provider, reviewable-action,
 admin extension/flow, bundle, packaging, and signing models/functions documented
 in [`docs/python-api.md`](docs/python-api.md).

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/README.md

@@ -2,7 +2,7 @@
 
 SDK for building, validating, signing, and packaging Nutria plugins.
 
-Release `0.3.0` is intentionally breaking. It accepts only manifest schema
+Release `0.3.2` uses the intentionally breaking schema introduced in 0.3.0. It accepts only manifest schema
 `3.0`, requires typed capabilities and world providers, and makes authority,
 audience, task-context requirements, and exposure explicit. There is no runtime
 migration for schema 2.0/2.1 manifests and no compatibility/model-callability
@@ -15,7 +15,7 @@ and exact delivery of an approved snapshot.
 ## Install
 
 ```bash
-uv add nutria-plugin==0.3.0
+uv add nutria-plugin==0.3.2
 ```
 
 ## Scaffold and validate
@@ -100,6 +100,26 @@ errors = validate_plugin_dir(Path("."))
 archive = pack_plugin(Path("."), Path("dist/plugin.zip"))
 ```
 
+### Validate MCP results against declared outputs
+
+Manifest validation checks the descriptor itself. Protocol-level plugin tests
+must also validate the payload Nutria receives after MCP transport:
+
+```python
+from nutria_plugin import validate_capability_result
+
+payload = validate_capability_result(
+    capability,
+    structured_content=call_result.structuredContent,
+    text_content=call_result.content[0].text,
+)
+```
+
+This normalizes FastMCP's scalar JSON envelope and raises
+`MCPResultContractError` when a declared path such as `.items` does not
+materialize. It does not execute the tool and should be used in a bounded,
+fixture-backed or read-only MCP integration test.
+
 The package exports the strict manifest, capability, provider, reviewable-action,
 admin extension/flow, bundle, packaging, and signing models/functions documented
 in [`docs/python-api.md`](docs/python-api.md).

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/docs/index.md

@@ -1,6 +1,6 @@
 # nutria-plugin SDK documentation
 
-Developer reference for SDK `0.3.0` and manifest schema `3.0`.
+Developer reference for SDK `0.3.1` and manifest schema `3.0`.
 
 | Document | Purpose |
 |---|---|

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/docs/manifest.md

@@ -1,7 +1,7 @@
 # plugin.json manifest reference
 
 `plugin.json` is the single source of truth for plugin identity, runtime,
-capability authority, and provider topology. SDK 0.3.0 accepts exactly schema
+capability authority, and provider topology. SDK 0.3.1 accepts exactly schema
 `3.0`; older schemas and unknown fields fail validation.
 
 ## Required top-level fields

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/docs/python-api.md

@@ -1,6 +1,6 @@
 # Python API reference
 
-SDK 0.3.0 exposes the strict schema 3.0 API.
+SDK 0.3.1 exposes the strict schema 3.0 API.
 
 ```python
 from nutria_plugin import (

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/docs/quickstart.md

@@ -3,7 +3,7 @@
 ## Install and scaffold
 
 ```bash
-uv add nutria-plugin==0.3.0
+uv add nutria-plugin==0.3.1
 nutria-plugin new inventory-lookup --name "Inventory Lookup"
 ```
 

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/docs/reviewable-actions.md

@@ -1,6 +1,6 @@
 # Reviewable actions and external writes
 
-SDK 0.3.0 schema 3.0 defines one reviewable-action architecture:
+SDK 0.3.1 schema 3.0 defines one reviewable-action architecture:
 
 ```text
 ChatBotNutralia -> task context, encrypted draft, revision, approval, idempotency, receipts

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nutria-plugin"
-version = "0.3.0"
+version = "0.3.2"
 description = "SDK for building, validating, signing, and packaging Nutria plugins"
 readme = "README.md"
 license = {text = "MIT"}

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/src/nutria_plugin/__init__.py

@@ -15,7 +15,7 @@ Signing:
     generate_keypair, sign_manifest, verify_manifest, SignatureStatus
 """
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"
 
 from .capabilities import (
     CapabilityDescriptor,
@@ -55,6 +55,13 @@ from .manifest import (
 from .bundle import PluginBundleError, extract_plugin_bundle, load_plugin_bundle, validate_zip
 from .packaging import PackagingError, pack_plugin, scaffold_plugin, validate_plugin_dir
 from .signing import SignatureStatus, generate_keypair, sign_manifest, verify_manifest
+from .mcp_results import (
+    MCPResultContractError,
+    normalize_mcp_result,
+    project_result_path,
+    validate_capability_result,
+    validate_declared_outputs,
+)
 
 __all__ = [
     "__version__",
@@ -103,4 +110,10 @@ __all__ = [
     "generate_keypair",
     "sign_manifest",
     "verify_manifest",
+    # MCP result contracts
+    "MCPResultContractError",
+    "normalize_mcp_result",
+    "project_result_path",
+    "validate_capability_result",
+    "validate_declared_outputs",
 ]

nutria_plugin-0.3.2/src/nutria_plugin/mcp_results.py

@@ -0,0 +1,104 @@
+"""MCP result normalization and declared-output conformance helpers.
+
+These helpers intentionally do not import the MCP package. Plugin tests and
+Nutria hosts can pass protocol values they already received while the SDK keeps
+one definition of the payload against which manifest ``result_path`` bindings
+are evaluated.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+
+class MCPResultContractError(ValueError):
+    """Raised when a successful MCP result violates declared output bindings."""
+
+
+def _decode_json_container(value: Any) -> Any:
+    if not isinstance(value, str):
+        return value
+    try:
+        decoded = json.loads(value)
+    except (TypeError, json.JSONDecodeError):
+        return value
+    return decoded if isinstance(decoded, dict | list) else value
+
+
+def normalize_mcp_result(
+    *,
+    structured_content: Any = None,
+    text_content: str | None = None,
+) -> Any:
+    """Return the canonical provider payload from an MCP tool response.
+
+    Structured content is authoritative. FastMCP wraps tools annotated as
+    returning ``str`` in an exact ``{"result": <string>}`` object; when that
+    scalar is a complete JSON object or array, it represents the tool payload
+    and is safely unwrapped. All other structured objects are preserved.
+    """
+
+    if structured_content is not None:
+        if isinstance(structured_content, Mapping) and set(structured_content) == {"result"}:
+            decoded = _decode_json_container(structured_content.get("result"))
+            if isinstance(decoded, dict | list):
+                return decoded
+        return structured_content
+    return _decode_json_container(text_content or "")
+
+
+def project_result_path(payload: Any, result_path: str) -> Any:
+    """Resolve one manifest result path or raise a conformance error."""
+
+    declared_path = str(result_path or "").strip()
+    if not declared_path:
+        raise MCPResultContractError("declared output is missing result_path")
+    if declared_path == "$":
+        return payload
+    if not declared_path.startswith("."):
+        raise MCPResultContractError(f"invalid declared output path: {declared_path}")
+
+    current = payload
+    for part in declared_path[1:].split("."):
+        if not part or not isinstance(current, Mapping) or part not in current:
+            raise MCPResultContractError(
+                f"declared output path did not materialize: {declared_path}"
+            )
+        current = current[part]
+    if current is None:
+        raise MCPResultContractError(
+            f"declared output path did not materialize: {declared_path}"
+        )
+    return current
+
+
+def validate_declared_outputs(
+    payload: Any,
+    produces: Iterable[Mapping[str, Any]],
+) -> None:
+    """Assert that every declared output exists with compatible cardinality."""
+
+    for binding in produces:
+        value = project_result_path(payload, str(binding.get("result_path") or ""))
+        if binding.get("many") and not isinstance(value, list):
+            raise MCPResultContractError(
+                f"declared many output is not a list: {binding.get('result_path')}"
+            )
+
+
+def validate_capability_result(
+    capability: Mapping[str, Any],
+    *,
+    structured_content: Any = None,
+    text_content: str | None = None,
+) -> Any:
+    """Normalize an MCP result and validate one capability's output contract."""
+
+    payload = normalize_mcp_result(
+        structured_content=structured_content,
+        text_content=text_content,
+    )
+    validate_declared_outputs(payload, capability.get("produces") or ())
+    return payload

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/src/nutria_plugin/packaging.py

@@ -283,6 +283,7 @@ def pack_plugin(
 
     if output_path is None:
         output_path = Path(f"{manifest.id}-{manifest.version}.zip")
+    output_path.parent.mkdir(parents=True, exist_ok=True)
     output_path.write_bytes(data)
     return output_path
 

nutria_plugin-0.3.2/tests/test_mcp_results.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import pytest
+
+from nutria_plugin.mcp_results import (
+    MCPResultContractError,
+    normalize_mcp_result,
+    validate_capability_result,
+    validate_declared_outputs,
+)
+
+
+def test_normalizes_fastmcp_json_string_result_envelope() -> None:
+    payload = normalize_mcp_result(
+        structured_content={
+            "result": '{"ok":true,"chats":[{"chat_ref":"chat-1"}]}'
+        },
+        text_content="ignored",
+    )
+
+    assert payload == {"ok": True, "chats": [{"chat_ref": "chat-1"}]}
+
+
+def test_preserves_provider_owned_result_object() -> None:
+    payload = normalize_mcp_result(
+        structured_content={"result": {"id": "op-1"}, "status": "complete"}
+    )
+
+    assert payload == {"result": {"id": "op-1"}, "status": "complete"}
+
+
+def test_validates_nested_many_output() -> None:
+    validate_declared_outputs(
+        {"data": {"items": [{"id": "item-1"}]}},
+        [{"result_path": ".data.items", "many": True}],
+    )
+
+
+def test_rejects_missing_declared_output() -> None:
+    with pytest.raises(
+        MCPResultContractError,
+        match=r"declared output path did not materialize: \.chats",
+    ):
+        validate_declared_outputs(
+            {"result": '{"chats":[]}'},
+            [{"result_path": ".chats", "many": True}],
+        )
+
+
+def test_rejects_non_list_many_output() -> None:
+    with pytest.raises(MCPResultContractError, match="many output is not a list"):
+        validate_declared_outputs(
+            {"messages": {"id": "message-1"}},
+            [{"result_path": ".messages", "many": True}],
+        )
+
+
+def test_validates_capability_against_protocol_values() -> None:
+    capability = {
+        "produces": [
+            {"result_path": ".chats", "resource_type": "whatsapp_chat", "many": True}
+        ]
+    }
+
+    payload = validate_capability_result(
+        capability,
+        structured_content={"result": '{"ok":true,"chats":[]}'},
+    )
+
+    assert payload == {"ok": True, "chats": []}

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/tests/test_packaging.py

@@ -56,6 +56,17 @@ def test_pack_plugin_produces_zip(tmp_path):
     assert out.stat().st_size > 0
 
 
+def test_pack_plugin_creates_output_directory(tmp_path):
+    src = tmp_path / "myplugin"
+    scaffold_plugin(src, "my-plugin", "My Plugin")
+    out = tmp_path / "dist" / "nested" / "output.zip"
+
+    result = pack_plugin(src, out)
+
+    assert result == out
+    assert out.is_file()
+
+
 def test_pack_plugin_default_output_name(tmp_path, monkeypatch):
     src = tmp_path / "myplugin"
     scaffold_plugin(src, "my-plugin")

{nutria_plugin-0.3.0 → nutria_plugin-0.3.2}/uv.lock

@@ -262,7 +262,7 @@ wheels = [
 
 [[package]]
 name = "nutria-plugin"
-version = "0.3.0"
+version = "0.3.2"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },