QMD MCP

QMD MCP は、QMD を長時間実行される Streamable HTTP MCP サーバーとしてパッケージ化します。QMD の検索とドキュメント取得に加えて、制限付きのインデックス保守操作を提供し、任意のシェル実行を公開しません。

これはコミュニティ保守の統合です。アップストリームの QMD プロジェクトとは提携しておらず、承認もされておらず、公式に保守もされていません。

フィードバックと貢献

バグ報告や機能リクエストには GitHub Issues を、提案された変更にはプルリクエストを使用してください。開発ワークフロー、テスト要件、コーディング規約については CONTRIBUTING.md を参照してください。セキュリティ問題は SECURITY.md の非公開プロセスに従う必要があります。

リリースの変更は CHANGELOG.md に記録されます。

Related MCP server: Keenable MCP

クイックスタート

公開 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 は、レキシカル専用のままにすべきコレクション向けの 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 は再ランキングを無効にして実行されます;

• query_reranked は別の CPU 負荷の高い再ランキングパスを提供します;

• クエリ結果には、QMD_SOURCE_RELATIVE_ROOT が設定され、ソースパスが一意に解決される場合、信頼できるファイルシステムハンドオフのための正確な source_relative_path を含めることができます;

• ドキュメント取得はデフォルトで内部テキストを返し、明示的なオプトインの MCP リソース公開を提供します。

一度に実行される管理ジョブは 1 つだけです。完了したジョブはメモリ内に制限付きの履歴として保持されます。完全な 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 パッケージバージョンを消費し、イメージビルド中に小さなフェイルクローズ互換性パッチセットを適用します。期待されるアップストリームパッチターゲットが正確に一致しなくなった場合、ビルドは失敗します。

現在のアップストリームバージョン、パッチインベントリ、更新プロセスについては UPSTREAM.md を参照してください。

検証

コンテナビルドが主要な検証境界です。ロックされた依存関係セットをインストールし、すべてのアップストリームパッチを適用し、完全なユニット/プロパティテストスイートを実行し、JavaScript 構文チェックを実行し、ランタイムステージの前に開発専用依存関係を削除します。CI はまた、イメージを起動し、MCP プロトコルを初期化し、正確な 9 ツールのサーフェスを検証し、一時的な Markdown コレクションに対して実際のインデックス更新を実行し、結果のドキュメント数を検証します。

依存関係とベースイメージの更新は Dependabot によって提案されます。QMD の更新は、提案されたバージョンに対してイメージビルドと機能リリース受け入れが合格した後にのみ受け入れられます。

リリース

バージョンは v0.1.3 などの SemVer タグを使用します。リリースは正確な CI グリーンコミットを指す必要があります。タグトリガーのリリースワークフロー:

1. タグが package.json と一致することを検証します;

2. linux/amd64 イメージをビルドします;

3. GHCR に公開します;

4. 不変のイメージダイジェストを記録します;

5. SBOM/来歴と GitHub アテステーションを公開します;

6. 対応する GitHub Release を作成します。

通常の CI はイメージやリリースを公開しません。リリースタグは不変であり、異なるコミットに再利用されることはありません。

ライセンス

QMD MCP のオリジナルラッパーコードは MIT ライセンスです。QMD およびバンドルされた依存関係はそれぞれのライセンスを保持します。LICENSE と UPSTREAM.md を参照してください。