内容
# kotlin-lib-mcp
[](https://github.com/aoreshkov/kotlin-lib-mcp/actions/workflows/ci.yml)
[](https://github.com/aoreshkov/kotlin-lib-mcp/actions/workflows/codeql.yml)
[](https://github.com/aoreshkov/kotlin-lib-mcp/releases/latest)
[](LICENSE)
[](https://kotlinlang.org)
为您的AI代理提供任何Maven发布的Kotlin/Java库的**真实源代码**。
一个 [MCP](https://modelcontextprotocol.io) 服务器，根据请求下载库的源代码（例如 `io.ktor:ktor-client-core:3.5.1`），使用Kotlin **分析API**（独立K2/FIR模式）解析它们，并向MCP客户端（如Claude Code和Claude Desktop）公开结构化信息 - 公共API表面、KDoc、依赖项/元数据、原始源代码 + 搜索。 一个可选的Compose Desktop仪表盘在进程中运行相同的服务器。
<!-- mcp-name: io.github.aoreshkov/kotlin-lib-mcp -->
<details><summary>Compose Desktop 仪表盘</summary>
</details>
## 为什么选择这个而不是文档查找服务器？
大多数文档MCP服务器都抓取已渲染的文档站点或向模型提供预先消化的摘要。而这个服务器则直接从**已发布的源代码jar**工作 - 即真相：
- **解析签名，而不是正则表达式猜测。** 声明使用与Kotlin IDE相同的分析API进行分析，因此 `get_api_signature` 返回真正的、类型解析的签名（当传递依赖项缺失时，会有优雅的尽力回退）。
- **KMP感知。** Kotlin多平台库发布每个目标的源代码jar；这些通过 `.module` Gradle元数据正确解析，每个符号都标记有其目标。
- **KDoc作为数据。** 摘要、描述和标签按声明提取 - 而不是整个HTML页面。
- **您请求的精确版本，首次获取后离线。** 所有内容都缓存在磁盘上，按 `group/artifact/version` 键控；不会重新下载，文档与您实际依赖的版本之间不会有偏差。
- **需要时提供原始源代码。** `get_source` 和有界 `search_source` 允许代理读取实际实现，而不仅仅是API。
## 快速开始（无需构建）
**选项1 - 发布zip。** 下载最新的 [发布](https://github.com/aoreshkov/kotlin-lib-mcp/releases/latest)，解压（需要Java 21+运行时），然后：
```sh
claude mcp add kotlin-lib -- /path/to/kotlin-lib-mcp-server-<version>/bin/server --transport stdio
```
**选项2 - Docker.**
```sh
claude mcp add kotlin-lib -- docker run -i --rm -v kotlin-lib-mcp-cache:/home/mcp/.cache ghcr.io/aoreshkov/kotlin-lib-mcp
```
**选项3 - MCP注册表。** 服务器已发布到 [官方MCP注册表](https://registry.modelcontextprotocol.io) 作为 `io.github.aoreshkov/kotlin-lib-mcp`；支持注册表的客户端可以从那里安装。
或在 `.mcp.json` / Claude Desktop配置中：
```json
{
"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` - 域名绑定保护默认允许localhost主机； `--allowed-host` / `--allowed-origin` 扩展了非localhost部署的允许列表。
命令行标志： `--transport stdio|http` ， `--port <int>` （默认为3000）， `--allowed-host <host>` / `--allowed-origin <url>` （可重复；扩展http传输的仅限localhost的默认值）， `--cache-dir <path>` ， `--repo <url>` （可重复；Maven Central是默认值）， `--help` 。
## 工具
所有工具都接受一个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` | 具有签名的声明；按 `package` 和 `visibility` 过滤 |
| `get_api_signature` | 按完全限定名称解析的单个声明的签名 |
| `get_kdoc` | 单个声明的KDoc（摘要、描述、标签） |
| `get_source` | 文件（ `path` ）或单个声明（ `fqName` ）的原始源代码 |
| `search_source` | 子字符串/正则表达式搜索；有界，返回 `file:line` 代码片段 |
| `get_dependencies` | 来自 `.pom`/`.module` 的依赖树；有界 `depth` |
| `list_versions` | 从 `maven-metadata.xml` 发布版本，新版本优先 |
| `get_latest_version` | 从 `maven-metadata.xml` 最新稳定版本（和最新版本） |
每个工具都提供了MCP规范鼓励客户端使用的元数据：显示 `title` 、 **行为注解** （除了 `fetch_library` 之外的所有地方都为 `readOnlyHint: true` ，它是累积的 - `destructiveHint: false` ， `idempotentHint: true` ；访问Maven仓库的工具设置 `openWorldHint: true` ，缓存工具设置 `false` ），以及从响应DTO的序列化器派生的类型化 **`outputSchema`** 。结果携带漂亮的JSON文本和匹配的 `structuredContent` 对象，因此结构化输出客户端和纯文本客户端看到的负载相同。
`fetch_library` 还报告 **进度通知** （下载 → 分析 → 缓存），当客户端发送 `progressToken` 时，服务器宣传 **日志记录能力** - 其日志作为 `notifications/message` 镜像到客户端（尊重 `logging/setLevel` ），这在stdio上很重要，因为stderr通常被丢弃。
**资源：** 每个缓存库都可以通过 `kotlinlib://{group}/{artifact}/{version}/index` 读取（解析后的索引为JSON）；库被获取时，列表会更新，并且相同的URI形状作为 **资源模板** 发布，因此任何缓存坐标都可以直接寻址。 **提示：** `explain_public_api(coordinate, package?)` 渲染一个解释请求，该请求基于缓存的签名和KDoc。
## 从源代码构建
```sh
./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 # 服务器/build/install/server/bin中的独立启动器
```
需要JDK 21（通过Gradle工具链自动解析）。
| 模块 | 它是什么 |
|---|---|
| `core/` | KMP库：领域模型 + 端口（ `commonMain` ）；Maven获取器，zip提取器，分析API分析器，磁盘缓存（ `jvmMain` ） |
| `server/` | JVM应用程序：MCP工具/资源/提示 + stdio和流式HTTP传输 |
| `dashboard/` | 嵌入服务器（可选）的Compose Desktop控制面板 |
## 缓存
下载内容和解析后的索引位于OS缓存目录 + `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` 重写它。
## 注意事项
- **stdio规则：** stdout仅承载MCP协议帧；所有日志记录都转到stderr（Kermit → SLF4J → Logback， `logback.xml` ）。
- Kotlin和Analysis API工件在 `gradle/libs.versions.toml` 中版本锁定 - 将它们一起提升。符号类型无法解析（缺少传递依赖）会降级为 `bestEffort: true` PSI签名而不是失败。
## 贡献
欢迎贡献 - 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。发布历史记录在 [CHANGELOG.md](CHANGELOG.md) 中；安全报告通过 [私人漏洞报告](SECURITY.md) 进行。
## 许可证
[Apache-2.0](LICENSE)
