kiri-mcp-server 0.10.0 → 0.12.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.10.0-blue.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.12.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/)
@@ -20,11 +20,22 @@
 - **📝 Phrase-Aware**: Recognizes compound terms (kebab-case, snake_case) for precise matching
 - **🔒 Concurrency-Safe** _(v0.9.7+)_: Per-database queues, canonicalized DuckDB paths, and bootstrap-safe locking prevent FTS rebuild conflicts and keep locks consistent across symlinks—even on first run
 
-## 🆕 What’s New in v0.9.8
+## 🆕 What's New in v0.12.0
 
-- First-time bootstrap now skips redundant DuckDB locking, so `kiri` / `kiri-server` can index fresh repositories without deadlocking on their own locks.
-- Added regression coverage (`tests/server/indexBootstrap.spec.ts`) to ensure repeated `ensureDatabaseIndexed` calls reuse the lock cleanly.
-- All reliability upgrades from v0.9.7 (automatic ILIKE degrade during FTS rebuilds, canonicalized DB paths, expanded verify suite) remain in effect.
+### 🔧 Improvements
+
+- **Request Tracing**: Added optional `requestId` parameter to `context_bundle` for debugging and tracing
+- **Tokenizer Enhancement**: Improved keyword extraction with camelCase/snake_case variant support
+- **Path Penalties**: Configurable path penalties via config files for fine-tuned search results
+
+### 🐛 Bug Fixes
+
+- **TypeScript Compatibility**: Fixed build errors related to `exactOptionalPropertyTypes`
+- **Search Precision**: Improved candidate trimming to only affect fallback-only results
+
+### 📚 Documentation
+
+- Added path penalties user and developer guides (EN/JA)
 
 ## ⚙️ Prerequisites
 
@@ -43,6 +54,27 @@ npm --version   # Should be >= v9.0.0
 git --version   # Should be >= v2.0
 ```
 
+## ⚠️ Troubleshooting
+
+### Migration or Database Issues
+
+If you encounter issues after upgrading (database corruption, migration failures, etc.), the simplest solution is to delete the database and let KIRI recreate it:
+
+```bash
+# For MCP users (Claude Code, Codex CLI, etc.)
+# 1. Restart your MCP client to stop the KIRI server
+# 2. Delete the database
+rm -rf .kiri/
+# 3. Restart your MCP client - KIRI will automatically reindex
+
+# For CLI/Daemon users
+pkill -f "kiri.*daemon"  # Stop daemon if running
+rm -rf .kiri/            # Delete database
+kiri --repo . --db .kiri/index.duckdb --full  # Reindex
+```
+
+> **Note**: Deleting the database is safe - it only removes the index, not your source code. KIRI will automatically rebuild the index on next startup. For MCP users, no manual reindexing is needed.
+
 ## 🚀 Quick Start for MCP Users
 
 ### Step 1: Install KIRI
@@ -55,6 +87,11 @@ Choose one of the following methods:
 npm install -g kiri-mcp-server
 ```
 
+## 📚 Documentation
+
+- [Authoring Docs for KIRI Search](docs/documentation-best-practices.md) – best practices for writing metadata-rich, link-aware documentation so that `context_bundle` and the docs vs. docs-plain benchmark maintain high precision. Includes guidance on querying custom front-matter keys via `meta.<key>:<value>` (for example, `meta.id:runbook-001`).
+- [Path Penalties (User Guide)](docs/user/path-penalties.md) – `.kiri/config.yaml` と環境変数でパス倍率を設定する手順、優先順位、正規化ルール、適用タイミングをまとめたユーザー向けガイド。
+
 > **Note**: This installs the `kiri` command globally. You can verify with `kiri --version`.
 
 **Option B: Use npx (No Permanent Installation)**
@@ -188,6 +225,8 @@ The most powerful tool for getting started with unfamiliar code. Provide a task
 
 Tip: Avoid leading command words like `find` or `show`; instead list concrete modules, files, and observed symptoms to keep rankings sharp.
 
+> **Docs search tip:** Set `boost_profile: "docs"` and include metadata filters when the target lives under `docs/`. Front matter keys are queryable via `meta.<key>:<value>` or `frontmatter.<key>:<value>` — e.g., `meta.id:runbook-001`, `tag:degrade`, `category:operations`. Use `docmeta.<key>:<value>` (or legacy `metadata.<key>`) when you want strict doc-only filtering. See the [Metadata alias reference](docs/documentation-best-practices.md#metadata-aliases--filters) for the full list. This keeps `context_bundle` aligned with the docs vs docs-plain benchmark expectations.
+
 **v0.8.0 improvements:**
 
 - **⚡ Compact mode default (BREAKING)**: `compact: true` is now default, reducing token usage by ~95% (55K → 2.5K tokens). Set `compact: false` to restore full preview mode.
@@ -259,6 +298,9 @@ Fast search across all indexed files. Supports multi-word queries, hyphenated te
 - Multi-word: `"tools call implementation"` → Finds files containing ANY word
 - Hyphenated: `"MCP-server-handler"` → Splits on hyphens and searches each part
 - Single word: `"DuckDB"` → Exact match
+- Metadata filter: `meta.<key>:<value>` / `frontmatter.<key>:<value>` matches front matter (e.g., `meta.id:runbook-001`); `tag:<value>` / `category:<value>` remain shorthand aliases for those standard keys. Use `docmeta.<key>:<value>` (or `metadata.<key>`) when you need strict doc-only filtering.
+
+> **Docs search tip:** Combine `boost_profile: "docs"` (either by parameter or CLI flag) with metadata filters for Markdown corpora. Refer to the [Metadata alias reference](docs/documentation-best-practices.md#metadata-aliases--filters) when issuing `files_search` requests so the same filters you use in benchmarks carry over to ad-hoc queries, and switch to `docmeta.*` when you want docs only.
 
 **Parameters:**
 
@@ -751,11 +793,11 @@ See [docs/architecture.md](docs/architecture.md) for detailed technical informat
 
 ### Performance
 
-| Metric                        | Target | Current       |
-| ----------------------------- | ------ | ------------- |
-| **Time to First Result**      | ≤ 1.0s | ✅ 0.8s       |
-| **Precision @ 10**            | ≥ 0.7  | ✅ 0.75       |
-| **Token Reduction (compact)** | ≥ 90%  | ✅ 95% (v0.8) |
+| Metric                        | Target | Current                                                                                 |
+| ----------------------------- | ------ | --------------------------------------------------------------------------------------- |
+| **Time to First Result**      | ≤ 1.0s | ✅ 0.8s                                                                                 |
+| **Precision @ 10**            | ≥ 0.7  | ⚠️ 0.25 (2025-11-21, dataset v2025-11-docs-plain, K=10, see var/eval/2025-11-21-k10.md) |
+| **Token Reduction (compact)** | ≥ 90%  | ✅ 95% (v0.8)                                                                           |
 
 ### Evaluation & Quality Assurance
 

package/config/kiri.yml

@@ -0,0 +1,25 @@
+path_penalties:
+  # Reduce noisy auxiliary packages
+  - prefix: ".eslint-plugin-local/"
+    multiplier: 0.1
+  - prefix: "cli/"
+    multiplier: 0.25
+  - prefix: "cli/src/"
+    multiplier: 0.2
+  - prefix: "extensions/"
+    multiplier: 0.15
+  - prefix: "tests/eval/"
+    multiplier: 0.05
+  - prefix: "datasets/"
+    multiplier: 0.05
+  - prefix: "tests/"
+    multiplier: 0.3
+  - prefix: "examples/"
+    multiplier: 0.1
+  - prefix: "fixtures/"
+    multiplier: 0.1
+  - prefix: "testdata/"
+    multiplier: 0.1
+  # Suppress repo-local baseline fixtures that surface via fallback
+  - prefix: "packages/assay-kit/baseline-tests"
+    multiplier: 0.05

package/config/scoring-profiles.yml

@@ -1,57 +1,104 @@
-# Scoring weight profiles for context_bundle
-# Each profile defines weights for different ranking signals
-
 default:
-  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: 0.6 # Structural similarity weight (reduced to prevent false positives from similar structure)
-  docPenaltyMultiplier: 0.5 # Multiplicative penalty for docs (0.5 = 50% reduction)
-  configPenaltyMultiplier: 0.05 # Multiplicative penalty for config files (0.05 = 95% reduction)
-  implBoostMultiplier: 1.3 # Multiplicative boost for implementation files (1.3 = 30% boost)
-
-bugfix:
   textMatch: 1.0
-  pathMatch: 1.5
+  pathMatch: 1.2
+  editingPath: 1.8
+  dependency: 1.0
+  proximity: 0.3
+  structural: 0.9
+  docPenaltyMultiplier: 0.6
+  configPenaltyMultiplier: 0.05
+  implBoostMultiplier: 1.5
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01
+feature:
+  textMatch: 1.0
+  pathMatch: 1.4
   editingPath: 1.8
-  dependency: 0.7 # Higher: bugs often in dependencies
+  dependency: 1.1
   proximity: 0.35
-  structural: 0.7 # Reduced: prevent canvas-agent matching when searching page-agent
+  structural: 0.95
   docPenaltyMultiplier: 0.5
   configPenaltyMultiplier: 0.05
-  implBoostMultiplier: 1.3
-
+  implBoostMultiplier: 1.5
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01
+bugfix:
+  textMatch: 1.0
+  pathMatch: 1.3
+  editingPath: 1.6
+  dependency: 1.2
+  proximity: 0.3
+  structural: 0.85
+  docPenaltyMultiplier: 0.5
+  configPenaltyMultiplier: 0.05
+  implBoostMultiplier: 1.4
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01
+debug:
+  textMatch: 1.0
+  pathMatch: 1.3
+  editingPath: 1.7
+  dependency: 1.2
+  proximity: 0.35
+  structural: 0.9
+  docPenaltyMultiplier: 0.5
+  configPenaltyMultiplier: 0.05
+  implBoostMultiplier: 1.45
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01
+api:
+  textMatch: 1.0
+  pathMatch: 1.5
+  editingPath: 1.8
+  dependency: 1.0
+  proximity: 0.3
+  structural: 0.95
+  docPenaltyMultiplier: 0.55
+  configPenaltyMultiplier: 0.05
+  implBoostMultiplier: 1.4
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01
+editor:
+  textMatch: 1.0
+  pathMatch: 1.4
+  editingPath: 1.9
+  dependency: 1.0
+  proximity: 0.4
+  structural: 0.9
+  docPenaltyMultiplier: 0.6
+  configPenaltyMultiplier: 0.05
+  implBoostMultiplier: 1.4
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01
 testfail:
   textMatch: 1.0
   pathMatch: 1.5
   editingPath: 1.6
-  dependency: 0.85 # Very high: failed tests reveal dependencies
+  dependency: 0.85
   proximity: 0.3
-  structural: 0.7 # Reduced: focus on actual test dependencies
+  structural: 0.8
   docPenaltyMultiplier: 0.5
   configPenaltyMultiplier: 0.05
   implBoostMultiplier: 1.3
-
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.2 # testfailではテストファイルへのペナルティを緩和（80%削減、他は98%削減）
+  lockPenaltyMultiplier: 0.01
 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 # Already balanced for type analysis
-  docPenaltyMultiplier: 0.5
-  configPenaltyMultiplier: 0.05
-  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.6 # Reduced: focus on actual feature files
+  proximity: 0.4
+  structural: 0.6
   docPenaltyMultiplier: 0.5
   configPenaltyMultiplier: 0.05
   implBoostMultiplier: 1.3
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01

package/dist/config/kiri.yml

@@ -0,0 +1,25 @@
+path_penalties:
+  # Reduce noisy auxiliary packages
+  - prefix: ".eslint-plugin-local/"
+    multiplier: 0.1
+  - prefix: "cli/"
+    multiplier: 0.25
+  - prefix: "cli/src/"
+    multiplier: 0.2
+  - prefix: "extensions/"
+    multiplier: 0.15
+  - prefix: "tests/eval/"
+    multiplier: 0.05
+  - prefix: "datasets/"
+    multiplier: 0.05
+  - prefix: "tests/"
+    multiplier: 0.3
+  - prefix: "examples/"
+    multiplier: 0.1
+  - prefix: "fixtures/"
+    multiplier: 0.1
+  - prefix: "testdata/"
+    multiplier: 0.1
+  # Suppress repo-local baseline fixtures that surface via fallback
+  - prefix: "packages/assay-kit/baseline-tests"
+    multiplier: 0.05

package/dist/config/scoring-profiles.yml

@@ -1,57 +1,104 @@
-# Scoring weight profiles for context_bundle
-# Each profile defines weights for different ranking signals
-
 default:
-  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: 0.6 # Structural similarity weight (reduced to prevent false positives from similar structure)
-  docPenaltyMultiplier: 0.5 # Multiplicative penalty for docs (0.5 = 50% reduction)
-  configPenaltyMultiplier: 0.05 # Multiplicative penalty for config files (0.05 = 95% reduction)
-  implBoostMultiplier: 1.3 # Multiplicative boost for implementation files (1.3 = 30% boost)
-
-bugfix:
   textMatch: 1.0
-  pathMatch: 1.5
+  pathMatch: 1.2
+  editingPath: 1.8
+  dependency: 1.0
+  proximity: 0.3
+  structural: 0.9
+  docPenaltyMultiplier: 0.6
+  configPenaltyMultiplier: 0.05
+  implBoostMultiplier: 1.5
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01
+feature:
+  textMatch: 1.0
+  pathMatch: 1.4
   editingPath: 1.8
-  dependency: 0.7 # Higher: bugs often in dependencies
+  dependency: 1.1
   proximity: 0.35
-  structural: 0.7 # Reduced: prevent canvas-agent matching when searching page-agent
+  structural: 0.95
   docPenaltyMultiplier: 0.5
   configPenaltyMultiplier: 0.05
-  implBoostMultiplier: 1.3
-
+  implBoostMultiplier: 1.5
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01
+bugfix:
+  textMatch: 1.0
+  pathMatch: 1.3
+  editingPath: 1.6
+  dependency: 1.2
+  proximity: 0.3
+  structural: 0.85
+  docPenaltyMultiplier: 0.5
+  configPenaltyMultiplier: 0.05
+  implBoostMultiplier: 1.4
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01
+debug:
+  textMatch: 1.0
+  pathMatch: 1.3
+  editingPath: 1.7
+  dependency: 1.2
+  proximity: 0.35
+  structural: 0.9
+  docPenaltyMultiplier: 0.5
+  configPenaltyMultiplier: 0.05
+  implBoostMultiplier: 1.45
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01
+api:
+  textMatch: 1.0
+  pathMatch: 1.5
+  editingPath: 1.8
+  dependency: 1.0
+  proximity: 0.3
+  structural: 0.95
+  docPenaltyMultiplier: 0.55
+  configPenaltyMultiplier: 0.05
+  implBoostMultiplier: 1.4
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01
+editor:
+  textMatch: 1.0
+  pathMatch: 1.4
+  editingPath: 1.9
+  dependency: 1.0
+  proximity: 0.4
+  structural: 0.9
+  docPenaltyMultiplier: 0.6
+  configPenaltyMultiplier: 0.05
+  implBoostMultiplier: 1.4
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01
 testfail:
   textMatch: 1.0
   pathMatch: 1.5
   editingPath: 1.6
-  dependency: 0.85 # Very high: failed tests reveal dependencies
+  dependency: 0.85
   proximity: 0.3
-  structural: 0.7 # Reduced: focus on actual test dependencies
+  structural: 0.8
   docPenaltyMultiplier: 0.5
   configPenaltyMultiplier: 0.05
   implBoostMultiplier: 1.3
-
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.2 # testfailではテストファイルへのペナルティを緩和（80%削減、他は98%削減）
+  lockPenaltyMultiplier: 0.01
 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 # Already balanced for type analysis
-  docPenaltyMultiplier: 0.5
-  configPenaltyMultiplier: 0.05
-  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.6 # Reduced: focus on actual feature files
+  proximity: 0.4
+  structural: 0.6
   docPenaltyMultiplier: 0.5
   configPenaltyMultiplier: 0.05
   implBoostMultiplier: 1.3
+  blacklistPenaltyMultiplier: 0.01
+  testPenaltyMultiplier: 0.02
+  lockPenaltyMultiplier: 0.01

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "kiri-mcp-server",
-    "version": "0.10.0",
+    "version": "0.12.0",
     "description": "KIRI context extraction platform",
     "type": "module",
     "packageManager": "pnpm@9.0.0",
@@ -65,12 +65,20 @@
         "verify:eval": "tsx scripts/test/verify-all.ts --category eval",
         "eval:golden": "tsx scripts/eval/run-golden.ts",
         "eval:golden:verbose": "tsx scripts/eval/run-golden.ts --verbose",
+        "assay:evaluate": "tsx scripts/assay/run-evaluation.ts",
+        "assay:compare": "tsx scripts/assay/run-comparison.ts",
+        "assay:compare:help": "tsx scripts/assay/run-comparison.ts --help",
+        "assay:baseline": "tsx scripts/assay/baseline.ts",
+        "assay:profile-matrix": "tsx scripts/assay/run-profile-matrix.ts",
+        "assay:report-matrix": "tsx scripts/assay/report-matrix.ts",
         "check": "pnpm run lint && pnpm run test",
         "prepublishOnly": "pnpm run build"
     },
     "dependencies": {
         "chokidar": "^4.0.3",
+        "csv-parse": "^5.5.6",
         "duckdb": "^1.1.0",
+        "fast-deep-equal": "^3.1.3",
         "gpt-tokenizer": "^3.2.0",
         "p-queue": "^9.0.0",
         "tree-sitter": "^0.22.0",

package/dist/src/indexer/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/indexer/cli.ts"],"names":[],"mappings":"AAkBA,UAAU,cAAc;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA0tBD,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAiTvE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/indexer/cli.ts"],"names":[],"mappings":"AAgCA,UAAU,cAAc;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAw9CD,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAkWvE"}