Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix(mcp): complete persistence and setup fixes (#1394)

Sameer Kadam798a7455e404
diff --git a/mcp/README.md b/mcp/README.md
index 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.py
index 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_ok
if _graph is None:
from semantica.context import ContextGraph
_graph = ContextGraph(advanced_analytics=True)
+ _load_ok = True # default: safe to persist
kg_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 file
return _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 = True
diff --git a/mcp/tools/decisions.py b/mcp/tools/decisions.py
index 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 annotations
import logging
+import os
from 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_safe
log = 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.py
index 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 annotations
import logging
+import os
from 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_safe
log = 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.py
index 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
+ raise
self.logger.info(f"Saved context graph to {path}")
diff --git a/semantica/mcp_server/__init__.py b/semantica/mcp_server/__init__.py
index 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_ok
if _graph is None:
from semantica.context import ContextGraph
_graph = ContextGraph(advanced_analytics=True)
+ _kg_load_ok = True # default: safe to persist
kg_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 file
return _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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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()