From bd107a027a049dc64f19b9dadeb463852cf13a7c Mon Sep 17 00:00:00 2001
From: Anibal Angulo <a8065384@banorte.com>
Date: Sun, 22 Feb 2026 16:02:46 +0000
Subject: [PATCH] Update README

---
 README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/README.md b/README.md
index e69de29..0192487 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,87 @@
+# 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
+```