# knowledge-search-mcp

An MCP (Model Context Protocol) server that exposes a `knowledge_search` tool for semantic search over a knowledge base backed by Vertex AI Vector Search and Google Cloud Storage.

## How it works

1. A natural-language query is embedded using a Gemini embedding model.
2. The embedding is sent to a Vertex AI Matching Engine index endpoint to find nearest neighbors.
3. The matched document contents are fetched from a GCS bucket and returned to the caller.

## Prerequisites

- Python ≥ 3.12
- [uv](https://docs.astral.sh/uv/) for dependency management
- A Google Cloud project with:
  - A Vertex AI Vector Search index and deployed endpoint
  - A GCS bucket containing the indexed document chunks
  - Application Default Credentials (or a service account) with appropriate permissions

## Configuration

Create a `config.yaml` file or `.env` file (see `Settings` in `src/knowledge_search_mcp/config.py` for all options):

```env
PROJECT_ID=my-gcp-project
LOCATION=us-central1
BUCKET=my-knowledge-bucket
INDEX_NAME=my-index
DEPLOYED_INDEX_ID=my-deployed-index
ENDPOINT_NAME=projects/…/locations/…/indexEndpoints/…
ENDPOINT_DOMAIN=123456789.us-central1-aiplatform.googleapis.com
# optional
EMBEDDING_MODEL=gemini-embedding-001
SEARCH_LIMIT=10
```

## Usage

### Install dependencies

```bash
uv sync
```

### Run the MCP server

**Using the installed command (recommended):**

```bash
# stdio transport (default)
uv run knowledge-search-mcp

# SSE transport for remote clients
uv run knowledge-search-mcp --transport sse --port 8080

# streamable-http transport
uv run knowledge-search-mcp --transport streamable-http --port 8080
```

**Or run directly:**

```bash
uv run python -m knowledge_search_mcp.main
```

### Run the interactive agent (ADK)

The bundled agent spawns the MCP server as a subprocess and provides a REPL:

```bash
uv run python agent.py
```

Or connect to an already-running SSE server:

```bash
uv run python agent.py --remote http://localhost:8080/sse
```

### Run tests

```bash
uv run pytest
```

## Docker

```bash
docker build -t knowledge-search-mcp .
docker run -p 8080:8080 --env-file .env knowledge-search-mcp
```

The container starts the server in SSE mode on the port specified by `PORT` (default `8080`).

## Project structure

```
src/knowledge_search_mcp/
├── __init__.py       Package initialization
├── config.py         Configuration management (Settings, args parsing)
├── logging.py        Cloud Logging setup
└── main.py           MCP server, vector search client, and GCS storage helper
agent.py              Interactive ADK agent that consumes the MCP server
tests/                Test suite
pyproject.toml        Project metadata, dependencies, and entry points
```