# Weaviate Docs MCP Server

MCP server for searching Weaviate documentation using semantic search.

## Setup

1. Clone the Weaviate docs repository:
```bash
git clone https://github.com/weaviate/docs.git
```

2. Install dependencies:
```bash
uv sync
```

3. Create `.env` file:
```bash
cp .env.example .env
```

Edit `.env` with your credentials:
- `WEAVIATE_DOCS_MCP_URL`: Your Weaviate cluster URL
- `WEAVIATE_DOCS_MCP_API_KEY`: Your Weaviate API key
- `COHERE_API_KEY`: Your Cohere API key (for embeddings)
- `CATALOG_COLLECTION_NAME`: Collection name (default: `DocCatalog`)
- `DOCS_ROOT_PATH`: Base path to the docs folder (default: `./docs/docs`)
- `DOCS_PATHS`: (Optional) Comma-separated subdirectories to scan (default: `weaviate,deploy`)

## Usage

### With Claude Desktop

Add to your Claude Desktop config:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "weaviate-docs": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/jphwang/code/weaviate-docs-mcp",
        "run",
        "weaviate-docs-mcp"
      ]
    }
  }
}
```

### Available Tools

#### search_docs
Search documentation by semantic similarity.

**Parameters:**
- `query` (string, required): Search query to find relevant documentation
- `return_type` (string, optional): Format of results (default: "full_documents")

**Returns:** Up to 5 most relevant documents with full content and referenced code files

## Catalog Management

The catalog must be updated manually before the MCP server can search documents.

### Update the catalog

Run the standalone script to scan for new/modified documents:

```bash
python update_catalog.py
```

Or limit the number of documents (useful for testing):

```bash
python update_catalog.py --limit 5
```

This script:
- Scans the docs directory for new or modified markdown files
- Generates metadata (title, topics, summary, doctype) using AI
- Stores metadata in both local `catalog.json` and Weaviate
- Removes entries for deleted documents
- **Syncs local catalog with Weaviate**: Re-adds any documents that exist in the local catalog but are missing from Weaviate

The script intelligently handles three scenarios:
1. **New or modified documents**: Generates fresh metadata and updates both catalog and Weaviate
2. **Deleted documents**: Removes from both local catalog and Weaviate
3. **Out-of-sync documents**: Re-syncs documents that exist in local catalog but missing from Weaviate (e.g., after Weaviate collection recreation)

## Architecture

This MCP server is designed for **read-only documentation search**. Catalog management is intentionally kept separate as an admin operation.

### Components

- **MCP Server** (`src/weaviate_docs_mcp/server.py`) - Provides `search_docs` tool for clients
- **Catalog Script** (`update_catalog.py`) - Admin tool to rebuild the search index
- **Document Loader** - Parses markdown files and extracts referenced code
- **Database Layer** - Connects to Weaviate for vector search

### Why separate catalog updates?

Catalog updates are expensive operations that:
- Process potentially thousands of documents
- Use AI credits for metadata generation
- Take significant time (minutes to hours)
- Should be controlled by administrators

By keeping this separate, the MCP server remains fast and focused on search.

## Development

Run the server:
```bash
uv run weaviate-docs-mcp
```