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

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

Prerequisites

Python ≥ 3.12
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):

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

uv sync

Run the MCP server

Using the installed command (recommended):

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

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:

uv run python agent.py

Or connect to an already-running SSE server:

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

Run tests

uv run pytest

Docker

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

2.7 KiB Raw Permalink Blame History