vector-mcp

Action-Routed-MCP- und Agent-Schnittstellen für eine kontrollierte Verwaltung und den Abruf von Vektor-Collections.
Die native Voreinstellung ist epistemic-graph. Sichere, optional aktivierbare Provider umfassen PostgreSQL/pgvector, Qdrant und MongoDB Atlas.

Version: 3.1.0

Verwaltete Fähigkeit

• MCP-Tools: vector_collection_management und vector_search

• Skill-Provider: der konsolidierte Workflow vector-mcp-operations

• Ontologie-Provider: die gebündelte Vektorabruf-Ontologie

• Quell-Connector-Provider: ein schreibgeschütztes Vektor-Collection-Inventar-Preset

• Laufzeitkonfiguration: AgentConfig, Umgebungsvariablen und Secret-Referenzen

• Datenschutz-Profil: keine eingecheckten Endpunkte, Anmeldedaten, persönlichen Identitäten oder Host-Pfade

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

Installation

Verwenden Sie die kleinste, für die Bereitstellung benötigte Extra-Menge:

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

Die Laufzeit erfordert agent-utilities>=2.0.0 und dessen in sich geschlossenen, vollständigen epistemic-graph-Engine-Vertrag. Ein reines, nur aus Zahlen bestehendes oder unvollständiges Engine-Profil ist keine unterstützte Bereitstellung.

Für einen ausgewählten Storage-Provider:

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

Das Extra all aktiviert jeden unterstützten optionalen Provider sowie die Agent-, Langfuse- und Logfire-Laufzeiten. Produktionsimages sollten nur die Provider installieren, die sie auch betreiben.

MCP-Konfiguration

Das Paket enthält eine neutrale Agent-Startkonfiguration, die nur den Befehl, den kondensierten Tool-Modus und die Tool-Umschaltungen enthält. Laufzeitwerte werden von AgentConfig geerbt oder vom Betreiber injiziert. Detaillierte Anweisungen zur Verwendung der zugrunde liegenden API-Wrapper, erweiterten Schemabindungen und Entwickler-SDK-Referenzen werden in docs/index.md gepflegt.

MCP

Dieser Server nutzt dynamische Action-Routed-Tools, um den Token-Overhead zu optimieren und die IDE-Kompatibilität zu maximieren.

Verfügbare MCP-Tools

Automatisch aus dem laufenden MCP-Server generiert — nicht manuell bearbeiten.

Kondensierte Action-Routed-Tools (MCP_TOOL_MODE=condensed)

2 Action-Routed-Tools · 0 Verbose-1:1-Tools. Jedes ist aktiviert, sofern sein <DOMAIN>TOOL-Toggle nicht auf false gesetzt ist; MCP_TOOL_MODE wählt die Oberfläche (**intent Standard* – die sechs Verb-Tools, granulare, bei Bedarf geladene Menge · condensed Action-Routed · verbose 1:1 · both). Automatisch generiert – nicht manuell bearbeiten.*

Detaillierte Tool-Schemas, Parameterformen und Validierungsbedingungen sind in der Benutzeranleitung erhalten.

Dynamische Tool-Auswahl und Sichtbarkeit

Dieser MCP-Server unterstützt dynamische Toolset-Auswahl und Sichtbarkeitsfilterung zur Laufzeit. Damit können Sie die bereitgestellte Auswahl an Tools einschränken, um die Sprengung des LLM-Kontextfensters zu vermeiden.

Sie können die Toolfilterung über mehrere Eingabekanäle konfigurieren:

• CLI-Argumente: Übergeben Sie beim Start --tools oder --toolsets (oder deren deaktivierte Gegenstücke --disabled-tools und --disabled-toolsets).

• Umgebungsvariablen: Definieren Sie Standard-Umgebungsvariablen:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• HTTP-SSE-Request-Header: Übergeben Sie während der Transportinitialisierung benutzerdefinierte Header:

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

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

• HTTP-SSE-Request-Abfrageparameter: Hängen Sie Abfrageparameter direkt an die Transport-URL an:

  • ?tools=tool1,tool2

  • ?tags=tag1

Wenn Abfragewerte oder -parameter angegeben werden, gleicht eine LLM-freie Knowledge-Graph-Auflösungsebene (unter Verwendung von DynamicToolOrchestrator) die Abfrageabsichten mit bekannten Tool-Tags, -Namen oder -Beschreibungen ab, mit sicherem Fallback und automatischer 24-Stunden-Hintergrund-Cache-Aktualisierung.

MCP-Konfigurationsbeispiele

Installieren Sie das auf Konnektoren ausgerichtete [mcp]-Extra. Beispiele verwenden vector-mcp[mcp], um FastMCP / FastAPI über agent-utilities[mcp] hinzuzufügen; Der erforderliche Agent-Utilities-Core bringt weiterhin epistemic-graph[full] mit. Das [agent-runtime]-Extra aktiviert zusätzlich die Modell-Orchestrierung.

stdio-Transport (lokale IDEs – 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"
      }
    }
  }
}

Laufzeit-Referenzen erfordern einen alias-bewussten Launcher wie GraphOS. Andere Launcher müssen diese Einträge weglassen und die aufgelösten Werte durch ihre eigene Laufzeit-Secret-Grenze injizieren.

Streamable-HTTP-Transport (Netzwerk / Produktion)

{
  "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"
      }
    }
  }
}

Alternativ können Sie sich über url mit einer bereits bereitgestellten Streamable-HTTP-Instanz verbinden:

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

Führen Sie ein geprüftes Container-Image als stdio-Kind mit minimalen Privilegien aus (ohne Listener oder veröffentlichten Port):

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

Für containerisiertes Netzwerk-HTTP stellen Sie einen authentifizierten TLS-Ingress (oder direktes Server-TLS), exakte MCP_ALLOWED_HOSTS und eine genaue Trusted-Proxy-CIDR-Richtlinie über das vom Betreiber verwaltete Bereitstellungsprofil bereit. Der Generator gibt keinen unauthentifizierten Non-Loopback-Listener aus.

Automatisch generiert aus der Code-Env-Oberfläche (MCP_TOOL_MODE + Paketvariablen) – nicht manuell bearbeiten.

Zusätzliche Bereitstellungsoptionen

vector-mcp kann auch als lokaler Container (Docker / Podman / uv) ausgeführt oder alsität Remote-Bereitstellung konsumiert werden. Der Bereitstellungsleitfaden enthält vollständige, copy-paste-fähige mcp_config.json für alle vier Transporte – stdio, streamable-http, lokaler Container / uv und Remote-URL:

• Lokaler Container / uv – starten Sie den Server über mcp_config.json via uvx, docker run oder podman run, oder zeigen Sie auf einen lokalen streamable-http-Container per url.

• Remote-URL – verbinden Sie sich mit einem Server hinter Caddie unter https://vector-mcp.example.invalid/mcp mit dem Schlüssel "url".

Umgebungsvariablen

Umgebungsvariablen des Pakets

Geerbte agent-utilities-Variablen (gelten für jeden Connector)

31 Paket- + 20 geerbte Variable(n). Automatisch generiert aus .env.example + dem gemeinsamen agent-utilities-Set — nicht bearbeiten.

Jede Variable, die der Server liest, nach Zweck gruppiert. Siehe .env.example für die kanonische, direkt kopierbare Liste — inklusive der Verbindungseinstellungen DATABASE_TYPE / GRAPH_SERVICE_SOCKET / GRAPH_SERVICE_AUTH_SECRET für das native epistemic-graph-Backend. Backend-Endpunkte, Datenbankspeicherorte und Zugangsdaten für optional aktivierbare Provider (Postgres/Qdrant/Mongo/Chroma/Couchbase) sind niemals in der README dokumentierte Literalwerte oder MCP-Tool-Argumente — sie werden zur Laufzeit über AgentConfig und secret:///env:///vault://-Referenzen aufgelöst.

MCP-Server / Transport

Tool-Umschalter

Jedes aktionsgeroutete Tool kann einzeln über seine Umschalt-Env-Variable deaktiviert werden (gesetzt auf false). Die vollständige Liste befindet sich in der Tabelle Available MCP Tools weiter oben.

Telemetrie & Governance

Agent-CLI (nur vollständige [agent]-Laufzeit)

Siehe .env.example für einen direkt kopierbaren Ausgangspunkt.

Provider- und Ontologie-Integration

Das Paket bringt seine Skills, Prompts, Ontologie und den Quell-Connector über Python-Einstiegspunkte ein. Der Collection-Inventory-Connector ist bewusst schreibgeschützt und registriert Collection-Metadaten, nicht Dokument- oder Embedding-Payloads.

Generierte Connector-Signaturen dürfen erst neu erstellt werden, nachdem das installierte MCP-Schema beobachtet wurde und ein Release-Signierschlüssel zur Laufzeit bereitgestellt ist. Eine Signatur aus einem älteren Tool-Schema oder einer älteren Ontologie darf niemals weitergetragen werden.

Entwicklungs-Checks

Kostengünstige Prüfungen, die keine Provider starten:

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

Provider-Tests verwenden gemockte SDK-Schnittstellen und führen keine Netzwerkaufrufe aus. Die Live-Qualifizierung ist ein separates Deployment-Gate und muss die vom Betreiber bereitgestellten AgentConfig und Secrets verwenden.

Dokumentation

• Installation

• Konfiguration und Datenschutz

• Bereitstellung

• Verwendung

• Architekturübersicht

Der schlanke :mcp-Container mit streamable-http (docker/mcp.compose.yml) veröffentlicht Port :8000 mit einem /health-Check; die vollständige Compose-Service-Definition finden Sie unter Bereitstellung.

Lizenz

Siehe LICENSE.

Bereitstellen mit agent-utilities-deployment

Stellen Sie dieses Paket mit dem konsolidierten agent-utilities-deployment-Workflow bereit. Der Workflow wählt unter installiertem Paket, bearbeitbarer Quelle oder unveränderlichem Container; zeichnet nur Laufzeit-Secret- und TLS-Profil-Referenzen in AgentConfig auf; und führt die Gates für Doctor, Registrierung.

Policy, Observability und Rollback aus. Bitten Sie Ihren Agenten, „vector-mcp mit agent-utilities-deployment bereitzustellen“.

Das Repository enthält kein Deployment-Profil, keinen Anmeldedatenwert, keinen Zertifikatspfad und keinen umgebungsspezifischen Endpunkt. Stellen Sie diese zur Laufzeit über AgentConfig und den konfigurierten Secret-Provider bereit.

Installation

Wählen Sie das Extra, das zu dem passt, was Sie ausführen möchten:

GXP8table

Container-Images (:mcp vs. :agent)

Ein mehrstufiges docker/Dockerfile erstellt zwei passend dimensionierte Images, ausgewählt über --target:

Hmm, I noticed a bug — in my draft, I wrote "container uses :8000" but the original "provides publishes :8000 with a /health check; see Installation for the full compose Service definition." I used "Port :8000" but original says "publishes :8000" - the content seems to be the port number "8000" with a colon? The original has backticks around :8000 (colon + port), likely a mistaken markdown but preserve as code. In my output I should preserve :8000. I wrote Port :8000`` — okay.

Wait, let's review original: "The slim :mcp streamable-http container (docker/mcp.compose.yml) publishes :8000 with a /health check". Indeed :8000 is the port written with colon inside code ticks. Keep. So "veröffentlicht :8000 mit einem /health-Check" - fine.

In my draft, I typed accidentally "Port : :8000"? Avoid. Use exactly :8000.

Also in the deployment section, "register with the operator-provided service" we need "Verfügbar" etc.

Now with the "hentai" line "Ein mehrstufiges docker/Dockerfile erstellt ..." — should be "Einmehrstufiges Dockerfile" but "docker/Dockerfile" is a path. We could say "Das mehrstufige docker/Dockerfile erstellt ...". The original: "One multi-stage docker/Dockerfile builds ..." – since docker/Dockerfile is file path. We keep as tech.

Also for "Install modes" first column "Installationsmodus" but original "Install mode". Good.

Now some other thing: I appended "GXP8table" a typo. I'll fix.

Also in the Deployment table I wrote "registry-example.invalid" instead of correct "registry.example.invalid". Need to keep exactly.

Also in "Full agent CLI" heading — agent.

Now, double-check the line "Das Repository enthält kein Deployment-Profile, keine Anmeldeniedwerte, keinen Zertifikatspfad und keinen umgebungsspezifischen Endpunkt." I need to preserve "environment-specific endpoint" singular. Use "keinen umgebungsspezifischen Endpunkt".

Now final polish.

Let me rewrite the entire souped-up text cleanly:

Geerbte agent-utilities-Variablen (gelten für jeden Connector)

31 Paket- + 20 geerbte Variable(n). Automatisch generiert aus .env.example + dem gemeinsamen agent-utilities-Set — nicht bearbeiten.

Jede Variable, die der Server liest, gruppiert nach Zweck. Siehe .env.example für die kanonische, direkt kopierbare Liste — einschließlich der Verbindungseinstellungen DATABASE_TYPE / GRAPH_SERVICE_SOCKET / GRAPH_SERVICE_AUTH_SECRET für das native epistemic-graph-Backend. Backend-Endpunkte, Datenbankspeicherorte und Zugangsdaten für opt-in fähige Provider (Postgres/Qdrant/Mongo/Chroma/Couchbase) sind niemals README-dokumentierte Literalwerte oder MCP-Tool-Argumente — sie werden zur Laufzeit über AgentConfig und secret:///env:///vault://-Referenzen aufgelöst.

MCP server / transport

→ "### MCP-Server / Transport"

...

Blah.

Actually, I want to double-check translations for "source connector": original "source connector" probably "source (data source) connector". I wrote "Quell-Connector". It's acceptable.

"Generated connector signatures must be recreated only after the installed MCP schema is observed and a release signing key is available at runtime." — perhaps reads "beobachtet wird und ein Release-Signaturschlüssel zur Laufzeit zur Verfügung steht." I will use "beobachtet". Better perhaps "überprüft" but the original "observed" -> "beobachtet". Use "beobachtet".

"A signature from an older tool schema or ontology must never be copied forward." — "Eine Signatur aus einem älteren Tool-Schema oder einer älteren Ontologie darf niemals in neue Versionen übernommen werden." Better. Or "weiterverwendet". I'll use "übernommen".

"Development checks" — "## Entwicklungsprüfungen". I previously considered "Entwicklungs-Checks". Both okay. Since "checks" might be dynamic. I'll go with "Entwicklungs-Checks" honestly.

One more: The low-cost paragraph: "Low-cost checks that do not launch providers:. Translate: "Kostengünstige Checks, die keine Provider starten:" Good.

Now final output as prepared.

I'll ensure no "AgentConfig" incorrectly assuming. Keep.

Let's produce the#### Geerbte agent-utilities-Variablen (gelten für jeden Connector)

31 Paket- + 20 geerbte Variable(n). Automatisch generiert aus .env.example + dem gemeinsamen agent-utilities-Satz — nicht bearbeiten.

Jede Variable, die der Server liest, nach Zweck gruppiert. Siehe .env.example für die kanonische, direkt kopierbare Liste — einschließlich der Verbindungseinstellungen DATABASE_TYPE / GRAPH_SERVICE_SOCKET / GRAPH_SERVICE_AUTH_SECRET für das native epistemic-graph-Backend. Backend-Endpunkte, Datenbankspeicherorte und Zugangsdaten für optional aktivierbare Provider (Postgres/Qdrant/Mongo/Chroma/Couchbase) sind niemals in der README dokumentierte Literalwerte oder MCP-Tool-Argumente — sie werden zur Laufzeit über AgentConfig und secret:///env:///vault://-Referenzen aufgelöst.

MCP-Server / Transport

Tool-Umschalter

Jedes aktionsgeroutete Tool kann einzeln über seine Umschalt-Env-Variable deaktiviert werden (auf false gesetzt). Die vollständige Liste finden Sie in der Tabelle Available MCP Tools weiter oben.

Telemetrie & Governance

Agent-CLI (nur vollständige [agent]-Laufzeit)

Siehe .env.example für einen direkt kopierbaren Ausgangspunkt.

Provider- und Ontologie-Integration

Das Paket bringt seine Skills, Prompts, Ontologie und den Quell-Connector über Python-Einstiegspunkte ein. Der Collection-Inventory-Connector ist bewusst read-only und registriert Collection-Metadaten, keine Dokument- oder Embedding-Payloads.

Generierte Connector-Signaturen dürfen erst nachgezogen werden, wenn das installierte MCP-Schema beobachtet wurde und zur Laufzeit ein Release-Signaturschlüssel bereitgestellt wird. Eine Signatur aus einem älteren Tool-Schema oder einer älteren Ontologie darf niemals weitergetragen werden.

Entwicklungs-Checks

Kostengünstige Checks, die keine Provider starten:

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

Provider-Tests verwenden gemockte SDK-Grenzen und führen keine Netzwerkaufrufe durch. Die Live-Qualifizierung ist eine separate Deployment-Gate und muss mit den vom Betreiber bereitgestellten AgentConfig- und Secrets erfolgen.

Dokumentation

• Installation

• Konfiguration und Datenschutz

• Bereitstellung

• Verwendung

• Architekturübersicht

Der schlanke :mcp-Container mit streamable-http (docker/mcp.compose.yml) veröffentlicht :8000 mit einem /health-Check; die vollständige Compose-Service-Definition finden Sie unter Bereitstellung.

Lizenz

Siehe LICENSE.

Bereitstellen mit agent-utilities-deployment

Stellen Sie dieses Paket mit dem konsolidierten agent-utilities-deployment-Workflow bereit. Er wählt einen Installationspfad für bereits installierte Pakete, editierbaren Quellcode oder unveränderliche Container aus; protokolliert nur Laufzeit-Secret- und TLS-Profil-Referenzen in AgentConfig; und führt Doctor-, Registrierungs-, Policy-, Observability- und Rollback-Gates aus. Bitten Sie Ihren Agent, „vector-mcp mit agent-utilities-deployment bereitzustellen“.

Das Repository enthält weder Deployment-Profil, Anmeldedatenwert, Zertifizierungspfad noch gebietsspezifische Endpunkt. Geben Sie diese zur Laufzeit über AgentConfig und den konfigurierten Secret-Provider an.

Installation

Wählen Sie das Extra, das zu dem passt, was Sie ausführen möchten:

# 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]"

Container-Images (:mcp vs. :agent)

Ein mehrstufiges docker/Dockerfile erstellt zwei passend dimensionierte Abbilder, ausgewählt über --target:

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 führt den schlanken :mcp-Server aus; docker/agent.compose.yml führt den Agenten (:latest) mit einem am selben Ort laufenden :mcp-Sidecar aus.

Wissensgraph-Datenbank (epistemic-graph)

Der vollständige Agent ([agent] / :latest) bettet die epistemic-graph-Engine ein (die transitiv über agent-utilities[agent] eingezogen wird). Für die Produktion – oder um einen einzigen Wissensgraph mehreren Agents zu teilen – führen Sie epistemic-graph als eigenen Datenbankcontainer aus und verweisen den Agenten darauf, anstatt ihn einzubetten. Bereitstellungs-Rezepte (Single-Node + Raft HA), Verbindungskonfiguration und die vollständige Datenbankarchitektur (mit Diagrammen) sind im Deployment-Leitfaden für epistemic-graph dokumentiert. Der schlanke [mcp]-Server benötigt die Datenbank nicht.

Repository-Besitzer

Mitwirken

Beiträge sind willkommen! Bitte sorgen Sie für Codequalität, indem Sie vor dem Einreichen von Pull Requests die lokalen Prüfungen ausführen:

• Code mit ruff format . formatieren

• Code mit ruff check . linten

• Typsicherheit mit mypy . validieren

• Testsuites mit pytest ausführen

Bereitstellen mit agent-os-genesis

Dieses Paket kann für Sie – skill-geführt – durch den universellen Skill agent-os-genesis bereitgestellt werden (dessen Ein-Paket-Bereitstellungsmodus): Er wählt Ihre Installationsmethode, befüllt Secrets in OpenBao/Vault (oder .env), vertraut Ihrer Enterprise-CA, registriert den MCP-Server und verifiziert ihn – dieselbe Mechanik, mit der das gesamte Agent OS eingerichtet wird, eingeschränkt auf genau dieses Paket. Bitten Sie Ihren Agenten: „vector-mcp mit agent-os-genesis bereitstellen“.

Secrets werden aus vorhandenen Werten gelesen und über vault_sync befüllt – Sie werden nur nach fehlenden Werten gefragt.