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.

Ten tools — fetch_library · list_packages · list_declarations · get_api_signature · get_kdoc · get_source · search_source · 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.

There is no flag: capability negotiation is the opt-in. A client that advertises nothing — or advertises url-mode only, which servers must not answer with a form — keeps the previous silent latest-stable behavior exactly. Only public Maven version numbers are ever requested, so form mode is appropriate; URL mode exists for credentials and third-party authorization, and is deliberately unused here. Accepted values are validated against the offered list before they reach a repository URL, and a client that errors mid-question falls back to the default rather than failing the fetch.

Under --tasks, a task-augmented fetch_library parks in the input_required status while the question is outstanding and returns to working once answered; the elicitation/create carries the io.modelcontextprotocol/related-task _meta tying it to the task.

Tasks

Pass --tasks to accept task-augmented tools/call for fetch_library (SEP-1686) and answer tasks/get / tasks/result / tasks/list / tasks/cancel. Works on both transports.

Task records are persisted under <cache-dir>/tasks, so a completed task and its result are still retrievable after the server restarts. A task that was still running when the server stopped comes back as failed — its work did not survive, only the record did. Records are dropped once their TTL elapses (10 minutes by default, 1 hour maximum).

Task IDs are bearer tokens for tasks that outlive their session. A task belongs to the MCP session that created it, and while that session is connected no other session can read, list or cancel it. But a session ID is per-connection: after a restart your client reconnects with a new one, so a recovered task is instead reachable by anyone presenting its exact task ID. That is the model the MCP spec prescribes for servers with no authorization context — which this one is, being loopback-first with no auth — and task IDs are 122-bit SecureRandom UUIDs accordingly. tasks/list never returns recovered tasks, only the calling session's own. If you expose this server beyond loopback, put authentication in front of it.

Note on concurrency. A server-initiated request from inside a tool call only works because the SDK dispatches inbound requests concurrently once the session is initialized — otherwise the client's reply would be stuck behind the very handler waiting for it. Besides making elicitation possible, this means ping, tasks/get and notifications/cancelled are answered promptly during a long fetch_library instead of queueing behind it, and a fetch_library the client cancels actually stops.

Telemetry

Pass --otel to export a trace span for every MCP request (tools/call, resources/read, prompts/get, completion/complete) over OTLP/HTTP. It is off by default, and off means inert: no SDK, no exporter threads, no network.

Configuration is the standard OpenTelemetry environment surface — there are no bespoke flags:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318   # '/v1/traces' is appended for you
export OTEL_SERVICE_NAME=kotlin-lib-mcp                    # this is also the default
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=dev
server --transport stdio --otel

The protocol defaults to http/protobuf, the endpoint to http://localhost:4318, and the exporter uses the JDK's built-in HTTP client (no OkHttp on the classpath). Everything is overridable: OTEL_EXPORTER_OTLP_HEADERS for a hosted collector's API key, OTEL_TRACES_EXPORTER, OTEL_BSP_SCHEDULE_DELAY, and so on.

Endpoint gotcha. With the generic OTEL_EXPORTER_OTLP_ENDPOINT, /v1/traces is appended automatically. With the per-signal OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, the URL is used as-is — you must spell out the path yourself. This is the most common OTLP misconfiguration.

Spans follow the MCP semantic conventions: named {method} {target} (e.g. tools/call fetch_library), SpanKind.SERVER, and carrying mcp.method.name, gen_ai.tool.name, mcp.session.id, and network.transport (pipe for stdio, tcp for http). A tool that returns isError is marked error.type=tool_error. Inbound trace context is picked up from the JSON-RPC params._meta bag (traceparent/tracestate, per SEP-414), so a client that traces its own work gets one connected trace.

Those mcp.* and gen_ai.* attributes are still Development status upstream and may be renamed — one more reason the whole feature is opt-in.

Resources: each cached library is readable at kotlinlib://{group}/{artifact}/{version}/index (the parsed index as JSON); the list updates as libraries are fetched, and the same URI shape is published as a resource template, so any cached coordinate is directly addressable. Prompt: explain_public_api(coordinate, package?) renders an explanation request grounded in the cached signatures and KDoc.

Icons: the server, every tool, the prompt and the library-index resource/template each declare an SEP-973 icon, so a client can show the surface visually instead of as a wall of snake_case. They are inlined as data: URIs rather than hosted URLs — a stdio server has no origin, and the spec asks consumers to prefer same-origin icons and fetch them without credentials, so inlining removes the third-party fetch entirely and keeps the icons working offline and inside the container image. The payload is PNG, the one format icon-rendering clients must support (image/svg+xml is only a SHOULD, and the spec warns it may carry executable content). The glyphs are drawn by tools/src/main/kotlin/GenerateIcons.kt (./gradlew :tools:generateIcons) and kept small — about 800 bytes encoded each, since they ride in every tools/list.

Building from source

./gradlew build                                    # build everything
./gradlew test                                     # unit tests
./gradlew :server:run --args="--transport stdio"   # local MCP over stdio (default)
./gradlew :server:run --args="--transport http --port 3000"   # Streamable HTTP at /mcp
./gradlew :dashboard:run                           # Compose Desktop UI
./gradlew :server:installDist                      # standalone launcher in server/build/install/server/bin

Requires JDK 21 (resolved automatically via Gradle toolchains).

Cache

Downloads and the parsed index live under the OS cache dir + kotlin-lib-mcp (%LOCALAPPDATA%\kotlin-lib-mcp on Windows, ~/Library/Caches/kotlin-lib-mcp on macOS, $XDG_CACHE_HOME/kotlin-lib-mcp elsewhere), keyed by group/artifact/version — browsable and safe to delete. --cache-dir overrides it. Under --tasks, task records live in a tasks/ subdirectory of the same root.

Notes

• stdio rule: stdout carries only MCP protocol frames; all logging goes to stderr (Kermit → SLF4J → Logback, logback.xml).
• Kotlin and the Analysis API artifacts are version-locked in gradle/libs.versions.toml — bump them together. Symbols whose types can't be resolved (missing transitive deps) degrade to bestEffort: true PSI signatures instead of failing.

Privacy

Nothing about you is collected, stored remotely, or shared. There is no analytics, no phone-home, no account, and no credential of any kind.

• What leaves your machine. Only requests to the Maven repositories you point it at (Maven Central by default, --repo to change): the maven-metadata.xml, .pom/.module metadata and sources jar for the coordinates you ask about. Those repositories see the coordinate and your IP, under their own privacy policies. Pulling the Docker image likewise talks to GHCR. That is the complete list of outbound traffic.
• What it reads. Downloaded library sources only. It does not read, index or transmit your project's code — it has no access to it.
• What it stores, and where. Downloaded artifacts and the parsed index, on your disk only, under the OS cache directory (see Cache) or --cache-dir. Under --tasks, task records live in a tasks/ subdirectory. Nothing is written anywhere else.
• Retention. Cached libraries stay until you delete them — the directory is browsable and safe to remove at any time. Task records are dropped once their TTL elapses (10 minutes by default, 1 hour maximum).
• Logs. stderr on your machine. --forward-logs-to-client (opt-in) mirrors them to your MCP client; --otel (opt-in) exports trace spans to the OTLP collector you configure, and carries no personal data — method names, tool names, session id, transport. Both are off by default.
• Contact. Questions: open an issue. Security or privacy reports: private vulnerability reporting.

Contributing

Contributions welcome — see CONTRIBUTING.md. Release history lives in CHANGELOG.md; security reports go through private vulnerability reporting.

Support

If kotlin-lib-mcp saves you time, consider sponsoring its maintenance. Sponsorship funds keeping the Analysis API version-lock current with new Kotlin releases and the supply-chain-hardened release pipeline. Every tier is appreciated.

License

Apache-2.0