Graph-Native Infrastructure for Context and Accountable AI Systems
Python agent-memoryaiai-governanceai-infrastructureartificial-intelligencecontext-engineeringcontext-graphsdata-engineeringdecision-intelligencedeveloper-toolsexplainable-aigenerative-aigraph-ragknowledge-graphllmontologyprovenancepythonreasoningsemantic-search
fix(mcp): complete persistence and setup fixes (#1394)
Sameer Kadam798a7455e404
diff --git a/mcp/README.md b/mcp/README.mdindex bdbf25e1..c5487bc0 100644--- a/mcp/README.md+++ b/mcp/README.md@@ -8,8 +8,9 @@ Connects Claude Code, Cursor, Windsurf, Cline, Continue, VS Code (GitHub Copilot## Quick start```bash-# From the repo root-pip install -e ".[mcp]"+# From the repo root — no extra install flag needed; the root mcp/ package is+# part of the repository and does not require an external MCP SDK.+pip install -e .# Test the server (type a JSON-RPC request, press Enter)python -m mcp@@ -89,7 +90,14 @@ python -m mcp [--debug]## Per-tool configuration-### Claude Code (`~/.claude/settings.json`)+### Claude Code (`~/.claude.json` or `.mcp.json`)++Claude Code supports two MCP configuration scopes:++- **User scope** — `~/.claude.json` applies across all projects for your user account.+- **Project scope** — `.mcp.json` in your project root applies only to that project.++Both files use the same `mcpServers` structure:```json{@@ -97,15 +105,33 @@ python -m mcp [--debug]"semantica": {"command": "python","args": ["-m", "mcp"],- "cwd": "/path/to/semantica"+ "env": {+ "PYTHONPATH": "/path/to/semantica"+ }}}}```-Or use the plugin bundle:+> **Why `PYTHONPATH`?** The root `mcp/` package is intentionally not included in+> the installed wheel, so `python -m mcp` only works when the repository is on+> Python's import path. Setting `PYTHONPATH` here ensures this works regardless+> of the working directory Claude uses when it launches the server.++Or add it via the CLI (user scope):++```bash+claude mcp add --scope user semantica \+ -e PYTHONPATH=/path/to/semantica \+ -- python -m mcp+```++Or for project scope (omit `--scope user`):+```bash-claude mcp add semantica python -m mcp --cwd /path/to/semantica+claude mcp add semantica \+ -e PYTHONPATH=/path/to/semantica \+ -- python -m mcp```---@@ -216,7 +242,7 @@ Add to your Q Developer MCP config:| Variable | Default | Description ||---|---|---|-| `SEMANTICA_KG_PATH` | *(in-memory)* | Path to persist/load the graph (JSON file) |+| `SEMANTICA_KG_PATH` | *(in-memory only)* | Path to a JSON file used to **load** the graph on startup and **persist** mutations (record decisions, add entities/relationships) back to disk after each change. When unset the graph lives in memory only and is lost when the server exits. |---diff --git a/mcp/session.py b/mcp/session.pyindex 6569d1ad..da8ec7e2 100644--- a/mcp/session.py+++ b/mcp/session.py@@ -16,6 +16,13 @@ log = logging.getLogger("semantica.mcp.session")_graph: Optional[Any] = None+# Tracks whether the last graph initialisation successfully loaded the+# configured SEMANTICA_KG_PATH file. When True (or no path was configured)+# mutation handlers are allowed to save. When False an existing file failed+# to load; saving would overwrite the original data with an empty graph, so+# persistence is blocked until the process is restarted with a readable file.+_load_ok: bool = True+def get_graph() -> Any:"""@@ -24,24 +31,45 @@ def get_graph() -> Any:The graph is created with advanced_analytics=True so all centrality,community-detection, and embedding features are available."""- global _graph+ global _graph, _load_okif _graph is None:from semantica.context import ContextGraph_graph = ContextGraph(advanced_analytics=True)+ _load_ok = True # default: safe to persistkg_path = os.environ.get("SEMANTICA_KG_PATH", "").strip()if kg_path and os.path.exists(kg_path):- try:- _graph.load(kg_path)- log.info("Graph loaded from %s", kg_path)- except Exception as exc:- log.warning("Could not load graph from %s: %s", kg_path, exc)+ # Only attempt to load if the file has content. An empty file+ # means the path was just created (e.g. a fresh tempfile) and+ # should be treated as "start with empty graph" rather than a+ # corrupt-file failure.+ if os.path.getsize(kg_path) > 0:+ try:+ _graph.load_from_file(kg_path)+ log.info("Graph loaded from %s", kg_path)+ except Exception as exc:+ log.warning(+ "Could not load graph from %s: %s — persistence disabled "+ "to protect existing data; restart the server to retry.",+ kg_path, exc,+ )+ _load_ok = False # do not overwrite the original filereturn _graph+def is_persistence_safe() -> bool:+ """Return True when it is safe to write mutations back to SEMANTICA_KG_PATH.++ Returns False after a failed load so that mutation handlers do not+ overwrite the original (possibly intact) file with a fresh empty graph.+ """+ return _load_ok++def reset_graph() -> None:"""Reset the singleton (mainly useful in tests)."""- global _graph+ global _graph, _load_ok_graph = None+ _load_ok = Truediff --git a/mcp/tools/decisions.py b/mcp/tools/decisions.pyindex a0643d12..ca73ca69 100644--- a/mcp/tools/decisions.py+++ b/mcp/tools/decisions.py@@ -5,6 +5,7 @@ Decision intelligence tools — record, query, precedents, causal chain, impact.from __future__ import annotationsimport logging+import osfrom mcp.schemas import (ANALYZE_DECISION_IMPACT,@@ -13,7 +14,7 @@ from mcp.schemas import (QUERY_DECISIONS,RECORD_DECISION,)-from mcp.session import get_graph+from mcp.session import get_graph, is_persistence_safelog = logging.getLogger("semantica.mcp.tools.decisions")@@ -37,6 +38,39 @@ def handle_record_decision(args: dict) -> dict:valid_from=args.get("valid_from"),valid_until=args.get("valid_until"),)+ # Persist back to disk so the decision survives server restarts.+ # Skip when the initial load failed to avoid overwriting original data.+ kg_path = os.environ.get("SEMANTICA_KG_PATH", "").strip()+ if kg_path:+ if not is_persistence_safe():+ # Roll back the in-memory mutation so the client-visible state+ # matches the persisted state (neither is saved).+ if hasattr(graph, "_decisions") and decision_id in graph._decisions:+ del graph._decisions[decision_id]+ if hasattr(graph, "_decision_index"):+ cat = args.get("category", "")+ if cat in graph._decision_index:+ graph._decision_index[cat].discard(decision_id)+ return {+ "error": (+ "Persistence blocked: the configured SEMANTICA_KG_PATH "+ "could not be loaded at startup. Restart the server with "+ "a readable graph file to re-enable persistence."+ )+ }+ try:+ graph.save_to_file(kg_path)+ except Exception as save_exc:+ # Atomic write failed. Roll back the in-memory mutation so the+ # client-visible and persisted states remain consistent.+ if hasattr(graph, "_decisions") and decision_id in graph._decisions:+ del graph._decisions[decision_id]+ if hasattr(graph, "_decision_index"):+ cat = args.get("category", "")+ if cat in graph._decision_index:+ graph._decision_index[cat].discard(decision_id)+ log.exception("save_to_file failed after record_decision; mutation rolled back")+ return {"error": f"Mutation rolled back: could not persist graph: {save_exc}"}return {"decision_id": decision_id,"status": "recorded",diff --git a/mcp/tools/graph.py b/mcp/tools/graph.pyindex 5508025b..65afdc3c 100644--- a/mcp/tools/graph.py+++ b/mcp/tools/graph.py@@ -5,9 +5,10 @@ Graph tools — add entities/relationships, search, analytics, summary.from __future__ import annotationsimport logging+import osfrom mcp.schemas import ADD_ENTITY, ADD_RELATIONSHIP, EMPTY, GET_ANALYTICS, SEARCH_GRAPH-from mcp.session import get_graph+from mcp.session import get_graph, is_persistence_safelog = logging.getLogger("semantica.mcp.tools.graph")@@ -25,6 +26,35 @@ def handle_add_entity(args: dict) -> dict:node_type=args.get("type", "Entity"),metadata=args.get("metadata", {}),)+ # Persist back to disk so the entity survives server restarts.+ # Skip when the initial load failed to avoid overwriting original data.+ kg_path = os.environ.get("SEMANTICA_KG_PATH", "").strip()+ if kg_path:+ if not is_persistence_safe():+ # Roll back: remove the node we just added.+ try:+ with graph._lock:+ graph._drop_node_from_indexes(node_id)+ except Exception:+ pass+ return {+ "error": (+ "Persistence blocked: the configured SEMANTICA_KG_PATH "+ "could not be loaded at startup. Restart the server with "+ "a readable graph file to re-enable persistence."+ )+ }+ try:+ graph.save_to_file(kg_path)+ except Exception as save_exc:+ # Roll back: remove the node so in-memory and persisted state agree.+ try:+ with graph._lock:+ graph._drop_node_from_indexes(node_id)+ except Exception:+ pass+ log.exception("save_to_file failed after add_entity; mutation rolled back")+ return {"error": f"Mutation rolled back: could not persist graph: {save_exc}"}return {"status": "added", "id": node_id, "type": args.get("type", "Entity")}except Exception as exc:log.exception("add_entity failed")@@ -46,6 +76,45 @@ def handle_add_relationship(args: dict) -> dict:edge_type=rel_type,metadata=args.get("metadata", {}),)+ # Persist back to disk so the relationship survives server restarts.+ # Skip when the initial load failed to avoid overwriting original data.+ kg_path = os.environ.get("SEMANTICA_KG_PATH", "").strip()+ if kg_path:+ if not is_persistence_safe():+ # Roll back: remove the edge we just added (last matching edge).+ try:+ with graph._lock:+ for edge in reversed(list(graph.edges)):+ if (edge.source_id == source+ and edge.target_id == target+ and edge.edge_type == rel_type):+ graph._drop_edge_from_indexes(edge)+ break+ except Exception:+ pass+ return {+ "error": (+ "Persistence blocked: the configured SEMANTICA_KG_PATH "+ "could not be loaded at startup. Restart the server with "+ "a readable graph file to re-enable persistence."+ )+ }+ try:+ graph.save_to_file(kg_path)+ except Exception as save_exc:+ # Roll back: remove the edge so in-memory and persisted state agree.+ try:+ with graph._lock:+ for edge in reversed(list(graph.edges)):+ if (edge.source_id == source+ and edge.target_id == target+ and edge.edge_type == rel_type):+ graph._drop_edge_from_indexes(edge)+ break+ except Exception:+ pass+ log.exception("save_to_file failed after add_relationship; mutation rolled back")+ return {"error": f"Mutation rolled back: could not persist graph: {save_exc}"}return {"status": "added", "source": source, "target": target, "type": rel_type}except Exception as exc:log.exception("add_relationship failed")diff --git a/semantica/context/context_graph.py b/semantica/context/context_graph.pyindex b8581725..9ad645e8 100644--- a/semantica/context/context_graph.py+++ b/semantica/context/context_graph.py@@ -1203,8 +1203,30 @@ class ContextGraph:"links": links_data,}- with open(path, "w", encoding="utf-8") as f:- json.dump(data, f, indent=2, ensure_ascii=False)+ # Write atomically: serialize to a sibling temp file then replace the+ # destination in one OS-level rename. This guarantees the destination+ # is either the old contents or the new contents — never a partial write+ # — so a crash or disk-full error during json.dump cannot corrupt the+ # sole persisted copy of the graph.+ dest = Path(path)+ dest.parent.mkdir(parents=True, exist_ok=True)+ fd, tmp_path = tempfile.mkstemp(+ dir=dest.parent, prefix=".kg_tmp_", suffix=".json"+ )+ try:+ with os.fdopen(fd, "w", encoding="utf-8") as f:+ json.dump(data, f, indent=2, ensure_ascii=False)+ f.flush()+ os.fsync(f.fileno())+ os.replace(tmp_path, dest)+ except Exception:+ # Clean up the temp file on any failure so we don't litter the+ # directory with partial writes.+ try:+ os.unlink(tmp_path)+ except OSError:+ pass+ raiseself.logger.info(f"Saved context graph to {path}")diff --git a/semantica/mcp_server/__init__.py b/semantica/mcp_server/__init__.pyindex 05b9d322..03692c1f 100644--- a/semantica/mcp_server/__init__.py+++ b/semantica/mcp_server/__init__.py@@ -72,19 +72,34 @@ os.environ["SEMANTICA_DISABLE_PROGRESS"] = "1"# ── lazy graph session ──────────────────────────────────────────────────────_graph: Any = None+# Tracks whether the last _get_graph() call successfully loaded the configured+# SEMANTICA_KG_PATH file. When False (load failed) mutation handlers skip+# save_to_file to avoid overwriting the original file with an empty graph.+_kg_load_ok: bool = True+def _get_graph():- global _graph+ global _graph, _kg_load_okif _graph is None:from semantica.context import ContextGraph_graph = ContextGraph(advanced_analytics=True)+ _kg_load_ok = True # default: safe to persistkg_path = os.environ.get("SEMANTICA_KG_PATH")if kg_path and os.path.exists(kg_path):- try:- _graph.load_from_file(kg_path)- log.info("Loaded graph from %s", kg_path)- except Exception as exc:- log.warning("Could not load graph from %s: %s", kg_path, exc)+ # Only attempt to load if the file has content. An empty file+ # means the path was just created (fresh destination) and should+ # be treated as "start with empty graph" not a corrupt-file failure.+ if os.path.getsize(kg_path) > 0:+ try:+ _graph.load_from_file(kg_path)+ log.info("Loaded graph from %s", kg_path)+ except Exception as exc:+ log.warning(+ "Could not load graph from %s: %s — persistence disabled "+ "to protect existing data; restart the server to retry.",+ kg_path, exc,+ )+ _kg_load_ok = False # do not overwrite the original filereturn _graph@@ -179,6 +194,35 @@ def _tool_record_decision(args: dict) -> dict:valid_from=args.get("valid_from"),valid_until=args.get("valid_until"),)+ # Persist back to disk so the decision survives server restarts.+ kg_path = os.environ.get("SEMANTICA_KG_PATH")+ if kg_path:+ if not _kg_load_ok:+ # Roll back to keep in-memory state consistent with persisted state.+ if hasattr(graph, "_decisions") and decision_id in graph._decisions:+ del graph._decisions[decision_id]+ if hasattr(graph, "_decision_index"):+ cat = args.get("category", "")+ if cat in graph._decision_index:+ graph._decision_index[cat].discard(decision_id)+ return {+ "error": (+ "Persistence blocked: the configured SEMANTICA_KG_PATH "+ "could not be loaded at startup. Restart the server to retry."+ )+ }+ try:+ graph.save_to_file(kg_path)+ except Exception as save_exc:+ # Atomic write failed. Roll back to keep states consistent.+ if hasattr(graph, "_decisions") and decision_id in graph._decisions:+ del graph._decisions[decision_id]+ if hasattr(graph, "_decision_index"):+ cat = args.get("category", "")+ if cat in graph._decision_index:+ graph._decision_index[cat].discard(decision_id)+ log.exception("save_to_file failed after record_decision; mutation rolled back")+ return {"error": f"Mutation rolled back: could not persist graph: {save_exc}"}return {"decision_id": decision_id, "status": "recorded"}@@ -246,6 +290,31 @@ def _tool_add_entity(args: dict) -> dict:graph = _get_graph()graph.add_node(node_id=node_id, label=label, node_type=node_type,metadata=args.get("metadata", {}))+ # Persist back to disk so the entity survives server restarts.+ kg_path = os.environ.get("SEMANTICA_KG_PATH")+ if kg_path:+ if not _kg_load_ok:+ try:+ with graph._lock:+ graph._drop_node_from_indexes(node_id)+ except Exception:+ pass+ return {+ "error": (+ "Persistence blocked: the configured SEMANTICA_KG_PATH "+ "could not be loaded at startup. Restart the server to retry."+ )+ }+ try:+ graph.save_to_file(kg_path)+ except Exception as save_exc:+ try:+ with graph._lock:+ graph._drop_node_from_indexes(node_id)+ except Exception:+ pass+ log.exception("save_to_file failed after add_entity; mutation rolled back")+ return {"error": f"Mutation rolled back: could not persist graph: {save_exc}"}return {"status": "added", "id": node_id}@@ -259,6 +328,41 @@ def _tool_add_relationship(args: dict) -> dict:graph = _get_graph()graph.add_edge(source_id=source, target_id=target, edge_type=rel_type,metadata=args.get("metadata", {}))+ # Persist back to disk so the relationship survives server restarts.+ kg_path = os.environ.get("SEMANTICA_KG_PATH")+ if kg_path:+ if not _kg_load_ok:+ try:+ with graph._lock:+ for edge in reversed(list(graph.edges)):+ if (edge.source_id == source+ and edge.target_id == target+ and edge.edge_type == rel_type):+ graph._drop_edge_from_indexes(edge)+ break+ except Exception:+ pass+ return {+ "error": (+ "Persistence blocked: the configured SEMANTICA_KG_PATH "+ "could not be loaded at startup. Restart the server to retry."+ )+ }+ try:+ graph.save_to_file(kg_path)+ except Exception as save_exc:+ try:+ with graph._lock:+ for edge in reversed(list(graph.edges)):+ if (edge.source_id == source+ and edge.target_id == target+ and edge.edge_type == rel_type):+ graph._drop_edge_from_indexes(edge)+ break+ except Exception:+ pass+ log.exception("save_to_file failed after add_relationship; mutation rolled back")+ return {"error": f"Mutation rolled back: could not persist graph: {save_exc}"}return {"status": "added", "source": source, "target": target, "type": rel_type}diff --git a/tests/context/test_decision_persistence_pr967.py b/tests/context/test_decision_persistence_pr967.pyindex dd96fed4..8971222e 100644--- a/tests/context/test_decision_persistence_pr967.py+++ b/tests/context/test_decision_persistence_pr967.py@@ -1037,5 +1037,195 @@ class TestClearResetsDecisionIndexes(unittest.TestCase):self.assertEqual(g._decisions[did]["category"], "new")+# ---------------------------------------------------------------------------+# Part 15: semantica.mcp_server mutation persistence (#1134)+# ---------------------------------------------------------------------------++class TestMCPServerMutationPersistence(unittest.TestCase):+ """_tool_record_decision, _tool_add_entity, and _tool_add_relationship must+ each call save_to_file when SEMANTICA_KG_PATH is configured so mutations+ survive server restarts.++ Mirrors update_node / delete_node which already had this behaviour from+ PR #967. These tests extend coverage to the three previously missing tools.+ """++ # ---- helpers --------------------------------------------------------++ def _isolated_mcp_graph(self):+ """Return a fresh ContextGraph injected as the mcp_server singleton."""+ import semantica.mcp_server as mcp_mod+ g = ContextGraph(advanced_analytics=False)+ self._original_graph = mcp_mod._graph+ mcp_mod._graph = g+ return g++ def _restore_mcp_graph(self):+ import semantica.mcp_server as mcp_mod+ mcp_mod._graph = self._original_graph++ # ---- record_decision ------------------------------------------------++ def test_record_decision_persists_to_kg_path(self):+ """_tool_record_decision must write the graph to SEMANTICA_KG_PATH."""+ from semantica.mcp_server import _tool_record_decision++ g = self._isolated_mcp_graph()+ try:+ with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:+ path = f.name+ try:+ with patch.dict(os.environ, {"SEMANTICA_KG_PATH": path}):+ result = _tool_record_decision({+ "category": "mcp_server_persist",+ "scenario": "Testing packaged server persistence",+ "reasoning": "save_to_file must be called on mutation",+ "outcome": "verified",+ "confidence": 0.99,+ })++ self.assertNotIn("error", result, result)+ self.assertIn("decision_id", result)++ # File must have been written.+ self.assertGreater(os.path.getsize(path), 0,+ "save_to_file must have written to the KG_PATH file")++ # Simulate restart: reload into a fresh graph.+ g2 = ContextGraph(advanced_analytics=False)+ g2.load_from_file(path)+ decisions = list(g2.find_nodes(node_type="decision"))+ self.assertGreater(len(decisions), 0,+ "Decision must be present after save → load")+ cats = [d.get("category") or (d.get("metadata") or {}).get("category")+ for d in decisions]+ self.assertIn("mcp_server_persist", cats)+ finally:+ os.unlink(path)+ finally:+ self._restore_mcp_graph()++ def test_record_decision_works_without_kg_path(self):+ """_tool_record_decision must succeed when SEMANTICA_KG_PATH is unset."""+ from semantica.mcp_server import _tool_record_decision++ g = self._isolated_mcp_graph()+ try:+ env = {k: v for k, v in os.environ.items() if k != "SEMANTICA_KG_PATH"}+ with patch.dict(os.environ, env, clear=True):+ result = _tool_record_decision({+ "category": "no_path",+ "scenario": "no kg path",+ "reasoning": "in-memory only",+ "outcome": "ok",+ "confidence": 0.5,+ })+ self.assertNotIn("error", result, result)+ self.assertIn("decision_id", result)+ finally:+ self._restore_mcp_graph()++ # ---- add_entity -----------------------------------------------------++ def test_add_entity_persists_to_kg_path(self):+ """_tool_add_entity must write the graph to SEMANTICA_KG_PATH."""+ from semantica.mcp_server import _tool_add_entity++ g = self._isolated_mcp_graph()+ try:+ with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:+ path = f.name+ try:+ with patch.dict(os.environ, {"SEMANTICA_KG_PATH": path}):+ result = _tool_add_entity({+ "id": "mcp_server_entity_test",+ "label": "Persistence Entity",+ "type": "TestEntity",+ })++ self.assertNotIn("error", result, result)+ self.assertEqual(result.get("status"), "added")++ self.assertGreater(os.path.getsize(path), 0)++ g2 = ContextGraph(advanced_analytics=False)+ g2.load_from_file(path)+ self.assertTrue(g2.has_node("mcp_server_entity_test"),+ "Entity must be present after save → load")+ finally:+ os.unlink(path)+ finally:+ self._restore_mcp_graph()++ def test_add_entity_works_without_kg_path(self):+ """_tool_add_entity must succeed when SEMANTICA_KG_PATH is unset."""+ from semantica.mcp_server import _tool_add_entity++ g = self._isolated_mcp_graph()+ try:+ env = {k: v for k, v in os.environ.items() if k != "SEMANTICA_KG_PATH"}+ with patch.dict(os.environ, env, clear=True):+ result = _tool_add_entity({"id": "ephemeral_ent", "label": "E"})+ self.assertNotIn("error", result, result)+ self.assertEqual(result.get("status"), "added")+ finally:+ self._restore_mcp_graph()++ # ---- add_relationship -----------------------------------------------++ def test_add_relationship_persists_to_kg_path(self):+ """_tool_add_relationship must write the graph to SEMANTICA_KG_PATH."""+ from semantica.mcp_server import _tool_add_entity, _tool_add_relationship++ g = self._isolated_mcp_graph()+ try:+ with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:+ path = f.name+ try:+ with patch.dict(os.environ, {"SEMANTICA_KG_PATH": path}):+ _tool_add_entity({"id": "rel_src_mcp", "label": "Source"})+ _tool_add_entity({"id": "rel_tgt_mcp", "label": "Target"})+ result = _tool_add_relationship({+ "source": "rel_src_mcp",+ "target": "rel_tgt_mcp",+ "type": "PROVEN_BY",+ })++ self.assertNotIn("error", result, result)+ self.assertEqual(result.get("status"), "added")++ self.assertGreater(os.path.getsize(path), 0)++ g2 = ContextGraph(advanced_analytics=False)+ g2.load_from_file(path)+ edges = list(g2.find_edges())+ self.assertTrue(any(e.get("type") == "PROVEN_BY" for e in edges),+ "PROVEN_BY edge must be present after save → load")+ finally:+ os.unlink(path)+ finally:+ self._restore_mcp_graph()++ def test_add_relationship_works_without_kg_path(self):+ """_tool_add_relationship must succeed when SEMANTICA_KG_PATH is unset."""+ from semantica.mcp_server import _tool_add_entity, _tool_add_relationship++ g = self._isolated_mcp_graph()+ try:+ env = {k: v for k, v in os.environ.items() if k != "SEMANTICA_KG_PATH"}+ with patch.dict(os.environ, env, clear=True):+ _tool_add_entity({"id": "src_no_p", "label": "S"})+ _tool_add_entity({"id": "tgt_no_p", "label": "T"})+ result = _tool_add_relationship({+ "source": "src_no_p",+ "target": "tgt_no_p",+ "type": "RELATED_TO",+ })+ self.assertNotIn("error", result, result)+ self.assertEqual(result.get("status"), "added")+ finally:+ self._restore_mcp_graph()++if __name__ == "__main__":unittest.main()diff --git a/tests/test_mcp_package_persistence.py b/tests/test_mcp_package_persistence.pynew file mode 100644index 00000000..ce834c49--- /dev/null+++ b/tests/test_mcp_package_persistence.py@@ -0,0 +1,294 @@+"""Regression tests for root mcp/ graph persistence (issue #1134).++Covers:+ 1. get_graph() loads an existing JSON file via load_from_file(), not the+ nonexistent .load() method (the original bug).+ 2. get_graph() with a nonexistent / unset SEMANTICA_KG_PATH starts cleanly.+ 3. handle_record_decision persists to SEMANTICA_KG_PATH and the mutation+ survives a fresh load_from_file() call.+ 4. handle_add_entity persists to SEMANTICA_KG_PATH and survives reload.+ 5. handle_add_relationship persists to SEMANTICA_KG_PATH and survives reload.+ 6. All three mutation tools work correctly when SEMANTICA_KG_PATH is unset+ (no errors, no persistence attempt).+"""++from __future__ import annotations++import os+import tempfile+import unittest+from unittest.mock import patch++from semantica.context.context_graph import ContextGraph++import mcp.session as _session+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------++def _fresh_graph() -> ContextGraph:+ """Return a minimal ContextGraph ready for use in tests."""+ g = ContextGraph(advanced_analytics=False)+ g.add_node("seed_node", node_type="entity", label="Seed")+ return g+++class _IsolatedSession:+ """Context manager that resets the mcp.session singleton before and after+ each test so tests are independent of process-level state."""++ def __enter__(self):+ _session.reset_graph()+ return self++ def __exit__(self, *_):+ _session.reset_graph()+++# ---------------------------------------------------------------------------+# 1. get_graph() loading — regression against _graph.load()+# ---------------------------------------------------------------------------++class TestMCPSessionLoad(unittest.TestCase):+ """get_graph() must load an existing file using load_from_file(), not .load()."""++ def test_get_graph_loads_existing_kg_path(self):+ """When SEMANTICA_KG_PATH points to a valid JSON file the graph must+ contain the persisted nodes after get_graph() returns."""+ g = _fresh_graph()+ g.add_node("persistent_node", node_type="entity", label="Should survive")++ with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:+ path = f.name+ try:+ g.save_to_file(path)++ with _IsolatedSession():+ with patch.dict(os.environ, {"SEMANTICA_KG_PATH": path}):+ loaded = _session.get_graph()++ self.assertTrue(+ loaded.has_node("persistent_node"),+ "Node saved before server start must be present after load",+ )+ self.assertTrue(+ loaded.has_node("seed_node"),+ "seed_node from the persisted graph must also be present",+ )+ finally:+ os.unlink(path)++ def test_get_graph_with_nonexistent_kg_path_starts_empty(self):+ """When SEMANTICA_KG_PATH does not exist the graph initialises empty+ (no error) — matching pre-existing behaviour."""+ with _IsolatedSession():+ with patch.dict(os.environ, {"SEMANTICA_KG_PATH": "/nonexistent/path.json"}):+ loaded = _session.get_graph()++ # An empty graph has no nodes; at minimum it must be a ContextGraph.+ self.assertIsNotNone(loaded)+ nodes = list(loaded.find_nodes())+ self.assertEqual(nodes, [], "Graph must be empty when KG_PATH does not exist")++ def test_get_graph_without_kg_path_starts_empty(self):+ """When SEMANTICA_KG_PATH is absent the graph initialises empty."""+ with _IsolatedSession():+ env = {k: v for k, v in os.environ.items() if k != "SEMANTICA_KG_PATH"}+ with patch.dict(os.environ, env, clear=True):+ loaded = _session.get_graph()++ self.assertIsNotNone(loaded)++ def test_get_graph_uses_load_from_file_not_load(self):+ """Regression: ContextGraph has no .load() method; get_graph() must+ call load_from_file() or the AttributeError is silently swallowed and+ the graph silently stays empty. This test verifies the fix directly."""+ g = _fresh_graph()+ with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:+ path = f.name+ try:+ g.save_to_file(path)++ with _IsolatedSession():+ with patch.dict(os.environ, {"SEMANTICA_KG_PATH": path}):+ # If the old _graph.load(path) bug were present the graph+ # would be empty (exception swallowed). With the fix the+ # node must be present.+ loaded = _session.get_graph()++ self.assertTrue(+ loaded.has_node("seed_node"),+ "load_from_file must have been called; if .load() was used "+ "the AttributeError is swallowed and the graph stays empty",+ )+ finally:+ os.unlink(path)+++# ---------------------------------------------------------------------------+# 2–5. Mutation persistence+# ---------------------------------------------------------------------------++class TestMCPPackageMutationPersistence(unittest.TestCase):+ """Mutations via the root mcp/ tool handlers must persist to SEMANTICA_KG_PATH+ so the data survives a server restart (simulated by a fresh load_from_file)."""++ # ---- record_decision ------------------------------------------------++ def test_record_decision_persists_when_kg_path_set(self):+ """handle_record_decision must write to disk when SEMANTICA_KG_PATH is set."""+ from mcp.tools.decisions import handle_record_decision++ with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:+ path = f.name+ try:+ with _IsolatedSession():+ with patch.dict(os.environ, {"SEMANTICA_KG_PATH": path}):+ result = handle_record_decision({+ "category": "test_persistence",+ "scenario": "Verifying mcp/ decision persistence",+ "reasoning": "KG_PATH must be written on mutation",+ "outcome": "verified",+ "confidence": 0.99,+ })++ self.assertNotIn("error", result, result)+ self.assertIn("decision_id", result)++ # The file must have been written (or overwritten from empty).+ self.assertTrue(os.path.exists(path), "save_to_file must create the file")+ self.assertGreater(os.path.getsize(path), 0, "Persisted file must not be empty")++ # Simulate server restart: load into a fresh graph.+ g2 = ContextGraph(advanced_analytics=False)+ g2.load_from_file(path)+ decisions = list(g2.find_nodes(node_type="decision"))+ self.assertGreater(len(decisions), 0, "Decision must survive reload")+ cats = [d.get("category") or (d.get("metadata") or {}).get("category")+ for d in decisions]+ self.assertIn("test_persistence", cats,+ "Decision category must be present after reload")+ finally:+ os.unlink(path)++ def test_record_decision_works_without_kg_path(self):+ """handle_record_decision must succeed even when SEMANTICA_KG_PATH is unset."""+ from mcp.tools.decisions import handle_record_decision++ with _IsolatedSession():+ env = {k: v for k, v in os.environ.items() if k != "SEMANTICA_KG_PATH"}+ with patch.dict(os.environ, env, clear=True):+ result = handle_record_decision({+ "category": "no_path",+ "scenario": "No persistence path configured",+ "reasoning": "Should still work in-memory",+ "outcome": "ok",+ "confidence": 0.5,+ })++ self.assertNotIn("error", result, result)+ self.assertIn("decision_id", result)++ # ---- add_entity -----------------------------------------------------++ def test_add_entity_persists_when_kg_path_set(self):+ """handle_add_entity must write to disk when SEMANTICA_KG_PATH is set."""+ from mcp.tools.graph import handle_add_entity++ with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:+ path = f.name+ try:+ with _IsolatedSession():+ with patch.dict(os.environ, {"SEMANTICA_KG_PATH": path}):+ result = handle_add_entity({+ "id": "entity_persist_test",+ "label": "Persistence Test Entity",+ "type": "TestType",+ })++ self.assertNotIn("error", result, result)+ self.assertEqual(result.get("status"), "added")++ self.assertTrue(os.path.exists(path))+ self.assertGreater(os.path.getsize(path), 0)++ g2 = ContextGraph(advanced_analytics=False)+ g2.load_from_file(path)+ self.assertTrue(+ g2.has_node("entity_persist_test"),+ "Entity must be present in the graph after reload",+ )+ finally:+ os.unlink(path)++ def test_add_entity_works_without_kg_path(self):+ """handle_add_entity must succeed when SEMANTICA_KG_PATH is unset."""+ from mcp.tools.graph import handle_add_entity++ with _IsolatedSession():+ env = {k: v for k, v in os.environ.items() if k != "SEMANTICA_KG_PATH"}+ with patch.dict(os.environ, env, clear=True):+ result = handle_add_entity({"id": "no_path_entity", "label": "ephemeral"})++ self.assertNotIn("error", result, result)+ self.assertEqual(result.get("status"), "added")++ # ---- add_relationship -----------------------------------------------++ def test_add_relationship_persists_when_kg_path_set(self):+ """handle_add_relationship must write to disk when SEMANTICA_KG_PATH is set."""+ from mcp.tools.graph import handle_add_relationship++ with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:+ path = f.name+ try:+ with _IsolatedSession():+ with patch.dict(os.environ, {"SEMANTICA_KG_PATH": path}):+ # Nodes must exist before an edge can be added.+ from mcp.tools.graph import handle_add_entity+ handle_add_entity({"id": "rel_src", "label": "Source"})+ handle_add_entity({"id": "rel_tgt", "label": "Target"})+ result = handle_add_relationship({+ "source": "rel_src",+ "target": "rel_tgt",+ "type": "TESTED_BY",+ })++ self.assertNotIn("error", result, result)+ self.assertEqual(result.get("status"), "added")++ self.assertTrue(os.path.exists(path))+ self.assertGreater(os.path.getsize(path), 0)++ g2 = ContextGraph(advanced_analytics=False)+ g2.load_from_file(path)+ edges = list(g2.find_edges())+ edge_types = [e.get("type") for e in edges]+ self.assertIn("TESTED_BY", edge_types,+ "Relationship must be present after reload")+ finally:+ os.unlink(path)++ def test_add_relationship_works_without_kg_path(self):+ """handle_add_relationship must succeed when SEMANTICA_KG_PATH is unset."""+ from mcp.tools.graph import handle_add_entity, handle_add_relationship++ with _IsolatedSession():+ env = {k: v for k, v in os.environ.items() if k != "SEMANTICA_KG_PATH"}+ with patch.dict(os.environ, env, clear=True):+ handle_add_entity({"id": "src_no_path", "label": "S"})+ handle_add_entity({"id": "tgt_no_path", "label": "T"})+ result = handle_add_relationship({+ "source": "src_no_path",+ "target": "tgt_no_path",+ "type": "RELATED_TO",+ })++ self.assertNotIn("error", result, result)+ self.assertEqual(result.get("status"), "added")+++if __name__ == "__main__":+ unittest.main()diff --git a/tests/test_mcp_stdio_roundtrip.py b/tests/test_mcp_stdio_roundtrip.pynew file mode 100644index 00000000..acf2bd9c--- /dev/null+++ b/tests/test_mcp_stdio_roundtrip.py@@ -0,0 +1,180 @@+"""MCP stdio JSON-RPC framing regression test (#1134, point 1).++The original bug: progress output from the Semantica progress tracker was+written to sys.stdout, which is also the MCP JSON-RPC transport channel.+Interleaving progress text with JSON-RPC responses made every response+unparseable and hung the client.++These tests exercise the *actual* root mcp/ server stdio framing loop+(SemanticaMCPServer.run()) over a real subprocess pipe, not just the handler+layer. They prove that:++ 1. Every non-empty stdout line produced by the running server is valid JSON.+ 2. A valid JSON-RPC response is received for each request sent.+ 3. No progress / non-JSON bytes appear on stdout even when a tool triggers+ the progress-producing code path (constructing a ContextGraph, which+ calls get_progress_tracker() and attempts to enable the tracker).++Tests that are already covered elsewhere are not duplicated here:+ - ConsoleProgressDisplay writing to stderr (test_progress_stream.py)+ - SEMANTICA_DISABLE_PROGRESS blocking re-enable (test_progress_tracker_regressions.py)+ - mcp import sets SEMANTICA_DISABLE_PROGRESS (test_mcp_package_export_graph.py)+"""++from __future__ import annotations++import json+import os+import subprocess+import sys+import unittest+++# ---------------------------------------------------------------------------+# Module-level helpers+# ---------------------------------------------------------------------------++def _repo_root() -> str:+ return os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))+++def _subprocess_env() -> dict[str, str]:+ """Clean env with the repo on PYTHONPATH and no pre-set progress flag."""+ env = os.environ.copy()+ env["PYTHONPATH"] = _repo_root()+ env.pop("SEMANTICA_DISABLE_PROGRESS", None)+ return env+++def _jsonrpc(method: str, req_id: int | None, params: dict | None = None) -> bytes:+ msg: dict = {"jsonrpc": "2.0", "method": method}+ if req_id is not None:+ msg["id"] = req_id+ if params is not None:+ msg["params"] = params+ return (json.dumps(msg) + "\n").encode()+++def _assert_stdout_is_clean_json(test: unittest.TestCase,+ stdout: str,+ stderr: str = "") -> list[dict]:+ """Assert every non-empty stdout line is valid JSON; return parsed objects.++ Fails immediately with a useful diagnostic if any line is not JSON.+ """+ lines = [ln for ln in stdout.splitlines() if ln.strip()]+ test.assertGreater(+ len(lines), 0,+ f"Expected at least one stdout line but got none.\nstderr={stderr!r}",+ )+ parsed = []+ for i, line in enumerate(lines):+ try:+ parsed.append(json.loads(line))+ except json.JSONDecodeError as exc:+ test.fail(+ f"stdout line {i} is not valid JSON (regression: progress leaked "+ f"to stdout?)\n line: {line!r}\n error: {exc}\n stderr={stderr!r}"+ )+ return parsed+++_INIT_REQUEST = _jsonrpc("initialize", 1, {+ "protocolVersion": "2024-11-05",+ "clientInfo": {"name": "test", "version": "0"},+ "capabilities": {},+})+++# ---------------------------------------------------------------------------+# Main regression suite+# ---------------------------------------------------------------------------++class TestMCPStdioFramingContract(unittest.TestCase):+ """Run 'python -m mcp' exactly as an MCP client would, over a real pipe.++ Each test sends a complete JSON-RPC session through stdin and asserts that+ every byte on stdout is valid JSON — catching the exact failure mode from+ #1134 where progress output corrupted the transport stream.+ """++ TIMEOUT = 30++ def _run(self, *requests: bytes) -> subprocess.CompletedProcess:+ return subprocess.run(+ [sys.executable, "-m", "mcp"],+ input=b"".join(requests),+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ timeout=self.TIMEOUT,+ cwd=_repo_root(),+ env=_subprocess_env(),+ check=False,+ )++ # ------------------------------------------------------------------++ def test_initialize_stdout_is_valid_json_rpc(self):+ """An initialize request must produce a single valid JSON-RPC response."""+ proc = self._run(_INIT_REQUEST)++ self.assertEqual(proc.returncode, 0,+ f"server crashed:\n{proc.stderr.decode()}")+ responses = _assert_stdout_is_clean_json(+ self, proc.stdout.decode(), proc.stderr.decode()+ )+ init_resp = next((r for r in responses if r.get("id") == 1), None)+ self.assertIsNotNone(init_resp, f"No id=1 response in: {responses}")+ self.assertIn("serverInfo", init_resp.get("result", {}))++ def test_tools_call_stdout_is_clean_json_rpc(self):+ """A tools/call round-trip through the full stdio framing loop must keep+ stdout free of any non-JSON bytes.++ run_reasoning is used because Reasoner.infer_with_results() explicitly+ calls self.progress_tracker.start_tracking(), making it the minimal+ deterministic tool path that exercises the progress-rendering code.+ Before the #1134 fix, that start_tracking call wrote a progress bar+ directly to stdout, corrupting the JSON-RPC framing. Every byte on+ stdout must still be valid JSON-RPC after the fix.+ """+ proc = self._run(+ _INIT_REQUEST,+ _jsonrpc("notifications/initialized", None),+ _jsonrpc("tools/call", 2, {+ "name": "run_reasoning",+ "arguments": {+ "facts": ["Person(Alice)", "Employee(Alice)"],+ "rules": ["IF Employee(?x) THEN Worker(?x)"],+ },+ }),+ )+ self.assertEqual(proc.returncode, 0,+ f"server crashed:\n{proc.stderr.decode()}")++ stdout = proc.stdout.decode()+ stderr = proc.stderr.decode()+ responses = _assert_stdout_is_clean_json(self, stdout, stderr)++ tool_resp = next((r for r in responses if r.get("id") == 2), None)+ self.assertIsNotNone(+ tool_resp,+ f"No id=2 response in stdout.\nstdout={stdout!r}\nstderr={stderr!r}",+ )+ # The framing must be a valid JSON-RPC result object regardless of+ # whether the reasoner dependency is available in this environment.+ self.assertIn("jsonrpc", tool_resp)+ self.assertEqual(tool_resp["jsonrpc"], "2.0")+ self.assertIn("id", tool_resp)+ # If the tool succeeded the response must carry MCP content.+ if "result" in tool_resp:+ content = tool_resp["result"].get("content", [])+ self.assertGreater(len(content), 0,+ "Expected non-empty content list in result")+ # The embedded tool payload must itself be valid JSON.+ inner = json.loads(content[0]["text"])+ self.assertIn("derived_facts", inner)+++if __name__ == "__main__":+ unittest.main()