vector-mcp

ガバナンスされたベクトルコレクション管理と検索のための、Action-routed MCP およびエージェントインターフェースです。 ネイティブのデフォルトは epistemic-graph です。セキュアなオプトインプロバイダーは、PostgreSQL/pgvector、 Qdrant、MongoDB Atlas をカバーしています。

バージョン: 3.1.0

ガバナンス機能

• MCP ツール: vector_collection_management と vector_search

• スキルプロバイダー: 統合された vector-mcp-operations ワークフロー

• オントロジープロバイダー: パッケージ化されたベクトル検索オントロジー

• ソースコネクタプロバイダー: 読み取り専用のベクトルコレクションインベントリプリセット

• ランタイム構成: AgentConfig、環境変数、およびシークレット参照

• プライバシーポスチャ: チェックイン済みのエンドポイント、認証情報、個人情報、ホストパスは一切含まれません

Related MCP server: production-grade-mcp-agentic-system

インストール

デプロイに必要な最小限の extra セットを使用してください:

uvx --from 'vector-mcp[mcp]' vector-mcp

ランタイムには、agent-utilities>=2.0.0 と、その自己完結型の完全な epistemic-graph エンジン契約が必要です。数値のみ、または部分的なエンジンプロファイルだけでは、 サポート対象のデプロイメントにはなりません。

選択したストレージプロバイダーを使用する場合:

uv add 'vector-mcp[postgres]'
uv add 'vector-mcp[qdrant]'
uv add 'vector-mcp[mongodb]'

all extra は、サポートされているすべてのオプションプロバイダーに加えて、エージェント、Langfuse、Logfire ランタイムを有効にします。本番イメージには、実際に運用するプロバイダーのみをインストールしてください。

MCP 構成

このパッケージには、コマンド、condensed ツールモード、ツールトグルのみを含む、中立的な エージェント起動構成が含まれています。ランタイム値は AgentConfig から継承されるか、 運用者によって注入されます。基盤となる API ラッパー、拡張スキーマバインディング、 開発者向け SDK リファレンスの使用方法の詳細は、docs/index.md に記載されています。

MCP

このサーバーは、動的な Action-Routed ツールを利用して、トークンのオーバーヘッドを最適化し、IDE との互換性を最大化します。

利用可能な MCP ツール

ライブ MCP サーバーから自動生成されています — 手動で編集しないでください。

Condensed action-routed ツール (MCP_TOOL_MODE=condensed)

action-routed ツール 2 件 · verbose 1:1 ツール 0 件。各ツールは、対応する <DOMAIN>TOOL トグルが false に設定されていない限り有効です。MCP_TOOL_MODE はサーフェスを選択します(**intent がデフォルト* — 6 つの動詞ツールからなる、オンデマンドで読み込まれる詳細セット · condensed action-routed · verbose 1:1 · both)。自動生成 — 手動で編集しないでください。*

詳細なツールスキーマ、パラメータ形状、検証制約は、使用ガイド に記載されています。

動的なツールの選択と可視性

この MCP サーバーは、実行時に動的なツールセットの選択と可視性フィルタリングをサポートしています。これにより、公開するツールのセットを制限して、LLM のコンテキストウィンドウが肥大化するのを防ぐことができます。

ツールのフィルタリングは、複数の入力チャネルで構成できます:

• CLI 引数: 起動時に --tools または --toolsets(または、無効化用の対応引数である --disabled-tools と --disabled-toolsets)を渡します。

• 環境変数: 標準の環境変数を定義します:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• HTTP SSE リクエストヘッダー: トランスポート初期化時にカスタムヘッダーを渡します:

  • x-mcp-enabled-tools / x-mcp-disabled-tools

  • x-mcp-enabled-tags / x-mcp-disabled-tags

• HTTP SSE リクエストクエリパラメータ: トランスポート接続 URL にクエリパラメータを直接追加します:

  • ?tools=tool1,tool2

  • ?tags=tag1

クエリ文字列またはパラメータが指定されると、LLM を使用しない ナレッジグラフ解決レイヤー(DynamicToolOrchestrator を使用)が、クエリの意図を既知のツールタグ、名前、または説明と照合し、安全なフォールバックと 24 時間ごとの自動バックグラウンドキャッシュ更新を行います。

MCP 構成例

コネクタ特化の [mcp] extra をインストールしてください。 例では vector-mcp[mcp] を使用して、 agent-utilities[mcp] 経由で FastMCP / FastAPI を追加しています。必要な Agent Utilities コアには、 引き続き epistemic-graph[full] が含まれます。[agent-runtime] extra は、さらに モデルオーケストレーションを有効にします。

stdio トランスポート(ローカル IDE — Cursor、Claude Desktop、VS Code)

{
  "mcpServers": {
    "vector-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "vector-mcp[mcp]",
        "vector-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "COLLECTION_MANAGEMENTTOOL": "True",
        "DATABASE_TYPE": "epistemic_graph",
        "LLM_SSL_VERIFY": "False",
        "SEARCHTOOL": "True",
        "VECTOR_DB_TYPE": "epistemic_graph"
      }
    }
  }
}

ランタイム参照には、GraphOS のようなエイリアス対応ランチャーが必要です。その他の ランチャーは、これらのエントリを省略し、解決済みの値を独自の ランタイムシークレット境界を通じて注入する必要があります。

Streamable-HTTP トランスポート(ネットワーク / 本番)

{
  "mcpServers": {
    "vector-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "vector-mcp[mcp]",
        "vector-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "COLLECTION_MANAGEMENTTOOL": "True",
        "DATABASE_TYPE": "epistemic_graph",
        "LLM_SSL_VERIFY": "False",
        "SEARCHTOOL": "True",
        "VECTOR_DB_TYPE": "epistemic_graph"
      }
    }
  }
}

または、事前にデプロイされた Streamable-HTTP インスタンスに url で接続します:

{
  "mcpServers": {
    "vector-mcp": {
      "url": "http://localhost:8000/vector-mcp/mcp"
    }
  }
}

レビュー済みのコンテナイメージを、最小権限の stdio 子プロセスとして実行します (リスナーや公開ポートなし):

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e COLLECTION_MANAGEMENTTOOL=True \
  -e DATABASE_TYPE=epistemic_graph \
  -e LLM_SSL_VERIFY=False \
  -e SEARCHTOOL=True \
  -e VECTOR_DB_TYPE=epistemic_graph \
  registry.example.invalid/vector-mcp@sha256:<digest> vector-mcp

コンテナ化されたネットワーク HTTP の場合は、認証付き TLS イングレス(または サーバー直接の TLS)、正確な MCP_ALLOWED_HOSTS、正確な信頼済みプロキシ CIDR ポリシーを運用者管理のデプロイメントプロファイルを通じて指定してください。 ジェネレーターは、認証されていない非ループバックリスナーを生成しません。

コードから読み取った環境変数サーフェス(MCP_TOOL_MODE + パッケージ変数)から自動生成 — 手動で編集しないでください。

追加のデプロイメントオプション

vector-mcp は、ローカルコンテナ(Docker / Podman / uv)として実行することも、 リモートデプロイメントから利用することもできます。 デプロイメントガイドには、4 つすべてのトランスポート — stdio、 streamable-http、ローカルコンテナ / uv、リモート URL — に対応する、コピー＆ペースト可能な完全な mcp_config.json が含まれています:

• ローカルコンテナ / uv — uvx、docker run、または podman run を使用して mcp_config.json からサーバーを起動するか、 url でローカルの streamable-http コンテナを指定します。

• リモート URL — "url" キーを使用して、Caddy の背後にデプロイされたサーバー(https://vector-mcp.example.invalid/mcp)に接続します。

環境変数

パッケージ環境変数

継承された agent-utilities 変数（すべてのコネクタに適用）

31 パッケージ + 20 継承変数。.env.example + 共有 agent-utilities セットから自動生成 — 編集しないでください。

サーバーが読み取るすべての変数を目的別にまとめています。正式なコピー＆ペースト用リストは .env.example を参照してください。ネイティブの epistemic-graph バックエンド用の DATABASE_TYPE / GRAPH_SERVICE_SOCKET / GRAPH_SERVICE_AUTH_SECRET 接続設定も含まれます。オプトインプロバイダー（Postgres/Qdrant/Mongo/Chroma/Couchbase）のバックエンドエンドポイント、データベースの場所、および資格情報は、README に文書化されたリテラル値や MCP ツール引数になることはありません。これらは実行時に AgentConfig と secret:///env:///vault:// 参照を通じて解決されます。

MCP サーバー / トランスポート

ツールの切り替え

各アクションルーティングツールは、対応するトグル環境変数（false に設定）で個別に無効化できます。完全なリストは上記の 利用可能な MCP ツール テーブルにあります。

テレメトリとガバナンス

Agent CLI（完全な [agent] ランタイムのみ）

コピー＆ペースト用の出発点として .env.example を参照してください。

プロバイダーとオントロジーの統合

このパッケージは、スキル、プロンプト、オントロジー、およびソースコネクタを Python エントリポイント経由で提供します。コレクションインベントリコネクタは意図的に読み取り専用であり、ドキュメントや埋め込みペイロードではなく、コレクションメタデータを登録します。

生成されたコネクタ署名は、インストール済みの MCP スキーマを確認し、ランタイムでリリース署名キーが提供された後にのみ再作成する必要があります。古いツールスキーマまたはオントロジーからの署名を前方にコピーしてはなりません。

開発チェック

プロバイダーを起動しない低コストのチェック:

python scripts/security_sanitizer.py
python scripts/security_contract.py --contract .security/security-contract.json validate
python -m compileall -q vector_mcp

プロバイダーテストはモック化された SDK 境界を使用し、ネットワーク呼び出しを行いません。ライブ認定は別のデプロイメントゲートであり、オペレーターが提供する AgentConfig とシークレットを使用する必要があります。

ドキュメント

• インストール

• 設定とプライバシー

• デプロイ

• 使用法

• アーキテクチャ概要

スリムな :mcp streamable-http コンテナ（docker/mcp.compose.yml）は /health チェック付きで :8000 を公開します。完全な compose サービス定義は デプロイ を参照してください。

ライセンス

LICENSE を参照してください。

agent-utilities-deployment でデプロイ

このパッケージを統合された agent-utilities-deployment ワークフローでプロビジョニングします。このワークフローは、インストール済みパッケージ、編集可能ソース、またはイミュータブルコンテナのパスを選択し、AgentConfig にはランタイムシークレットと TLS プロファイルの参照のみを記録します。また、doctor、registration、policy、observability、rollback の各ゲートを実行します。エージェントに 「vector-mcp を agent-utilities-deployment でデプロイ」 と依頼してください。

このリポジトリには、デプロイプロファイル、資格情報の値、証明書パス、環境固有のエンドポイントは埋め込まれていません。これらは実行時に AgentConfig と設定済みのシークレットプロバイダーを通じて提供してください。

インストール

実行したいものに合った extra を選択してください:

# MCP server only (recommended for tool hosting — slim deps)
uv pip install "vector-mcp[mcp]"

# Full agent runtime (Pydantic AI + epistemic-graph engine)
uv pip install "vector-mcp[agent]"

# Everything (development)
uv pip install "vector-mcp[all]"      # or: python -m pip install "vector-mcp[all]"

コンテナイメージ（:mcp と :agent）

1 つのマルチステージ docker/Dockerfile が、--target で選択される 2 つの適切なサイズのイメージをビルドします:

docker build --target mcp   -t knucklessg1/vector-mcp:mcp    docker/   # slim MCP server
docker build --target agent -t knucklessg1/vector-mcp:latest docker/   # full agent

docker/mcp.compose.yml はスリムな :mcp サーバーを実行し、docker/agent.compose.yml は同じ場所に配置された :mcp サイドカーを伴うエージェント（:latest）を実行します。

ナレッジグラフデータベース（epistemic-graph）

フルエージェント（[agent] / :latest）は、epistemic-graph エンジンを埋め込みます（agent-utilities[agent] 経由で推移的に取り込まれます）。本番環境では — または複数のエージェント間で1つのナレッジグラフを共有するには — epistemic-graph を独立したデータベースコンテナとして実行し、埋め込む代わりにエージェントからそれを参照させてください。デプロイレシピ（シングルノード + Raft HA）、接続設定、データベース全体のアーキテクチャ（図解付き）は、epistemic-graph デプロイメントガイド に文書化されています。スリムな [mcp] サーバーはデータベースを必要としません。

リポジトリオーナー

コントリビュート

コントリビューションを歓迎します！プルリクエストを提出する前に、ローカルチェックを実行してコード品質を確保してください：

• ruff format . でコードをフォーマットします

• ruff check . でコードを lint します

• mypy . で型安全性を検証します

• pytest でテストスイートを実行します

agent-os-genesis でデプロイ

このパッケージは、スキルガイド付きで、agent-os-genesis ユニバーサルスキル（その シングルパッケージデプロイモード）によってプロビジョニングできます。インストール方法の選択、OpenBao/Vault（または .env）へのシークレットのシード、エンタープライズ CA の信頼設定、MCP サーバーの登録と検証を行います。これは Agent OS 全体を立ち上げるのと同じ仕組みを、このパッケージだけに絞ったものです。エージェントに 「vector-mcp を agent-os-genesis でデプロイ」 と依頼してください。

シークレットは既存のものが読み込まれ、vault_sync 経由でシードされます。不足しているものだけがプロンプトで求められます。