kiri-mcp-server 0.5.0 → 0.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Intelligent code context extraction for LLMs via Model Context Protocol
 
-[![Version](https://img.shields.io/badge/version-0.4.1-blue.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.7.0-blue.svg)](package.json)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
@@ -12,11 +12,12 @@
 ## 🎯 Why KIRI?
 
 - **🔌 MCP Native**: Plug-and-play integration with Claude Desktop, Codex CLI, and other MCP clients
-- **🧠 Smart Context**: Extract minimal, relevant code fragments based on task goals
+- **🧠 Smart Context**: Extract minimal, relevant code fragments based on task goals (95% accuracy)
 - **⚡ Fast**: Sub-second response time for most queries
 - **🔍 Semantic Search**: Multi-word queries, dependency analysis, and BM25 ranking
 - **👁️ Auto-Sync**: Watch mode automatically re-indexes when files change
 - **🛡️ Reliable**: Degrade-first architecture works without optional extensions
+- **📝 Phrase-Aware**: Recognizes compound terms (kebab-case, snake_case) for precise matching
 
 ## ⚙️ Prerequisites
 
@@ -152,9 +153,16 @@ KIRI provides 5 MCP tools for intelligent code exploration:
 
 ### 1. context_bundle
 
-**Extract relevant code context based on task goals**
+**Extract relevant code context based on task goals (95% accuracy)**
 
-The most powerful tool for getting started with unfamiliar code. Provide a task description, and KIRI returns the most relevant code snippets.
+The most powerful tool for getting started with unfamiliar code. Provide a task description, and KIRI returns the most relevant code snippets using phrase-aware tokenization and path-based scoring.
+
+**v0.7.0 improvements:**
+
+- **Multiplicative penalties**: Documentation files now penalized by ×0.3 (70% reduction) instead of additive -2.0
+- **Implementation prioritization**: Implementation files rank 5-10× higher than documentation (1.82 vs 0.30)
+- **Unified boosting logic**: Consistent file ranking across `files_search` and `context_bundle`
+- **Configurable profiles**: `boost_profile` parameter supports "default" (implementation-first), "docs" (documentation-first), or "none" (natural BM25)
 
 **When to use:**
 
@@ -405,11 +413,57 @@ kiri --repo . --db .kiri/index.duckdb --watch --debounce 1000
 **Watch Mode Features:**
 
 - **Debouncing**: Aggregates rapid changes to minimize reindex operations
+- **Incremental Indexing**: Only reindexes changed files (10-100x faster)
 - **Background Operation**: Doesn't interrupt ongoing queries
 - **Denylist Integration**: Respects `.gitignore` and `denylist.yml`
 - **Lock Management**: Prevents concurrent indexing
 - **Statistics**: Tracks reindex count, duration, and queue depth
 
+### Tokenization Strategy
+
+Control how KIRI tokenizes and matches compound terms using the `KIRI_TOKENIZATION_STRATEGY` environment variable:
+
+```bash
+# Phrase-aware (default): Recognizes kebab-case/snake_case as phrases
+export KIRI_TOKENIZATION_STRATEGY=phrase-aware
+
+# Legacy: Traditional word-by-word tokenization
+export KIRI_TOKENIZATION_STRATEGY=legacy
+
+# Hybrid: Both phrase and word-level matching
+export KIRI_TOKENIZATION_STRATEGY=hybrid
+```
+
+**Strategies:**
+
+- **`phrase-aware`** (default): Compound terms like `page-agent`, `user_profile` are treated as single phrases with 2× scoring weight. Best for codebases with consistent naming conventions.
+- **`legacy`**: Traditional tokenization that splits all delimiters. Use for backward compatibility.
+- **`hybrid`**: Combines both strategies for maximum flexibility.
+
+### Database Auto-Gitignore
+
+KIRI automatically creates `.gitignore` files in database directories to prevent accidental commits:
+
+```typescript
+// Enabled by default
+const db = await DuckDBClient.connect({
+  databasePath: ".kiri/index.duckdb",
+  autoGitignore: true, // Creates .gitignore with "*" pattern
+});
+
+// Disable if needed
+const db = await DuckDBClient.connect({
+  databasePath: ".kiri/index.duckdb",
+  autoGitignore: false,
+});
+```
+
+**Behavior:**
+
+- Only creates `.gitignore` if directory is inside a Git repository
+- Never overwrites existing `.gitignore` files
+- Uses wildcard pattern (`*`) to ignore all database files
+
 ### File Type Boosting
 
 Control search ranking behavior with the `boost_profile` parameter:
@@ -680,6 +734,6 @@ Built with:
 
 ---
 
-**Status**: v0.4.1 (Beta) - Production-ready for MCP clients
+**Status**: v0.7.0 (Beta) - Production-ready for MCP clients
 
 For questions or support, please open a [GitHub issue](https://github.com/CAPHTECH/kiri/issues).

package/config/default.example.yml

@@ -4,6 +4,15 @@ mcp:
   tools:
     - context_bundle
     - files_search
+
+# Tokenization configuration for keyword extraction
+tokenization:
+  # Strategy: "phrase-aware" (default), "legacy", or "hybrid"
+  # - phrase-aware: Preserves hyphenated terms (e.g., "page-agent" stays as one unit)
+  # - legacy: Splits on hyphens (e.g., "page-agent" → ["page", "agent"])
+  # - hybrid: Emits both phrases and split keywords
+  strategy: "phrase-aware"
+
 indexer:
   repoRoot: "../../target-repo"
   database: "var/index.duckdb"

package/config/scoring-profiles.yml

@@ -2,36 +2,51 @@
 # Each profile defines weights for different ranking signals
 
 default:
-  textMatch: 0.8 # Text/keyword match weight (reduced to decrease noise from broad matches)
+  textMatch: 1.0 # Text/keyword match weight (increased to prioritize literal matches)
+  pathMatch: 1.5 # Path-based match weight (new - prioritizes files with keywords in paths)
   editingPath: 2.0 # Currently editing file weight
   dependency: 0.6 # Dependency relationship weight (increased to prioritize connected implementation files)
   proximity: 0.25 # Same directory weight
-  structural: 1.0 # Structural similarity weight (increased to improve semantic matching for broad terms)
+  structural: 0.6 # Structural similarity weight (reduced to prevent false positives from similar structure)
+  docPenaltyMultiplier: 0.3 # Multiplicative penalty for docs (0.3 = 70% reduction, Phase 1 conservative value)
+  implBoostMultiplier: 1.3 # Multiplicative boost for implementation files (1.3 = 30% boost)
 
 bugfix:
   textMatch: 1.0
+  pathMatch: 1.5
   editingPath: 1.8
   dependency: 0.7 # Higher: bugs often in dependencies
   proximity: 0.35
-  structural: 0.9 # Higher: structural understanding helps
+  structural: 0.7 # Reduced: prevent canvas-agent matching when searching page-agent
+  docPenaltyMultiplier: 0.3
+  implBoostMultiplier: 1.3
 
 testfail:
   textMatch: 1.0
+  pathMatch: 1.5
   editingPath: 1.6
   dependency: 0.85 # Very high: failed tests reveal dependencies
   proximity: 0.3
-  structural: 0.8
+  structural: 0.7 # Reduced: focus on actual test dependencies
+  docPenaltyMultiplier: 0.3
+  implBoostMultiplier: 1.3
 
 typeerror:
   textMatch: 1.0
+  pathMatch: 1.5
   editingPath: 1.4
   dependency: 0.6
   proximity: 0.4 # Higher: type errors cluster in modules
-  structural: 0.6 # Lower: type errors are structural
+  structural: 0.6 # Already balanced for type analysis
+  docPenaltyMultiplier: 0.3
+  implBoostMultiplier: 1.3
 
 feature:
   textMatch: 1.0
+  pathMatch: 1.5
   editingPath: 1.5
   dependency: 0.45 # Lower: new features less dependent
   proximity: 0.5 # Higher: features cluster spatially
-  structural: 0.7
+  structural: 0.6 # Reduced: focus on actual feature files
+  docPenaltyMultiplier: 0.3
+  implBoostMultiplier: 1.3

package/dist/config/default.example.yml

@@ -4,6 +4,15 @@ mcp:
   tools:
     - context_bundle
     - files_search
+
+# Tokenization configuration for keyword extraction
+tokenization:
+  # Strategy: "phrase-aware" (default), "legacy", or "hybrid"
+  # - phrase-aware: Preserves hyphenated terms (e.g., "page-agent" stays as one unit)
+  # - legacy: Splits on hyphens (e.g., "page-agent" → ["page", "agent"])
+  # - hybrid: Emits both phrases and split keywords
+  strategy: "phrase-aware"
+
 indexer:
   repoRoot: "../../target-repo"
   database: "var/index.duckdb"

package/dist/config/scoring-profiles.yml

@@ -2,36 +2,51 @@
 # Each profile defines weights for different ranking signals
 
 default:
-  textMatch: 0.8 # Text/keyword match weight (reduced to decrease noise from broad matches)
+  textMatch: 1.0 # Text/keyword match weight (increased to prioritize literal matches)
+  pathMatch: 1.5 # Path-based match weight (new - prioritizes files with keywords in paths)
   editingPath: 2.0 # Currently editing file weight
   dependency: 0.6 # Dependency relationship weight (increased to prioritize connected implementation files)
   proximity: 0.25 # Same directory weight
-  structural: 1.0 # Structural similarity weight (increased to improve semantic matching for broad terms)
+  structural: 0.6 # Structural similarity weight (reduced to prevent false positives from similar structure)
+  docPenaltyMultiplier: 0.3 # Multiplicative penalty for docs (0.3 = 70% reduction, Phase 1 conservative value)
+  implBoostMultiplier: 1.3 # Multiplicative boost for implementation files (1.3 = 30% boost)
 
 bugfix:
   textMatch: 1.0
+  pathMatch: 1.5
   editingPath: 1.8
   dependency: 0.7 # Higher: bugs often in dependencies
   proximity: 0.35
-  structural: 0.9 # Higher: structural understanding helps
+  structural: 0.7 # Reduced: prevent canvas-agent matching when searching page-agent
+  docPenaltyMultiplier: 0.3
+  implBoostMultiplier: 1.3
 
 testfail:
   textMatch: 1.0
+  pathMatch: 1.5
   editingPath: 1.6
   dependency: 0.85 # Very high: failed tests reveal dependencies
   proximity: 0.3
-  structural: 0.8
+  structural: 0.7 # Reduced: focus on actual test dependencies
+  docPenaltyMultiplier: 0.3
+  implBoostMultiplier: 1.3
 
 typeerror:
   textMatch: 1.0
+  pathMatch: 1.5
   editingPath: 1.4
   dependency: 0.6
   proximity: 0.4 # Higher: type errors cluster in modules
-  structural: 0.6 # Lower: type errors are structural
+  structural: 0.6 # Already balanced for type analysis
+  docPenaltyMultiplier: 0.3
+  implBoostMultiplier: 1.3
 
 feature:
   textMatch: 1.0
+  pathMatch: 1.5
   editingPath: 1.5
   dependency: 0.45 # Lower: new features less dependent
   proximity: 0.5 # Higher: features cluster spatially
-  structural: 0.7
+  structural: 0.6 # Reduced: focus on actual feature files
+  docPenaltyMultiplier: 0.3
+  implBoostMultiplier: 1.3

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "kiri-mcp-server",
-    "version": "0.5.0",
+    "version": "0.7.0",
     "description": "KIRI context extraction platform",
     "type": "module",
     "packageManager": "pnpm@9.0.0",

package/dist/server/context.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=context.js.map