Kotlin & Java Library Sources

kotlin-lib-mcp

为你的 AI Agent 提供任何已发布到 Maven 的 Kotlin/Java 库的真实源码。

这是一个 MCP 服务，可按请求下载库的源码（例如 io.ktor:ktor-client-core:3.5.1），使用 Kotlin Analysis API（独立 K2/FIR 模式）解析源码，并向 MCP 客户端提供结构化信息——公共 API 面、KDoc、依赖项/元数据、原始源码及搜索功能。支持 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 · diff_versions · diff_api · get_dependencies · list_versions · get_latest_version — 另提供 MCP 资源和提示词。

这些按钮会安装 Docker 镜像。关于 Claude Code 插件（在你的 JDK 上运行）、IntelliJ IDEA，或不使用 Docker 运行发布 zip，请参阅快速开始。

Compose Desktop 仪表板

## 为什么选择它，而不是文档查询服务？

大多数文档 MCP 服务会抓取渲染后的文档网站，或向模型提供预先整理好的摘要。本工具基于已发布的源码 JAR运行——这才是事实依据：

• 解析后的签名，而非正则表达式猜测。 声明使用与 Kotlin IDE 同一套 Analysis API 进行分析，因此 get_api_signature 会返回真实且已解析类型的签名（如果缺少传递依赖项，也会尽力提供回退结果）。
• 支持 KMP。 Kotlin Multiplatform 库会按目标平台发布源码 JAR；本工具会通过 .module Gradle 元数据正确解析，并为每个符号标记其目标平台。
• 将 KDoc 作为数据处理。 摘要、描述和标签会按声明提取，而不是从整页 HTML 中提取。
• 使用你指定的准确版本，首次获取后即可离线使用。 所有内容都会缓存在磁盘上，并以 group/artifact/version 为键；无需重新下载，文档与实际依赖的版本也不会出现偏差。
• 需要时可查看原始源码。 get_source 和有范围限制的 search_source 能让 Agent 阅读实际实现，而不仅仅是 API。

快速开始（无需构建）

选项 1 — Claude Code 插件。 包含服务以及让 Claude 主动调用它的技能、两个 命令（/kotlin-lib:api、/kotlin-lib:migrate）和一个设置助手。需要 JDK 25+——可以是 PATH 中的版本，也可以是在插件的 java 选项中通过路径指定的其他版本；无需 Docker。 首次使用时会下载发布版 zip：

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

请参阅 plugin/README.md，了解其中包含的内容。

选项 2 — 发布版 zip。 下载最新的 发布版，解压（需要 Java 25+ 运行时），然后：

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。 JetBrains IDE 也是 MCP 客户端——大多数 Kotlin 代码都在这里编写。打开 Settings | Tools | AI Assistant | Model Context Protocol (MCP)， 点击 Add，选择 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 在其自身的 MCP 设置中也使用相同的 JSON。如果不想使用 Docker，可以将 command/args 替换为发布版 zip 启动器（bin/server --transport stdio）。

选项 5 — MCP Registry。 此服务已作为 io.github.aoreshkov/kotlin-lib-mcp 发布到 官方 MCP Registry，并列入 GitHub MCP Registry；支持注册表的客户端 可以从中安装。条目声明了两个可选参数，客户端在安装时可能会询问你是否提供：--repo， 用于指定每个额外的 Maven 仓库（例如私有仓库，或 AndroidX 使用的 https://maven.google.com），以及 --max-concurrent-fetches。

或者，在 .mcp.json / Claude Desktop 配置中：

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

Streamable HTTP。 运行 --transport http --port 3000，并将客户端指向 http://127.0.0.1:3000/mcp。默认情况下，只有本机可以访问：服务绑定到环回地址， 且 DNS 重绑定保护会拒绝 Host（或 Origin）标头中除 localhost、127.0.0.1 或 [::1] 之外的值。没有内置身份验证，因此若要向其他 机器提供服务，请在前面放置带身份验证的反向代理，然后使用 --host 绑定到更广的地址（例如 0.0.0.0），并通过 --allowed-host 指定公共主机名（浏览器客户端还需设置 --allowed-origin）。

在 Docker 中，环回地址指向容器自身，已发布的端口无法访问该地址。请在容器内绑定所有 网络接口，并在主机上仅将端口发布到环回地址——端点仍为 http://127.0.0.1:3000/mcp，其他机器仍无法访问：

docker run --rm -p 127.0.0.1:3000:3000 -v kotlin-lib-mcp-cache:/home/mcp/.cache \
  ghcr.io/aoreshkov/kotlin-lib-mcp --transport http --host 0.0.0.0 --port 3000

CLI 标志 — server --help 会列出所有标志及其默认值、OTEL_* 变量和 示例：--transport stdio|http；--port、--host、--allowed-host 和 --allowed-origin， 这些标志仅适用于 http 传输方式，因此与 stdio 一起传入会导致用法错误；--cache-dir； --repo（可重复指定，添加在 Maven Central 之上）；--max-concurrent-fetches；以及可选启用项 --forward-logs-to-client（仅限 stdio）、--otel（参见遥测）和 --tasks（参见 任务）。--version 会输出服务的版本。命令行错误会以状态码 2 退出，内部错误则以状态码 70 退出（sysexits.h）。收到 SIGTERM 或 Ctrl-C 后，服务会在 5 秒内干净地停止： 进程结束前会保存任务记录并刷新缓冲的跟踪数据。

工具

所有工具都接受一个 Maven coordinate（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	声明及其签名和弃用信息；可按 package、visibility 和 deprecated 筛选；分页
get_api_signature	按 FQ 名称获取单个声明解析后的签名，以及其弃用信息和 ReplaceWith
get_kdoc	获取单个声明的 KDoc（摘要、说明、标签）
get_source	获取文件（path）或单个声明（fqName）的原始源码；按行分页
search_source	子字符串/正则搜索；范围受限，返回 file:line 代码片段
diff_versions	两个已获取版本之间的统一差异；先显示摘要，分页，并可按 path 筛选
diff_api	两个已获取版本之间的公共 API 变更 — 新增、移除、变更、弃用（含 ReplaceWith）；先显示摘要，分页，并可按 package 和 change 筛选
get_dependencies	从 .pom/.module 获取依赖树；depth 和 maxNodes 范围受限
list_versions	从 maven-metadata.xml 获取已发布的版本，按从新到旧排序；分页
get_latest_version	从 maven-metadata.xml 获取最新稳定版本（以及最新发布版本）

每个工具都会提供 MCP 规范鼓励客户端使用的元数据：显示用的 title、 行为注解（除 fetch_library 外，所有工具均为 readOnlyHint: true；fetch_library 仅添加数据 — destructiveHint: false、idempotentHint: true；访问 Maven 仓库的工具会设置 openWorldHint: true，仅使用缓存的工具则设为 false）、根据响应 DTO 的序列化器生成的类型化 outputSchema，以及一个图标。结果同时包含精简的 JSON 文本和对应的 structuredContent 对象，因此结构化输出客户端和纯文本客户端看到的内容相同。

当客户端发送 progressToken 时，fetch_library 还会报告进度通知（下载 → 分析 → 缓存）。日志默认写入 stderr（规范允许所有 stdio 日志采用此方式）；已弃用的 MCP 日志记录功能 — 将日志镜像到客户端为 notifications/message（遵循 logging/setLevel）— 可通过 --forward-logs-to-client 选择启用，供能显示 MCP 日志消息但会丢弃 stderr 的 stdio 客户端使用。使用 --transport http 时会拒绝启用该功能，因为每个会话都会收到其他所有会话的日志。

信息征询

调用 fetch_library 时若未指定版本（io.ktor:ktor-client-core 或 …:latest），就必须猜测。如果客户端声明了 elicitation 能力，服务端会改为询问：发送一个 elicitation/create 表单模式请求，内含单选版本选择器——采用 SEP-1330 中带标题的 oneOf 结构，并将最新稳定版预选为 schema 的 default。

用户	服务端
接受某个版本	仅获取该版本
拒绝	获取最新稳定版，行为与以往相同
取消（关闭对话框）	不下载任何内容，并返回工具错误，提示再次调用 fetch_library 并明确指定 group:artifact:version

没有标志位：能力协商本身就是选择加入。未声明任何能力的客户端，或仅声明 URL 模式的客户端（服务端不得对此回复表单），都会完全沿用之前静默获取最新稳定版的行为。这里只会请求公开的 Maven 版本号，因此适合使用表单模式；URL 模式用于凭据和第三方授权，本场景有意不使用。接受的值会先根据提供的列表进行验证，再用于构造仓库 URL；如果客户端在提问过程中出错，则会回退到默认版本，而不是使获取失败。

使用 --tasks 时，带任务功能的 fetch_library 会在等待问题答复期间处于 input_required 状态，答复后则回到 working 状态；elicitation/create 会携带 io.modelcontextprotocol/related-task _meta，将其关联到该任务。

任务

传入 --tasks，即可支持 fetch_library 的带任务功能 tools/call（SEP-1686），并响应 tasks/get / tasks/result / tasks/list / tasks/cancel。两种传输方式均可使用。

任务记录会持久化在 <cache-dir>/tasks 下，因此即使服务端重启，仍可获取已完成任务及其结果。服务端停止时仍在运行的任务会恢复为 failed——其工作不会保留，只有记录会保留。记录会在 TTL 到期后删除（默认 10 分钟，最长 1 小时）。

任务 ID 是可用于访问超出会话生命周期任务的持有者令牌。 任务属于创建它的 MCP 会话；只要该会话仍处于连接状态，其他会话就无法读取、列出或取消它。但会话 ID 是针对每个连接生成的：重启后，客户端会使用新的会话 ID 重新连接，因此恢复的任务可以由任何能提供准确任务 ID 的人访问。这是 MCP 规范为没有授权上下文的服务端规定的模型——本服务端正是如此：优先仅监听回环地址且不进行身份验证——因此任务 ID 使用 122 位的 SecureRandom UUID。tasks/list 绝不会返回恢复的任务，只会返回调用会话自己的任务。如果要将此服务端暴露给回环地址之外的网络，请在其前方设置身份验证。

并发说明。 只有因为 SDK 会在会话初始化后并发分发入站请求，从工具调用内部发起的服务端请求才可正常工作——否则客户端的回复就会被卡在正在等待该回复的处理程序之后。除了让信息征询成为可能，这还意味着在长时间运行的 fetch_library 期间，ping、tasks/get 和 notifications/cancelled 都能及时得到响应，而不会排在其后；客户端取消的 fetch_library 也会真正停止。

遥测

传入 --otel，即可通过 OTLP/HTTP 为每个 MCP 请求（tools/call、resources/read、 prompts/get、completion/complete）导出一个跟踪 Span。默认关闭；关闭时不会产生任何活动：不启动 SDK、没有导出器线程，也不会进行网络通信。

配置使用标准的 OpenTelemetry 环境变量，无需专用标志：

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

协议默认为 http/protobuf，端点默认为 http://localhost:4318，导出器使用 JDK 内置的 HTTP 客户端（类路径中无需 OkHttp）。所有配置均可覆盖：例如，为托管的收集器提供 API 密钥的 OTEL_EXPORTER_OTLP_HEADERS、OTEL_TRACES_EXPORTER、OTEL_BSP_SCHEDULE_DELAY 等。

端点注意事项。 使用通用的 OTEL_EXPORTER_OTLP_ENDPOINT 时，会自动追加 /v1/traces。使用针对信号的 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 时，URL 则会原样使用——必须自行写出路径。这是最常见的 OTLP 配置错误。

Span 遵循 MCP 语义约定：命名为 {method} {target}（例如 tools/call fetch_library），类型为 SpanKind.SERVER，并携带 mcp.method.name、gen_ai.tool.name、 mcp.session.id 和 network.transport（stdio 对应 pipe，http 对应 tcp）。返回 isError 的工具会标记为 error.type=tool_error。入站跟踪上下文从 JSON-RPC params._meta 字段中获取（traceparent/tracestate，参见 SEP-414），因此，跟踪自身工作的客户端可以获得一条连贯的跟踪链路。

这些 mcp.* 和 gen_ai.* 属性在上游仍处于 Development 状态，可能会更名——这也是将整个功能设为可选的又一个理由。

资源：每个已缓存的库都可以通过 kotlinlib://{group}/{artifact}/{version}/index 读取——这是一个 JSON 摘要，包含 KMP 目标、声明、文件和包的数量，以及其包列表（最多 200 个）。每个包的公共 API（每项声明的签名和 KDoc 摘要，最多 200 项）可通过 kotlinlib://{group}/{artifact}/{version}/package/{package} 读取；超过上限的内容可由工具分批获取。获取库后，资源列表会随之更新；两种 URI 形式都会作为资源模板发布，因此可直接寻址任何已缓存的坐标；模板变量（包括 package）会根据缓存内容自动补全。工具也会提供资源链接：fetch_library 会返回指向库索引的 resource_link，而 list_packages 会为每一页的前 20 个包提供链接，让客户端无需再次查找即可附加它们。提示词：explain_public_api(coordinate, package?) 会生成解释请求，并以缓存的签名和 KDoc 为依据。

图标：服务、每个工具、提示词以及库索引资源/模板都会声明一个 SEP-973 图标，让客户端可以用视觉方式展示这些内容，而不是显示一大片蛇形命名。图标以内联的 data: URI 提供，而非托管 URL——stdio 服务没有源地址，且规范建议使用者优先选择同源图标并在不携带凭据的情况下获取，因此内联可以完全避免第三方获取，并确保图标在离线状态及容器映像中正常工作。负载为 PNG，这是渲染图标的客户端必须支持的格式（image/svg+xml 仅为建议支持，且规范警告它可能包含可执行内容）。这些图形由 tools/src/main/kotlin/GenerateIcons.kt （./gradlew :tools:generateIcons）绘制，并保持精简——每个编码后约 800 字节，因为它们会随每个 tools/list 一起发送。

从源代码构建

./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

需要 JDK 25（使用 Gradle 工具链：如果检测到已安装的 JDK 25，就会使用它；否则 Gradle 会下载一个）。

模块	说明
core/	KMP 库：领域模型和端口（commonMain）；Maven 获取器、zip 解压器、Analysis API 分析器、磁盘缓存（jvmMain）
server/	JVM 应用：MCP 工具/资源/提示词，以及 stdio 和 Streamable HTTP 传输
dashboard/	Compose Desktop 控制面板，内嵌服务（可选）
tools/	用于生成服务所提供的 SEP-973 图标 PNG 的生成器。该模块不会随产品发布，只会发布其输出

缓存

下载内容和解析后的索引存放在操作系统缓存目录下的 kotlin-lib-mcp （Windows 上为 %LOCALAPPDATA%\kotlin-lib-mcp，macOS 上为 ~/Library/Caches/kotlin-lib-mcp， 其他系统上为 $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 中锁定—— 升级时需同时更新。如果符号的类型无法解析（缺少传递依赖），则会降级为 bestEffort: true 的 PSI 签名，而不会失败。

隐私

不会收集、远程存储或分享任何与你有关的信息。 没有分析、没有自动联网上报、没有账户，也不会收集任何凭据。

• 哪些内容会离开你的设备。 只有发往你指定的 Maven 仓库的请求（默认是 Maven Central，可通过 --repo 更改）：你所查询坐标对应的 maven-metadata.xml、.pom/.module 元数据以及 sources jar。这些仓库会看到坐标和你的 IP 地址，并遵循各自的隐私政策。拉取 Docker 镜像也会连接 GHCR，而 Claude Code 插件的启动器会连接此仓库的 GitHub releases（最多每天请求一次 releases API；有新服务时会下载）。这就是全部的出站流量。
• 读取哪些内容。 仅下载的库源代码。它不会读取、索引或传输你项目的代码——它无法访问这些代码。
• 存储哪些内容以及存储位置。 下载的工件和解析后的索引仅存储在你的磁盘上，位置为操作系统缓存目录（见缓存）或 --cache-dir 指定的目录。启用 --tasks 时，任务记录存放在 tasks/ 子目录中。不会在其他位置写入任何内容。
• 保留期限。 缓存的库会一直保留，直到你将其删除——该目录便于浏览，可随时安全移除。任务记录会在其 TTL 到期后删除（默认 10 分钟，最长 1 小时）。
• 日志。 日志写入你设备上的 stderr。--forward-logs-to-client（可选启用）会将日志转发到你的 MCP 客户端；--otel（可选启用）会将跟踪跨度导出到由你配置的 OTLP 收集器，且不包含个人数据——只有方法名称、工具名称、会话 ID 和传输方式。两者默认均关闭。
• 联系。 有问题请提交 issue。 安全或隐私问题请通过私密漏洞报告渠道提交。

贡献

欢迎贡献——请参阅 CONTRIBUTING.md。发布历史见 CHANGELOG.md；安全问题请通过 私密漏洞报告渠道提交。

支持

如果 kotlin-lib-mcp 为你节省了时间，可以考虑 赞助其维护工作。赞助资金将用于确保 Analysis API 版本锁定能及时跟进 Kotlin 新版本，并维护供应链安全加固的发布流程。感谢每个级别的支持。

许可证

Apache-2.0