# Google Search MCP Server

A Model Context Protocol (MCP) server that provides Google Custom Search functionality.

**🎯 This repository demonstrates 5 different deployment patterns** for the same MCP functionality:

1. **[stdio Mode](#1-stdio-mode-default-mcp)** - Standard MCP over stdin/stdout for local development and MCP client integration
2. **[HTTP over SSE](#2-http-over-sse-mcp-transport)** - MCP HTTP transport using Server‑Sent Events (browser-friendly)
3. **[HTTP Streamable](#3-http-streamable-non-sse)** - MCP Streamable HTTP transport (non‑SSE)
4. **[AWS Lambda + AgentCore Gateway](#4-aws-lambda--agentcore-gateway)** - Serverless deployment with OAuth authentication
5. **[Containerized MCP Service](#5-containerized-mcp-service)** - Docker containers deployed to ECS Fargate for scalable cloud deployment

## Installation

Clone the repository and install dependencies:

```bash
git clone https://github.com/jspv/google-search-mcp.git
cd google-search-mcp
uv sync
```

## Project structure

- `server.py` / `server_http.py` / `server_http_stream.py` — MCP servers (stdio, HTTP, streaming)
- `lambda_handler.py` — AWS Lambda adapter for MCP stdio server
- `Dockerfile.mcp` — Container image for HTTP/streaming MCP service
- `deploy/` — legacy deployment assets (use `deploy_aws_agentcore_auth0/`)
- `deploy_aws_agentcore_auth0/` — canonical Auth0 + AgentCore Gateway deploy scripts and templates
   - `build_zip.sh` — build Lambda ZIP
   - `deploy_lambda.sh` — deploy Lambda via CloudFormation
   - `AGENTCORE_GATEWAY_CHECKLIST.md` — complete Gateway (Lambda + Cognito) integration checklist
   
   - `deploy_gateway.sh` — attempt AgentCore setup via CLI
   - `gen_tool_schema.sh` — generate MCP tool schema (uses Python stdio client)
   - `cloudformation-*.yaml` — infrastructure templates
   - `README-*.md` — deployment-specific docs
- `scripts/` — developer/CI utilities
   - `dump_tool_schema.py` — dump schema from an MCP server over stdio
- `dist/` — build artifacts and generated outputs
   - `schema/tool-schema.json` — generated tool schema for AgentCore
   - `google_search_mcp_lambda.zip` — built Lambda package
- `tests/` — unit and integration tests


### Optional Dependencies

Install additional dependencies based on your deployment needs:

```bash
# For HTTP/streaming modes
uv sync --extra http

# For AWS Lambda deployment
uv sync --extra lambda

# For containerized deployments (ECS/Fargate)
uv sync --extra container

# For AWS (both Lambda and container)
uv sync --extra aws

# For development
uv sync --extra dev

# Install multiple extras
uv sync --extra http --extra aws --extra dev
```

## Configuration

This server uses [Dynaconf](https://www.dynaconf.com/) for configuration management, supporting both `.env` files and environment variables.

### Setup

1. Copy the example environment file:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` and add your Google API credentials:
   ```bash
   GOOGLE_API_KEY=your_actual_api_key_here
   GOOGLE_CX=your_custom_search_engine_id_here
   ```

### Environment Variable Override

Environment variables will **override** `.env` file values when both are present. This allows for flexible deployment scenarios:

- **Development**: Use `.env` file for local development
- **Production**: Use environment variables for production deployment
- **CI/CD**: Environment variables can override defaults for testing

#### Example:

If your `.env` file contains:
```bash
GOOGLE_API_KEY=dev_key_from_file
```

And you set an environment variable:
```bash
export GOOGLE_API_KEY=prod_key_from_env
```

The server will use `prod_key_from_env` (environment variable takes precedence).

### Required Configuration

- `GOOGLE_API_KEY`: Your Google Custom Search API key
- `GOOGLE_CX`: Your Custom Search Engine ID

Get these from:
- API Key: [Google Cloud Console](https://console.developers.google.com/)
- Search Engine ID: [Google Custom Search](https://cse.google.com/cse/all)

### Optional Configuration

- `ALLOW_DOMAINS` (`GOOGLE_ALLOW_DOMAINS` env var): Comma-separated list of allowed domains (e.g., `example.com, docs.python.org`).
   When set, results outside these domains are filtered out.

- Logging:
   - `LOG_QUERIES` (`GOOGLE_LOG_QUERIES`): Enable logging of query hash, timing, and key params.
   - `LOG_QUERY_TEXT` (`GOOGLE_LOG_QUERY_TEXT`): Also log full query text (off by default).
   - `LOG_LEVEL` (`GOOGLE_LOG_LEVEL`): Set logging level (e.g., `INFO`, `DEBUG`).
   - `LOG_FILE` (`GOOGLE_LOG_FILE`): Optional path to also write logs to a file (stderr remains enabled).

## Usage

This project provides 5 different deployment patterns for the same Google Search MCP functionality:

### 1. stdio Mode (Default MCP)

Standard MCP server for local development and integration with MCP clients:

```bash
# Run via uv (recommended)
uv run python -m server

# Or direct execution
python server.py

# Run via uvx (no activation, from any folder)
uvx --from /Users/justin/src/google_search_mcp google-search-mcp

# Run via pipx (isolated, globally available)
pipx install /Users/justin/src/google_search_mcp
google-search-mcp
```

Communicates over stdin/stdout using the standard MCP protocol.

### 2. HTTP over SSE (MCP transport)

MCP over HTTP using Server‑Sent Events (SSE). This exposes the standard MCP HTTP endpoints used by browser clients.

```bash
# Install HTTP extras and run
uv sync --extra http
uv run python -m server_http

# Or via console script (if installed)
uv run google-search-mcp-http

# With custom host/port
HOST=0.0.0.0 PORT=8000 uv run python -m server_http
```

Available MCP endpoints (not a custom REST API):
- `GET /sse` — SSE connection for events
- `POST /messages` — MCP message handling

Notes:
- CORS enabled by default (customize with `CORS_ORIGINS`).
- Same configuration as stdio mode (`GOOGLE_API_KEY`, `GOOGLE_CX`, etc.).

### 3. HTTP Streamable (non‑SSE)

MCP Streamable HTTP transport for clients that don’t use SSE.

```bash
# Start the Streamable HTTP MCP server
uv sync --extra http
uv run python -m server_http_stream

# Or via console script (if installed)
uv run google-search-mcp-stream

# Custom host/port
HOST=0.0.0.0 PORT=8000 uv run python -m server_http_stream
```

Notes:
- Not a REST interface. Use an MCP client that supports the Streamable HTTP transport.
- CORS behavior matches the SSE app and is configurable via `CORS_ORIGINS`.

### 4. AWS Lambda + AgentCore Gateway

**Prerequisites**: 
```bash
# Install Lambda dependencies
uv sync --extra lambda

# Configure AWS credentials
aws configure
```

Deploy to AWS Lambda with Bedrock AgentCore Gateway integration:

```bash
# Build and deploy
./deploy_aws_agentcore_auth0/build_zip.sh        # Cross-platform build
./deploy_aws_agentcore_auth0/deploy_lambda.sh    # Deploy via CloudFormation
./deploy_aws_agentcore_auth0/deploy_gateway.sh # Setup AgentCore Gateway

# Test the deployment
python3 deploy_aws_agentcore_auth0/test_gateway_auth0.py https://your-gateway-url.amazonaws.com client-id client_secret https://your-domain.auth0.com [audience]
```

Features:
- JSON-RPC 2.0 protocol with OAuth authentication
- Serverless execution with environment variable inheritance
- Integrated with AWS Bedrock AgentCore ecosystem

### 5. Containerized MCP Service

**Prerequisites**:
```bash
# Install container dependencies (for ECR/ECS deployment)
uv sync --extra container

# Configure Docker and AWS
docker --version
aws configure
```

**Local Testing**:
```bash
# Build container
docker build -f Dockerfile.mcp -t google-search-mcp .

# Run locally
docker run -p 8000:8000 --env-file .env -e MCP_MODE=http-stream google-search-mcp
```

**Deploy to AWS ECS Fargate**:
```bash
# Deploy to ECS Fargate
./deploy/deploy_mcp_container.sh google-search-mcp us-east-1 ecs-fargate
```

Features:
- Multi-mode container supporting stdio, HTTP, and streaming
- Scalable deployment via ECS Fargate
- Environment variable configuration
- Health checks and monitoring

**Note**: AgentCore Runtime uses preview SDK and requires manual configuration as APIs are not publicly available.

### Configuration Notes

All deployment patterns use the same configuration:
- Set `DYNACONF_DOTENV_PATH` for .env loading when needed
- Environment variables override settings.toml values
- Logging configuration applies across all modes

## Quick Start

This project uses httpx with HTTP/2 support enabled. The dependency is declared as `httpx[http2]` and will install the `h2` package automatically.

### Using uv (recommended)

```bash
# Install dependencies
uv sync

# Create and configure environment
cp .env.example .env
$EDITOR .env

# Run tests (optional sanity check)
uv run pytest -q

# Start the MCP server (stdio mode)
uv run python server.py
```

### Quick Test (no MCP client required)

Test the search function directly:

```bash
uv run python -c 'import asyncio, server; print(asyncio.run(server.search("site:python.org httpx", num=2, safe="off")))'
```

Note: `safe` must be `off` or `active`, and `num` is clamped to maximum of 10 per Google CSE limits.

### Logging behavior

If `LOG_QUERIES` is enabled, the server will write a single line per request to stdout containing:
- q_hash (short, non-reversible hash of the query), dt_ms (latency), num, start, safe, and endpoint (cse/siterestrict)
- If `LOG_QUERY_TEXT` is true, it also includes the full `q` text.

Example log line:

```
2025-09-27T12:34:56+0000 INFO google_search_mcp: search q_hash=1a2b3c4d dt_ms=123 num=5 start=1 safe=off endpoint=cse q="site:python.org httpx"
```

When a client spawns the server via `uvx`, logs go to the server process’s stderr by default (safe for MCP stdio). To persist logs regardless of the client’s stderr handling:

- Set a file path (absolute recommended):
   ```
   GOOGLE_LOG_QUERIES=true
   GOOGLE_LOG_FILE=/var/log/google_search_mcp.log
   ```
- Or redirect stderr in the launch command:
   ```
   uvx --from /path/to/repo google-search-mcp 2>> /tmp/google_search_mcp.log
   ```

## Testing

### Unit Tests

Run the test suite to validate functionality:

```bash
# Run all tests
uv run pytest

# Run with quiet output
uv run pytest -q

# Run specific test files
uv run pytest tests/test_server.py
uv run pytest tests/test_server_http.py
```

## Testing

## Testing

The project includes a comprehensive test suite located in the `tests/` directory. All tests use pytest and mock external dependencies for reliable, fast execution.

### Unit Tests

Run the comprehensive test suite to validate functionality:

```bash
# Run all tests
uv run pytest

# Run with quiet output
uv run pytest -q

# Run specific test modules
uv run pytest tests/test_server.py              # Core MCP server functionality  
uv run pytest tests/test_server_http.py         # HTTP endpoint testing
uv run pytest tests/test_server_http_stream.py  # HTTP streaming testing
uv run pytest tests/test_client.py              # Client integration
uv run pytest tests/test_logging.py             # Logging configuration
```

### Local Testing

Use an MCP client (e.g., Inspector or your app) that supports SSE or Streamable HTTP transports. There is no custom REST `list_tools`/`call_tool` in this server.

### AWS Gateway Testing

For AWS AgentCore Gateway deployments, use the dedicated test script:

```bash
# Test gateway with authentication
python3 deploy_aws_agentcore_auth0/test_gateway_auth0.py \
   "https://your-gateway.amazonaws.com/mcp" \
   "client-id" \
   "client-secret" \
   "https://your-domain.auth0.com" \
   "https://your-gateway.amazonaws.com/mcp"  # audience (optional depending on IdP)
```

This validates authentication, tool listing, and tool execution through the gateway.

## Deployment Details

### AWS Lambda + AgentCore Gateway
- Uses JSON-RPC 2.0 protocol with OAuth authentication
- Cognito client credentials flow required
- Manual console configuration for compute targets and MCP providers (APIs not publicly available)
- See [`deploy/README-lambda-zip.md`](deploy/README-lambda-zip.md) for detailed instructions (use scripts under `deploy_aws_agentcore_auth0/`)

### AWS AgentCore Runtime  
- Uses preview AgentCore SDK (placeholder implementation)
- Requires manual configuration as APIs are not publicly available
- Container-based deployment via ECR integration
- Provides persistent sessions with microVM isolation