kmp-api-lookup-mcp

Servidor MCP para la búsqueda rápida de APIs de klib de iOS en Kotlin/Native.

El servidor indexa los klibs de la plataforma Kotlin/Native local en una base de datos SQLite persistente y expone una API MCP compacta para la búsqueda de símbolos y el mantenimiento del índice.

Instalación

Requisitos previos

• Node.js 22+

• Una instalación local de Kotlin/Native con klibs de plataforma disponibles a través de KONAN_HOME o ~/.konan

Desde npm (recomendado)

npm install -g kmp-api-lookup-mcp

Ejecutar sin instalación global mediante npx

npx -y kmp-api-lookup-mcp

Esto no instala el paquete de forma global. npm descarga y ejecuta el binario publicado bajo demanda.

Desde el código fuente

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

Inicio rápido

Como servidor MCP

Añada el servidor a la configuración de su cliente MCP.

Ubicaciones comunes de los archivos de configuración:

• 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

En el repositorio se incluyen archivos de ejemplo listos para copiar:

• claude_desktop_config.json.example para una instalación global de npm

• claude_desktop_config.npx.json.example para ejecutar el paquete publicado a través de npx

• claude_desktop_config.konan_home.json.example para una instalación global de npm con KONAN_HOME explícito

• claude_desktop_config.from_source.json.example para ejecutar el servidor compilado desde el repositorio

Si el paquete está instalado globalmente:

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

Si prefiere no instalar el paquete globalmente:

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

Esto es conveniente para una configuración rápida, pero el primer inicio puede ser más lento porque npx puede necesitar descargar el paquete.

Si desea apuntar directamente a una instalación específica de 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"
			}
		}
	}
}

Si ejecuta el servidor desde el código fuente:

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

Primera ejecución

Después de que el servidor se inicie, los pasos habituales son:

1. Llame a get_klib_index_status para ver si ya existe un índice.

2. Si falta el índice, llame a rebuild_klib_index para la versión de Kotlin/Native y el objetivo que necesite.

3. Comience a consultar símbolos con lookup_symbol.

Ejemplo de solicitud de reconstrucción:

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

Alcance actual

• Servidor MCP ESM de npm en TypeScript sobre stdio

• Caché persistente de SQLite en el directorio de caché del usuario

• Detección de instalaciones precompiladas de Kotlin/Native a través de KONAN_HOME, ~/.konan o una ruta explícita

• Reconstrucción manual del índice desde klib dump-metadata-signatures

• Enriquecimiento bajo demanda desde klib dump-metadata para firmas completas de Kotlin, jerarquía de clases e importaciones

• Respuestas MCP en JSON estructurado con resúmenes de texto cortos

Herramientas implementadas

lookup_symbol

Resuelve una clase, miembro o alias/constante de plataforma de nivel superior de la plataforma Apple de Kotlin/Native en una tarjeta de desarrollo compacta.

Entrada:

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

Comportamiento:

• Una consulta de clase como AVPlayer devuelve una tarjeta de clase con:

  • firma completa de la clase Kotlin

  • superclase e interfaces implementadas

  • todos los constructores, métodos de instancia y métodos de clase cuando detail se omite o se establece en compact, agrupados por nombre de miembro para reducir el tamaño de la salida

  • una lista de properties separada en modo compacto con indicadores explícitos accessors.getter y accessors.setter cuando existen métodos getter/setter coincidentes para esa propiedad

  • el modo compacto solo elimina los métodos de acceso a propiedades duplicados; no recorta métodos no relacionados de la superficie de la clase

  • el conjunto completo de miembros directos, miembros de extensión del puente ObjC y miembros de la clase Meta cuando detail se establece en full

  • requiredImports para la generación de código

• Una consulta de miembro como AVPlayer.play o play devuelve una tarjeta agrupada compacta con firmas de sobrecarga e importaciones.

• Los alias y constantes de plataforma exactos de nivel superior como AVPlayerStatus, AVLayerVideoGravity o AVPlayerItemDidPlayToEndTimeNotification se resuelven en tarjetas de miembros con ámbito de paquete en lugar de degradarse a coincidencias de clase difusas.

• Si la consulta es ambigua, la herramienta devuelve una lista corta de alternativas en lugar de volcar filas de búsqueda sin procesar.

• La salida omite intencionalmente campos ruidosos como rutas de DB, IDs internos, volcados de metadatos sin procesar, etapas de coincidencia y rutas de instalación.

• detail tiene como valor predeterminado compact. Use "detail": "full" solo cuando realmente necesite toda la superficie de la clase.

get_klib_index_status

Devuelve un resumen compacto del índice.

Entrada:

{}

La salida incluye:

• ready

• versiones y objetivos de Kotlin/Native descubiertos

• conjuntos de datos indexados con recuentos

• recuentos agregados de símbolos

• lastRebuildAt

rebuild_klib_index

Construye o actualiza el índice SQLite desde klibs locales.

Entrada:

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

Reglas:

• kotlinVersion y konanHome son opcionales, pero puede proporcionar como máximo uno de ellos.

• Si ambos se omiten, se utiliza la última instalación local de Kotlin/Native descubierta.

• Si se omite target, el servidor prefiere ios_simulator_arm64, luego ios_arm64, luego ios_x64.

• Si se omiten frameworks, la reconstrucción cubre todos los frameworks para el objetivo seleccionado.

• dryRun=true calcula el plan de reconstrucción sin escribir en SQLite.

• force=true ignora las comprobaciones de frescura.

• cleanBefore=true elimina las filas existentes para los frameworks afectados antes de escribir registros nuevos.

Diseño de almacenamiento

El servidor almacena los datos fuera del repositorio.

• SQLite DB: directorio de caché del usuario + klib-index.sqlite

• Metadatos del servicio: directorio de caché del usuario + state.json

Ubicaciones típicas de caché:

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

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

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

Reglas de descubrimiento

Las instalaciones se descubren en este orden:

1. Argumento konanHome explícito cuando una herramienta lo proporciona

2. KONAN_HOME

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

Cada instalación se valida comprobando:

• bin/klib

• klib/platform/

Configuración de MCP

Ejecutar desde el código fuente

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

Anulación de entorno opcional:

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

Ejecutar como binario instalado

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

Configuración típica de binario instalado

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

Desarrollo

Scripts

• npm run dev inicia el servidor desde fuentes de TypeScript

• npm run build compila a dist/

• npm start ejecuta el servidor compilado

• npm run typecheck ejecuta la comprobación de tipos de TypeScript

• npm test ejecuta Vitest

• npm run test:watch inicia Vitest en modo de vigilancia

Flujo de trabajo local

npm install
npm run typecheck
npm run build
npm test

Publicación

La publicación en npm se gestiona mediante GitHub Actions.

• Envíe una etiqueta con el formato vX.Y.Z donde X.Y.Z coincida con la version en package.json.

• El flujo de trabajo Publish Package valida el paquete y lo publica en npm.

• El paquete npm debe estar configurado para la publicación confiable desde el repositorio de GitHub SuLG-ik/kmp-api-lookup-mcp.

• Consulte PUBLISHING.md para la configuración única de npm y los pasos exactos de lanzamiento.

Cobertura de pruebas

El conjunto de pruebas actual cubre:

• Registro de herramientas MCP

• Análisis de líneas de dump-metadata-signatures

• Comportamiento de almacenamiento y búsqueda en SQLite en accesorios sintéticos

• Creación del tiempo de ejecución del servidor

Estructura del proyecto

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