프로젝트 소개

fumasignal-mcp는 Fumadocs로 구축된 문서 사이트를 검색하고 읽을 수 있게 해주는 서드파티 비공식 Model Context Protocol(MCP) 서버입니다. 배포된 Fumadocs URL 또는 로컬 프로젝트 디렉토리를 가리키며, MCP 클라이언트에게 일련의 읽기 전용 도구를 노출합니다. 프로젝트명은 Fumadocs 작성자 핸들이자 AI 클라이언트와 외부 도구 사이 메시지를 전달한다는 상징에서 유래했습니다. 저자는 이 프로젝트가 Fumadocs 프로젝트와 무관함을 명시적으로 밝힙니다. 운영 모드 서버는 두 가지 모드로 실행됩니다. 원격 모드는 배포된 사이트의 원본을 제공하면 되며 로컬 설정이 필요없습니다. 로컬 모드는 오프라인 작업이나 배포 전 검사에 적합합니다. 단일 npx 바이너리로 배포되므로 일반 실행 방식은 `npx -y fumasignal-mcp --url https://your-docs.com`이며 모든 접근은 문서 비수정성을 엄격히 지킵니다. 제공 도구 일곱 가지 도구가 제공됩니다. `search_docs`는 전체 텍스트 검색을 수행하며 쿼리와 태그 인수를 받습니다. `list_pages`는 문서 페이지 목록을 URL 접두사로 필터링할 수 있게 제공하며, `get_page`는 페이지의 전체 Markdown 콘텐츠를 가져옵니다. `get_section`은 제목 앵커로 섹션을 조회하고, `get_toc`은 페이지의_heading_과 앵커를 나열합니다. `get_meta`는 frontmatter를 JSON으로 반환하고, `get_llms_txt`는 `llms.txt`(또는 full 옵션 시 `llms-full.txt`)를 가져옵니다. 페이지 참조는 URL 경로, absolute same-host URL, slug 형태로 지정할 수 있습니다. 클라이언트 구성 README에는 Claude Desktop, Claude Code, Cursor, VS Code(GitHub Copilot Chat), Continue.dev용 구성 스니펫이 stdio 트랜스포트 방식으로 문서화되어 있으며, 여러 문서 사이트는 다른 키로 여러 인스턴스를 등록해 서비스할 수 있습니다. Continue.dev는 재사용 가능한 JSON 파일과 네이티브 YAML 포맷 둘 다 지원합니다. CLI 플래그 및 환경 변수 `--url`, `--local`, `--search-path`, `--docs-prefix`, `--content-dir`, `--auth-header`, `--cache-ttl`(기본 300000ms) 등의 플래그가 제공되며, 각각 `FUMASIGNAL_*` 환경 변수와 매핑됩니다. 명시적 플래그가 우선하며 `FUMASIGNAL_LOG_LEVEL`은 대응 플래그가 없는 별도 설정입니다. 시크릿은 셸 히스토리와 프로세스 목록에 남지 않도록 환경 변수로 전달할 것을 권장합니다. 검색 동작 원리 원격 모드에서는 `search_docs`가 Orama API를 호출하고 flat-array 및 hits/document 응답 형태 모두 처리하며, `list_pages`는 sitemap.xml을 가져와 필터링합니다. 페이지 검색은 `.md`, `.mdx`, `/raw` URL을 시도한 후 실패 시 Turndown으로 렌더링 HTML을 스크랩합니다. 응답은 5분 기본 TTL로 메모리에 캐시됩니다. 로컬 모드에서는 content 디렉토리 내 Markdown/MDX 파일을 gray-matter로 파싱하고, 인덱스 파일을 docs 루트에 매핑하며 헤딩 가중치 토큰 매칭으로 검색 결과 score를 계산합니다. 호환성 및 테스트 Node.js 20 이상이 필요하며 기본 Orama API와 표준 sitemap 레이아웃에서 테스트되었고, Claude Desktop, Claude Code, Cursor, VS Code, Zed, Cline 등 모든 STDIO MCP 클라이언트와 동작합니다. 280개 이상의 단위 테스트가 검색, sitemap, HTML 경로를 커버하는 fixtures와 함께 제공됩니다. 트러블슈팅 및 개발 README에는 흔한 문제들을 다루고 있습니다. sitemap이 없으면 `list_pages`만 영향받으며, 검색 404는 비기본 검색 경로 또는 path 포함된 URL을 의미합니다. HTML 스크랩은 Markdown 엔드포인트 없는 사이트에서 노이즈를 생성할 수 있으며 MCP Inspector 스크립트로 도구 등록을 검증할 수 있습니다. 개발 지침은 클론, 설치, `tsc`로 타입 체크, `eslint`로 linting, `vitest`로 테스트, `tsup`으로 빌드를 포함하며 합산 체크 스크립트가 제공됩니다. 기여는 MIT 라이선스로 환영되며 비_trivial_ 변경은 이슈 등록 후 진행해 주세요.