Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix(mcp): accept entity_id in get_provenance (#1248)

csy204fc0e6b157bf
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9e3652da..c0a3fd77 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,6 +36,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Never auto-applies: returns `draft: True` plus a Turtle serialization for human review, per the OBIE/ontology-learning convention that frequency alone yields proposals, not final ontologies
- New `tests/test_bootstrap_schema.py`
+### Fixed
+
+- **MCP `get_provenance` ignored the advertised `entity_id` argument, so every schema-compliant call failed** (closes #1248) by @csy20 — `GET_PROVENANCE` requires `entity_id` and `tools/list` advertises that key, but `handle_get_provenance` only read `node_id` and always returned `{"error": "node_id is required", "provenance": []}`. The handler now reads `entity_id` first and still accepts `node_id` as a compatibility alias. New `tests/test_mcp_package_get_provenance.py`
+
## [0.7.0] - 2026-09-07
### Changed
diff --git a/semantica_mcp/mcp/README.md b/semantica_mcp/mcp/README.md
index c5487bc0..901b83b4 100644
--- a/semantica_mcp/mcp/README.md
+++ b/semantica_mcp/mcp/README.md
@@ -73,7 +73,7 @@ python -m mcp [--debug]
| Tool | Description |
|---|---|
| `export_graph` | Export graph to JSON, CSV, GraphML, Parquet, Turtle, N-Triples, RDF/XML, JSON-LD |
-| `get_provenance` | Audit history and source lineage for a node |
+| `get_provenance` | Audit history and source lineage for a node (`entity_id`) |
---
diff --git a/semantica_mcp/mcp/tools/export.py b/semantica_mcp/mcp/tools/export.py
index fa135e7b..d880ad2f 100644
--- a/semantica_mcp/mcp/tools/export.py
+++ b/semantica_mcp/mcp/tools/export.py
@@ -146,10 +146,17 @@ def handle_export_graph(args: dict) -> dict:
def handle_get_provenance(args: dict) -> dict:
- """Retrieve the provenance / audit history for a node."""
- node_id = args.get("node_id", "").strip()
+ """Retrieve the provenance / audit history for a node.
+
+ The advertised schema requires ``entity_id``. ``node_id`` is accepted as
+ a compatibility alias for callers that discovered the old handler key
+ (#1248).
+ """
+ # Prefer the public schema field; fall back to the legacy key.
+ entity_id = str(args.get("entity_id") or "").strip()
+ node_id = entity_id or str(args.get("node_id") or "").strip()
if not node_id:
- return {"error": "node_id is required", "provenance": []}
+ return {"error": "entity_id is required", "provenance": []}
include_metadata = bool(args.get("include_metadata", True))
try:
graph = get_graph()
diff --git a/tests/test_mcp_package_get_provenance.py b/tests/test_mcp_package_get_provenance.py
new file mode 100644
index 00000000..fd4295ce
--- /dev/null
+++ b/tests/test_mcp_package_get_provenance.py
@@ -0,0 +1,199 @@
+"""Regression tests for MCP get_provenance argument names (issue #1248).
+
+Pre-fix bug
+-----------
+``GET_PROVENANCE`` (and therefore ``tools/list``) requires ``entity_id``, but
+``handle_get_provenance`` only read ``node_id``. Every schema-compliant call
+returned ``{"error": "node_id is required", "provenance": []}``.
+
+Post-fix expectations
+---------------------
+- ``entity_id`` is accepted (the advertised contract).
+- ``node_id`` remains a compatibility alias.
+- When both are provided, ``entity_id`` wins.
+- Missing / whitespace-only ids still error, naming ``entity_id``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import unittest
+import warnings
+from unittest.mock import patch
+
+os.environ["SEMANTICA_DISABLE_PROGRESS"] = "1"
+
+
+class _DummyTracker:
+ """Stand-in for semantica.kg.ProvenanceTracker with a real get_provenance."""
+
+ calls: list = []
+
+ def get_provenance(self, node_id):
+ _DummyTracker.calls.append(node_id)
+ return [{"source": "unit-test", "origin": "fixture"}]
+
+
+class _FakeGraph:
+ """Minimal graph: handlers only need find_nodes() for the fallback path."""
+
+ def find_nodes(self):
+ return [
+ {
+ "id": "apple_inc",
+ "type": "entity",
+ "content": "apple_inc",
+ "metadata": {"source": "wiki"},
+ },
+ {"id": "other", "type": "entity", "content": "other", "metadata": {}},
+ ]
+
+
+class _GraphSessionMixin:
+ def setUp(self):
+ import semantica_mcp.mcp.session as _session
+
+ self._orig_graph = _session._graph
+ _session._graph = _FakeGraph()
+ _DummyTracker.calls = []
+
+ def tearDown(self):
+ import semantica_mcp.mcp.session as _session
+
+ _session._graph = self._orig_graph
+ _DummyTracker.calls = []
+
+
+class TestGetProvenanceSchema(unittest.TestCase):
+ """tools/list must keep advertising entity_id, not node_id."""
+
+ def test_schema_requires_entity_id(self):
+ from semantica_mcp.mcp.schemas import GET_PROVENANCE
+
+ self.assertEqual(GET_PROVENANCE["required"], ["entity_id"])
+ self.assertIn("entity_id", GET_PROVENANCE["properties"])
+ self.assertNotIn("node_id", GET_PROVENANCE["properties"])
+
+ def test_tools_list_advertises_entity_id(self):
+ from semantica_mcp.mcp.server import _handle_tools_list
+
+ response = _handle_tools_list(1, {})
+ tools = response["result"]["tools"]
+ provenance = next(t for t in tools if t["name"] == "get_provenance")
+ schema = provenance["inputSchema"]
+ self.assertEqual(schema["required"], ["entity_id"])
+ self.assertIn("entity_id", schema["properties"])
+ self.assertNotIn("node_id", schema["properties"])
+
+
+class TestGetProvenanceArgs(_GraphSessionMixin, unittest.TestCase):
+ """Handler reads entity_id (schema) and node_id (alias)."""
+
+ def _call(self, args):
+ from semantica_mcp.mcp.tools.export import handle_get_provenance
+
+ with patch("semantica.kg.ProvenanceTracker", _DummyTracker):
+ return handle_get_provenance(args)
+
+ def test_entity_id_is_accepted(self):
+ """The pre-fix failure: schema-compliant callers passed entity_id."""
+ result = self._call({"entity_id": "apple_inc"})
+ self.assertNotIn("error", result, result)
+ self.assertEqual(result["node_id"], "apple_inc")
+ self.assertEqual(_DummyTracker.calls, ["apple_inc"])
+ self.assertEqual(result["count"], 1)
+ self.assertEqual(result["provenance"][0]["source"], "unit-test")
+
+ def test_legacy_node_id_still_works(self):
+ result = self._call({"node_id": "apple_inc"})
+ self.assertNotIn("error", result, result)
+ self.assertEqual(result["node_id"], "apple_inc")
+ self.assertEqual(_DummyTracker.calls, ["apple_inc"])
+
+ def test_entity_id_wins_when_both_are_provided(self):
+ result = self._call({"entity_id": "apple_inc", "node_id": "other"})
+ self.assertNotIn("error", result, result)
+ self.assertEqual(result["node_id"], "apple_inc")
+ self.assertEqual(_DummyTracker.calls, ["apple_inc"])
+
+ def test_empty_entity_id_falls_back_to_node_id(self):
+ result = self._call({"entity_id": " ", "node_id": "apple_inc"})
+ self.assertNotIn("error", result, result)
+ self.assertEqual(result["node_id"], "apple_inc")
+ self.assertEqual(_DummyTracker.calls, ["apple_inc"])
+
+ def test_entity_id_is_stripped(self):
+ result = self._call({"entity_id": " apple_inc "})
+ self.assertNotIn("error", result, result)
+ self.assertEqual(result["node_id"], "apple_inc")
+ self.assertEqual(_DummyTracker.calls, ["apple_inc"])
+
+ def test_missing_id_errors_with_entity_id(self):
+ result = self._call({})
+ self.assertEqual(result["error"], "entity_id is required")
+ self.assertEqual(result["provenance"], [])
+ self.assertEqual(_DummyTracker.calls, [])
+
+ def test_whitespace_only_errors(self):
+ result = self._call({"entity_id": " ", "node_id": "\t"})
+ self.assertEqual(result["error"], "entity_id is required")
+ self.assertEqual(result["provenance"], [])
+ self.assertEqual(_DummyTracker.calls, [])
+
+ def test_empty_strings_error(self):
+ result = self._call({"entity_id": "", "node_id": ""})
+ self.assertEqual(result["error"], "entity_id is required")
+ self.assertEqual(_DummyTracker.calls, [])
+
+
+class TestGetProvenanceDispatch(_GraphSessionMixin, unittest.TestCase):
+ """JSON-RPC tools/call and call_tool use the same handler."""
+
+ def test_call_tool_with_entity_id_is_not_an_error(self):
+ from semantica_mcp.mcp.server import call_tool
+
+ with patch("semantica.kg.ProvenanceTracker", _DummyTracker):
+ result = call_tool("get_provenance", {"entity_id": "apple_inc"})
+ self.assertNotIn("error", result, result)
+ self.assertEqual(result["node_id"], "apple_inc")
+
+ def test_tools_call_entity_id_is_not_iserror(self):
+ from semantica_mcp.mcp.server import _handle_tools_call
+
+ with patch("semantica.kg.ProvenanceTracker", _DummyTracker):
+ response = _handle_tools_call(
+ 1, {"name": "get_provenance", "arguments": {"entity_id": "apple_inc"}}
+ )
+ self.assertNotIn("error", response)
+ self.assertFalse(response["result"]["isError"])
+ payload = json.loads(response["result"]["content"][0]["text"])
+ self.assertNotIn("error", payload)
+ self.assertEqual(payload["node_id"], "apple_inc")
+
+ def test_tools_call_missing_id_is_error_content(self):
+ from semantica_mcp.mcp.server import _handle_tools_call
+
+ response = _handle_tools_call(1, {"name": "get_provenance", "arguments": {}})
+ self.assertTrue(response["result"]["isError"])
+ payload = json.loads(response["result"]["content"][0]["text"])
+ self.assertEqual(payload["error"], "entity_id is required")
+
+
+class TestGetProvenanceGraphFallback(_GraphSessionMixin, unittest.TestCase):
+ """Production path: kg.ProvenanceTracker has no get_provenance method."""
+
+ def test_entity_id_reaches_graph_fallback(self):
+ from semantica_mcp.mcp.tools.export import handle_get_provenance
+
+ with warnings.catch_warnings():
+ warnings.simplefilter("ignore", DeprecationWarning)
+ result = handle_get_provenance({"entity_id": "apple_inc"})
+ self.assertNotIn("error", result, result)
+ self.assertEqual(result["node_id"], "apple_inc")
+ self.assertGreater(result["count"], 0)
+ self.assertIn("wiki", result.get("sources", []))
+
+
+if __name__ == "__main__":
+ unittest.main()