Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

fix: return MCP load failures as tool strings

Frankie-Xu58a74287ee71
diff --git a/hyperextract/mcp_server.py b/hyperextract/mcp_server.py
index 94ad0c2..1fe04eb 100644
--- a/hyperextract/mcp_server.py
+++ b/hyperextract/mcp_server.py
@@ -76,6 +76,17 @@ def _load_ka(ka_path: str):
return ka
+_LOAD_ERRORS = (FileNotFoundError, ValueError, OSError, ImportError)
+
+
+def _safe_load_ka(ka_path: str):
+ """Load a KA, or return an explanation string (never raise)."""
+ try:
+ return _load_ka(ka_path)
+ except _LOAD_ERRORS as exc:
+ return f"Cannot load KA: {exc}"
+
+
def _dump(obj: Any) -> str:
return json.dumps(obj, ensure_ascii=False, indent=2, default=str)
@@ -220,7 +231,9 @@ def search(ka_path: str, query: str, top_k: int = 5) -> str:
"""
from hyperextract.utils.search_results import coerce_search_results
- ka = _load_ka(ka_path)
+ ka = _safe_load_ka(ka_path)
+ if isinstance(ka, str):
+ return ka
try:
results = ka.search(query, top_k=top_k)
except ValueError as e:
@@ -239,7 +252,9 @@ def ask(ka_path: str, question: str, top_k: int = 5) -> str:
Returns the generated answer. The KA must have an index.
"""
- ka = _load_ka(ka_path)
+ ka = _safe_load_ka(ka_path)
+ if isinstance(ka, str):
+ return ka
try:
response = ka.chat(question, top_k=top_k)
except ValueError as e:
@@ -263,7 +278,9 @@ def export_obsidian(
Returns a summary of how many notes were written.
"""
- ka = _load_ka(ka_path)
+ ka = _safe_load_ka(ka_path)
+ if isinstance(ka, str):
+ return ka
if not hasattr(ka, "export_obsidian"):
return (
"Obsidian export is only supported for graph-type knowledge abstracts "
@@ -292,7 +309,9 @@ def export_graphml(ka_path: str, output: str, overwrite: bool = False) -> str:
from hyperextract.utils.exporters import GraphMLHypergraphError
from hyperextract.utils.exporters.ka import GraphTypeError, export_ka_graphml
- ka = _load_ka(ka_path)
+ ka = _safe_load_ka(ka_path)
+ if isinstance(ka, str):
+ return ka
try:
dest = export_ka_graphml(ka, output, overwrite=overwrite)
except GraphTypeError as e:
@@ -321,7 +340,9 @@ def export_csv(ka_path: str, output: str, overwrite: bool = False) -> str:
is_hypergraph_ka,
)
- ka = _load_ka(ka_path)
+ ka = _safe_load_ka(ka_path)
+ if isinstance(ka, str):
+ return ka
hypergraph = is_hypergraph_ka(ka)
try:
dest = export_ka_csv(ka, output, overwrite=overwrite)
@@ -346,7 +367,9 @@ def export_jsonld(ka_path: str, output: str, overwrite: bool = False) -> str:
"""
from hyperextract.utils.exporters.ka import GraphTypeError, export_ka_jsonld
- ka = _load_ka(ka_path)
+ ka = _safe_load_ka(ka_path)
+ if isinstance(ka, str):
+ return ka
try:
dest = export_ka_jsonld(ka, output, overwrite=overwrite)
except GraphTypeError as e:
@@ -369,7 +392,9 @@ def export_cypher(ka_path: str, output: str, overwrite: bool = False) -> str:
"""
from hyperextract.utils.exporters.ka import GraphTypeError, export_ka_cypher
- ka = _load_ka(ka_path)
+ ka = _safe_load_ka(ka_path)
+ if isinstance(ka, str):
+ return ka
try:
dest = export_ka_cypher(ka, output, overwrite=overwrite)
except GraphTypeError as e:
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index 064bca0..661b272 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -419,6 +419,108 @@ def test_export_cypher_rejects_non_graph(monkeypatch, tmp_path):
assert "Cypher" in out
+# ---------------------------------------------------------------------------
+# search / ask / export — load failures must return strings, not raise
+# ---------------------------------------------------------------------------
+
+
+def _mcp_load_tools(ka_path: str, dest):
+ return (
+ ("search", lambda: mcp_server.search(ka_path, "q")),
+ ("ask", lambda: mcp_server.ask(ka_path, "q")),
+ (
+ "export_obsidian",
+ lambda: mcp_server.export_obsidian(ka_path, str(dest / "vault")),
+ ),
+ (
+ "export_graphml",
+ lambda: mcp_server.export_graphml(ka_path, str(dest / "g.graphml")),
+ ),
+ ("export_csv", lambda: mcp_server.export_csv(ka_path, str(dest / "csv"))),
+ (
+ "export_jsonld",
+ lambda: mcp_server.export_jsonld(ka_path, str(dest / "g.jsonld")),
+ ),
+ (
+ "export_cypher",
+ lambda: mcp_server.export_cypher(ka_path, str(dest / "g.cypher")),
+ ),
+ )
+
+
+ "tool_name",
+ [
+ "search",
+ "ask",
+ "export_obsidian",
+ "export_graphml",
+ "export_csv",
+ "export_jsonld",
+ "export_cypher",
+ ],
+)
+def test_load_missing_path_returns_string(tmp_path, tool_name):
+ tools = dict(_mcp_load_tools(str(tmp_path / "nope"), tmp_path / "out"))
+ out = tools[tool_name]()
+ assert isinstance(out, str)
+ assert out.startswith("Cannot load KA:")
+
+
+ "tool_name",
+ [
+ "search",
+ "ask",
+ "export_obsidian",
+ "export_graphml",
+ "export_csv",
+ "export_jsonld",
+ "export_cypher",
+ ],
+)
+def test_load_dir_without_data_json_returns_string(tmp_path, tool_name):
+ empty = tmp_path / "empty_ka"
+ empty.mkdir()
+ tools = dict(_mcp_load_tools(str(empty), tmp_path / "out"))
+ out = tools[tool_name]()
+ assert isinstance(out, str)
+ assert out.startswith("Cannot load KA:")
+ assert "data.json" in out
+
+
+ "tool_name",
+ [
+ "search",
+ "ask",
+ "export_obsidian",
+ "export_graphml",
+ "export_csv",
+ "export_jsonld",
+ "export_cypher",
+ ],
+)
+def test_load_client_error_returns_string(tmp_path, monkeypatch, tool_name):
+ ka = tmp_path / "ka"
+ ka.mkdir()
+ (ka / "data.json").write_text("{}", encoding="utf-8")
+ (ka / "metadata.json").write_text(
+ json.dumps({"template": "general/base_graph", "lang": "en"}),
+ encoding="utf-8",
+ )
+
+ def _boom():
+ raise ValueError("LLM API key is not configured")
+
+ monkeypatch.setattr(mcp_server, "_get_clients", _boom)
+ tools = dict(_mcp_load_tools(str(ka), tmp_path / "out"))
+ out = tools[tool_name]()
+ assert isinstance(out, str)
+ assert out.startswith("Cannot load KA:")
+ assert "not configured" in out
+
+
# ---------------------------------------------------------------------------
# FastMCP wiring (needs the optional `mcp` package)
# ---------------------------------------------------------------------------