Govcraft/rust-docs-mcp-server

⭐ 이 프로젝트가 마음에 드시나요? GitHub에서 저장소에 star를 눌러 지원을 표현하고 최신 소식을 받아보세요! ⭐

현대의 AI 기반 코딩 어시스턴트(Cursor, Cline, Roo Code 등)는 코드 구조와 구문을 이해하는 데 탁월하지만, 빠르게 진화하는 라이브러리와 프레임워크의 세부 사항, 특히 크레이트(crate)가 빈번하게 업데이트되는 Rust 생태계에서는 종종 어려움을 겪습니다. 이들의 학습 데이터 컷오프(training data cutoff)로 인해 최신 API에 대한 지식이 부족할 수 있으며, 이는 부정확하거나 오래된 코드 제안으로 이어질 수 있습니다.

이 MCP 서버는 특정 Rust 크레이트에 대한 집중적이고 최신화된 지식 소스를 제공함으로써 이러한 문제를 해결합니다. 특정 크레이트(예: serde, tokio, reqwest)에 대해 이 서버의 인스턴스를 실행함으로써, LLM 코딩 어시스턴트가 해당 크레이트와 관련된 코드를 작성하기 전에 사용할 수 있는 도구(query_rust_docs)를 제공하게 됩니다.

이 도구를 사용하도록 지시받으면, LLM은 크레이트의 API 또는 사용법에 대해 구체적인 질문을 던질 수 있으며, 현재 문서에서 직접 도출된 답변을 받을 수 있습니다. 이는 생성된 코드의 정확성과 관련성을 크게 향상시켜, 수동 수정의 필요성을 줄이고 개발 속도를 높여줍니다.

이 서버의 여러 인스턴스를 동시에 실행할 수 있으므로, LLM 어시스턴트는 코딩 세션 동안 여러 다른 크레이트의 문서에 접근할 수 있습니다.

이 서버는 지정된 Rust 크레이트의 문서를 가져오고, 콘텐츠에 대한 임베딩(embeddings)을 생성하며, 문서 컨텍스트를 기반으로 크레이트에 관한 질문에 답할 수 있는 MCP 도구를 제공합니다.

대상 문서: 서버 인스턴스당 단일 Rust 크레이트에 집중합니다.
기능 지원: 문서 생성을 위해 필요한 크레이트 기능(features)을 지정할 수 있습니다.
시맨틱 검색 (Semantic Search): OpenAI의 text-embedding-3-small 모델을 사용하여 주어진 질문에 대해 가장 관련성이 높은 문서 섹션을 찾습니다.
LLM 요약: OpenAI의 gpt-4o-mini-2024-07-18을 활용합니다.

검색된 문서 컨텍스트에만 기반하여 간결한 답변을 생성하도록 모델을 활용합니다.

캐싱 (Caching): 이후 실행 속도를 높이기 위해 크레이트 (crate), 버전, 및 요청된 기능 (features)을 기준으로 생성된 문서 콘텐츠와 임베딩 (embeddings)을 사용자의 XDG 데이터 디렉토리(~/.local/share/rustdocs-mcp-server/ 또는 유사한 경로)에 캐싱합니다.

MCP 통합 (MCP Integration): stdio를 통해 표준 MCP 서버로 실행되며, 도구 (tools)와 리소스 (resources)를 노출합니다.

OpenAI API 키: 임베딩 생성 및 답변 요약을 위해 필요합니다. 서버는 이 키가 OPENAI_API_KEY 환경 변수에 설정되어 있을 것으로 예상합니다. (서버는 또한 크레이트 의존성을 다운로드하고 OpenAI API와 상호작용하기 위해 네트워크 액세스가 필요합니다).

권장되는 설치 방법은 GitHub Releases 페이지에서 사용 중인 운영 체제에 맞는 사전 컴파일된 바이너리 (pre-compiled binary)를 다운로드하는 것입니다.

• Releases 페이지로 이동합니다.
• 시스템에 적합한 아카이브(.zip은 Windows용, .tar.gz는 Linux/macOS용)를 다운로드합니다.
• rustdocs_mcp_server (또는 rustdocs_mcp_server.exe) 바이너리를 압축 해제합니다.
• 바이너리를 시스템의 PATH 환경 변수에 포함된 디렉토리(예: /usr/local/bin, ~/bin)에 배치합니다.

소스 코드로 직접 빌드하는 것을 선호한다면, Rust 툴체인 (Rust Toolchain)이 설치되어 있어야 합니다.

저장소 복제 (Clone the repository):
git clone https://github.com/Govcraft/rust-docs-mcp-server.git cd rust-docs-mcp-server

서버 빌드 (Build the server):
cargo build --release

새로운 크레이트에 대한 중요 참고 사항:

특정 크레이트에 대해 서버를 처음 사용하거나(또는 새로운 버전/기능 세트를 사용할 때), 문서를 다운로드하고 임베딩을 생성해야 합니다. 이 과정은 특히 문서가 방대한 크레이트의 경우 시간이 다소 소요될 수 있으며, 활성 인터넷 연결과 OpenAI API 키가 필요합니다.

새로운 크레이트 (crate) 설정을 AI 코딩 어시스턴트(Roo Code, Cursor 등)에 추가하기 전에, 명령줄(command line)에서 서버를 직접 한 번 실행하는 것을 권장합니다. 이를 통해 초기 임베딩 (embedding) 생성 및 캐싱 (caching) 과정을 완료할 수 있습니다. 서버가 준비되었음을 나타내는 시작 메시지(예: "MCP Server listening on stdio")가 나타나면 종료(Ctrl+C)해도 됩니다. 이후 코딩 어시스턴트에 의해 시작되는 실행을 포함한 모든 후속 실행은 캐시된 데이터를 사용하므로 훨씬 빠르게 시작됩니다.

서버는 명령줄에서 실행되며, 대상 크레이트에 대한 **패키지 ID 명세 (Package ID Specification)**가 필요합니다. 이 명세는 Cargo에서 사용하는 형식(예: crate_name, crate_name@version_req)을 따릅니다. 전체 명세에 대한 자세한 내용은 man cargo-pkgid 또는 Cargo 문서를 참조하십시오.

선택적으로 -F 또는 --features 플래그를 사용하여 필요한 크레이트 기능 (features)을 쉼표로 구분된 목록으로 지정할 수 있습니다. 이는 cargo doc이 성공하기 위해 특정 기능 활성화가 필요한 크레이트(예: async-stripe와 같이 런타임 기능이 필요한 크레이트)의 경우 필수적입니다.

# API 키 설정 (실제 키로 교체하세요)
export OPENAI_API_KEY="sk-..."
# 예시: serde의 최신 1.x 버전에 대해 서버 실행
...

특정 크레이트 버전 및 기능 세트에 대한 첫 실행 시, 서버는 다음 작업을 수행합니다:

• cargo doc을 사용하여 (지정된 기능을 포함하여) 크레이트 문서를 다운로드합니다.
• HTML 문서를 파싱 (parse)합니다.
• OpenAI API를 사용하여 문서 콘텐츠에 대한 임베딩 (embeddings)을 생성합니다 (이 과정은 시간이 다소 소요될 수 있으며 비용이 발생할 수 있지만, 대부분의 크레이트의 경우 일반적으로 1미국 센트의 아주 적은 일부에 불과합니다. 테스트 중 5,000페이지 이상의 문서를 가진 async-stripe와 같은 대규모 크레이트의 임베딩 생성 비용도 단 0.18달러 USD였습니다).
• 문서 콘텐츠와 임베딩을 캐시 (cache)하여 비용이 다시 발생하지 않도록 합니다.
• MCP 서버를 시작합니다.

동일한 crate 버전 *및 기능 세트 (feature set)*에 대한 후속 실행은 캐시 (cache)에서 데이터를 로드하므로 시작 속도가 훨씬 빨라집니다.

서버는 표준 입출력 (stdio)을 통해 Model Context Protocol (MCP)을 사용하여 통신합니다. 서버는 다음을 노출합니다:

도구 (Tool): query_rust_docs

설명 (Description): 시맨틱 검색 (semantic search) 및 LLM 요약 (summarization)을 사용하여 서버가 시작된 특정 Rust crate에 대한 문서를 쿼리합니다.

입력 스키마 (Input Schema):

{ "type": "object", "properties": { "question": { "type": "string", "description": "The specific question about the crate's API or usage." } }, "required": ["question"] }

출력 (Output): 관련 문서 컨텍스트 (context)를 기반으로 LLM이 생성한 답변을 포함하는 텍스트 응답이며, From <crate_name> docs:라는 접두사가 붙습니다.

.MCP 호출 예시 (Example MCP Call):

{ "jsonrpc": "2.0", "method": "callTool", "params": { "tool_name": "query_rust_docs", "arguments": { "question": "How do I make a simple GET request with reqwest?" } }, "id": 1 }

리소스 (Resource): crate://<crate_name>

설명 (Description): 이 서버 인스턴스가 구성된 Rust crate의 이름을 제공합니다.

URI: crate://<crate_name>

(예: crate://serde, crate://reqwest)

콘텐츠 (Content): crate 이름을 포함하는 일반 텍스트 (plain text).

로깅 (Logging): 서버는 정보성 로그 (시작 메시지, 쿼리 처리 단계)를 logging/message 알림을 통해 MCP 클라이언트로 다시 보냅니다.

Roo Code와 같은 MCP 클라이언트를 구성하여 이 서버의 여러 인스턴스를 실행하고, 각 인스턴스가 서로 다른 crate를 대상으로 하도록 설정할 수 있습니다. 다음은 reqwest와 async-stripe를 위한 서버를 구성하는 Roo Code의 mcp_settings.json 파일 예시 스니펫입니다 (async-stripe에 추가된 features 인수에 유의하세요):

{
"mcpServers": {
"rust-docs-reqwest": {
...

참고:

• /path/to/your/rustdocs_mcp_server가 시스템의 PATH에 포함되어 있지 않다면, 컴파일된 바이너리의 실제 경로로 교체하세요. - YOUR_OPENAI_API_KEY_HERE를 실제 OpenAI API 키로 교체하세요. - 키 (rust-docs-reqwest, rust-docs-async-stripe

)는 Roo Code 내에서 서버 인스턴스를 식별하기 위해 사용자가 임의로 지정하는 이름입니다.

Claude Desktop 사용자의 경우, MCP 설정에서 서버를 구성할 수 있습니다.
다음은 serde 및 async-stripe를 위한 서버 구성 예시입니다:

{
"mcpServers": {
"rust-docs-serde": {
...

참고:

• rustdocs_mcp_server가 시스템의 PATH에 있는지 확인하거나 전체 경로(예: /path/to/your/rustdocs_mcp_server)를 제공하세요. - 키(rust-docs-serde, rust-docs-async-stripe-rt)는 서버 인스턴스를 식별하기 위해 사용자가 임의로 선택하는 이름입니다. - Claude Desktop이 접근할 수 있는 곳에 OPENAI_API_KEY 환경 변수를 설정해야 함을 기억하세요 (이는 시스템 전체에 설정하거나 Claude Desktop을 실행하는 방식을 통해 설정할 수 있습니다). Claude Desktop의 MCP 구성은 Roo Code처럼 서버별로 환경 변수를 설정하는 것을 직접적으로 지원하지 않을 수 있습니다. - 예시는 async-stripe와 같이 특정 기능(features)이 필요한 크레이트(crates)를 위해 -F 인자를 추가하는 방법을 보여줍니다.

위치: 캐시된 문서(documentation)와 임베딩(embeddings)은 XDG 데이터 디렉토리에 저장되며, 일반적으로 ~/.local/share/rustdocs-mcp-server/<crate_name>/<sanitized_version_req>/<features_hash>/embeddings.bin 경로에 위치합니다. sanitized_version_req는 버전 요구 사항에서 유도되며, features_hash는 시작 시 요청된 특정 기능 조합을 나타내는 해시(hash)입니다. 이를 통해 서로 다른 기능 세트가 별도로 캐시되도록 보장합니다. 형식: 데이터는 bincode 직렬화(serialization)를 사용하여 캐시됩니다. 재생성: 캐시 파일이 누락되었거나, 손상되었거나, 디코딩할 수 없는 경우 서버는 자동으로 문서와 임베딩을 재생성합니다.

초기화: clap을 사용하여 명령줄에서 크레이트 사양(crate specification) 및 선택적 기능(optional features)을 파싱합니다. 캐시 확인: 특정 크레이트, 버전 요구 사항 및 기능 세트에 대해 기존에 존재하는 캐시 파일이 있는지 확인합니다. 문서 생성 (캐시 미스 시): - 대상 크레이트에만 의존하는 임시 Rust 프로젝트를 생성하며, 해당 프로젝트의 Cargo.toml에서 지정된 기능(features)을 활성화합니다.

• cargo doc를 실행합니다.

• cargo를 사용하여 임시 디렉토리에 HTML 문서 (documentation)를 생성하기 위한 라이브러리 API (library API)를 사용합니다. - index.html을 포함하는 하위 디렉토리를 검색하여 target/doc 내에서 올바른 출력 디렉토리를 동적으로 찾아냅니다.

• 대상 크레이트 (crate)에만 의존하는 임시 Rust 프로젝트를 생성하며, 해당 프로젝트의 Cargo.toml에서 지정된 기능 (features)을 활성화합니다.

콘텐츠 추출 (캐시 미스 시):

• 찾아낸 문서 디렉토리 내의 생성된 HTML 파일들을 탐색합니다.
• scraper 크레이트 (crate)를 사용하여 각 HTML 파일을 파싱하고, 메인 콘텐츠 영역 (<section id="main-content">)에서 텍스트 콘텐츠를 추출합니다.

임베딩 생성 (캐시 미스 시):

• async-openai 크레이트 (crate)와 tiktoken-rs를 사용하여 text-embedding-3-small 모델로 추출된 각 문서 청크 (chunk)에 대한 임베딩 (embeddings)을 생성합니다. - 처리된 토큰 (tokens) 수를 기반으로 예상 비용을 계산합니다.

캐싱 (캐시 미스 시):

• bincode를 사용하여 추출된 문서 콘텐츠와 그에 상응하는 임베딩을 캐시 파일(경로에 기능 해시 포함)에 저장합니다.

서버 시작:

• 로드되었거나 생성된 문서 및 임베딩으로 RustDocsServer를 초기화합니다.

MCP 서빙:

• rmcp를 사용하여 stdio를 통해 MCP 서버를 시작합니다.

쿼리 처리 (query_rust_docs 도구):

• 사용자의 질문에 대한 임베딩을 생성합니다.
• 질문 임베딩과 모든 캐시된 문서 임베딩 간의 코사인 유사도 (cosine similarity)를 계산합니다.
• 유사도가 가장 높은 문서 청크를 식별합니다.
• OpenAI API를 통해 사용자의 질문과 가장 잘 일치하는 문서 청크의 콘텐츠를 gpt-4o-mini-2024-07-18 모델로 전송합니다. - LLM은 오직 제공된 컨텍스트 (context)에만 기반하여 질문에 답하도록 프롬프트가 작성됩니다. - LLM의 응답을 MCP 클라이언트에 반환합니다.

이 프로젝트는 MIT 라이선스 (MIT License) 하에 라이선스가 부여됩니다.

Copyright (c) 2025 Govcraft

Govcraft는 1인 기업입니다. 기업의 지원도, 투자자도 없으며, 오직 제가 유용한 도구들을 만들고 있습니다. 이 프로젝트가 도움이 된다면, 후원이 작업을 지속하는 데 큰 힘이 됩니다.