docs2mcp

Markdown, HTML 또는 TXT 파일 디렉토리를 원격의 읽기 전용 MCP 서버로 변환하여, 호환되는 모든 MCP 클라이언트나 에이전트가 문서 검색을 위해 연결할 수 있게 합니다. 여기에는 AskMesh, Claude 통합, Codex 및 사용자 정의 MCP 클라이언트가 포함됩니다.

빠른 시작

uvx docs2mcp serve ./docs \
  --base-url https://docs.example.com/docs \
  --host 0.0.0.0 \
  --port 8765

uvx는 PyPI에서 격리된 환경을 생성하고 수동 설치 단계 없이 게시된 docs2mcp CLI를 실행합니다. 체크아웃에서 로컬 개발을 하려면 대신 python -m docs2mcp.runtime을 사용하세요.

파일 감시 및 주기적 재동기화를 통한 증분 동기화 활성화:

uvx docs2mcp serve ./docs \
  --host 0.0.0.0 \
  --port 8765 \
  --watch \
  --sync-interval 30

첫 번째 시작 시 전체 디렉토리를 스캔합니다. 이후 변경 사항은 문서별로 적용됩니다. 새 파일은 삽입되고, 수정된 파일은 다시 인덱싱되며, 삭제된 파일은 제거되고, 변경되지 않은 파일은 건너뜁니다. 감시자는 짧은 디바운스 창을 사용하며, 주기적 스캔은 이벤트를 안정적으로 발생시키지 않는 파일 시스템을 위한 폴백을 제공합니다.

DNS 리바인딩 보호가 활성화된 특정 공용 주소에 바인딩할 때는 들어오는 Host 헤더를 명시적으로 허용하세요:

uvx docs2mcp serve ./docs \
  --host 0.0.0.0 \
  --port 8765 \
  --allowed-host 'docs.example.com:*'

설치와 시작에 동일한 Python 인터프리터를 사용하세요. docs2mcp는 공식 MCP Python SDK mcp>=1.27.0,<2를 요구합니다. mcp라는 이름의 더 오래되거나 관련 없는 패키지는 mcp.server.fastmcp를 제공하지 않습니다.

레거시 doc2mcp 명령은 호환성 별칭으로 계속 사용할 수 있습니다.

프로세스는 시작 시 MCP 연결 구성을 출력합니다. 인증은 선택 사항입니다. Bearer 인증을 활성화하려면 --token을 전달하고, 인증 없이 실행하려면 생략하세요.

{
  "endpoint": "http://127.0.0.1:8765/mcp",
  "auth_type": "none",
  "token": null,
  "search_tool": "search_docs",
  "read_tool": "get_document",
  "contract_version": "agent-qa.docs/v1"
}

MCP 클라이언트 구성에 endpoint, 인증 모드, search_docs 및 get_document 값을 입력하세요. auth_type이 none이면 인증 없음을 선택하고 토큰을 비워 두세요. Streamable HTTP를 지원하는 클라이언트는 AskMesh 전용 어댑터 없이 동일한 엔드포인트에 연결할 수 있습니다.

GET /readyz는 문서 수와 추가, 업데이트, 삭제, 건너뜀, 실패, 기간 및 마지막 오류를 포함한 최신 동기화 카운터를 보고합니다.

Related MCP server: Synapse

지원 형식

MVP는 .md, .markdown, .txt, .html 및 .htm을 지원합니다. 인덱싱은 SQLite FTS5를 사용하므로 별도의 벡터 데이터베이스가 필요하지 않습니다.

MCP 계약

서버는 상호 운용 가능한 agent-qa.docs/v1 문서 계약을 구현하며 두 가지 읽기 전용 도구를 노출합니다:

• search_docs(query, limit): route, title, url, snippet 및 score를 반환합니다.

• get_document(route, max_characters): 문서 내용, 섹션 및 인용 URL을 반환합니다.

search_docs.query는 SQLite FTS5 구문을 사용합니다. 공백은 AND 쿼리이고, OR는 두 용어 중 하나와 일치하며, 따옴표로 묶인 텍스트는 정확한 구문을 검색하고, NOT은 용어를 제외하며, *는 접두사 일치를 활성화합니다. 의미론적 자연어 검색이 아니므로 클라이언트는 이 구문을 사용자에게 표시해야 합니다.

모든 MCP 클라이언트에서 연결

원격 MCP 연결을 지원하는 모든 클라이언트에서 Streamable HTTP 엔드포인트와 두 도구 이름을 사용하세요. AskMesh는 지원되는 통합 중 하나입니다. Claude 기반 클라이언트, Codex 및 사용자 정의 에이전트는 동일한 엔드포인트와 읽기 전용 계약을 사용할 수 있습니다.

현재 제한 사항

이 릴리스는 단일 호스트 MVP입니다. 문서는 로컬 디렉토리에서 가져오고 인덱스는 SQLite에 저장됩니다. Git 동기화, PDF 파싱, 객체 스토리지, 벡터 검색 및 다중 테넌트 제어 플레인은 이후 릴리스에서 계획되어 있습니다.