doc-lib-mcp

doc-lib-mcp MCP 서버

문서 수집, 청킹, 의미 검색 및 메모 관리를 위한 MCP(모델 컨텍스트 프로토콜) 서버입니다.

구성 요소

자원

• 다음을 사용하여 간단한 메모 저장 시스템을 구현합니다.
  • 개별 노트에 액세스하기 위한 사용자 지정 note:// URI 체계
  • 각 노트 리소스에는 이름, 설명 및 text/plain MIME 유형이 있습니다.

프롬프트

• 프롬프트를 제공합니다:
  • summarize-notes : 저장된 모든 노트의 요약을 생성합니다.
    • 세부 수준(간략/상세)을 제어하기 위한 선택적 "스타일" 인수
    • 현재 모든 노트와 스타일 선호도를 결합하여 프롬프트를 생성합니다.

도구

서버는 다양한 도구를 구현합니다.

• add-note : 메모리 내 노트 저장소에 새 노트를 추가합니다.
  • 인수: name (문자열), content (문자열)
• ingest-string : 메시지를 통해 제공된 마크다운 또는 일반 텍스트 문자열을 수집하고 청크화합니다.
  • 인수: content (문자열, 필수), source (문자열, 선택 사항), tags (문자열 목록, 선택 사항)
• ingest-markdown : 마크다운(.md) 파일을 수집하고 청크화합니다.
  • 인수: path (문자열)
• ingest-python : Python(.py) 파일을 수집하고 청크화합니다.
  • 인수: path (문자열)
• ingest-openapi : OpenAPI JSON 파일을 수집하고 청크화합니다.
  • 인수: path (문자열)
• ingest-html : HTML 파일을 수집하고 청크화합니다.
  • 인수: path (문자열)
• ingest-html-url : URL에서 HTML 콘텐츠를 수집하고 청크화합니다(동적 콘텐츠의 경우 Playwright를 선택적으로 사용).
  • 인수: url (문자열), dynamic (부울, 선택 사항)
• smart_ingestion : Gemini를 사용하여 파일에서 기술적으로 관련된 모든 콘텐츠를 추출한 다음 강력한 마크다운 논리를 사용하여 이를 덩어리로 나눕니다.
  • 인수:
    • path (문자열, 필수): 수집할 파일 경로입니다.
    • prompt (문자열, 선택 사항): Gemini에 사용할 사용자 정의 프롬프트입니다.
    • tags (문자열 목록, 선택 사항): 분류를 위한 태그의 선택 사항 목록입니다.
  • Gemini 2.0 Flash 001을 사용하여 코드, 구성, 마크다운 구조, 기술적 정의만 추출합니다(요약이나 해설은 제외).
  • 추출된 콘텐츠를 Mistune 3.x 기반 청커로 전달하여 코드 블록과 마크다운/내러티브 콘텐츠를 별도의 청크로 보존합니다.
  • 각 청크는 의미 검색 및 회수를 위해 내장되어 저장됩니다.
• 검색 청크 : 수집된 콘텐츠에 대한 의미 검색
  • 인수:
    • query (문자열): 의미 검색 쿼리입니다.
    • top_k (정수, 선택 사항, 기본값 3): 반환할 상위 결과 수입니다.
    • type (문자열, 선택 사항): 청크 유형(예: code , html , markdown )별로 결과를 필터링합니다.
    • tag (문자열, 선택 사항): 청크 메타데이터의 태그로 결과를 필터링합니다.
  • 주어진 쿼리에 가장 관련성이 높은 청크를 반환하며, 선택적으로 유형 및/또는 태그로 필터링할 수 있습니다.
• delete-source : 주어진 소스에서 모든 청크를 삭제합니다.
  • 인수: source (문자열)
• delete-chunk-by-id : id로 하나 이상의 청크를 삭제합니다.
  • 인수: id (정수, 선택 사항), ids (정수 목록, 선택 사항)
  • id 지정하여 단일 청크를 삭제할 수 있으며, ids 지정하여 여러 청크를 한 번에 삭제할 수 있습니다.
• update-chunk-type : id로 청크의 유형 속성을 업데이트합니다.
  • 인수: id (정수, 필수), type (문자열, 필수)
• ingest-batch : 여러 문서 파일(마크다운, OpenAPI JSON, Python)을 일괄적으로 수집하고 청크화합니다.
  • 인수: paths (문자열 목록)
• list-sources : 태그나 의미 검색을 통한 선택적 필터링을 통해 메모리에 수집되어 저장된 모든 고유 소스(파일 경로)를 나열합니다.
  • 인수:
    • tag (문자열, 선택 사항): 청크 메타데이터의 태그로 소스를 필터링합니다.
    • query (문자열, 선택 사항): 관련 소스를 찾기 위한 의미적 검색 쿼리입니다.
    • top_k (정수, 선택 사항, 기본값 10): 쿼리를 사용할 때 반환할 상위 소스 수입니다.
• get-context : 태그, 유형, 의미적 유사성으로 필터링하여 AI 컨텍스트로 사용할 관련 콘텐츠 청크(콘텐츠만)를 검색합니다.
  • 인수:
    • query (문자열, 선택 사항): 의미 검색 쿼리입니다.
    • tag (문자열, 선택 사항): 청크 메타데이터의 특정 태그로 결과를 필터링합니다.
    • type (문자열, 선택 사항): 청크 유형(예: '코드', '마크다운')별로 결과를 필터링합니다.
    • top_k (정수, 선택 사항, 기본값 5): 검색할 상위 관련 청크의 수입니다.
• update-chunk-metadata : ID로 청크의 메타데이터 필드를 업데이트합니다.
  • 인수: id (정수), metadata (객체)
• tag-chunks-by-source : 지정된 소스(URL 또는 파일 경로)와 연관된 모든 청크의 메타데이터에 지정된 태그를 추가합니다. 기존 태그와 병합합니다.
  • 인수: source (문자열), tags (문자열 목록)
• list-notes : 현재 저장된 모든 노트와 그 내용을 나열합니다.

청킹 및 코드 추출

• Markdown, Python, OpenAPI 및 HTML 파일은 효율적인 검색을 위해 논리적인 청크로 분할됩니다.
• 마크다운 청커는 Mistune 3.x의 AST API와 정규식을 사용하여 모든 원본 형식을 보존하면서 코드 블록과 내러티브별로 콘텐츠를 견고하게 분리합니다.
• 코드 블록과 마크다운/내러티브 콘텐츠는 모두 별도의 청크로 보존됩니다.
• HTML 청커는 readability-lxml 라이브러리를 사용하여 주요 콘텐츠를 먼저 추출한 다음, <pre> 태그에서 블록 코드 조각을 전용 "코드" 청크로 추출합니다. 인라인 <code> 콘텐츠는 내러티브 청크의 일부로 유지됩니다.

의미 검색

• search-chunks 도구는 수집된 모든 콘텐츠에 대해 벡터 기반 의미 검색을 수행하여 주어진 쿼리에 가장 관련성이 높은 청크를 반환합니다.
• 의미 순위를 매기기 전에 청크 유형(예: code , html , markdown ) 및/또는 청크 메타데이터의 태그별로 결과를 필터링하기 위한 선택적 type 및 tag 인수를 지원합니다.
• 이를 통해 '비용 및 사용량'과 관련된 'langfuse' 태그가 지정된 모든 코드 청크'와 같이 매우 구체적인 검색이 가능합니다.

메타데이터 관리

• 청크에는 분류 및 태그 지정을 위한 metadata 필드가 포함되어 있습니다.
• update-chunk-metadata 도구를 사용하면 ID를 사용하여 모든 청크의 메타데이터를 업데이트할 수 있습니다.
• tag-chunks-by-source 도구를 사용하면 특정 소스의 모든 청크에 한 번의 작업으로 태그를 추가할 수 있습니다. 태그 지정을 통해 새 태그를 기존 태그와 병합하고 이전 태그는 그대로 유지합니다.

구성

[TODO: 구현에 맞는 구성 세부 정보 추가]

빠른 시작

설치하다

클로드 데스크탑

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

개발

건축 및 출판

배포를 위해 패키지를 준비하려면:

1. 종속성 동기화 및 잠금 파일 업데이트:

지엑스피1

2. 패키지 배포 빌드:

이렇게 하면 dist/ 디렉토리에 소스와 휠 배포판이 생성됩니다.

3. PyPI에 게시:

참고: 환경 변수나 명령 플래그를 통해 PyPI 자격 증명을 설정해야 합니다.

• 토큰: --token 또는 UV_PUBLISH_TOKEN
• 또는 사용자 이름/비밀번호: --username / UV_PUBLISH_USERNAME 및 --password / UV_PUBLISH_PASSWORD

디버깅

MCP 서버는 stdio를 통해 실행되므로 디버깅이 어려울 수 있습니다. 최상의 디버깅 환경을 위해서는 MCP Inspector 사용을 강력히 권장합니다.

다음 명령을 사용하여 npm 통해 MCP Inspector를 시작할 수 있습니다.

Inspector를 실행하면 브라우저에서 접근하여 디버깅을 시작할 수 있는 URL이 표시됩니다.