kmp-api-lookup-mcp

MCP-Server für die schnelle Suche nach Kotlin/Native iOS klib-APIs.

Der Server indiziert lokale Kotlin/Native-Plattform-klibs in einer persistenten SQLite-Datenbank und stellt eine kompakte MCP-API für die Symbolsuche und Indexwartung bereit.

Installation

Voraussetzungen

• Node.js 22+

• Eine lokale Kotlin/Native-Installation mit Plattform-klibs, verfügbar über KONAN_HOME oder ~/.konan

Über npm (empfohlen)

npm install -g kmp-api-lookup-mcp

Ausführen ohne globale Installation via npx

npx -y kmp-api-lookup-mcp

Dies installiert das Paket nicht global. npm lädt die veröffentlichte Binärdatei bei Bedarf herunter und führt sie aus.

Aus dem Quellcode

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

Schnellstart

Als MCP-Server

Fügen Sie den Server zu Ihrer MCP-Client-Konfiguration hinzu.

Typische Speicherorte für Konfigurationsdateien:

• 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

Kopierfertige Beispieldateien sind im Repository enthalten:

• claude_desktop_config.json.example für eine globale npm-Installation

• claude_desktop_config.npx.json.example für das Ausführen des veröffentlichten Pakets über npx

• claude_desktop_config.konan_home.json.example für eine globale npm-Installation mit explizitem KONAN_HOME

• claude_desktop_config.from_source.json.example für das Ausführen des gebauten Servers aus dem Repository

Wenn das Paket global installiert ist:

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

Wenn Sie das Paket nicht global installieren möchten:

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

Dies ist praktisch für eine schnelle Einrichtung, aber der erste Start kann langsamer sein, da npx das Paket möglicherweise herunterladen muss.

Wenn Sie direkt auf eine bestimmte Kotlin/Native-Installation verweisen möchten:

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

Wenn Sie den Server aus dem Quellcode ausführen:

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

Erster Start

Nachdem der Server gestartet wurde, sind die üblichen ersten Schritte:

1. Rufen Sie get_klib_index_status auf, um zu sehen, ob bereits ein Index existiert.

2. Wenn der Index fehlt, rufen Sie rebuild_klib_index für die benötigte Kotlin/Native-Version und das Ziel (Target) auf.

3. Beginnen Sie mit der Abfrage von Symbolen mit lookup_symbol.

Beispiel für eine Rebuild-Anfrage:

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

Aktueller Umfang

• TypeScript npm ESM MCP-Server über stdio

• Persistenter SQLite-Cache im Benutzer-Cache-Verzeichnis

• Erkennung von vorinstallierten Kotlin/Native-Installationen über KONAN_HOME, ~/.konan oder einen expliziten Pfad

• Manueller Index-Rebuild über klib dump-metadata-signatures

• On-Demand-Anreicherung über klib dump-metadata für vollständige Kotlin-Signaturen, Klassenhierarchie und Importe

• Strukturierte JSON-MCP-Antworten mit kurzen Textzusammenfassungen

Implementierte Tools

lookup_symbol

Löst eine Kotlin/Native Apple-Plattform-Klasse, einen Member oder einen Alias/eine Konstante auf oberster Ebene in eine kompakte Entwicklungskarte auf.

Eingabe:

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

Verhalten:

• Eine Klassenabfrage wie AVPlayer gibt eine Klassenkart mit folgenden Informationen zurück:

  • vollständige Kotlin-Klassensignatur

  • Superklasse und implementierte Interfaces

  • alle Konstruktoren, Instanzmethoden und Klassenmethoden, wenn detail weggelassen oder auf compact gesetzt ist, gruppiert nach Member-Name, um die Ausgabegröße zu reduzieren

  • eine separate properties-Liste im kompakten Modus mit expliziten accessors.getter- und accessors.setter-Flags, wenn passende Getter/Setter-Methoden für diese Eigenschaft existieren

  • der kompakte Modus entfernt nur duplizierte Eigenschafts-Accessor-Methoden; er kürzt keine unabhängigen Methoden von der Klassenschnittstelle

  • die vollständige direkte Member-Menge, ObjC-Bridge-Erweiterungsmember und Meta-Klassenmember, wenn detail auf full gesetzt ist

  • requiredImports für die Codegenerierung

• Eine Member-Abfrage wie AVPlayer.play oder play gibt eine kompakte gruppierte Karte mit Überladungssignaturen und Importen zurück.

• Exakte Plattform-Aliase und Konstanten auf oberster Ebene wie AVPlayerStatus, AVLayerVideoGravity oder AVPlayerItemDidPlayToEndTimeNotification werden als Member-Karten im Paket-Scope aufgelöst, anstatt in unscharfe Klassenübereinstimmungen zu zerfallen.

• Wenn die Abfrage mehrdeutig ist, gibt das Tool eine kurze Liste von Alternativen zurück, anstatt rohe Suchergebnisse auszugeben.

• Die Ausgabe lässt absichtlich verrauschte Felder wie DB-Pfade, interne IDs, rohe Metadaten-Dumps, Suchstufen und Installationspfade weg.

• detail ist standardmäßig auf compact gesetzt. Verwenden Sie "detail": "full" nur, wenn Sie wirklich die gesamte Klassenschnittstelle benötigen.

get_klib_index_status

Gibt eine kompakte Indexzusammenfassung zurück.

Eingabe:

{}

Die Ausgabe enthält:

• ready

• erkannte Kotlin/Native-Versionen und Targets

• indizierte Datensätze mit Anzahlen

• aggregierte Symbolanzahlen

• lastRebuildAt

rebuild_klib_index

Erstellt oder aktualisiert den SQLite-Index aus lokalen klibs.

Eingabe:

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

Regeln:

• kotlinVersion und konanHome sind optional, aber Sie dürfen maximal eines davon angeben.

• Wenn beide weggelassen werden, wird die zuletzt erkannte lokale Kotlin/Native-Installation verwendet.

• Wenn target weggelassen wird, bevorzugt der Server ios_simulator_arm64, dann ios_arm64, dann ios_x64.

• Wenn frameworks weggelassen wird, deckt der Rebuild alle Frameworks für das ausgewählte Target ab.

• dryRun=true berechnet den Rebuild-Plan, ohne in SQLite zu schreiben.

• force=true ignoriert Frischeprüfungen.

• cleanBefore=true entfernt existierende Zeilen für die betroffenen Frameworks, bevor neue Datensätze geschrieben werden.

Speicherlayout

Der Server speichert Daten außerhalb des Repositorys.

• SQLite DB: Benutzer-Cache-Verzeichnis + klib-index.sqlite

• Service-Metadaten: Benutzer-Cache-Verzeichnis + state.json

Typische Cache-Speicherorte:

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

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

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

Erkennungsregeln

Installationen werden in dieser Reihenfolge erkannt:

1. Explizites konanHome-Argument, wenn ein Tool es bereitstellt

2. KONAN_HOME

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

Jede Installation wird validiert durch Prüfung auf:

• bin/klib

• klib/platform/

MCP-Konfiguration

Aus dem Quellcode ausführen

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

Optionale Umgebungsvariablen-Überschreibung:

{
	"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"
			}
		}
	}
}

Als installierte Binärdatei ausführen

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

Typische Konfiguration für installierte Binärdateien

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

Entwicklung

Skripte

• npm run dev startet den Server aus TypeScript-Quellen

• npm run build kompiliert nach dist/

• npm start führt den kompilierten Server aus

• npm run typecheck führt die TypeScript-Typenprüfung aus

• npm test führt Vitest aus

• npm run test:watch startet Vitest im Watch-Modus

Lokaler Workflow

npm install
npm run typecheck
npm run build
npm test

Veröffentlichung

npm-Veröffentlichung wird über GitHub Actions abgewickelt.

• Pushen Sie ein Tag im Format vX.Y.Z, wobei X.Y.Z mit der version in package.json übereinstimmt.

• Der Publish Package-Workflow validiert das Paket und veröffentlicht es auf npm.

• Das npm-Paket muss für Trusted Publishing aus dem GitHub-Repository SuLG-ik/kmp-api-lookup-mcp konfiguriert sein.

• Siehe PUBLISHING.md für die einmalige npm-Einrichtung und die genauen Release-Schritte.

Testabdeckung

Die aktuelle Testsuite deckt ab:

• MCP-Tool-Registrierung

• dump-metadata-signatures Zeilen-Parsing

• SQLite-Speicher- und Suchverhalten bei synthetischen Fixtures

• Server-Laufzeiterstellung

Projektstruktur

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