kiri-mcp-server

KIRI MCP Server

Intelligent code context extraction for LLMs via Model Context Protocol

KIRI is an MCP server that provides intelligent code context extraction from Git repositories. It indexes your codebase into DuckDB and exposes semantic search tools for LLMs.

Why KIRI?

• MCP Native: Plug-and-play with Claude Desktop, Codex CLI, and other MCP clients
• Smart Context: Extract minimal, relevant code fragments based on task goals
• Accurate: MRR 1.0 — the most relevant file always ranks first
• Fast: Sub-second response time for most queries
• Semantic Search: Multi-word queries, dependency analysis, BM25 ranking
• Auto-Sync: Watch mode automatically re-indexes on file changes
• Phrase-Aware: Recognizes compound terms (kebab-case, snake_case)

Quick Start

1. Install

npm install -g kiri-mcp-server

Or use npx without installation.

2. Configure Claude Code

Edit ~/.claude/mcp.json:

{
  "mcpServers": {
    "kiri": {
      "command": "kiri",
      "args": ["--repo", ".", "--db", ".kiri/index.duckdb", "--watch"]
    }
  }
}

3. Restart Claude Code

KIRI automatically indexes your repository on first startup.

Other MCP clients: See Setup Guide for Codex CLI and other configurations.

MCP Tools

Tool	Purpose	Example
context_bundle	Find relevant code for a task	goal: "auth token refresh bug"
files_search	Search files by keywords	query: "handler"
snippets_get	Read specific code sections	path: "src/server/handlers.ts"
deps_closure	Analyze dependencies	direction: "inbound"
semantic_rerank	Refine search results	candidates: [...]

Full documentation: Tools Reference

Supported Languages

Language	Extensions	Parser
TypeScript	.ts, .tsx	TypeScript Compiler API
Swift	.swift	tree-sitter-swift
PHP	.php	tree-sitter-php
Java	.java	tree-sitter-java
Dart	.dart	Dart Analysis Server
Rust	.rs	tree-sitter-rust

Other languages are indexed but use full-file snippets instead of symbol extraction.

Troubleshooting

Database Issues

# Delete and rebuild
rm -rf .kiri/
# Restart MCP client - KIRI will automatically reindex

Daemon Timeout (Large Repositories)

{
  "env": { "KIRI_DAEMON_READY_TIMEOUT": "480" }
}

Stale Lock File

rm -f .kiri/index.duckdb.sock.lock

Version Mismatch After Upgrade

pkill -f "kiri.*daemon"

More issues: See full troubleshooting guide below.

For Developers

git clone https://github.com/CAPHTECH/kiri.git
cd kiri
pnpm install
pnpm run build
pnpm run test
pnpm run dev  # HTTP server on :8765

Guidelines: See AGENTS.md for development standards.

Documentation

Document	Description
Setup Guide	Installation and MCP client configuration
Tools Reference	Complete MCP tools documentation
Configuration	Environment variables and advanced settings
Architecture	System design and data flow
Data Model	Database schema details
Search & Ranking	Search algorithms
API Reference	Complete API documentation
Authoring Docs	Writing metadata-rich documentation

Changelog

See CHANGELOG.md for release notes.

Recent highlights:

• v0.25.6: Fix daemon startup deadlock from v0.25.5
• v0.25.4: snippets_get content size handling improvements
• v0.25.3: Query language guidance in MCP tool descriptions (PR #182)
• v0.25.2: Auto reindex on DeserializeDeletes IO corruption (PR #181)

Detailed Troubleshooting

Daemon Initialization Timeout

Problem: "Daemon did not become ready within X seconds"

Solutions:

• Increase timeout (Claude Code: KIRI_DAEMON_READY_TIMEOUT=480, Codex CLI: startup_timeout_sec = 480)
• Check logs: cat .kiri/index.duckdb.daemon.log
• Manual test: kiri --repo . --db .kiri/index.duckdb --port 8765

Command Not Found

# Verify installation
npm list -g kiri-mcp-server

# Re-link
npm link kiri-mcp-server

# Or use npx
npx kiri-mcp-server@latest --repo . --db .kiri/index.duckdb

Slow Indexing

• Check size: git ls-files | wc -l
• Review .gitignore
• Add denylist: Create .kiri/denylist.yml:

patterns:
  - "**/*.min.js"
  - "**/vendor/**"

DuckDB Native Binding Errors

# Use pnpm link, not npm link
rm -rf node_modules pnpm-lock.yaml
pnpm install --frozen-lockfile
pnpm rebuild duckdb
pnpm run build
pnpm link --global

Schema Mismatch (Degrade Mode)

pkill -f "kiri.*daemon"
rm -f .kiri/index.duckdb.sock.lock .kiri/index.duckdb.sock
kiri --repo . --db .kiri/index.duckdb --full

Getting Help

• Check logs: .kiri/index.duckdb.daemon.log
• Enable debug: DEBUG=kiri:*
• GitHub Issues
• Discussions

License

MIT License - See LICENSE.

Acknowledgments

Built with Model Context Protocol, DuckDB, and tree-sitter.

Status: v0.25.6 (Beta) - Production-ready for MCP clients