freepeak LeanKG Code Search (HTTP-gated)
LeanKG is preferred when the MCP HTTP server is up. If health fails, exit this skill immediately and use default Cursor/editor tools.
Gate (ALWAYS FIRST)
curl -sf --max-time 2 http://localhost:9699/health
| Result | Next step |
|---|---|
| Success (2xx) | Continue with LeanKG MCP below |
| Fail / timeout / connection refused | Exit skill. Use Grep, Glob, Read. Do not call LeanKG MCP, mcp_init, or leankg CLI |
Re-check health only if the user asks or you have reason to believe the server came back.
When HTTP is healthy: LeanKG MCP
Project path (Docker vs host)
When talking to Docker MCP on :9699, pass the container mount as project=:
| Target | project= |
|---|---|
| This LeanKG repo | /workspace |
| Extra bind (compose override) | /workspace-other (or the container side of the bind) |
Do not pass a Mac host path (e.g. /Users/.../leankg) as project against Docker RocksDB.
Prefer-order (discover → exact)
Session start (overview):
get_overview_context(project=…) # L0+L1 summary — not load_layer(L0) alone
→ optional load_layer for progressive budgets
→ get_architecture for deep single-call overview
Natural-language / domain questions (discover before query_graph):
1. mcp_status(project=…)
2. concept_search(query=…) # domain concepts first
3. semantic_search(query=…) # HNSW ANN if embeddings exist — REQUIRED before query_graph
4. search_code / find_function # name/type fallback
5. query_graph / explain_node / shortest_path # only after seeds / known endpoints
6. get_context / get_impact_radius / get_dependencies / …
on the returned qualified_name or file — never full-graph dumps
BAN: Do not call query_graph as the first NL discovery tool. Run concept_search → semantic_search first; use query_graph to expand the frontier after hits.
Exact symbol / file known:
mcp_status → find_function / query_file → get_context → impact/deps tools
Finding Code
| Task | Tool | Example |
|---|---|---|
| Domain / NL search | concept_search |
concept_search(query="authentication", project="/workspace") |
| Semantic / meaning | semantic_search |
semantic_search(query="payment refund", project="/workspace") |
| Name / type search | search_code |
search_code(query="Handler", project="/workspace") |
| Function definition | find_function |
find_function(name="ProcessOrder", project="/workspace") |
| File by pattern | query_file |
query_file(pattern="auth", project="/workspace") |
| Callers / call graph | get_callers / get_call_graph |
pass project= |
Reading & Context (after discovery)
| Task | Tool |
|---|---|
| File / symbol context | get_context |
| Blast radius | get_impact_radius |
| Imports / dependents | get_dependencies / get_dependents |
| Tests | get_tested_by |
| NL subgraph (after discovery) | query_graph (frontier-local; mega-safe) — not first-hop NL |
| Session overview | get_overview_context |
| Environment filter | env= on search_code / semantic_search / concept_search / kg_* |
Doc↔code join (structural markdown ↔ file keys)
After mcp_index_docs, path aliases resolve on read; markdown refs resolve to indexed file keys on write.
1. FR / US requirement ID → get_traceability / get_traceability_matrix / link_element
2. Known file or doc path → get_files_for_doc / find_related_docs (canonical docs/… keys)
3. Domain / workflow → concept_search → kg_trace_workflow
4. Fuzzy NL → semantic_search → kg_semantic_context
5. Fallback → search_code / Read
Miss payloads include tried[] — do not assume empty graph when aliases fail.
Hard-removed tools (do not call)
mcp_hello, mcp_impact, get_doc_for_file, find_clones, wake_up, search_by_environment, get_graph_report (use get_god_nodes + get_architecture), orchestrate (use query_graph / kg_context / search_code), search_by_requirement (use get_traceability)
If mcp_status is not ready (but HTTP health was OK)
Try other known container mounts from LEANKG_PROJECT_DIRS, then fall back to default Grep/Glob/Read.
Do not run mcp_init or local CLI indexing as a substitute when the preferred path is Docker HTTP MCP.
If LeanKG returns EMPTY results
Fall back to default mode: Grep, Glob, Read.
Default mode (HTTP down OR LeanKG empty)
Grep / Glob / Read
No Tier 2 leankg CLI. No forced mcp_init. Default editor tools are enough.
BAN: Do not call LeanKG tools when :9699 health failed.
BAN: Do not materialize full element/relationship tables on mega graphs — use keyed / ANN / frontier tools only.