version: "1.0.0" name: weaviate-setup description: Interactive onboarding for the Weaviate knowledge store. Guides users through choosing a deployment type (Cloud, Local Docker, or Custom), setting environment variables, and verifying the connection. Activates when users want to set up or configure Weaviate for persistent knowledge storage.

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. 8 knowledge tools (knowledge_search, knowledge_related, knowledge_stats, knowledge_fetch, knowledge_ingest, knowledge_schema, knowledge_ask, knowledge_query) enable semantic search and AI-powered Q&A across accumulated research.

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 cloud service at console.weaviate.cloud — free tier available, no infrastructure to manage"
        - label: "Local Docker"
          description: "Run Weaviate locally via Docker on port 8080 — full control, no network latency"
        - label: "Custom/Self-hosted"
          description: "Your own Weaviate deployment at a custom URL"

Step 2: Collect Credentials (based on choice)

If Weaviate Cloud:

• Tell the user to go to https://console.weaviate.cloud, create a free cluster, then copy the cluster URL and API key
• Ask them to provide both values

If Local Docker:

• Provide the docker-compose snippet:

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

• Note: Our collections use the text2vec-weaviate vectorizer (Weaviate's built-in embedding service). No sidecar container needed.
• The URL will be http://localhost:8080
• No API key needed for local

If Custom:

• Ask for the full URL (including port)
• Ask if authentication is required (API key)

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=weaviate

Cloud deployment:

GEMINI_API_KEY=<their-gemini-key>
WEAVIATE_URL=<cluster-url>
WEAVIATE_API_KEY=<key>

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).
• Keep .mcp.json free of unresolved placeholders like ${WEAVIATE_URL}.

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 will attempt to connect and search. On first connection, the server auto-creates all 12 collections. If the search returns empty results with no error, the connection is working.

Then confirm collections exist:

knowledge_stats()

This should return counts for all 12 collections (all 0 initially). If it returns an error, troubleshoot based on the error category:

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 (AI answers with sources) and knowledge_query (natural language search). Requires the weaviate-agents package."
        - 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="...") -- natural language object retrieval with automatic query understanding

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

12 Collections Created Automatically

Supported Deployment URLs

Graceful Degradation

If WEAVIATE_URL is not set, the server works identically to before -- no errors, no changes. All store operations silently return None. Knowledge tools return empty results with a hint to configure Weaviate.