kmp-api-lookup-mcp

Kotlin/Native iOS klib APIを高速に検索するためのMCPサーバー。

このサーバーは、ローカルのKotlin/Nativeプラットフォームklibを永続的なSQLiteデータベースにインデックス化し、シンボル検索とインデックス管理のためのコンパクトなMCP APIを提供します。

インストール

前提条件

• Node.js 22以上

• KONAN_HOME または ~/.konan を通じて利用可能なプラットフォームklibを含む、ローカルのKotlin/Nativeインストール環境

npmからインストール（推奨）

npm install -g kmp-api-lookup-mcp

グローバルインストールせずにnpxで実行

npx -y kmp-api-lookup-mcp

これはパッケージをグローバルにインストールしません。npmが公開されているバイナリをオンデマンドでダウンロードして実行します。

ソースからインストール

git clone https://github.com/SuLG-ik/kmp-api-lookup-mcp.git
cd kmp-api-lookup-mcp
npm install
npm run build
npm link

クイックスタート

MCPサーバーとして使用

MCPクライアントの設定にサーバーを追加します。

一般的な設定ファイルの場所:

• macOS Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows Claude Desktop: %APPDATA%/Claude/claude_desktop_config.json

• Linux Claude Desktop: ~/.config/Claude/claude_desktop_config.json

リポジトリにはコピーして使える設定ファイルの例が含まれています:

• claude_desktop_config.json.example (グローバルnpmインストール用)

• claude_desktop_config.npx.json.example (npx経由で公開パッケージを実行する場合)

• claude_desktop_config.konan_home.json.example (明示的な KONAN_HOME を指定したグローバルnpmインストール用)

• claude_desktop_config.from_source.json.example (リポジトリからビルドしたサーバーを実行する場合)

パッケージがグローバルにインストールされている場合:

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "kmp-api-lookup-mcp"
		}
	}
}

パッケージをグローバルにインストールしたくない場合:

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "npx",
			"args": ["-y", "kmp-api-lookup-mcp"]
		}
	}
}

これは素早いセットアップには便利ですが、初回起動時は npx がパッケージをダウンロードする必要があるため、時間がかかる場合があります。

特定のKotlin/Nativeインストール環境を直接指定したい場合:

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "kmp-api-lookup-mcp",
			"env": {
				"KONAN_HOME": "/Users/you/.konan/kotlin-native-prebuilt-macos-aarch64-2.2.21"
			}
		}
	}
}

ソースからサーバーを実行する場合:

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "node",
			"args": ["/absolute/path/to/kmp-api-lookup-mcp/dist/index.js"]
		}
	}
}

初回実行

サーバー起動後、通常は以下の手順を行います:

1. get_klib_index_status を呼び出し、インデックスが既に存在するか確認します。

2. インデックスがない場合は、必要なKotlin/Nativeバージョンとターゲットに対して rebuild_klib_index を呼び出します。

3. lookup_symbol でシンボルのクエリを開始します。

インデックス再構築リクエストの例:

{
	"kotlinVersion": "2.2.21",
	"target": "ios_simulator_arm64",
	"frameworks": ["AVFoundation", "AVKit", "MediaPlayer", "AVFAudio"]
}

現在のスコープ

• stdio経由のTypeScript npm ESM MCPサーバー

• ユーザーキャッシュディレクトリ内の永続的なSQLiteキャッシュ

• KONAN_HOME、~/.konan、または明示的なパスによるKotlin/Nativeプリビルド環境の検出

• klib dump-metadata-signatures による手動インデックス再構築

• 完全なKotlinシグネチャ、クラス階層、インポートのための klib dump-metadata からのオンデマンドな情報拡充

• 短いテキスト要約を含む構造化されたJSON MCPレスポンス

実装済みのツール

lookup_symbol

Kotlin/Native Appleプラットフォームのクラス、メンバー、またはトップレベルのプラットフォームエイリアス/定数を、コンパクトな開発用カードとして解決します。

入力:

{
	"query": "AVPlayer",
	"frameworks": ["AVFoundation"],
	"detail": "compact",
	"queryKind": "auto"
}

動作:

• AVPlayer のようなクラスクエリは、以下の情報を含むクラスカードを1つ返します:

  • 完全なKotlinクラスシグネチャ

  • スーパークラスおよび実装されたインターフェース

  • detail が省略されているか compact に設定されている場合、すべてのコンストラクタ、インスタンスメソッド、クラスメソッド（出力サイズを減らすためにメンバー名でグループ化）

  • コンパクトモードでは、プロパティに対応するゲッター/セッターメソッドが存在する場合、明示的な accessors.getter および accessors.setter フラグを持つ properties リストを別途作成

  • コンパクトモードは重複するプロパティアクセサーメソッドのみを削除し、クラス表面から無関係なメソッドをトリミングすることはありません

  • detail が full に設定されている場合、完全な直接メンバーセット、ObjCブリッジ拡張メンバー、および Meta クラスメンバー

  • コード生成のための requiredImports

• AVPlayer.play や play のようなメンバークエリは、オーバーロードのシグネチャとインポートを含むコンパクトなグループ化カードを返します。

• AVPlayerStatus、AVLayerVideoGravity、AVPlayerItemDidPlayToEndTimeNotification のような正確なトップレベルのプラットフォームエイリアスや定数は、曖昧なクラスマッチに陥ることなく、パッケージスコープのメンバーカードとして解決されます。

• クエリが曖昧な場合、ツールは生の検索結果をダンプする代わりに、短い代替リストを返します。

• 出力には、DBパス、内部ID、生のメタデータダンプ、マッチングステージ、インストールパスなどのノイズの多いフィールドは意図的に含まれていません。

• detail のデフォルトは compact です。クラスの全表面が必要な場合にのみ "detail": "full" を使用してください。

get_klib_index_status

コンパクトなインデックスの要約を返します。

入力:

{}

出力には以下が含まれます:

• ready (準備完了状態)

• 検出されたKotlin/Nativeバージョンとターゲット

• カウント付きのインデックス済みデータセット

• 合計シンボル数

• lastRebuildAt (最終再構築日時)

rebuild_klib_index

ローカルのklibからSQLiteインデックスを構築または更新します。

入力:

{
	"kotlinVersion": "2.2.21",
	"target": "ios_simulator_arm64",
	"frameworks": ["Foundation", "UIKit"],
	"force": false,
	"dryRun": false,
	"cleanBefore": true
}

ルール:

• kotlinVersion と konanHome はオプションですが、最大でどちらか一方のみを指定できます。

• 両方とも省略された場合、最後に検出されたローカルのKotlin/Nativeインストール環境が使用されます。

• target が省略された場合、サーバーは ios_simulator_arm64、次に ios_arm64、その次に ios_x64 を優先します。

• frameworks が省略された場合、再構築は選択されたターゲットのすべてのフレームワークを対象とします。

• dryRun=true は、SQLiteに書き込まずに再構築計画を計算します。

• force=true は、鮮度チェックを無視します。

• cleanBefore=true は、新しいレコードを書き込む前に、影響を受けるフレームワークの既存の行を削除します。

ストレージレイアウト

サーバーはデータをリポジトリ外に保存します。

• SQLite DB: ユーザーキャッシュディレクトリ + klib-index.sqlite

• サービスメタデータ: ユーザーキャッシュディレクトリ + state.json

一般的なキャッシュの場所:

• macOS: ~/Library/Caches/kmp-api-lookup-mcp/

• Linux: ${XDG_CACHE_HOME:-~/.cache}/kmp-api-lookup-mcp/

• Windows: %LOCALAPPDATA%/kmp-api-lookup-mcp/

検出ルール

インストール環境は以下の順序で検出されます:

1. ツールが提供する明示的な konanHome 引数

2. KONAN_HOME

3. ~/.konan/kotlin-native-prebuilt-*

各インストール環境は、以下が存在するかどうかで検証されます:

• bin/klib

• klib/platform/

MCP設定

ソースから実行

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "node",
			"args": ["/absolute/path/to/kmp-api-lookup-mcp/dist/index.js"]
		}
	}
}

オプションの環境変数オーバーライド:

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "node",
			"args": ["/absolute/path/to/kmp-api-lookup-mcp/dist/index.js"],
			"env": {
				"KONAN_HOME": "/Users/you/.konan/kotlin-native-prebuilt-macos-aarch64-2.2.21"
			}
		}
	}
}

インストール済みバイナリとして実行

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "kmp-api-lookup-mcp"
		}
	}
}

一般的なインストール済みバイナリの設定

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "kmp-api-lookup-mcp",
			"env": {
				"KONAN_HOME": "/Users/you/.konan/kotlin-native-prebuilt-macos-aarch64-2.2.21"
			}
		}
	}
}

開発

スクリプト

• npm run dev: TypeScriptソースからサーバーを起動

• npm run build: dist/ にコンパイル

• npm start: コンパイルされたサーバーを実行

• npm run typecheck: TypeScriptの型チェックを実行

• npm test: Vitestを実行

• npm run test:watch: ウォッチモードでVitestを起動

ローカルワークフロー

npm install
npm run typecheck
npm run build
npm test

公開

npmへの公開はGitHub Actionsによって処理されます。

• package.json の version と一致する vX.Y.Z 形式のタグをプッシュします。

• Publish Package ワークフローがパッケージを検証し、npmに公開します。

• npmパッケージは、SuLG-ik/kmp-api-lookup-mcp GitHubリポジトリからの信頼された公開（Trusted Publishing）用に設定されている必要があります。

• 一回限りのnpmセットアップと正確なリリース手順については、PUBLISHING.md を参照してください。

テストカバレッジ

現在のテストスイートは以下をカバーしています:

• MCPツールの登録

• dump-metadata-signatures の行解析

• 合成フィクスチャ上でのSQLiteストレージと検索動作

• サーバーランタイムの作成

プロジェクト構造

.
├── src/
│   ├── index.ts
│   ├── config/
│   ├── indexer/
│   ├── server/
│   ├── storage/
│   ├── tools/
│   ├── search-utils.ts
│   └── types.ts
├── test/
├── package.json
├── tsconfig.json
├── tsconfig.build.json
└── vitest.config.ts