kmp-api-lookup-mcp

MCP-сервер для быстрого поиска API klib Kotlin/Native для iOS.

Сервер индексирует локальные klib платформы Kotlin/Native в постоянную базу данных SQLite и предоставляет компактный MCP API для поиска символов и обслуживания индекса.

Установка

Предварительные требования

• Node.js 22+

• Локальная установка Kotlin/Native с klib платформы, доступными через KONAN_HOME или ~/.konan

Из 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 для глобальной установки npm с явным указанием KONAN_HOME

• 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. Если индекс отсутствует, вызовите rebuild_klib_index для нужной версии Kotlin/Native и целевой платформы.

3. Начните поиск символов с помощью lookup_symbol.

Пример запроса на пересборку:

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

Текущая область применения

• TypeScript npm ESM MCP-сервер через stdio

• Постоянный кэш SQLite в каталоге кэша пользователя

• Обнаружение предустановленных версий Kotlin/Native через KONAN_HOME, ~/.konan или явный путь

• Ручная пересборка индекса из klib dump-metadata-signatures

• Обогащение по требованию из klib dump-metadata для полных сигнатур Kotlin, иерархии классов и импортов

• Структурированные JSON-ответы MCP с краткими текстовыми сводками

Реализованные инструменты

lookup_symbol

Разрешает класс, член или псевдоним/константу платформы Apple в Kotlin/Native в компактную карточку разработки.

Входные данные:

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

Поведение:

• Запрос класса, например AVPlayer, возвращает одну карточку класса с:

  • полной сигнатурой класса Kotlin

  • суперклассом и реализованными интерфейсами

  • всеми конструкторами, методами экземпляра и методами класса, когда detail опущен или установлен в compact, сгруппированными по имени члена для уменьшения размера вывода

  • отдельным списком properties в компактном режиме с явными флагами accessors.getter и accessors.setter, когда для этого свойства существуют соответствующие методы получения/установки

  • компактный режим удаляет только дублирующиеся методы доступа к свойствам; он не обрезает несвязанные методы с поверхности класса

  • полным набором прямых членов, членами расширения моста ObjC и членами класса Meta, когда detail установлен в full

  • requiredImports для генерации кода

• Запрос члена, например AVPlayer.play или play, возвращает компактную сгруппированную карточку с сигнатурами перегрузок и импортами.

• Точные псевдонимы и константы платформы верхнего уровня, такие как AVPlayerStatus, AVLayerVideoGravity или AVPlayerItemDidPlayToEndTimeNotification, разрешаются в карточки членов с областью действия пакета, а не деградируют до нечеткого сопоставления классов.

• Если запрос неоднозначен, инструмент возвращает короткий список альтернатив вместо вывода необработанных строк поиска.

• Вывод намеренно опускает шумные поля, такие как пути к БД, внутренние идентификаторы, необработанные дампы метаданных, этапы сопоставления и пути установки.

• detail по умолчанию имеет значение compact. Используйте "detail": "full" только тогда, когда вам действительно нужна вся поверхность класса.

get_klib_index_status

Возвращает компактную сводку индекса.

Входные данные:

{}

Вывод включает:

• ready

• обнаруженные версии и целевые платформы Kotlin/Native

• проиндексированные наборы данных с количеством

• совокупное количество символов

• lastRebuildAt

rebuild_klib_index

Создает или обновляет индекс SQLite из локальных klib.

Входные данные:

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

• Отправьте тег в формате vX.Y.Z, где X.Y.Z соответствует version в package.json.

• Рабочий процесс Publish Package проверяет пакет и публикует его в npm.

• Пакет npm должен быть настроен для доверенной публикации из репозитория GitHub SuLG-ik/kmp-api-lookup-mcp.

• См. PUBLISHING.md для однократной настройки npm и точных шагов выпуска.

Покрытие тестами

Текущий набор тестов охватывает:

• Регистрацию инструментов 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