# 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 `.env` file (see `Settings` in `main.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 (stdio)

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

### Run the MCP server (SSE, e.g. for remote clients)

```bash
uv run python main.py --transport sse --port 8080
```

### 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
```

## 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

```
main.py          MCP server, vector search client, and GCS storage helper
agent.py         Interactive ADK agent that consumes the MCP server
Dockerfile       Multi-stage build for Cloud Run / containerized deployment
pyproject.toml   Project metadata and dependencies
```