Domain-friendly tool interfaces with typed responses

- CRUD tools use entity-specific parameter names (contact_id, deal_id)
  instead of generic entity_id
- list/search/relationship tools return {entities, count, ...} envelope
  instead of bare arrays
- All entity-derived tools declare outputSchema and return
  structuredContent per MCP spec 2025-06-18
- Add build_entity_output_schema() and build_list_output_schema() to
  upjack.schema

Release 0.3.0

Author: mgoldsborough

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 
 This project follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.3.0] - 2026-03-27
+
+### Changed
+- **Breaking:** CRUD tools use entity-specific parameter names (`contact_id`, `deal_id`) instead of generic `entity_id`
+- **Breaking:** `list_*` and `search_*` tools return `{entities: [...], count, ...}` envelope instead of bare arrays
+- **Breaking:** `query_*_by_relationship` and `get_related_*` tools return the same envelope format
+- All entity-derived tools declare `outputSchema` and return `structuredContent` (MCP spec 2025-06-18)
+- Added `build_entity_output_schema()` and `build_list_output_schema()` helpers to `upjack.schema`
+- Internal: `_wrap_list()` helper for consistent response envelope construction
+
 ## [0.2.0] - 2026-03-26
 
 ### Added

lib/python/e2e/test_crm_mcpb.py

@@ -107,8 +107,8 @@ async def test_seed_and_list(bundle_path):
             assert seed_data["errors"] == []
 
             list_result = await session.call_tool("list_contacts", {})
-            contacts = json.loads(list_result.content[0].text)
-            assert len(contacts) == 2
+            result_data = json.loads(list_result.content[0].text)
+            assert result_data["count"] == 2
 
 
 @pytest.mark.asyncio
@@ -134,15 +134,15 @@ async def test_full_crud_cycle(bundle_path):
             assert contact_id.startswith("ct_")
 
             # Get
-            get_result = await session.call_tool("get_contact", {"entity_id": contact_id})
+            get_result = await session.call_tool("get_contact", {"contact_id": contact_id})
             fetched = json.loads(get_result.content[0].text)
             assert fetched["first_name"] == "Bob"
             assert fetched["email"] == "bob@test.com"
 
             # Update
             update_result = await session.call_tool(
                 "update_contact",
-                {"entity_id": contact_id, "data": {"lead_score": 85}},
+                {"contact_id": contact_id, "data": {"lead_score": 85}},
             )
             updated = json.loads(update_result.content[0].text)
             assert updated["lead_score"] == 85
@@ -153,19 +153,16 @@ async def test_full_crud_cycle(bundle_path):
                 "search_contacts",
                 {"query": "Bob"},
             )
-            results = json.loads(search_result.content[0].text)
-            assert len(results) == 1
-            assert results[0]["lead_score"] == 85
+            search_data = json.loads(search_result.content[0].text)
+            assert search_data["count"] == 1
+            assert search_data["entities"][0]["lead_score"] == 85
 
             # Delete
-            delete_result = await session.call_tool("delete_contact", {"entity_id": contact_id})
+            delete_result = await session.call_tool("delete_contact", {"contact_id": contact_id})
             deleted = json.loads(delete_result.content[0].text)
             assert deleted["status"] == "deleted"
 
             # Verify gone from list
             list_result = await session.call_tool("list_contacts", {})
-            if list_result.content:
-                active = json.loads(list_result.content[0].text)
-            else:
-                active = []
-            assert all(c["id"] != contact_id for c in active)
+            list_data = json.loads(list_result.content[0].text)
+            assert all(c["id"] != contact_id for c in list_data["entities"])

lib/python/e2e/test_research_mcpb.py

@@ -85,5 +85,5 @@ async def test_seed_data(bundle_path):
             assert seed_data["errors"] == []
 
             list_result = await session.call_tool("list_topics", {})
-            topics = json.loads(list_result.content[0].text)
-            assert len(topics) == 2
+            result_data = json.loads(list_result.content[0].text)
+            assert result_data["count"] == 2

lib/python/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "upjack"
-version = "0.2.0"
+version = "0.3.0"
 description = "Schema-driven entity management for AI-native applications"
 readme = "README.md"
 license = {text = "Apache-2.0"}

lib/python/src/upjack/__init__.py

@@ -1,6 +1,6 @@
 """NimbleBrain Upjack — schema-driven entity management for AI-native applications."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from upjack.activity import ACTIVITY_ENTITY_DEF, get_activity_schema
 from upjack.app import UpjackApp

lib/python/src/upjack/schema.py

@@ -212,3 +212,38 @@ def validate_schema_change(
         )
 
     return diagnostics
+
+
+def build_entity_output_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    """Build an output schema for a single-entity tool response.
+
+    Returns the full entity schema (including base fields) with JSON Schema
+    meta keywords stripped, suitable for use as a tool's ``outputSchema``.
+    """
+    result = copy.deepcopy(schema)
+    result.pop("$schema", None)
+    result.pop("$id", None)
+    return result
+
+
+def build_list_output_schema(entity_schema: dict[str, Any]) -> dict[str, Any]:
+    """Build an output schema for a list/search response envelope.
+
+    Returns an object schema with ``entities`` (array of entity schemas)
+    and ``count`` (integer).
+    """
+    item_schema = build_entity_output_schema(entity_schema)
+    return {
+        "type": "object",
+        "properties": {
+            "entities": {
+                "type": "array",
+                "items": item_schema,
+            },
+            "count": {
+                "type": "integer",
+                "description": "Number of entities returned",
+            },
+        },
+        "required": ["entities", "count"],
+    }