Astro Docs MCP 서버

AI 에이전트에게 Astro 문서 접근 권한을 제공하는 MCP 서버입니다. 이 서버를 통해 AI 어시스턴트는 사용자의 Astro 관련 작업을 지원할 때 Astro 문서를 조회하고 참조할 수 있습니다.

이 TypeScript 기반 MCP 서버는 Astro를 위한 문서 검색 시스템을 구현합니다. 다음을 제공하여 핵심 MCP 개념을 보여줍니다.

• URI 및 메타데이터를 사용하여 Astro 문서 섹션을 나타내는 리소스
• Astro 문서 검색 도구
• 일반적인 점성술 질문 및 작업에 대한 프롬프트

특징

자원

• astro-docs:// URI를 통해 Astro 문서를 나열하고 액세스합니다.
• 각 문서 섹션에는 제목, 내용 및 범주가 있습니다.
• 간단한 콘텐츠 액세스를 위한 일반 텍스트 MIME 유형

도구

• search_docs - Astro 문서 검색
  • 필수 매개변수로 검색 쿼리를 사용합니다.
  • 일치하는 문서 섹션을 반환합니다.

프롬프트

• explain_astro_islands - Astro Islands 건축에 대한 자세한 설명을 받아보세요
• astro_project_setup - 새로운 Astro 프로젝트 설정 가이드
• astro_vs_other_frameworks - Astro를 다른 웹 프레임워크와 비교

프로젝트 구조

• src/ - MCP 서버의 소스 코드
  • index.ts - 주요 MCP 서버 구현
  • scripts/ - 빌드 및 테스트를 위한 도우미 스크립트
    • build.js - TypeScript를 변환하고 런처 스크립트를 생성하는 빌드 스크립트
    • test-client.js - 서버 기능 확인을 위한 테스트 클라이언트
• bin/ - 생성된 실행 가능 스크립트
  • astro-docs-mcp - MCP 서버를 위한 기본 런처 스크립트
• build/ - 컴파일된 JavaScript 파일(생성됨)

요구 사항

• Node.js v16 이상이 필요합니다.
• 최상의 호환성을 위해 Node.js v20+가 권장됩니다.
• 서버는 ES 모듈 구문을 사용합니다.
• pnpm 패키지 관리자(npm보다 선호됨)

설치

종속성 설치

종속성 설치:

지엑스피1

서버를 빌드하세요:

자동 재빌드를 사용한 개발의 경우:

서버 실행

Claude Desktop을 사용한 구성

Claude Desktop과 함께 사용하려면 서버 구성을 추가하세요.

MacOS의 경우: ~/Library/Application Support/Claude/claude_desktop_config.json Windows의 경우: %APPDATA%/Claude/claude_desktop_config.json

중요: 구성에서는 스크립트의 절대 경로를 사용해야 합니다.

/full/absolute/path/to/astro-mcp/ 설치 디렉토리의 실제 절대 경로로 바꾸세요.

예를 들어, 저장소가 /Users/username/projects/astro-mcp 에 있는 경우 명령은 다음과 같습니다.

디버깅

MCP 서버는 stdio를 통해 통신하므로 디버깅이 어려울 수 있습니다. 패키지 스크립트로 제공되는 MCP Inspector를 사용하는 것이 좋습니다.

검사기는 브라우저에서 디버깅 도구에 액세스할 수 있는 URL을 제공합니다.

테스트

서버가 올바르게 작동하는지 확인하기 위해 테스트 클라이언트가 제공됩니다.

이렇게 하면 여러 개의 명령이 서버로 전송되고 응답이 표시됩니다.

문제 해결

서버에 문제가 발생하는 경우:

1. 경로 문제 : 가장 흔한 문제는 구성 경로가 잘못되었다는 것입니다. 다음 사항을 확인하세요.
   • claude_desktop_config.json에서 스크립트에 대한 절대 경로를 사용하고 있습니다.
   • 경로는 bin/astro-docs-mcp (루트 스크립트가 아님)를 가리킵니다.
   • 빌드 디렉토리가 존재하며 index.js( ls -la build/ )를 포함합니다.
   • 모든 스크립트에는 실행 권한이 있습니다.
2. "모듈을 찾을 수 없음" 오류 : Cannot find module '/build/index.js' 와 같은 오류가 표시되면 다음을 확인하세요.
   • 빌드 단계( pnpm run build )를 실행했다는 것
   • 스크립트가 올바른 디렉토리에서 실행되고 있는지
   • 스크립트 실행에 절대 경로가 사용되고 있습니다.
3. Node.js 버전 : Node.js v16 이상을 사용하고 있는지 확인하세요. 최상의 결과를 얻으려면 v20 이상을 사용하세요.
   node --version
4. 스크립트 권한 : 스크립트에 실행 권한이 있는지 확인하세요.
   chmod +x bin/astro-docs-mcp src/scripts/build.js src/scripts/test-client.js
5. JSON 출력 문제 : 디버그 메시지가 stdout으로 전송되면 Claude Desktop이 유효한 JSON만 수신할 것으로 예상하기 때문에 혼란을 야기합니다. 저희 스크립트는 모든 디버그 출력을 stderr로 올바르게 리디렉션합니다.

Claude Desktop과 함께 사용

1. 위의 설치 단계에 따라 서버를 설치하세요.
2. 스크립트의 절대 경로를 포함하도록 구성 파일을 편집하여 Claude Desktop을 구성합니다.
   { "mcp_servers": [ { "id": "astro-docs-mcp", "name": "Astro Docs", "command": "/full/absolute/path/to/astro-mcp/bin/astro-docs-mcp", "type": "built-in" } ] }
3. Claude Desktop을 다시 시작합니다.
4. 이제 다음 명령을 사용하여 Astro 문서와 상호 작용할 수 있습니다.
   • list - 사용 가능한 Astro 문서 섹션 목록
   • search <query> - Astro 문서 검색
   • read astro-docs:///<id> - 특정 문서 섹션 읽기

향후 개선 사항

• Astro 웹사이트에서 실시간 문서를 가져옵니다.
• 더욱 포괄적인 문서 섹션 추가
• 문서 버전 관리 지원 구현
• 일반적인 Astro 패턴에 대한 코드 예제와 스니펫을 추가합니다.