Weaviate Knowledge Store Setup

You are guiding a user through setting up Weaviate as the persistent knowledge store for the video-research MCP server. Analysis and research tools attempt write-through storage when configured; infrastructure/query tools do not create analysis records and storage failures are non-fatal. Use knowledge_search, knowledge_related, knowledge_stats, knowledge_fetch, knowledge_ingest, and knowledge_schema; optional knowledge_ask provides AI Q&A. knowledge_query remains available but is deprecated in favor of knowledge_search.

Setup Flow

Follow these steps IN ORDER. Use AskUserQuestion for each decision point.

Step 1: Deployment Type

Ask the user which Weaviate deployment they want to use:

AskUserQuestion:
  questions:
    - question: "Which Weaviate deployment will you use?"
      header: "Deployment"
      multiSelect: false
      options:
        - label: "Weaviate Cloud (Recommended)"
          description: "Managed service at console.weaviate.cloud — check current plans and embedding costs"
        - label: "Local Docker"
          description: "Run Weaviate locally via Docker; the selected embedding provider may still use a network service"
        - label: "Custom/Self-hosted"
          description: "Your own Weaviate deployment at a custom URL"

Step 2: Collect Credentials (based on choice)

If Weaviate Cloud:

• Direct the user to https://console.weaviate.cloud to select an authorized plan and obtain the cluster URL/API key
• Collect the URL; have the user store the key locally and confirm its presence without pasting it into chat

If Local Docker:

• Select the server version using the official Docker guide. This example uses its 2026-10-06 documented image and OpenAI vectorizer; it is not a tested deployment receipt:

services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.39.8
    ports:
      - "127.0.0.1:8080:8080"
      - "127.0.0.1:50051:50051"
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: "true"
      PERSISTENCE_DATA_PATH: "/var/lib/weaviate"
      DEFAULT_VECTORIZER_MODULE: text2vec-openai
      ENABLE_MODULES: text2vec-openai

• Weaviate Embeddings are Cloud-only. For this Docker example, configure the already supported OpenAI vectorizer and authorize its embedding costs separately. No local model or sidecar is selected.
• The URL will be http://localhost:8080
• Anonymous loopback access needs no Weaviate API key; the OpenAI vectorizer still needs its provider key.
• Before retaining knowledge, add the persistent volume from the official Docker guide. PERSISTENCE_DATA_PATH alone does not preserve data when the container is replaced.

If Custom:

• Ask for the full URL (including port)
• Ask whether authentication is required; keep any API key in local configuration

Step 3: Configure Environment

Once you have the URL (and optionally API key), tell the user to configure the shared server config file (recommended) or shell env:

Option A -- Shared config file (recommended for plugin users): Edit ~/.config/video-research-mcp/.env:

Docker deployment:

GEMINI_API_KEY=<their-gemini-key>
WEAVIATE_URL=http://localhost:8080
WEAVIATE_VECTORIZER=openai
OPENAI_API_KEY=<locally-stored-embedding-key>

Cloud deployment:

GEMINI_API_KEY=<their-gemini-key>
WEAVIATE_URL=<cluster-url>
WEAVIATE_API_KEY=<locally-stored-key>
WEAVIATE_VECTORIZER=weaviate

The server auto-detects WEAVIATE_VECTORIZER based on OPENAI_API_KEY: if present → openai, otherwise → weaviate (built-in embeddings). Setting it explicitly avoids surprises.

Notes:

• Use a full URL with scheme (https://... for cloud, http://localhost:8080 for local).
• Verify substitutions resolve in the server process; supported client placeholders may remain in .mcp.json.

Option B -- Shell environment:

export WEAVIATE_URL="<their-url>"
export WEAVIATE_API_KEY="<their-key-if-any>"  # only for Cloud/authenticated deployments

Step 4: Verify Connection

After the user has configured the environment, tell them to restart Claude Code (or the MCP server) and test with:

knowledge_search(query="test")

This attempts connection, collection setup, and search only when WEAVIATE_URL is configured. An empty result also occurs when storage is disabled; confirm configuration and test a known record before claiming retrieval works.

Then confirm collections exist:

knowledge_stats()

Inspect the returned collection list and errors. Disabled storage returns an empty list; per-collection failures can appear as zero counts. Check a known record or server diagnostics before interpreting zeros as an empty healthy store. Troubleshoot reported errors:

Step 5: Confirm Working

Once knowledge_stats returns successfully, tell the user:

1. The knowledge connection works; verify a known stored record separately before claiming analysis persistence
2. Use knowledge_search(query="...") to find past results semantically (supports hybrid, semantic, keyword modes)
3. Use knowledge_related(object_id="...", collection="...") to find similar items
4. Use knowledge_fetch(object_id="...", collection="...") to retrieve a specific object by UUID
5. Use knowledge_stats() to see how much knowledge has accumulated
6. Use knowledge_ingest(collection="...", properties={...}) to manually insert data
7. The file cache continues to work alongside Weaviate -- dual persistence

Step 6: Optional -- Enable QueryAgent Tools

Ask the user if they want AI-powered Q&A over their knowledge store:

AskUserQuestion:
  questions:
    - question: "Do you want to enable AI-powered knowledge Q&A?"
      header: "QueryAgent (Optional)"
      multiSelect: false
      options:
        - label: "Yes -- install weaviate-agents"
          description: "Enables knowledge_ask; requires weaviate-agents and a compatible authorized QueryAgent service. knowledge_query is deprecated."
        - label: "No -- skip for now"
          description: "You can install it later with: uv pip install 'video-research-mcp[agents]'"

If yes, tell them to install the agents extra:

uv pip install 'video-research-mcp[agents]'

Then restart the MCP server and test:

knowledge_ask(query="What have I researched so far?")

If successful, they now also have:

• knowledge_ask(query="...") -- AI-generated answers grounded in stored knowledge, with source citations
• knowledge_query(query="...") -- deprecated natural-language retrieval; prefer knowledge_search

These tools use Weaviate's AsyncQueryAgent, which automatically translates natural-language queries into optimized Weaviate operations.

Collections Created Automatically

Supported Deployment URLs

Graceful Degradation

Without WEAVIATE_URL, analysis remains available and write-through storage is skipped. Basic search/stats return empty results; optional agent tools can return dependency/configuration errors. Report persistence separately from analysis success.