kmp-api-lookup-mcp

用于快速查找 Kotlin/Native iOS klib API 的 MCP 服务器。

该服务器将本地 Kotlin/Native 平台 klibs 索引到持久化的 SQLite 数据库中，并提供一个紧凑的 MCP API 用于符号查找和索引维护。

安装

前置要求

• Node.js 22+

• 本地安装有 Kotlin/Native，且可通过 KONAN_HOME 或 ~/.konan 访问平台 klibs

从 npm 安装（推荐）

npm install -g kmp-api-lookup-mcp

通过 npx 运行（无需全局安装）

npx -y kmp-api-lookup-mcp

这不会全局安装该包。npm 会按需下载并运行已发布的二进制文件。

从源码安装

git clone https://github.com/SuLG-ik/kmp-api-lookup-mcp.git
cd kmp-api-lookup-mcp
npm install
npm run build
npm link

快速入门

作为 MCP 服务器

将服务器添加到您的 MCP 客户端配置中。

常见的配置文件位置：

• macOS Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows Claude Desktop: %APPDATA%/Claude/claude_desktop_config.json

• Linux Claude Desktop: ~/.config/Claude/claude_desktop_config.json

仓库中包含了可直接复制的示例文件：

• claude_desktop_config.json.example 用于全局 npm 安装

• claude_desktop_config.npx.json.example 用于通过 npx 运行已发布的包

• claude_desktop_config.konan_home.json.example 用于带有显式 KONAN_HOME 的全局 npm 安装

• claude_desktop_config.from_source.json.example 用于从仓库运行已构建的服务器

如果包已全局安装：

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "kmp-api-lookup-mcp"
		}
	}
}

如果您不想全局安装该包：

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "npx",
			"args": ["-y", "kmp-api-lookup-mcp"]
		}
	}
}

这对于快速设置很方便，但首次启动可能会较慢，因为 npx 可能需要下载该包。

如果您想直接指向特定的 Kotlin/Native 安装目录：

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "kmp-api-lookup-mcp",
			"env": {
				"KONAN_HOME": "/Users/you/.konan/kotlin-native-prebuilt-macos-aarch64-2.2.21"
			}
		}
	}
}

如果您从源码运行服务器：

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "node",
			"args": ["/absolute/path/to/kmp-api-lookup-mcp/dist/index.js"]
		}
	}
}

首次运行

服务器启动后，通常的步骤是：

1. 调用 get_klib_index_status 查看索引是否已存在。

2. 如果索引缺失，针对您需要的 Kotlin/Native 版本和目标平台调用 rebuild_klib_index。

3. 使用 lookup_symbol 开始查询符号。

重建请求示例：

{
	"kotlinVersion": "2.2.21",
	"target": "ios_simulator_arm64",
	"frameworks": ["AVFoundation", "AVKit", "MediaPlayer", "AVFAudio"]
}

当前范围

• 基于 stdio 的 TypeScript npm ESM MCP 服务器

• 用户缓存目录中的持久化 SQLite 缓存

• 通过 KONAN_HOME、~/.konan 或显式路径发现预构建的 Kotlin/Native 安装

• 从 klib dump-metadata-signatures 手动重建索引

• 从 klib dump-metadata 按需获取完整的 Kotlin 签名、类层次结构和导入信息

• 带有简短文本摘要的结构化 JSON MCP 响应

已实现的工具

lookup_symbol

将 Kotlin/Native Apple 平台类、成员或顶级平台别名/常量解析为紧凑的开发卡片。

输入：

{
	"query": "AVPlayer",
	"frameworks": ["AVFoundation"],
	"detail": "compact",
	"queryKind": "auto"
}

行为：

• 像 AVPlayer 这样的类查询会返回一张包含以下内容的类卡片：

  • 完整的 Kotlin 类签名

  • 超类和已实现的接口

  • 当 detail 被省略或设置为 compact 时，所有构造函数、实例方法和类方法，按成员名称分组以减小输出大小

  • 在紧凑模式下，当属性存在匹配的 getter/setter 方法时，会有一个单独的 properties 列表，并带有显式的 accessors.getter 和 accessors.setter 标志

  • 紧凑模式仅移除重复的属性访问器方法；它不会从类表面修剪不相关的方法

  • 当 detail 设置为 full 时，包含完整的直接成员集、ObjC 桥接扩展成员和 Meta 类成员

  • 用于代码生成的 requiredImports

• 像 AVPlayer.play 或 play 这样的成员查询会返回一张紧凑的分组卡片，其中包含重载签名和导入信息。

• 精确的顶级平台别名和常量（如 AVPlayerStatus、AVLayerVideoGravity 或 AVPlayerItemDidPlayToEndTimeNotification）会解析为包作用域的成员卡片，而不是退化为模糊的类匹配。

• 如果查询有歧义，工具会返回一个简短的候选项列表，而不是转储原始搜索行。

• 输出特意省略了诸如数据库路径、内部 ID、原始元数据转储、匹配阶段和安装路径等嘈杂字段。

• detail 默认为 compact。仅在确实需要整个类表面时才使用 "detail": "full"。

get_klib_index_status

返回紧凑的索引摘要。

输入：

{}

输出包括：

• ready

• 已发现的 Kotlin/Native 版本和目标平台

• 带有计数的已索引数据集

• 聚合符号计数

• lastRebuildAt

rebuild_klib_index

从本地 klibs 构建或刷新 SQLite 索引。

输入：

{
	"kotlinVersion": "2.2.21",
	"target": "ios_simulator_arm64",
	"frameworks": ["Foundation", "UIKit"],
	"force": false,
	"dryRun": false,
	"cleanBefore": true
}

规则：

• kotlinVersion 和 konanHome 是可选的，但您最多只能提供其中一个。

• 如果两者都省略，则使用最新发现的本地 Kotlin/Native 安装。

• 如果省略 target，服务器优先选择 ios_simulator_arm64，其次是 ios_arm64，然后是 ios_x64。

• 如果省略 frameworks，重建将涵盖所选目标平台的所有框架。

• dryRun=true 计算重建计划而不写入 SQLite。

• force=true 忽略新鲜度检查。

• cleanBefore=true 在写入新记录之前删除受影响框架的现有行。

存储布局

服务器将数据存储在仓库之外。

• SQLite 数据库：用户缓存目录 + klib-index.sqlite

• 服务元数据：用户缓存目录 + state.json

典型的缓存位置：

• macOS: ~/Library/Caches/kmp-api-lookup-mcp/

• Linux: ${XDG_CACHE_HOME:-~/.cache}/kmp-api-lookup-mcp/

• Windows: %LOCALAPPDATA%/kmp-api-lookup-mcp/

发现规则

安装按以下顺序发现：

1. 工具提供显式 konanHome 参数时

2. KONAN_HOME

3. ~/.konan/kotlin-native-prebuilt-*

每个安装都通过检查以下内容进行验证：

• bin/klib

• klib/platform/

MCP 配置

从源码运行

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "node",
			"args": ["/absolute/path/to/kmp-api-lookup-mcp/dist/index.js"]
		}
	}
}

可选的环境变量覆盖：

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "node",
			"args": ["/absolute/path/to/kmp-api-lookup-mcp/dist/index.js"],
			"env": {
				"KONAN_HOME": "/Users/you/.konan/kotlin-native-prebuilt-macos-aarch64-2.2.21"
			}
		}
	}
}

作为已安装的二进制文件运行

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "kmp-api-lookup-mcp"
		}
	}
}

典型的已安装二进制文件配置

{
	"mcpServers": {
		"kmp-api-lookup": {
			"command": "kmp-api-lookup-mcp",
			"env": {
				"KONAN_HOME": "/Users/you/.konan/kotlin-native-prebuilt-macos-aarch64-2.2.21"
			}
		}
	}
}

开发

脚本

• npm run dev 从 TypeScript 源码启动服务器

• npm run build 编译到 dist/

• npm start 运行已编译的服务器

• npm run typecheck 运行 TypeScript 类型检查

• npm test 运行 Vitest

• npm run test:watch 在监视模式下启动 Vitest

本地工作流

npm install
npm run typecheck
npm run build
npm test

发布

npm 发布由 GitHub Actions 处理。

• 推送格式为 vX.Y.Z 的标签，其中 X.Y.Z 与 package.json 中的 version 匹配。

• Publish Package 工作流会验证包并将其发布到 npm。

• npm 包必须配置为从 SuLG-ik/kmp-api-lookup-mcp GitHub 仓库进行可信发布。

• 请参阅 PUBLISHING.md 了解一次性 npm 设置和确切的发布步骤。

测试覆盖率

当前的测试套件涵盖：

• MCP 工具注册

• dump-metadata-signatures 行解析

• 合成夹具上的 SQLite 存储和搜索行为

• 服务器运行时创建

项目结构

.
├── src/
│   ├── index.ts
│   ├── config/
│   ├── indexer/
│   ├── server/
│   ├── storage/
│   ├── tools/
│   ├── search-utils.ts
│   └── types.ts
├── test/
├── package.json
├── tsconfig.json
├── tsconfig.build.json
└── vitest.config.ts