Skip to content

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

feat: align MCP info with he info chunks and sources

Frankie-Xue372deb5fb64
diff --git a/docs/en/mcp.md b/docs/en/mcp.md
index 13978db..5fe4ec0 100644
--- a/docs/en/mcp.md
+++ b/docs/en/mcp.md
@@ -42,7 +42,7 @@ Point your MCP client at the `he-mcp` command. For a Claude Desktop–style conf
| Tool | Description | Needs index | Needs LLM |
|------|-------------|:-----------:|:---------:|
| `list_templates` | List available extraction templates | — | — |
-| `info` | Stats for a KA (template, counts, index status) | — | — |
+| `info` | Stats for a KA (template, counts, chunks, timestamps; `include_sources` for ledger rows) | — | — |
| `search` | Semantic retrieval over a KA | ✓ | embedder |
| `ask` | RAG question-answering over a KA | ✓ | ✓ |
| `export_obsidian` | Export a KA to an Obsidian vault | — | embedder |
diff --git a/docs/zh/mcp.md b/docs/zh/mcp.md
index ea9157f..c3c5576 100644
--- a/docs/zh/mcp.md
+++ b/docs/zh/mcp.md
@@ -42,7 +42,7 @@ python -m hyperextract.mcp_server
| 工具 | 说明 | 需要索引 | 需要 LLM |
|------|-------------|:-----------:|:---------:|
| `list_templates` | 列出可用的提取模板 | — | — |
-| `info` | KA 统计(模板、数量、索引状态) | — | — |
+| `info` | KA 统计(模板、数量、chunks、时间戳;`include_sources` 可返回来源账本) | — | — |
| `search` | KA 语义检索 | ✓ | 嵌入器 |
| `ask` | KA 上的 RAG 问答 | ✓ | ✓ |
| `export_obsidian` | 将 KA 导出为 Obsidian 知识库 | — | 嵌入器 |
diff --git a/hyperextract/mcp_server.py b/hyperextract/mcp_server.py
index 3b4a1c1..f9ac1f1 100644
--- a/hyperextract/mcp_server.py
+++ b/hyperextract/mcp_server.py
@@ -6,7 +6,8 @@ deletes a KA.
Tools:
- list_templates : list available extraction templates
- - info : stats for a knowledge abstract (no LLM needed)
+ - info : stats for a knowledge abstract (chunks, timestamps,
+ optional sources; no LLM needed)
- search : semantic retrieval over a KA (needs an index)
- ask : RAG question-answering over a KA (needs an index)
- export_obsidian : export a KA to an Obsidian vault
@@ -101,13 +102,16 @@ def list_templates() -> str:
return _dump(out)
-def info(ka_path: str) -> str:
+def info(ka_path: str, include_sources: bool = False) -> str:
"""Show information and statistics for a knowledge abstract.
Args:
ka_path: Path to the knowledge abstract directory.
+ include_sources: When true, include source-ledger rows (same files
+ ``he info --sources`` reads). Default false.
- Returns JSON with template, language, node/edge counts, and index status.
+ Returns JSON with template, language, node/edge counts, optional chunks,
+ created/updated timestamps, index status, and optional sources.
Does not require LLM/embedder configuration.
"""
path = Path(ka_path)
@@ -116,9 +120,11 @@ def info(ka_path: str) -> str:
return f"Not a knowledge abstract (no data.json): {ka_path}"
data = json.loads(data_file.read_text(encoding="utf-8"))
+ chunks = 0
if isinstance(data, dict):
nodes = len(data.get("nodes", data.get("entities", [])))
edges = len(data.get("edges", data.get("relations", [])))
+ chunks = len(data.get("chunks", []))
elif isinstance(data, list):
nodes, edges = len(data), 0
else:
@@ -132,16 +138,61 @@ def info(ka_path: str) -> str:
index_dir = path / "index"
index_built = index_dir.exists() and any(index_dir.iterdir())
- return _dump(
- {
- "path": str(path),
- "template": meta.get("template"),
- "lang": meta.get("lang"),
- "nodes": nodes,
- "edges": edges,
- "index_built": index_built,
- }
+ payload: dict[str, Any] = {
+ "path": str(path),
+ "template": meta.get("template"),
+ "lang": meta.get("lang"),
+ "nodes": nodes,
+ "edges": edges,
+ "index_built": index_built,
+ }
+ if chunks:
+ payload["chunks"] = chunks
+ if meta.get("created_at"):
+ payload["created"] = meta["created_at"]
+ if meta.get("updated_at"):
+ payload["updated"] = meta["updated_at"]
+ if include_sources:
+ payload["sources"] = _source_ledger_rows(path)
+ return _dump(payload)
+
+
+def _source_ledger_rows(path: Path) -> list[dict[str, Any]]:
+ """Collect source-ledger rows using the same files as ``he info --sources``."""
+ ledger_files = (
+ path / "sources_nodes.json",
+ path / "sources_edges.json",
+ path / "sources_chunks.json",
+ path / "sources_items.json",
)
+ combined: dict[str, dict[str, Any]] = {}
+ for ledger_path in ledger_files:
+ if not ledger_path.exists():
+ continue
+ try:
+ entries = json.loads(ledger_path.read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError, TypeError, ValueError):
+ continue
+ if not isinstance(entries, list):
+ continue
+ for entry in entries:
+ if not isinstance(entry, dict):
+ continue
+ sid = entry.get("source_id")
+ if sid is None:
+ continue
+ record = combined.setdefault(
+ str(sid),
+ {
+ "source_id": str(sid),
+ "raw_items": 0,
+ "content_hash": entry.get("content_hash"),
+ },
+ )
+ record["raw_items"] += len(entry.get("raw_items", []))
+ if record.get("content_hash") is None:
+ record["content_hash"] = entry.get("content_hash")
+ return [combined[key] for key in sorted(combined)]
def search(ka_path: str, query: str, top_k: int = 5) -> str:
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index ef4c689..bd0a127 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -74,6 +74,52 @@ def test_info_reports_counts(tmp_path):
assert out["edges"] == 1
assert out["index_built"] is True
assert out["template"] == "general/base_graph"
+ assert "created" in out
+ assert "updated" in out
+ assert "sources" not in out
+
+
+def test_info_includes_chunks_and_optional_sources(tmp_path):
+ ka = tmp_path / "doc_ka"
+ ka.mkdir()
+ (ka / "data.json").write_text(
+ json.dumps({"chunks": [{"content": "a"}, {"content": "b"}]}),
+ encoding="utf-8",
+ )
+ (ka / "metadata.json").write_text(
+ json.dumps(
+ {
+ "template": "general/base_document",
+ "lang": "en",
+ "created_at": "2026-09-12T00:00:00",
+ "updated_at": "2026-09-12T01:00:00",
+ }
+ ),
+ encoding="utf-8",
+ )
+ (ka / "sources_chunks.json").write_text(
+ json.dumps(
+ [
+ {
+ "source_id": "doc-1",
+ "content_hash": "abc",
+ "raw_items": [{"content": "a"}, {"content": "b"}],
+ }
+ ]
+ ),
+ encoding="utf-8",
+ )
+
+ out = json.loads(mcp_server.info(str(ka)))
+ assert out["chunks"] == 2
+ assert out["created"] == "2026-09-12T00:00:00"
+ assert out["updated"] == "2026-09-12T01:00:00"
+ assert "sources" not in out
+
+ with_sources = json.loads(mcp_server.info(str(ka), include_sources=True))
+ assert with_sources["sources"] == [
+ {"source_id": "doc-1", "raw_items": 2, "content_hash": "abc"}
+ ]
def test_info_rejects_non_ka(tmp_path):