weaviate-setup

Weaviate Knowledge Store Setup

You are guiding a user through setting up Weaviate as the persistent knowledge store for the video-research MCP server. All 28 tools automatically write results to Weaviate when configured. 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:

Error	Fix
WEAVIATE_CONNECTION	Check URL is reachable, Docker is running, firewall allows the port
WEAVIATE_SCHEMA	Collections couldn't be created -- check Weaviate version (need >= 1.25)
Weaviate not configured	WEAVIATE_URL env var is not set or server wasn't restarted

Step 5: Confirm Working

Once knowledge_stats returns successfully, tell the user:

1. All 28 tools now automatically store results to Weaviate
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

Collection	Populated by	Knowledge tools that query it
ResearchFindings	research_deep, research_assess_evidence, research_document	All 8 knowledge tools
VideoAnalyses	video_analyze, video_batch_analyze	All 8 knowledge tools
ContentAnalyses	content_analyze, content_batch_analyze	All 8 knowledge tools
VideoMetadata	video_metadata	All 8 knowledge tools
SessionTranscripts	video_continue_session	All 8 knowledge tools
WebSearchResults	web_search	All 8 knowledge tools
ResearchPlans	research_plan	All 8 knowledge tools
DeepResearchReports	research_web_status, research_web_followup	All 8 knowledge tools
CommunityReactions	comment-analyst agent outputs	All 8 knowledge tools
ConceptKnowledge	concept extraction/enrichment pipelines	All 8 knowledge tools
RelationshipEdges	relationship graph extraction	All 8 knowledge tools
CallNotes	call/meeting analysis pipelines	All 8 knowledge tools

Supported Deployment URLs

Type	Example URL	API Key
Weaviate Cloud	https://my-cluster-abc123.weaviate.network	Required
Local Docker	http://localhost:8080	Not needed
Custom	https://weaviate.mycompany.com:8080	Depends

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.