kotlin-lib-mcp

Дайте вашему AI‑агенту реальные исходники любой библиотеки на Kotlin/Java, опубликованной в Maven.

Сервер MCP, который по запросу загружает исходники библиотеки (например io.ktor:ktor-client-core:3.5.1), парсит их с помощью Kotlin Analysis API (режим standalone K2/FIR) и предоставляет структурированную информацию — поверхность публичного API, KDoc, зависимости/метаданные, исходники в сыром виде + поиск — клиентам MCP: Claude Code, Claude Desktop, IntelliJ IDEA (AI Assistant / Junie), VS Code и GitHub Copilot. Дополнительная панель на Compose Desktop запускает тот же сервер внутри процесса.

Десять инструментов — fetch_library · list_packages · list_declarations · get_api_signature · get_kdoc · get_source · search_source · get_dependencies · list_versions · get_latest_version — плюс ресурсы MCP и подсказка.

Эти инструменты устанавливают Docker-образ. Для Claude Code, IntelliJ IDEA, или чтобы запустить release zip без Docker, смотрите Quick start.

Панель управления Compose Desktop

Зачем этот проект и не сервер поиска документации?

Большинство серверов MCP собирают отрендеренные сайты документации или подают модель на заранее подготовленных резюме. Этот сервер работает напрямую с опубликованными исходниками — с истинной основой:

Разрешённые сигнатуры, а не догадки по регуляркам. Объявления анализируются тем же Analysis API, который питает Kotlin IDE, поэтому get_api_signature возвращает реальные сигнатуры с разрешением типов (с плавной попыткой на случай отсутствия транзитивных зависимостей).
KMP‑aware. Библиотеки Kotlin Multiplatform публикуют jars исходников по каждой целевой платформе; они корректно разрешаются через метаданные Gradle .module, и каждый символ помечен своими целями.
KDoc как данные. Сводки, описания и теги извлекаются по каждой декларации — а не по целым HTML-страницам.
Точная версия, которую вы запрашиваете, оффлайн после первого запроса. Всё кешируется на диске по ключу group/artifact/version; повторных загрузок нет, не возникает рассинхрон между доками и версией, на которую вы ссылались.
Сырые исходники, когда они нужны. get_source и ограниченный search_source позволяют агенту читать реальную реализацию, а не только API.

Быстрый старт (без сборки)

Вариант 1 — плагин Claude Code. Сервер с навыками, делающими Claude обращением к нему, две команды (/kotlin-lib:api, /kotlin-lib:migrate) и помощник настройки. Требуется Docker:

/plugin marketplace add aoreshkov/kotlin-lib-mcp
/plugin install kotlin-lib@kotlin_lib-mcp

См. plugin/README.md о том, что входит в пакет.

Вариант 2 — release zip. Скачать последнюю

release, распаковать (необходимо окружение Java 21+), затем:

/bin/server --transport stdio">``` claude mcp add kotlin-lib -- /path/to/kotlin-lib-mcp-server-<version>/bin/server --transport stdio


**Вариант 3 — Docker.**

claude mcp add kotlin-lib -- docker run -i --rm -v kotlin-lib-mcp-cache:/home/mcp/.cache ghcr.io/aoreshkov/kotlin-lib-mcp


**Вариант 4 — IntelliJ IDEA / Android Studio.** IDE от JetBrains тоже являются MCP-клиентами — именно здесь чаще пишут Kotlin. Откройте **Settings | Tools | AI Assistant | Model Context Protocol (MCP)**, нажмите **Add**, выберите transport **stdio** и вставьте:

{ "mcpServers": { "kotlin-lib": { "command": "docker", "args": ["run", "-i", "--rm", "-v", "kotlin-lib-mcp-cache:/home/mcp/.cache", "ghcr.io/aoreshkov/kotlin-lib-mcp"] } } }


Выберите глобальный или проектный уровень, нажмите **Apply**, и инструменты появятся в чат‑окне AI Assistant. Junie принимает такой же JSON в своих MCP‑настройках. При необходимости замените `command`/`args` на лаунчер release‑zip (`bin/server --transport stdio`), чтобы не пользоваться Docker.

**Вариант 5 — MCP Registry.** Сервер опубликован в официальном MCP‑регистре

[registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) как

`io.github.aoreshkov/kotlin-lib-mcp`, и указан в

[GitHub MCP Registry](https://github.com/mcp/aoreshkov/kotlin-lib-mcp); клиенты с поддержкой реестра могут установить его там.

Или в `.mcp.json` / Claude Desktop config:

/bin/server.bat",
      "args": ["--transport", "stdio"]
    }
  }
}">```
{
  "mcpServers": {
    "kotlin-lib": {
      "command": "C:/path/to/kotlin-lib-mcp-server-<version>/bin/server.bat",
      "args": ["--transport", "stdio"]
    }
  }
}

Для удалённого использования запустите HTTP‑транспорт (--transport http --port 3000) и укажите клиенту адрес

http://127.0.0.1:3000/mcp — защита от DNS‑rebinding по умолчанию разрешает только localhost; параметры --allowed-host/--allowed-origin расширяют белый список для развертываний не на localhost.

CLI‑флаги: --transport stdio|http, --port <int> (по умолчанию 3000), --allowed-host <host> /

--allowed-origin <url> (повторяемо; расширяет значения по умолчанию для http‑транспорта на localhost),

--cache-dir <path>, --repo <url> (повторяемо; Maven Central — по умолчанию),

--forward-logs-to-client (выбирать для зеркалирования логов клиенту; по умолчанию выключено, только stderr),

--otel (выбор экспорта OTLP/HTTP трасс; по умолчанию выключено — см. раздел Telemetry), --help.

Tools

Все инструменты работают с Maven‑координатой (group:artifact:version). Сначала вызывайте fetch_library — он загружает, распаковывает и анализирует исходники один раз; каждый другой инструмент отвечает из кешированного индекса. fetch_library, list_versions и get_latest_version также принимают group:artifact, а fetch_library может принимать group:artifact:latest для разрешения последней стабильной версии.

Инструмент	Назначение
fetch_library	Загрузить + проанализировать + кешировать; возвращает сводку. Идемпотентно. Версию можно опустить или указать latest
list_packages	Пакеты с количеством деклараций и целями KMP
list_declarations	декларации с сигнатурами; фильтрация по пакету и области видимости
get_api_signature	Разрешённая сигнатура одной декларации по полному имени (FQ)
get_kdoc	KDoc (краткое описание, описание, теги) одной декларации
get_source	Исходник файла (путь) или одной декларации (fqName)
search_source	Поиск по подстроке/регулярному выражению; ограниченный, возвращает фрагменты file:line
get_dependencies	Дерево зависимостей из .pom/.module; ограниченная глубина
list_versions	Опубликованные версии из maven-metadata.xml, сначала новые
get_latest_version	Последняя стабильная версия (и самая новая в целом) из maven-metadata.xml

Каждый инструмент сопровождает метаданные, которые MCP‑спецификация рекомендует использовать: отображаемый title, индикаторы поведения (readOnlyHint: true повсюду кроме fetch_library, который destructiveHint: false, idempotentHint: true; инструменты, обращающиеся к Maven‑репозиториям, устанавливают openWorldHint: true, кеш‑only инструменты false), типизированный outputSchema, выведенный из сериализатора DTO-ответа, и иконку. Результаты возвращают как красиво отформатированный JSON, так и соответствующий объект structuredContent, чтобы клиенты с различными режимами выдачи получали одинаковую нагрузку.

fetch_library также сообщает о прогрессе (download → analyze → cache), если клиент передаёт progressToken. Логи по умолчанию отправляются в stderr (что соответствует стандарту для всех stdio‑логов); устаревшая MCP‑возможность логирования — зеркалирование логов клиенту как notifications/message (с учётом logging/setLevel) — включается по выбору через --forward-logs-to-client, для клиентов stdio, которые выводят логи MCP, но не хотят видеть stderr.

Элиминация

Когда fetch_library вызывается без версии (например io.ktor:ktor-client-core, или …:latest), он должен догадаться. Если клиент объявляет способность elicitation, он запрашивает её: форма выбора версии — в формате single-select из SEP‑1330, с последней стабильной версией по умолчанию в схеме default.

Пользователь	Сервер
принимает версию	запрашиваемая версия загружается точно этой
отклоняет	загружает последнюю стабильную версию, как и раньше
отменяет (закрывает диалог)	ничего не загружает и возвращает ошибку инструмента с просьбой повторно вызвать fetch_library с явной group:artifact:version

Нет флага: согласование возможностей — это опциональный выбор. Клиент, который ничего не объявляет — или объявляет только url‑режим, не получает форм — сохраняет поведение прежней последней стабильной версии. Разрешаются только публичные Maven‑версии, поэтому режим формы уместен; режим по URL нужен для учётных данных и авторизации третьих сторон и здесь намеренно не используется. Принятые значения валидируются по списку перед тем, как обратиться к URL репозитория; клиент, который прерывает диалог на середине — возвращается к умолчанию, а не ломает загрузку.

Под --tasks задача‑модульный режим fetch_library помечается как input_required пока вопрос не получит ответ и возвращается к working после. elicitation/create несёт связанный _meta с задачей через io.modelcontextprotocol/related-task.

Задачи

Передавайте --tasks, чтобы активировать задачу‑модуль для fetch_library (SEP‑1686) и отвечать на tasks/get / tasks/result / tasks/list / tasks/cancel. Работает на обоих транспортах.

Записи задач сохраняются в <cache-dir>/tasks, чтобы завершённая задача и её результат оставались доступными после перезапуска сервера. Задача, которая была запущена, но завершается с ошибкой — её работа не сохраняется, сохраняется только запись. Записи удаляются после истечения TTL (по умолчанию 10 минут, максимум 1 час).

Идентификаторы задач — это bearer-токены для задач, выходящих за пределы вашей сессии. Задача принадлежит MCP‑сессии, которая её создала, и пока сессия подключена, другая сессия может читать, перечислять или отменять её. Но идентификатор сессии привязан к конкретному подключению: после перезапуска клиент повторно подключается под новой сессией, и восстановленная задача становится доступной каждому, кто знает её точный идентификатор. Такова модель MCP‑спецификации для серверов без контекста авторизации — и этот сервер ей следует. Идентификаторы задач — 122‑битовые UUID, созданные через SecureRandom.

tasks/list никогда не возвращает восстановленные задачи, только задачи текущей сессии. Если вы планируете выдать этот сервер вне локального хоста, добавьте аутентификацию.

Примечание о конкуренции. Запрос внутри вызова инструмента через сервер выполняется благодаря тому, что SDK распараллечивает входящие запросы после инициализации сессии — иначе обработчик ожидал бы ответа. Это делает возможным эеликацию и обеспечивает оперативные ответы на ping, tasks/get и notifications/cancelled во время длительного fetch_library, а также позволяет фактически остановить fetch_library, если клиент его отменяет.

Telemetry

Передайте --otel для экспорта трассировочной информации по каждому MCP‑запросу (tools/call, resources/read, prompts/get, completion/complete) через OTLP/HTTP. По умолчанию это выключено: без SDK, без экспортёрских потоков, без сетевых запросов.

Стандарт окружения для OpenTelemetry — без специальных флагов:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318   # '/v1/traces' добавляется автоматически
export OTEL_SERVICE_NAME=kotlin-lib-mcp                    # это значение по умолчанию
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=dev
server --transport stdio --otel

Протокол по умолчанию — http/protobuf, конечная точка — http://localhost:4318, экспортер использует встроенный HTTP‑клиент JDK (OkHttp в рантайме не подключён). Всё переопределимо: OTEL_EXPORTER_OTLP_HEADERS для ключа API у хостинг‑поставщика, OTEL_TRACES_EXPORTER, OTEL_BSP_SCHEDULE_DELAY и т. п.

Особенность конечной точки. Для общего OTEL_EXPORTER_OTLP_ENDPOINT к адресу автоматически добавляется /v1/traces. С сигналами OTEL_EXPORTER_OTLP_TRACES_ENDPOINT URL используется как есть — путь нужно прописать самим. Это частая ошибка в настройке OTLP.

Слои следов соответствуют генеральным соглашениям MCP: названия вида {method} {target} (например tools/call fetch_library), SpanKind.SERVER, и содержат mcp.method.name, gen_ai.tool.name, mcp.session.id, network.transport (pipe для stdio, tcp для http). Инструмент, возвращающий isError, помечается error.type=tool_error. Входящий контекст трассировки подхватывается из JSON‑RPC‑поля params._meta (traceparent/tracestate, согласно SEP‑414); таким образом клиент может проследить собственную работу.

Эти атрибуты mcp.* и gen_ai.* всё ещё находятся в статусе Development в upstream и могут быть переименованы — ещё одна причина держать эту фичу как opt‑in.

Resources: каждый кешированный library читаем на адресе

kotlinlib://{group}/{artifact}/{version}/index (разобранный индекс в формате JSON); список обновляется по мере загрузки библиотек, и та же структура URI публикуется как ресурс‑шаблон, так что любой закешированный координат становится доступным напрямую. Prompt: explain_public_api(coordinate, package?) запускает запрос объяснения, основанный на кешированных сигнатурах и KDoc.

Icons: сервер, каждый инструмент, подсказка и ресурс/шаблон индекса библиотеки объявляют по одному значку в соответствии с SEP‑973 — таким образом клиент может визуально видеть поверхность вместо длинного текста. Значки встроены как data: URIs, а не размещаются на сторонних хостах — у stdio‑сервера нет источника происхождения, и спецификация рекомендует использовать значки того же источника и загружать их без учётных данных, что позволяет работать оффлайн и в контейнере. Полезная нагрузка — PNG, формат значков, который обязаны поддерживать клиенты (поддержка image/svg+xml лишь как предпочтение, и в спецификации отмечается риск выполнения кода). Глифы рисуются в tools/src/main/kotlin/GenerateIcons.kt (./gradlew :tools:generateIcons) и держатся компактными — около 800 байт в кодировке каждый, так как они встроены в каждый tools/list.

Сборка из исходников

./gradlew build                                    # собрать всё
./gradlew test                                     # модульные тесты
./gradlew :server:run --args="--transport stdio"   # локальный MCP через stdio (по умолчанию)
./gradlew :server:run --args="--transport http --port 3000"   # потоковый HTTP на /mcp
./gradlew :dashboard:run                           # Compose Desktop UI
./gradlew :server:installDist                      # автономный лаунчер в server/build/install/server/bin

Требуется JDK 21 (автоматическое определение через Gradle toolchains).

Модуль	Что это такое
core/	KMP‑библиотека: доменная модель + порты (commonMain); Maven fetcher, zip extractor, Analysis API analyzer, on-disk cache (jvmMain)
server/	JVM‑приложение: MCP‑инструменты/ресурсы/подсказки + stdio и Streamable HTTP транспорты
dashboard/	Compose Desktop панель управления, встраивающая сервер (не обязательно)
tools/	Генераторы ассетов (иконки PNG, карточки превью). Никаких зависимостей в продакшн-пакете; ничего не зависит от него

Кеш

Загрузки и разобранный индекс хранятся в системном кеш‑каталоге + kotlin-lib-mcp

(%LOCALAPPDATA%\kotlin-lib-mcp в Windows, ~/Library/Caches/kotlin-lib-mcp в macOS,

$XDG_CACHE_HOME/kotlin-lib-mcp в остальных системах), по ключу group/artifact/version — браузируемо и безопасно для удаления. --cache-dir переопределяет этот путь. В разделе --tasks записи задач живут в подпапке tasks/ того же корня.

Примечания

stdio правило: stdout несёт только кадры MCP‑протокола; весь лог пишется в stderr

(Kermit → SLF4J → Logback, logback.xml).

Артефакты Kotlin и Analysis API фиксируются по версиям в gradle/libs.versions.toml — обновляйте их вместе. Символы, чьи типы не могут быть разрешены (отсутствуют транзитивные зависимости), падают обратно на сигнатуры PSI с bestEffort: true вместо ошибки.

Конфиденциальность

Ничего о вас не собирается, не хранится удалённо и не передаётся. Аналитика отсутствует, звонки на сервер не выполняются, учетная запись и креды отсутствуют.

Что отправляется с вашего устройства. Только запросы к Maven‑репозиториям, на которые вы указываете (Maven Central по умолчанию, --repo для смены): maven-metadata.xml, .pom/.module метаданные и исходники по координатам, которые вы запрашиваете. Эти репозитории видят координаты и ваш IP — в рамках их политики приватности. Скачивание Docker‑образа также обращается к GHCR. Это полный объём исходящего трафика.
Что читает. Только исходники загруженных библиотек. Он не читает, не индексирует и не передаёт код вашего проекта — у него нет доступа к нему.
Что хранится и где. Загруженные артефакты и разобранный индекс — только на вашем диске, в кеш‑каталоге ОС (см. раздел Cache) или --cache-dir. Записи задач живут в подпапке tasks/. Ничего больше не записывается.
Удержание. Кешированные библиотеки остаются до их удаления — каталог можно безопасно удалить в любой момент. Записи задач удаляются после истечения TTL (по умолчанию 10 минут, максимум 1 час).
Логи. stderr на вашей машине. --forward-logs-to-client (опционально) зеркалирует их в ваш MCP‑клиент; --otel (опционально) экспортирует трассировочные данные в OTLP‑коллектор, который вы укажите, и не содержит персональных данных — имена методов, имена инструментов, идентификатор сессии, транспорт. Оба параметра отключены по умолчанию.
Контакты. Вопросы: открыть issue. Сообщения об уязвимостях: private vulnerability reporting.

Внесение изменений

Принимаются вклад — смотрите CONTRIBUTING.md. История выпусков здесь: CHANGELOG.md; уведомления об уязвимостях проходят через private vulnerability reporting.

Поддержка

Если kotlin-lib-mcp экономит ваше время, рассмотрите возможность

финансирования его поддержки. Спонсорство помогает поддерживать актуальность версии Analysis API с новыми релизами Kotlin и надёжную сборку цепочек поставок. Любой уровень поддержки ценится.

Лицензия

Apache-2.0