papermoon-mkdocs-mcp

MkDocs 문서 사이트를 위한 경량 MCP 서버입니다. 마크다운 파일을 디스크에서 직접 읽고, 전체 텍스트 및 선택적 의미 검색을 제공하며, Model Context Protocol을 통해 프로젝트 구조를 노출합니다.

기능

• 5가지 MCP 도구 -- search, read_document, list_documents, get_project_info, get_document_outline

• SQLite FTS5 키워드 검색 (BM25 랭킹, 외부 의존성 없음)

• 선택적 의미 벡터 검색 (sentence-transformers 기반)

• 하이브리드 검색 -- 키워드 + 벡터 결과를 Reciprocal Rank Fusion으로 결합

• 증분 인덱싱 -- 파일 변경 시 빠른 업데이트

• 서버 재시작 후에도 유지되는 영구 SQLite 인덱스

• 내비게이션 인식 -- mkdocs.yml 및 .nav.yml 파싱

• 문서 제외 가능 -- 초안 및 내부 페이지를 MCP 표면에서 제외

• 보안 우선 -- 경로 탐색 방지, 읽기 전용 검색 연결

• 최소 의존성 -- 필수 3개, 선택 2개

Related MCP server: mdbook-mcp-server

설치

pip install papermoon-mkdocs-mcp

벡터 검색을 활성화하려면:

pip install papermoon-mkdocs-mcp[vector]

빠른 시작

MkDocs 프로젝트 루트(mkdocs.yml이 있는 위치)에서 실행:

cd /path/to/your/mkdocs-project
papermoon-mkdocs-mcp

또는 특정 구성 파일을 지정:

papermoon-mkdocs-mcp --config /path/to/mkdocs.yml

서버는 --config를 생략하면 현재 디렉터리에서 mkdocs.yml을 자동 감지합니다.

전송 옵션

기본적으로 서버는 stdio 전송을 사용합니다. 원격 또는 다중 클라이언트 설정을 위해 네트워크 전송으로 전환할 수 있습니다:

# Streamable HTTP (recommended for network access)
papermoon-mkdocs-mcp --transport streamable-http --host 0.0.0.0 --port 9000

# SSE (legacy client compatibility)
papermoon-mkdocs-mcp --transport sse --port 8080

보안 참고: 루프백이 아닌 주소에 바인딩할 때는 서버를 TLS를 종료하는 리버스 프록시(예: nginx, Caddy) 뒤에 배치하세요.

MCP 클라이언트 구성

Claude Desktop

Claude Desktop 구성 파일에 추가:

{
  "mcpServers": {
    "mkdocs": {
      "command": "papermoon-mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

참고: Claude Desktop이 명령을 찾지 못하는 경우(Failed to spawn process: No such file or directory), mkdocs-mcp 대신 실행 파일의 전체 경로를 사용하세요:

{
  "mcpServers": {
    "mkdocs": {
      "command": "/path/to/.venv/bin/mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

이는 패키지가 가상 환경에 설치되어 있고 해당 bin/ 디렉터리가 Claude Desktop의 PATH에 없는 경우 흔히 발생합니다.

Claude Code / VS Code

프로젝트 루트의 .mcp.json에 추가:

{
  "mcpServers": {
    "mkdocs": {
      "command": "papermoon-mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

사용 가능한 도구

search

키워드, 의미, 또는 하이브리드 검색으로 문서를 검색합니다.

경로, 제목, 관련성 점수(0.0--1.0 정규화), 텍스트 스니펫과 함께 순위가 매겨진 결과를 반환합니다.

read_document

상대 경로로 문서 파일을 읽습니다.

마크다운 본문(frontmatter 제거), 별도 필드로 파싱된 frontmatter, 제목 구조, 파일 메타데이터를 반환합니다.

list_documents

모든 문서 파일을 나열하며, 선택적으로 섹션으로 필터링합니다.

문서 메타데이터(경로, 제목, 설명, 카테고리, 크기, 수정 시간)를 반환합니다.

get_project_info

MkDocs 프로젝트 메타데이터를 가져옵니다. 매개변수를 받지 않습니다.

사이트 이름, 사이트 URL, docs 디렉터리, 테마, 내비게이션 트리, 문서 수, 인덱스 상태를 반환합니다.

get_document_outline

문서의 제목 구조(목차)를 가져옵니다.

문서 제목과 레벨, 텍스트, 앵커가 포함된 제목 목록을 반환합니다.

문서 제외

일부 마크다운 파일은 MCP를 통해 노출할 가치가 없습니다 -- 초안, 내부 런북, 생성된 임시 파일 등. mkdocs.yml에 mcp_exclude 목록을 추가하세요:

site_name: My Docs

mcp_exclude:
  - drafts/             # any directory named 'drafts', at any depth
  - internal/**         # anchored: only 'internal/' at the docs root
  - "*-scratch.md"      # by filename suffix, at any depth
  - "!internal/public.md"  # re-include one file from a broader rule

제외는 모든 곳에 동시에 적용됩니다. 제외된 문서는 내비게이션 트리에 없고, 검색 인덱스에 들어가지 않으며, list_documents에 나타나지 않고, read_document 및 get_document_outline에서 거부됩니다 -- 거부 응답은 존재하지 않는 파일에 대한 응답과 동일하므로 문서가 존재한다는 사실을 드러내지 않습니다.

mcp_exclude는 이 MCP 서버에만 영향을 줍니다. mkdocs build가 게시하는 내용은 변경하지 않습니다.

패턴 구문

패턴은 gitignore 스타일이며 docs_dir 기준 문서 경로와 일치합니다.

• /를 포함하는 패턴은 docs_dir에 고정됩니다. /가 없으면 모든 깊이에서 일치합니다.

• 끝에 /가 있으면 패턴이 디렉터리로 제한되므로 drafts/는 drafts.md라는 파일을 숨기지 않습니다.

• 규칙은 순서대로 평가되며 마지막으로 일치하는 규칙이 결정하므로 ! 재포함 규칙은 해당 규칙을 제외하는 규칙 뒤에 배치하세요.

• 빈 줄과 # 주석은 무시됩니다.

새로 제외된 파일은 다음 실행 시 인덱스에서 제거되고, 패턴을 제거하면 다시 포함됩니다 -- .mkdocs-mcp.db를 삭제할 필요가 없습니다.

아키텍처

src/mkdocs_mcp/
  config.py      -- MkDocs config detection and nav parsing
  exclusions.py  -- mcp_exclude pattern matching
  repository.py  -- SQLite schema and CRUD operations
  indexer.py     -- Index orchestration with incremental updates
  searcher.py    -- Keyword, vector, and hybrid search
  server.py      -- FastMCP server with 5 tool definitions
  utils.py       -- Path validation, frontmatter parsing, text extraction
  models.py      -- Pydantic response models

시작 시 서버는 mkdocs.yml을 읽고, docs 디렉터리를 스캔하며, SQLite FTS5 인덱스를 구축(또는 증분 업데이트)합니다. 검색 쿼리는 인덱스를 직접 조회합니다. 벡터 검색은 all-MiniLM-L6-v2로 쿼리를 임베딩하고 저장된 문서 임베딩과 비교합니다. 하이브리드 모드는 Reciprocal Rank Fusion을 사용하여 두 결과 목록을 융합합니다.

개발

git clone https://github.com/aspect-build/mkdocs-mcp.git
cd mkdocs-mcp
pip install -e ".[dev]"
pytest

린트 및 타입 검사:

ruff check .
mypy src/

요구 사항

• Python >= 3.10

• 필수: fastmcp (>=3.0, <4), pydantic (>=2.0, <3), pyyaml (>=6.0), markdown (>=3.4)

• 선택 (벡터 검색): sentence-transformers (>=3.0), numpy (>=1.24)

라이선스

자세한 내용은 LICENSE를 참조하세요.