# LeanKG MCP Server Validation Report

**Date:** 2026-05-24
**Status:** Complete

## Executive Summary

All LeanKG MCP HTTP server tools have been validated and are working correctly. The concept ontology system is operational with 2 domain entities loaded from YAML files.

---

## MCP Server Status

| Property | Value |
|----------|-------|
| **Server** | LeanKG MCP HTTP Server |
| **Port** | 9699 |
| **Transport** | HTTP (JSON-RPC) |
| **Authentication** | Disabled |
| **Storage Engine** | SQLite (direct mode) |

### Health Check
```
{"status": "ok"}
```

---

## Tool Validation Results

**Total Tools Tested:** 30
**Passed:** 30
**Failed:** 0

### Core Tools

| # | Tool Name | Status | Notes |
|---|-----------|--------|-------|
| 1 | mcp_hello | OK | Returns "Hello, World!" |
| 2 | mcp_status | OK | Shows database initialized |
| 3 | mcp_index | OK | Indexes code elements |
| 4 | kg_ontology_status | OK | Shows concept counts |
| 5 | search_code | OK | Returns code elements |
| 6 | find_function | OK | Locates function definitions |
| 7 | get_dependencies | OK | Shows direct imports |
| 8 | get_dependents | OK | Shows referencing files |
| 9 | get_context | OK | Returns AI-optimized context |
| 10 | get_call_graph | OK | Shows function calls |
| 11 | get_tested_by | OK | Shows test coverage |
| 12 | semantic_search | OK | Returns ranked results |
| 13 | query_file | OK | Finds files by pattern |
| 14 | find_large_functions | OK | Identifies oversized functions |
| 15 | get_clusters | OK | Shows code clusters |
| 16 | kg_context | OK | Ontology-aware context |
| 17 | kg_concept_map | OK | Domain concept mapping |
| 18 | kg_trace_workflow | OK | Traces workflow steps |
| 19 | search_knowledge | OK | Searches knowledge entries |
| 20 | add_knowledge | OK | Creates knowledge entries |
| 21 | get_service_context | OK | Service-level context |
| 22 | get_doc_tree | OK | Document structure |
| 23 | get_doc_for_file | OK | Documentation lookup |
| 24 | find_related_docs | OK | Related documentation |
| 25 | get_code_tree | OK | Code structure tree |
| 26 | mcp_index_docs | OK | Document indexing |
| 27 | detect_changes | OK | Change detection |
| 28 | get_service_graph | OK | Service dependency graph |
| 29 | get_review_context | OK | PR review context |
| 30 | get_impact_radius | OK | Impact analysis |

---

## Ontology System Status

### Concept Counts (domain_entity type)

| Type | Count |
|------|-------|
| domain_entity | 2 |
| service | 0 |
| api_endpoint | 0 |
| data_store | 0 |
| environment | 0 |
| known_issue | 0 |
| playbook | 0 |
| team_knowledge | 0 |

### Procedural Counts

| Type | Count |
|------|-------|
| workflow | 0 |
| workflow_step | 0 |
| decision_point | 0 |
| failure_mode | 0 |
| playbook_step | 0 |

### Loaded Concepts

1. **Refund** (`local:checkout-service:domain_entity:refund:v1`)
   - Type: domain_entity
   - Aliases: refund, reversal, chargeback, money back
   - Description: Money returned to a customer after payment capture

2. **Checkout** (`local:default:domain_entity:checkout:v1`)
   - Type: domain_entity
   - Aliases: checkout, place order, purchase flow
   - Description: End-to-end customer checkout workflow

### Ontology YAML Files

- `./ontology/concepts.yaml` - 2 concept nodes loaded
- `./ontology/workflows.yaml` - Not present (no procedural ontology)

---

## Bug Fixes Applied

### 1. CozoDB Query Syntax Fix (get_ontology_status)

**Problem:** Queries used `code_elements` without `*` prefix, causing "Requested rule code_elements not found" errors.

**Fix:** Changed queries to use `*code_elements` prefix and `regex_matches()` instead of `=~` operator.

**Commit:** `68dd72c` - fix: add * prefix and use row count for ontology status queries

### 2. Workflow Search Fix (search_workflows)

**Problem:** Query used `=~` operator which fails in CozoDB.

**Fix:** Replaced with `regex_matches()` function.

**Commit:** `7163c8f` - fix: replace =~ with regex_matches for workflow search

---

## Semantic Search Examples

### Query: "checkout"
```
domain_entity  | ontology://local:default:domain_entity:checkout:v1 | Checkout | 15.0
function       | ./src/hooks/mod.rs::generate_post_checkout_script | 4.0
function       | ./src/hooks/mod.rs::install_post_checkout | 4.0
property      | ./src/hooks/mod.rs::post_checkout_backup_exists | 4.0
property      | ./src/hooks/mod.rs::post_checkout_installed | 4.0
```

### Query: "refund"
```
domain_entity | ontology://local:checkout-service:domain_entity:refund:v1 | Refund | 15.0
```

---

## Multi-Project Support

The MCP server supports multi-project routing via path mapping:

| Host Path | Container Path |
|-----------|----------------|
| `/Users/linh.doan/work/be` | `/workspace-be` |

**Indexed Files:**
- LeanKG workspace: 271 files
- `/workspace-be` (be project): 22,008 files

---

## Git Commits (Recent)

| Commit | Description |
|--------|-------------|
| `7163c8f` | fix: replace =~ with regex_matches for workflow search |
| `68dd72c` | fix: add * prefix and use row count for ontology status queries |
| `3f53030` | feat: add /workspace-be volume mount to docker-compose.rocksdb.yml |

---

## Recommendations

1. **Add Workflows YAML**: Create `./ontology/workflows.yaml` to enable procedural ontology with workflow_step and failure_mode tracking.

2. **Start Docker Container**: Run `docker-compose -f docker-compose.rocksdb.yml up -d` to enable the RocksDB-backed container for production use.

3. **Enable Authentication**: Consider enabling authentication for the MCP HTTP server in production environments.

4. **Add Aliases**: The ontology nodes currently have 0 aliases. Consider adding alias mappings to improve semantic search recall.

---

*Generated by Claude Code - LeanKG MCP Server Validation*