# ADK MCP Server

An offline-first Model Context Protocol (MCP) server for querying Google ADK (Accessory Development Kit) documentation. This server uses LanceDB for vector search and FastMCP for the MCP interface, allowing AI models to access and understand ADK documentation.

## Features

- **Offline-first**: All documentation and vector indices are stored locally.
- **Fast Search**: Uses LanceDB and FastEmbed for efficient vector search.
- **MCP Integration**: Compatible with any MCP-enabled client (like Claude Desktop).
- **Easy Deployment**: Can be installed as a local tool using `uv`.

## Prerequisites

- Python 3.13 or higher
- [uv](https://github.com/astral-sh/uv) for dependency management and running.

## Installation

1.  **Clone the repository**:
    ```bash
    git clone <repository-url>
    cd adk-mcp-docs
    ```

2.  **Install dependencies**:
    ```bash
    make install
    # or
    uv sync
    ```

## Usage

### 1. Build the Index

Before running the server, you need to build the vector index from the documentation.

```bash
make build-index
# or
uv run src/adk_mcp/builder.py
```

### 2. Run the Server (Development)

To run the server in development mode with hot-reloading:

```bash
make run
# or
uv run fastmcp run src/adk_mcp/server.py
```

### 3. Local Deployment

To install the server as a local tool accessible via `uvx`:

```bash
make deploy-local
# or
uv tool install . --force
```

After installation, you can run the server using:

```bash
uvx adk-mcp
```

## Configuration for MCP Clients

### VS Code / Antigravity

For VS Code (with compatible MCP extensions) or Antigravity, create a file at `.vscode/mcp-servers.json` with the following content:

```json
{
  "mcpServers": {
    "adk-mcp": {
      "command": "uvx",
      "args": ["adk-mcp"]
    }
  }
}
```

### Cursor

1. Open Cursor Settings.
2. Go to **Features** > **MCP**.
3. Click **+ Add Bot**.
4. Set Name to `adk-mcp`.
5. Set Type to `command`.
6. Set Command to `uvx adk-mcp`.

### Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "adk-mcp": {
      "command": "uvx",
      "args": ["adk-mcp"]
    }
  }
}
```

## Project Structure

- `src/adk_mcp/`: Source code for the MCP server.
  - `builder.py`: Script to build the LanceDB index.
  - `server.py`: FastMCP server implementation.
  - `data/`: Directory for storing the LanceDB index (generated).
- `data/`: (Optional) Source documentation files (if not embedded in the package).
- `Makefile`: Convenient shortcuts for common tasks.
- `pyproject.toml`: Project metadata and dependencies.

## Chunking Strategy

The documentation is indexed using a context-aware chunking strategy to ensure high-quality search results:

1.  **Header-based Splitting**: Files are split by H1, H2, and H3 headers.
2.  **Contextual Headers**: Each chunk is prefixed with its hierarchical context (e.g., `Context: Getting Started > Installation > Python`).
3.  **Language Tab Handling**: Special handling for documentation with language tabs (e.g., `=== "Python"`, `=== "Go"`). Content within these tabs is indexed separately and tagged with the respective language.
4.  **Embeddings**: Uses the `BAAI/bge-small-en-v1.5` model for generating vector embeddings.

## Available Tools

### `search_adk`

Search the Google ADK documentation for relevant information.

**Arguments:**
- `query` (string): The search query.
- `language` (string): The programming language to filter by. Supported values: `"python"`, `"go"`, `"java"`, or `"all"`.

**Returns:**
- A formatted string containing the top 5 relevant chunks, including their source URLs and content.