kiri-mcp-server 0.10.0 → 0.11.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.11.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/)
@@ -55,6 +55,10 @@ 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`).
+
 > **Note**: This installs the `kiri` command globally. You can verify with `kiri --version`.
 
 **Option B: Use npx (No Permanent Installation)**
@@ -188,6 +192,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 +265,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:**
 

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/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.11.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"}