# MCP Knowledge Base Server

This folder contains the MCP server and unstructured-text ingestion pipeline for the support-ticket triage demo.

The server exposes knowledge-base articles and sample tickets through MCP tools. The search tool is backed by a local SQLite vector index built from Markdown files in `data/kb/`.

## Files

```text
mcp/
├── main.py              # FastMCP server
├── pipeline.py          # Ingest, chunk, embed, and store KB documents
├── vector_store.py      # SQLite vector search helpers
├── models.py            # Pydantic models returned by tools
└── data/
    ├── kb/              # Source knowledge-base articles
    ├── tickets/         # Sample support tickets
    └── index.db         # Generated SQLite index
```

## Tools

The MCP server currently exposes:

- `search_kb(query: str) -> list[Chunk]`
  Semantic search over indexed KB chunks.
- `get_article(name: str) -> str`
  Fetch a full KB article by filename.
- `list_tickets(status: str) -> list[Ticket]`
  List sample tickets by status.

## Setup

Install dependencies:

```bash
uv sync
```

Set the Gemini API key used for embeddings:

```bash
export GEMINI_API_KEY="..."
```

## Build The Index

Run the ingestion pipeline:

```bash
uv run python pipeline.py
```

The pipeline:

1. Reads Markdown files from `data/kb/`.
2. Normalizes and chunks each document.
3. Creates embeddings with `gemini-embedding-001`.
4. Stores chunks and embeddings in `data/index.db`.
5. Uses SHA-256 hashes to skip unchanged documents on reruns.

## Run The Server

Start the MCP server over stdio:

```bash
uv run python main.py
```

Most clients, including the ADK agent in `../agent`, launch this command as a subprocess instead of running it manually.

## Client Config Snippet

Example stdio client configuration:

```json
{
  "mcpServers": {
    "kb-server": {
      "command": "/Users/vianel/Workspace/samples/mcp/.venv/bin/python",
      "args": ["/Users/vianel/Workspace/samples/mcp/main.py"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
      }
    }
  }
}
```

## Smoke Tests

Rebuild the index and check that reruns skip unchanged files:

```bash
uv run python pipeline.py
uv run python pipeline.py
```

Then run the agent-side discovery script from `../agent`:

```bash
cd ../agent
uv run python discovery.py
```

You should see the MCP tools discovered by the client.