QMD MCP

QMD MCP는 QMD를 장기 실행형 Streamable HTTP MCP 서버로 패키징합니다. 임의의 셸 실행을 노출하지 않으면서 QMD 검색 및 문서 검색 기능과 함께 범위가 제한된 인덱스 유지 관리 작업을 제공합니다.

이 프로젝트는 커뮤니티가 유지 관리하는 통합 프로젝트입니다. 업스트림 QMD 프로젝트와 제휴, 보증 또는 공식 유지 관리 관계가 없습니다.

피드백 및 기여

버그 신고와 기능 요청은 GitHub Issues를, 제안된 변경 사항은 풀 리퀘스트를 사용하세요. 개발 워크플로, 테스트 요구 사항 및 코딩 규칙은 CONTRIBUTING.md를 참조하세요. 보안 문제는 SECURITY.md의 비공개 프로세스를 따라야 합니다.

릴리스 변경 사항은 CHANGELOG.md에 기록됩니다.

Related MCP server: Web Search MCP Remote Server

빠른 시작

공개 Docker 이미지는 GitHub Container Registry(GHCR)에 게시됩니다:

ghcr.io/x1pher/qmd-mcp:v0.1.3

패키지는 공개되어 있으므로 Docker는 이미지를 가져오는 데 GitHub 로그인이 필요하지 않습니다.

프로덕션 배포의 경우 버전 태그에만 의존하지 말고 해당 GitHub Release에 게시된 불변 다이제스트를 사용하세요.

이미지는 현재 linux/amd64를 지원합니다. 이미지 크기를 제한하기 위해 QMD linux-x64 네이티브 llama 런타임만 의도적으로 유지합니다.

1. 디렉터리 생성

mkdir -p qmd/config qmd/content
cd qmd

QMD가 인덱싱할 Markdown 파일을 content/에 넣으세요.

2. config/index.yml 생성

global_context: >-
  This is a local Markdown knowledge base. Search results are discovery evidence;
  read the source document before relying on a material claim.

collections:
  notes:
    path: /vault
    pattern: "**/*.md"
    ignore:
      - "archive/**"

  archive:
    path: /vault/archive
    pattern: "**/*.md"
    includeByDefault: false

  append-only-log:
    path: /vault/logs
    pattern: "history.md"
    includeByDefault: false
    embedding: false

path 값은 컨테이너 내부의 경로를 나타냅니다. 아래 Compose 예제는 ./content를 /vault에 마운트합니다.

embedding: false는 어휘 전용(lexical-only)으로 유지해야 하는 컬렉션을 위한 QMD MCP 래퍼 확장 기능입니다. 파일은 여전히 인덱싱되어 명시적 어휘(lex) 검색에 사용할 수 있지만, 임베딩 상태 확인, 예약된 임베딩 및 수동 start_embed 작업에서 제외됩니다. 의미론적 검색에 유용한 재현이 없이 벡터 재구축 비용만 추가되는 대용량 추가 전용 로그나 기타 정확한 조회 자료에 사용하세요.

3. compose.yml 생성

services:
  qmd-mcp:
    image: ghcr.io/x1pher/qmd-mcp:v0.1.3
    container_name: qmd-mcp
    environment:
      QMD_FORCE_CPU: "1"
      QMD_REFRESH_INTERVAL_MINUTES: "15"
      QMD_REFRESH_INITIAL_DELAY_SECONDS: "120"
    ports:
      - "127.0.0.1:8181:8181"
    volumes:
      - ./content:/vault:ro
      - ./config:/config:ro
      - qmd-data:/data
    healthcheck:
      test:
        - CMD
        - node
        - -e
        - >-
          fetch('http://127.0.0.1:8181/health')
          .then(r=>process.exit(r.ok?0:1))
          .catch(()=>process.exit(1))
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s
    restart: unless-stopped

volumes:
  qmd-data:

예제는 HTTP 포트를 루프백에만 바인딩합니다. 다른 컨테이너가 QMD MCP를 직접 호출해야 하는 경우 두 컨테이너를 공유 Docker 네트워크에 연결하고 호스트에 광범위하게 노출하는 대신 QMD 서비스 이름을 사용하세요.

QMD_FORCE_CPU=1은 예측 가능한 CPU 전용 배포를 제공합니다. 지원되는 가속을 QMD가 탐색하도록 의도적으로 허용하려면 이 값을 제거하거나 0으로 설정하세요.

4. 컨테이너 시작

docker compose up -d

서비스 확인:

curl --fail http://127.0.0.1:8181/health

Streamable HTTP MCP 엔드포인트는 다음과 같습니다:

http://127.0.0.1:8181/mcp

Docker CLI 대안

Compose 없이 동일한 릴리스를 실행할 수 있습니다:

docker volume create qmd-data

docker run -d \
  --name qmd-mcp \
  --restart unless-stopped \
  -p 127.0.0.1:8181:8181 \
  -e QMD_FORCE_CPU=1 \
  -e QMD_REFRESH_INTERVAL_MINUTES=15 \
  -e QMD_REFRESH_INITIAL_DELAY_SECONDS=120 \
  -v "$PWD/content:/vault:ro" \
  -v "$PWD/config:/config:ro" \
  -v qmd-data:/data \
  ghcr.io/x1pher/qmd-mcp:v0.1.3

QMD MCP가 제공하는 기능

QMD MCP는 QMD의 읽기 중심 MCP 도구를 유지하면서 범위가 제한된 관리 작업을 추가합니다:

• health는 인덱스 및 런타임 상태를 보고합니다;

• start_update는 범위가 제한된 비동기 파일시스템 재인덱싱 작업을 시작합니다;

• start_embed는 범위가 제한된 비동기 임베딩 작업을 시작합니다;

• job_status는 최근 관리 작업을 보고합니다;

• 예약된 새로고침 및 임베딩은 자동으로 실행될 수 있으며 embedding: false 컬렉션은 어휘 전용으로 유지됩니다;

• 일반 query는 재순위화(reranking)가 비활성화된 상태로 실행됩니다;

• query_reranked는 CPU 집약적인 별도의 재순위화 경로를 제공합니다;

• QMD_SOURCE_RELATIVE_ROOT가 구성되고 소스 경로가 모호하지 않게 확인될 때 쿼리 결과에는 권위 있는 파일시스템 핸드오프를 위한 정확한 source_relative_path가 포함될 수 있습니다;

• 문서 검색은 기본적으로 내부 텍스트를 반환하며, 명시적 옵트인 MCP 리소스 노출이 제공됩니다.

한 번에 하나의 관리 작업만 실행됩니다. 완료된 작업은 범위가 제한된 기록으로 메모리에 보관됩니다. 액세스 수준과 부작용을 포함한 전체 9개 도구 참조는 docs/tools.md를 참조하세요.

런타임 경로

컨테이너는 다음과 같은 안정적인 경로를 사용합니다:

소스 컬렉션은 일반적으로 읽기 전용으로 마운트해야 합니다. /data는 재구축 가능한 인덱스와 모델/런타임 캐시를 포함하므로 쓰기 가능 상태를 유지해야 합니다.

구성

Dockerfile은 일반적인 런타임 경로와 HTTP 리스너에 대한 작동 기본값을 제공합니다. 배포에 필요한 설정만 재정의하세요.

잘못된 범위 제한 숫자 값은 자동으로 수용되지 않고 시작 시 실패합니다. QMD_SOURCE_RELATIVE_ROOT는 절대 경로를 절대 노출하지 않습니다. 상대 소스 경로만 반환되며, 모호한 정규화 경로 충돌은 추측 대신 null을 반환합니다.

보안 모델

• 컨테이너는 업스트림 Node 이미지의 권한이 없는 node 사용자로 실행됩니다.

• 소스 컬렉션은 일반적으로 읽기 전용으로 마운트해야 합니다.

• 인덱스 및 캐시 상태는 소스 콘텐츠와 분리되어 유지됩니다.

• 관리는 노출된 작업 작업으로 제한됩니다. 래퍼는 QMD 저장소 API를 직접 호출하며 QMD CLI 업데이트 훅을 호출하거나 임의의 셸 실행을 노출하지 않습니다.

• MCP 요청 본문은 JSON 파싱 전에 1 MiB로 제한됩니다.

• 오류 메시지는 구성된 인덱스 및 구성 경로를 삭제합니다.

• MCP 전송은 인증 계층이 아닙니다. 신뢰할 수 있는 네트워크 경계에 유지하거나 인증된 MCP 게이트웨이 뒤에 배치하세요.

• 프로덕션 배포는 브랜치, latest 또는 기타 이동 태그 대신 불변 릴리스 이미지 다이제스트를 사용해야 합니다.

취약점 보고 및 배포 지침은 SECURITY.md를, 프로젝트에 적용되는 보안 설계 원칙, 일반적인 취약점 클래스 및 검토 기대 사항은 docs/SECURE-DEVELOPMENT.md를 참조하세요.

업스트림 관계

이 저장소는 전체 QMD 소스 트리의 포크가 아닙니다. 정확한 @tobilu/qmd 패키지 버전을 사용하며 이미지 빌드 중에 작은 fail-closed 호환성 패치 세트를 적용합니다. 예상된 업스트림 패치 대상이 더 이상 정확히 일치하지 않으면 빌드가 실패합니다.

현재 업스트림 버전, 패치 목록 및 업데이트 프로세스는 UPSTREAM.md를 참조하세요.

검증

컨테이너 빌드가 기본 검증 경계입니다. 잠긴 종속성 세트를 설치하고, 모든 업스트림 패치를 적용하고, 전체 단위/속성 테스트 스위트를 실행하고, JavaScript 구문 검사를 수행하고, 런타임 단계 전에 개발 전용 종속성을 제거합니다. CI는 또한 이미지를 시작하고, MCP 프로토콜을 초기화하고, 정확한 9개 도구 표면을 검증하고, 임시 Markdown 컬렉션에 대해 실제 인덱스 업데이트를 실행하고, 결과 문서 수를 확인합니다.

종속성 및 기본 이미지 업데이트는 Dependabot이 제안합니다. QMD 업데이트는 제안된 버전에 대해 이미지 빌드 및 기능 릴리스 수용 테스트가 통과된 후에만 수락됩니다.

릴리스

버전은 v0.1.3과 같은 SemVer 태그를 사용합니다. 릴리스는 정확한 CI 통과 커밋을 가리켜야 합니다. 태그 트리거 Release 워크플로는:

1. 태그가 package.json과 일치하는지 확인합니다;

2. linux/amd64 이미지를 빌드합니다;

3. GHCR에 게시합니다;

4. 불변 이미지 다이제스트를 기록합니다;

5. SBOM/증명(provenance) 및 GitHub 증명(attestation)을 게시합니다;

6. 해당 GitHub Release를 생성합니다.

일반 CI는 이미지나 릴리스를 게시하지 않습니다. 릴리스 태그는 불변이며 다른 커밋에 재사용되지 않습니다.

라이선스

QMD MCP의 원본 래퍼 코드는 MIT 라이선스입니다. QMD 및 번들된 종속성은 자체 라이선스를 유지합니다. LICENSE 및 UPSTREAM.md를 참조하세요.