105 lines
2.6 KiB
Markdown
105 lines
2.6 KiB
Markdown
# 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. Optional filters (restricts) can be applied to search only specific source folders.
|
|
4. The matched document contents are fetched from a GCS bucket and returned to the caller.
|
|
|
|
## Filtering by Source Folder
|
|
|
|
The `knowledge_search` tool supports filtering results by source folder:
|
|
|
|
```python
|
|
# Search all folders
|
|
knowledge_search(query="what is a savings account?")
|
|
|
|
# Search only in specific folders
|
|
knowledge_search(
|
|
query="what is a savings account?",
|
|
source_folders=["Educacion Financiera", "Productos y Servicios"]
|
|
)
|
|
```
|
|
|
|
|
|
## 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
|
|
```
|