Skip to main content
Glama
enesjakozh
dreyfus92

Astro Docs MCP Server

by dreyfus92
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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를 다른 웹 프레임워크와 비교

Related MCP server: Dedalus MCP Documentation Server

프로젝트 구조

  • 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

서버를 빌드하세요:

pnpm run build

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

pnpm run watch

서버 실행

pnpm start
# OR directly
./bin/astro-docs-mcp

Claude Desktop을 사용한 구성

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

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

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

{
  "mcp_servers": [
    {
      "id": "astro-docs-mcp",
      "name": "Astro Docs",
      "command": "/full/absolute/path/to/astro-mcp/bin/astro-docs-mcp",
      "type": "built-in"
    }
  ]
}

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

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

"/Users/username/projects/astro-mcp/bin/astro-docs-mcp"

디버깅

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

pnpm run inspector

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

테스트

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

pnpm test
# OR directly
node src/scripts/test-client.js

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

문제 해결

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

  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 패턴에 대한 코드 예제와 스니펫을 추가합니다.

Available Tools

1 tool
search_docsC

Search Astro documentation

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch term to find in Astro documentation

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action but reveals nothing about how the search works (e.g., scope, ranking, pagination), what the output looks like, or any constraints like rate limits or authentication needs. This leaves significant gaps for a tool with undocumented behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise at just three words, front-loading the essential action and resource without any wasted text. Every word earns its place, making it efficient and straightforward for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is incomplete for a search tool. It doesn't explain what the search returns, how results are structured, or any behavioral nuances, leaving the agent with insufficient context to use the tool effectively beyond the basic parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the single parameter 'query' clearly documented as 'Search term to find in Astro documentation'. The description adds no additional parameter details beyond what the schema provides, so it meets the baseline for high schema coverage without compensating value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Search') and resource ('Astro documentation'), making it immediately understandable. However, with no sibling tools mentioned, there's no opportunity to demonstrate differentiation from alternatives, which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, prerequisites, or contextual limitations. While the absence of sibling tools reduces the need for differentiation, it still lacks any usage instructions or exclusions, leaving the agent with minimal operational context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.0
    • First observedsearch_docs
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of confusion or overlap between tools. The single tool 'search_docs' has a clearly distinct and unambiguous purpose.

Naming Consistency5/5

The single tool name 'search_docs' follows a clear verb_noun pattern, and with only one tool, consistency is inherently perfect as there are no other names to compare against.

Tool Count2/5

A single tool for an 'Astro Docs MCP Server' feels too thin for the apparent scope. While search is a core function, documentation servers typically benefit from additional tools like browsing, filtering, or retrieving specific pages, making this count borderline inadequate.

Completeness2/5

The tool surface is severely incomplete for a documentation server. It only provides search functionality, lacking obvious gaps such as retrieving documentation pages, listing categories, or navigating content, which are essential for comprehensive agent interaction with documentation.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches