kmp-api-lookup-mcp

Kotlin/Native iOS klib API를 빠르게 조회하기 위한 MCP 서버입니다.

이 서버는 로컬 Kotlin/Native 플랫폼 klib을 영구적인 SQLite 데이터베이스로 인덱싱하고, 심볼 조회 및 인덱스 관리를 위한 간결한 MCP API를 제공합니다.

설치

사전 요구 사항

• Node.js 22+

• KONAN_HOME 또는 ~/.konan을 통해 플랫폼 klib을 사용할 수 있는 로컬 Kotlin/Native 설치

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를 통한 수동 인덱스 재빌드

• 전체 Kotlin 시그니처, 클래스 계층 구조 및 임포트를 위한 klib dump-metadata 기반의 온디맨드 보강

• 짧은 텍스트 요약이 포함된 구조화된 JSON MCP 응답

구현된 도구

lookup_symbol

Kotlin/Native Apple 플랫폼 클래스, 멤버 또는 최상위 플랫폼 별칭/상수를 간결한 개발 카드 형태로 확인합니다.

입력:

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

동작:

• AVPlayer와 같은 클래스 쿼리는 다음을 포함하는 하나의 클래스 카드를 반환합니다:

  • 전체 Kotlin 클래스 시그니처

  • 슈퍼클래스 및 구현된 인터페이스

  • detail이 생략되거나 compact로 설정된 경우 모든 생성자, 인스턴스 메서드 및 클래스 메서드 (출력 크기를 줄이기 위해 멤버 이름별로 그룹화됨)

  • compact 모드에서 해당 속성에 대한 getter/setter 메서드가 존재할 때 명시적인 accessors.getter 및 accessors.setter 플래그가 포함된 별도의 properties 목록

  • compact 모드는 중복된 속성 접근자 메서드만 제거하며, 클래스 표면에서 관련 없는 메서드를 삭제하지는 않음

  • detail이 full로 설정된 경우 전체 직접 멤버 세트, ObjC 브리지 확장 멤버 및 Meta 클래스 멤버

  • 코드 생성을 위한 requiredImports

• AVPlayer.play 또는 play와 같은 멤버 쿼리는 오버로드 시그니처와 임포트가 포함된 간결한 그룹화 카드를 반환합니다.

• AVPlayerStatus, AVLayerVideoGravity 또는 AVPlayerItemDidPlayToEndTimeNotification과 같은 정확한 최상위 플랫폼 별칭 및 상수는 모호한 클래스 일치로 떨어지지 않고 패키지 범위의 멤버 카드로 확인됩니다.

• 쿼리가 모호한 경우, 도구는 원시 검색 행을 덤프하는 대신 짧은 대안 목록을 반환합니다.

• 출력은 DB 경로, 내부 ID, 원시 메타데이터 덤프, 일치 단계 및 설치 경로와 같은 불필요한 필드를 의도적으로 생략합니다.

• detail은 기본적으로 compact입니다. 전체 클래스 표면이 정말로 필요한 경우에만 "detail": "full"을 사용하세요.

get_klib_index_status

간결한 인덱스 요약을 반환합니다.

입력:

{}

출력 포함 항목:

• ready

• 발견된 Kotlin/Native 버전 및 타겟

• 카운트가 포함된 인덱싱된 데이터셋

• 총 심볼 수

• lastRebuildAt

rebuild_klib_index

로컬 klib에서 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 DB: 사용자 캐시 디렉터리 + 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를 통해 처리됩니다.

• package.json의 version과 일치하는 vX.Y.Z 형식의 태그를 푸시합니다.

• Publish Package 워크플로우가 패키지를 검증하고 npm에 게시합니다.

• npm 패키지는 SuLG-ik/kmp-api-lookup-mcp GitHub 저장소에서 신뢰할 수 있는 게시(trusted publishing)를 위해 구성되어야 합니다.

• 일회성 npm 설정 및 정확한 릴리스 단계는 PUBLISHING.md를 참조하세요.

테스트 커버리지

현재 테스트 스위트는 다음을 포함합니다:

• 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