kotlin-lib-mcp

Give your AI agent the real sources of any Maven-published Kotlin/Java library.

An MCP server that, on request, downloads the sources of a library (e.g. io.ktor:ktor-client-core:3.5.1), parses them with the Kotlin Analysis API (standalone K2/FIR mode), and exposes structured information — public API surface, KDoc, dependencies/metadata, raw source + search — to MCP clients: Claude Code, Claude Desktop, IntelliJ IDEA (AI Assistant / Junie), VS Code and GitHub Copilot. An optional Compose Desktop dashboard runs the same server in-process.

Eleven tools — fetch_library · list_packages · list_declarations · get_api_signature · get_kdoc · get_source · search_source · diff_versions · get_dependencies · list_versions · get_latest_version — plus MCP resources and a prompt.

Those install the Docker image. For Claude Code, IntelliJ IDEA, or to run the release zip without Docker, see Quick start.

Why this and not a docs-lookup server?

Most documentation MCP servers scrape rendered doc sites or feed the model pre-digested summaries. This one works from the published sources jar — the ground truth:

• Resolved signatures, not regex guesses. Declarations are analyzed with the same Analysis API that powers the Kotlin IDE, so get_api_signature returns real, type-resolved signatures (with graceful best-effort fallback when transitive dependencies are missing).
• KMP-aware. Kotlin Multiplatform libraries publish per-target sources jars; these are resolved properly via .module Gradle metadata, and every symbol is tagged with its targets.
• KDoc as data. Summaries, descriptions and tags are extracted per declaration — not whole HTML pages.
• Exact version you asked for, offline after the first fetch. Everything is cached on disk keyed by group/artifact/version; no re-downloads, no drift between the docs and the version you actually depend on.
• Raw source when you need it. get_source and bounded search_source let the agent read the actual implementation, not just the API.

Quick start (no build required)

Option 1 — Claude Code plugin. The server plus skills that make Claude reach for it, two commands (/kotlin-lib:api, /kotlin-lib:migrate) and a setup helper. Needs Docker:

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

See plugin/README.md for what it bundles.

Option 2 — release zip. Download the latest release, unzip (needs a Java 21+ runtime), then:

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

Option 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

Option 4 — IntelliJ IDEA / Android Studio. JetBrains IDEs are MCP clients too — which is where most Kotlin gets written. Open Settings | Tools | AI Assistant | Model Context Protocol (MCP), click Add, pick the stdio transport and paste:

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

Choose global or project level, Apply, and the tools appear in the AI Assistant chat. Junie takes the same JSON in its own MCP settings. Swap command/args for the release-zip launcher (bin/server --transport stdio) if you'd rather not use Docker.

Option 5 — MCP Registry. The server is published to the official MCP registry as io.github.aoreshkov/kotlin-lib-mcp, and listed in the GitHub MCP Registry; registry-aware clients can install it from there.

Or in .mcp.json / Claude Desktop config:

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

For remote use, run the http transport (--transport http --port 3000) and point the client at http://127.0.0.1:3000/mcp — DNS-rebinding protection admits localhost hosts by default; --allowed-host/--allowed-origin extend the allowlist for non-localhost deployments.

CLI flags: --transport stdio|http, --port <int> (default 3000), --allowed-host <host> / --allowed-origin <url> (repeatable; extend the http transport's localhost-only defaults), --cache-dir <path>, --repo <url> (repeatable; Maven Central is the default), --forward-logs-to-client (opt into mirroring logs to the client; off by default, stderr-only), --otel (opt into OTLP/HTTP trace export; off by default — see Telemetry), --help.

Tools

All tools take a Maven coordinate (group:artifact:version). Call fetch_library first — it downloads, extracts and analyzes the sources once; every other tool answers from the cached index. fetch_library, list_versions and get_latest_version also accept group:artifact, and fetch_library accepts group:artifact:latest to resolve the latest stable release.

Every tool ships the metadata the MCP spec encourages clients to use: a display title, behavior annotations (readOnlyHint: true everywhere except fetch_library, which is additive-only — destructiveHint: false, idempotentHint: true; tools that reach Maven repositories set openWorldHint: true, cache-only tools false), a typed outputSchema derived from the response DTO's serializer, and an icon. Results carry both pretty-printed JSON text and the matching structuredContent object, so structured-output clients and plain-text clients see the same payload.

fetch_library also reports progress notifications (download → analyze → cache) when the client sends a progressToken. Logs go to stderr by default (which the spec blesses for all stdio logging); the deprecated MCP logging capability — mirroring logs to clients as notifications/message (respecting logging/setLevel) — is opt-in via --forward-logs-to-client, for stdio clients that surface MCP log messages but drop stderr.

Elicitation

When fetch_library is called without a version (io.ktor:ktor-client-core, or …:latest) it has to guess. If the client advertised the elicitation capability, it asks instead: an elicitation/create form-mode request carrying a single-select version picker — the titled oneOf shape from SEP-1330, with the latest stable release pre-selected as the schema default.