feat(celery Wave 7 #7): MCP graph tools — query_graph_entities / expand_graph_subgraph / get_entity_detail

[earayu]

Wave 7 §K.12.6 / §K.12.7 task #7. Architect ratify msg=da89237c locked Option A: 3 internal-only REST endpoints + 3 MCP tools, all REST-mediated (mirror existing aperag/mcp/tools/search_graph.py).

Summary

• Per-collection factory build_graph_search_service_for(collection) in aperag/indexing/graph_search_service.py (mirrors _build_lineage_graph_store_for).
• 3 internal-only endpoints under /api/v2/collections/{id}/graphs/ (GET .../entities/search, POST .../subgraph/expand, GET .../entities/{name}) — all read-only, all per-collection auth-scoped.
• 3 GraphService projection methods reusing GraphSearchService._render_description.
• 3 MCP tools in aperag/mcp/tools/graph_tools.py wired at the bottom of aperag/mcp/server.py.
• 21 new tests + 1 capability-negotiation teardown extension. Lint clean; 342 broad-sweep tests pass.

§K.12 12-invariant cross-check

#	Invariant	This PR
1	L1 graph data 不污染	N/A — read-only
2	L1 → L2 单向派生	N/A — read-only
3	Compactor 在 vector embed 之前	N/A (write-side, task #3)
4	Vector store via VectorStoreConnectorAdaptor	✅ factory uses _build_collection_qdrant_connector; no direct Qdrant import in the new tool / route surface
5	payload indexer filter pattern	✅ inherited from GraphSearchService.search_entities
6	uuid5 vector point id	N/A — read-only
7	snapshot-diff lineage name set	N/A — read-only
8	alias_map persist	N/A — task #6 owns; this PR's read paths transit LineageGraphStore so future alias decoration is transparent
9	upsert_entity alias redirect	N/A — task #6 owns
10	DB column length application-cap	✅ reuses spec-bounded inputs (top_k cap 100, hops cap 3); no new column writes
11	候选检测仅写不自动合并	✅ all 3 tools / endpoints are read-only
12	grep-zero LightRAG	✅ tool names + URL paths + view models LightRAG-clean (borderline docstring sweep stays in task #10 batch)

4-pattern pre-check matrix

• Pattern 1 v1 — legacy import unchanged; cutover lives in task feat: chat websocket connect #8, deletion in task feat: auth with github and google #10.
• Pattern 1 v2 (architect own-up) — MCPServerEntry (D9 remote-server URL registry) is NOT the in-process tool registry the original spec referenced; actual registration target is FastMCP via @mcp_server.tool. Architect ratify msg=da89237c locked Option A.
• Pattern 2 — new endpoints reach lineage tables exclusively through LineageGraphStore / GraphSearchService.
• Pattern 3 — Pydantic schemas appear in OpenAPI regen; frontend (cuiwenbo task feat: markdown response #9) regen is a no-op.

simple-stable 4 guardrail

• feat/frontend #1 不无限扩范围 — new endpoints exist solely to back 3 spec-locked MCP tools.
• feat: auth bearer token support #2 尽快上线 — task feat: chat animate #7 ships independently of task feat/collection model define #6 / feat: chat websocket connect #8.
• feat: api test #3 简单稳定 — same httpx-based pattern as the existing 8 D10 tools.
• fix: upload token #4 私有化部署免维护 — API_BASE_URL env keeps MCP colocated-or-detached.

Test plan

• CI lint-and-unit
• uv run pytest tests/unit_test/mcp/ tests/unit_test/service/ tests/unit_test/indexing/ — 342 pass
• uv run ruff check — clean
• @huangheng pass-1 review (12-invariant + ratify pattern lock)

🤖 Generated with Claude Code

[earayu]

🟢 LGTM ✅ (huangheng pass-1, per spec §K.12.11) — GitHub 不允许同账号 approve；verdict = ready to merge

12-invariant + 4-pattern + simple-stable 4-guardrail 全 paste（hard-gate format 第八个达标 PR），3 MCP tools + 3 internal-only REST endpoints + per-collection factory + 21 unit tests + 1 capability negotiation extension。Option (A) httpx-based pattern 100% mirror 现有 8 个 MCP tool，read-only D-3 严守，naming grep-zero LightRAG (added lines 仅 invariant-meta refs)。

12-invariant cross-check（task #7 scope）

#	Invariant	This PR	验证依据
1	L1 graph data 不污染	n/a	read-only 服务
2	L1 → L2 单向派生	n/a	read-only
3	Compactor 顺序	n/a	task #3 范畴
4	Vector store via VectorStoreConnectorAdaptor	✅	build_graph_search_service_for factory 复用 _build_collection_qdrant_connector，GraphSearchService 内部已 abide
5	payload indexer="graph_entity" filter	✅	inherited from GraphSearchService.search_entities（PR #1756 已 verified）
6	uuid5 deterministic id	n/a	read-only
7	snapshot-diff	n/a	task #3 范畴
8	alias_map persist	n/a	task #6 范畴
9	upsert 透明 alias redirect	n/a	task #6 范畴（read-side alias resolution 见 minor observation 1）
10	DB 列长度 cap	✅	top_k 1-100 cap (route line 307-308)，hops max 3 (per pydantic schema)
11	候选检测仅写不自动合并 (D-3)	✅	3 tools / 3 endpoints 全 read-only；零 mutation
12	命名 grep-zero LightRAG	⚠️ minor	added lines gh pr diff 1759 | grep -E '^\+' | grep -i lightrag → 2 hits，都是 invariant-meta references (# Per §K.12 invariant #12 (grep-zero LightRAG) + tool names are LightRAG-grep-zero clean)，不是 naming，task #10 sweep 一并清

Option (A) pattern conformity 验证

验证项	现有 8 tool	本 PR	状态
httpx-based + REST mediated	✅ all	✅ all 3 tools	✅ conform
API_BASE_URL env env-aware	✅	✅ line 47 import + 104/160/213 用	✅ conform
@mcp_server.tool(annotations=_register_tool_annotation(...)) decorator	✅ search_graph.py pattern	✅ line 53/116/172 严格 mirror	✅ conform
_parse_response defensive 解析（success/404/non-2xx）	✅ search_graph 内部	✅ line 224-244 同 convention	✅ conform
Tool docstring "Use this when / Do not use this when" 段	✅ existing	✅ all 3 tools	✅ conform

完整 mirror 现有 pattern，无 architecture asymmetry。👍

3 endpoint scope 验证

Method	Path	Backed by	范围
GET	/api/v2/collections/{id}/graphs/entities/search?q=&top_k=	graph_service.search_entities → GraphSearchService.search_entities	internal-only / read-only
POST	/api/v2/collections/{id}/graphs/subgraph/expand body	graph_service.expand_subgraph → GraphSearchService.get_subgraph → expand_neighbors_n_hops	internal-only / read-only
GET	/api/v2/collections/{id}/graphs/entities/{name}	graph_service.get_entity_detail → store.get_entity (direct，非 GraphSearchService — 见 observation 1)	internal-only / read-only

3 endpoint 全 per-collection auth-scoped (route line 299/326/356)，零 user-facing UI 消费 (frontend backward-compat 不破坏 — cuiwenbo task #9 OpenAPI regen 是 no-op)。

4-pattern pre-check matrix

PR body Pattern 1 v2 (architect own-up) 显式标注 mini-pattern 5/9 第三例 — D9 MCPServerEntry URL registry 与 in-process tool registry 错位的 architect-side spec drift。Pattern 2 dependency 接口签名全对齐已 merged commits。Pattern 3 per-collection binding（factory 模式）与 retrieval pipeline 现有一致。

simple-stable 4-guardrail

PR description 4 项全显式：smallest surface for spec-locked 3 tools / ships independent / pattern reuse / API_BASE_URL env-aware deployment。

测试覆盖

21 new + 1 capability negotiation = 22 tests:

• test_mcp/test_graph_tools.py (245 LOC): 3 tools happy path + 404 / non-2xx error path / params shape
• test_service/test_graph_search_service_layer.py (268 LOC): service.py 3 method 完整覆盖
• test_mcp/test_capability_negotiation.py (+3): 3 new tools 加进 capability list

完备。

2 个 minor observation（非阻塞，sediment 给 future task）

Observation 1: get_entity_detail bypasses GraphSearchService + alias decorator

service.py:get_entity_detail (line 253-277) 用 _build_lineage_graph_store(...) 直接，没走 GraphSearchService，没走 LineageGraphStoreWithAliasRedirect decorator。

当前 OK：

• decorator (PR #1758) 仅 intercept upsert_*（write 路径），不 redirect reads
• 即使 task #8 wire 装饰器到 _build_lineage_graph_store，read path get_entity 也不 redirect
• 所以 get_entity_detail("alias_name") 返 None / 404

潜在 UX 问题：

• 如 user UI 显示 alias name 给 agent (e.g., 用户合并 "OpenAI" → "OpenAI Inc."；UI 仍可能显示历史 "OpenAI" alias)
• agent 通过 MCP get_entity_detail("OpenAI") → 404
• 用户体验：agent 找不到刚见过的实体

两条路（任选 future follow-up）：

• (A) get_entity_detail resolve alias → canonical 后再 lookup（AliasMapRepository.resolve_canonical(name) 接 store.get_entity(canonical)）
• (B) UI 永远 surface canonical name 给 agent（前端责任 — alias 是用户合并意图，agent context 用 canonical）

建议：sediment 为 Wave 8 candidate W8-3 (read-side alias resolution at MCP / REST surface)。本 PR 可 merge，spec §K.12.7 没显式 mandate read-side resolution。

Observation 2: 2 added LightRAG meta-references

+# Per §K.12 invariant #12 (grep-zero LightRAG) the names are LightRAG-clean
+#12 the tool names are LightRAG-grep-zero clean.

都是 self-tracking comments 标注 "we comply with grep-zero rule"。strict 读取 invariant #12 仍算 hits；建议 task #10 sweep 一并清（或保留作 invariant compliance annotations，看 implementer）。

修完会 LGTM 的清单

实际上已经可以 merge ✅。observations 都是非阻塞 sediment 候选。

@chenyexuan work clean — Option (A) httpx pattern 严格 conform + tool docstring agent-guidance prose 完整（"Use this when / Do not use this when"）+ 22 tests 覆盖 happy path / error path / params shape 全。👍

task #8 wiring 再提醒（@chenyexuan task #8 PR 必交付）

1. worker_factory._build_lineage_graph_store wrap with LineageGraphStoreWithAliasRedirect（per PR #1758）
2. REST /graphs/nodes/merge route swap to LineageEntityMerger.merge_entities（per PR #1758）
3. retrieval pipeline _graph_search cutover 走 GraphSearchService（per PR #1756）

3 处 wiring 在 task #8 PR 一并交付，不做的话 PR #1758 inseparability gate + PR #1756 vector recall 都形同虚设。

@符炫炜 LGTM，可 merge。
@不穷 推进 task #7 → done after merge；critical path 余 #8 (含 3 处 wiring) + #9 + #10 = 3 PR 收尾 Wave 7。

@bryce task #10 close-out cleanup list 增量：

• 累积：task #1 (8 处 Wave 6 era 注释) / task #4 (line 249 fallback) / task #5 (6 处 docstring) / task #3 (relation payload naming + search_relations 升级 to vector recall — Wave 8 W8-1) / task #6 (无累积，全 align)
• 本轮 task #7: 2 处 invariant-meta LightRAG references in mcp/tools/graph_tools.py + service.py，sweep 时改成 neutral 表述 e.g. "grep-zero invariant compliance"