# LeanKG - AI Agent Context

## Project Overview

LeanKG is a lightweight knowledge graph for codebase understanding. It indexes code, builds dependency graphs, calculates impact radius, and exposes everything via MCP for AI tool integration.

**Tech Stack:** Rust + CozoDB + tree-sitter + MCP

## Quick Start

```bash
# Index a codebase
cargo run -- init
cargo run -- index ./src

# Calculate impact radius
cargo run -- impact src/main.rs 3

# Start MCP server
cargo run -- serve
```

## Development Workflow

**When implementing features, follow:** `docs/workflow-opencode-agent.md`

### Pattern: Update Docs → Implement → Test → Commit → Push → Bump Version → Tag

1. **Update docs first** - PRD (`docs/requirement/prd-leankg.md`) → HLD (`docs/design/hld-leankg.md`) → README
2. **Implement** - Follow patterns in `docs/workflow-opencode-agent.md`
3. **Build & test** - `cargo build && cargo test`
4. **Commit** - `git commit -m "feat: description"` (one feature per commit)
5. **Push** - `git pull --rebase && git push`
6. **Bump version** - Update `version` in `Cargo.toml`
7. **Tag** - `git tag -a v<version> -m "Release v<version>" && git push origin v<version>` (after version bump)

### Commit Message Rules

- **NEVER** add `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>` to commits
- **NEVER** add `🤖 Generated with Claude Code` or similar AI attribution
- **NEVER** add "Generated by" phrases in PR descriptions

## Key Commands

**IMPORTANT: Always use `--release` flag for builds. Debug builds are disabled.**

```bash
cargo build --release  # Build project (release)
cargo test             # Run tests
cargo run --release -- <cmd>  # Run CLI commands
```

## Important Files

| File | Purpose |
|------|---------|
| `src/lib.rs` | Module exports |
| `src/db/models.rs` | Data models (CodeElement, Relationship, BusinessLogic) |
| `src/graph/query.rs` | Graph query engine |
| `src/mcp/tools.rs` | MCP tool definitions |
| `src/mcp/handler.rs` | MCP tool handlers |
| `src/indexer/extractor.rs` | Code parsing with tree-sitter |

## Data Model

- **CodeElement** - Files, functions, classes with `qualified_name` (e.g., `src/main.rs::main`)
- **Relationship** - `imports`, `calls`, `tested_by`, `references`, `documented_by`
- **BusinessLogic** - Annotations linking code to business requirements

## MCP Tools

Core tools: `query_file`, `get_dependencies`, `get_dependents`, `get_impact_radius`, `get_review_context`, `find_function`, `get_call_graph`, `search_code`, `generate_doc`, `find_large_functions`, `get_tested_by`

Doc/Traceability tools: `get_doc_for_file`, `get_files_for_doc`, `get_doc_structure`, `get_traceability`, `search_by_requirement`, `get_doc_tree`, `get_code_tree`, `find_related_docs`

## Verification Status

See `docs/implementation-feature-verification-2026-03-25.md` for test results.

---

## LeanKG Tools Usage

### MANDATORY: Use LeanKG First, Fallback to Raw Tools

**This is a MANDATORY workflow - not optional guidance.**

#### Step 1: Always Try LeanKG First
1. Call `mcp_status` to check if LeanKG is ready
2. If not ready, call `mcp_init` with path: "/Users/linh.doan/work/harvey/freepeak/leankg/.leankg"
3. Use appropriate LeanKG tool: `search_code`, `find_function`, `query_file`, `get_impact_radius`, `get_dependencies`, `get_dependents`, `get_tested_by`, `get_context`

#### Step 2: Fallback Only If LeanKG Fails
- LeanKG returns empty results OR
- LeanKG returns error AND you need the data
- THEN you may use `Glob`, `Grep`, `Read` as fallback

#### Step 3: Never Skip LeanKG for Code Search
- NEVER say "I'll just use grep" without trying LeanKG first
- NEVER claim "LeanKG doesn't have this" without actually checking

| Task | LeanKG First | Fallback |
|------|--------------|----------|
| Where is X? | `search_code("X")` | `Grep("X")` |
| Find function | `find_function("name")` | `Grep("fn name")` |
| What breaks? | `get_impact_radius(file)` | Manual trace |
| What tests? | `get_tested_by(file)` | `Grep("test.*file")` |
| Read content | `get_context(file)` | `Read(file)` |

### Why This Matters
- LeanKG is 10-100x faster than raw grep on large codebases
- LeanKG understands code relationships (imports, calls, tests)
- Raw tools should be emergency fallback only

---

## MCP Server Management

### Known Issues
- **MCP HTTP stability**: Zombie processes and stale locks can accumulate on restart. See `docs/analysis/mcp-http-stability-analysis-2026-05-05.md`

### MCP HTTP Server Commands

```bash
# Check if running
lsof -i :9699 2>/dev/null | grep LISTEN

# Verify health
curl http://localhost:9699/health

# Verify SSE endpoint
curl -I http://localhost:9699/mcp/stream

# Clean restart (kill stale processes first)
lsof -ti :9699 | xargs kill -9 2>/dev/null; sleep 1
launchctl stop com.leankg.mcp-http 2>/dev/null; sleep 1
launchctl start com.leankg.mcp-http

# Watch for build changes
./scripts/watch-leankg-build.sh
```

---

*Last updated: 2026-05-05*
