# Datastore MCP Server

A Model Context Protocol (MCP) server that provides access to Google Cloud Datastore. This server enables AI assistants like Claude to interact with Datastore entities, perform queries, and manage data.

## Features

- **Entity Operations**: Create, read, update, and delete Datastore entities
- **Query Support**: Execute queries with filters, ordering, and pagination
- **Namespace Support**: Work with different Datastore namespaces
- **Emulator Support**: Connect to local Datastore emulator by default for development
- **Production Ready**: Easy configuration for production Google Cloud Datastore

## Installation

### Prerequisites

**Option 1: Docker (Recommended)**
- Docker Engine 20.10+
- Docker Compose v2.0+

**Option 2: Local Python**
- Python 3.10 or higher
- Google Cloud Datastore emulator (for local development) or Google Cloud project (for production)

### Install from source

```bash
# Clone the repository
git clone <repository-url>
cd datastore-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .
```

### Using uv (recommended)

```bash
# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .
```

### Using Docker (recommended for testing)

Docker provides an isolated environment with both the Datastore emulator and MCP server pre-configured.

```bash
# Run tests
make test

# Start all services (emulator + server)
make up

# View logs
make logs

# Stop services
make down
```

For detailed Docker documentation, see [DOCKER.md](DOCKER.md).

## Configuration

The server can be configured using environment variables or command-line arguments.

### Environment Variables

**For Emulator:**
- `DATASTORE_DATASET` - Dataset name (default: `test`)
- `DATASTORE_EMULATOR_HOST` - Datastore emulator host (default: `localhost:8081`)
- `DATASTORE_EMULATOR_HOST_PATH` - Emulator host path (default: `localhost:8081/datastore`)
- `DATASTORE_HOST` - Datastore HTTP host (default: `http://localhost:8081`)
- `DATASTORE_PROJECT_ID` - Google Cloud project ID (default: `test`)
- `DATASTORE_NAMESPACE` - Default namespace (optional)

**For Production:**
- `DATASTORE_PROJECT_ID` - Google Cloud project ID (required)
- `GOOGLE_APPLICATION_CREDENTIALS` - Path to service account key file (required)
- `DATASTORE_NAMESPACE` - Default namespace (optional)

### Running with Datastore Emulator (Default)

```bash
# Start the Datastore emulator (in a separate terminal)
gcloud beta emulators datastore start --host-port=localhost:8081

# Run the MCP server (uses emulator by default)
python src/datastore_mcp/server.py

# Or with custom emulator host
DATASTORE_EMULATOR_HOST=localhost:9090 python src/datastore_mcp/server.py
```

### Running with Production Datastore

```bash
# Set credentials and project
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
export DATASTORE_PROJECT_ID=your-gcp-project-id

# Unset emulator host to use production
unset DATASTORE_EMULATOR_HOST

# Run the server
python src/datastore_mcp/server.py
```

## Usage with Claude Desktop

Add this configuration to your Claude Desktop config file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

### For Emulator (Development)

```json
{
  "mcpServers": {
    "datastore": {
      "command": "python",
      "args": ["/path/to/datastore-mcp/src/datastore_mcp/server.py"],
      "env": {
        "DATASTORE_DATASET": "test",
        "DATASTORE_EMULATOR_HOST": "localhost:8081",
        "DATASTORE_EMULATOR_HOST_PATH": "localhost:8081/datastore",
        "DATASTORE_HOST": "http://localhost:8081",
        "DATASTORE_PROJECT_ID": "test"
      }
    }
  }
}
```

### For Production

```json
{
  "mcpServers": {
    "datastore": {
      "command": "python",
      "args": ["/path/to/datastore-mcp/src/datastore_mcp/server.py"],
      "env": {
        "DATASTORE_PROJECT_ID": "your-gcp-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json"
      }
    }
  }
}
```

### Using Docker with Claude Desktop (Recommended)

**Option 1: Fully Automated (Emulator + Server)**

Use the provided wrapper script (included in the repository):

**MacOS/Linux**: `start-datastore-mcp.sh`
**Windows**: `start-datastore-mcp.bat`

Then configure Claude Desktop:

**MacOS/Linux**:
```json
{
  "mcpServers": {
    "datastore": {
      "command": "/path/to/datastore-mcp/start-datastore-mcp.sh"
    }
  }
}
```

**Windows**:
```json
{
  "mcpServers": {
    "datastore": {
      "command": "C:\\path\\to\\datastore-mcp\\start-datastore-mcp.bat"
    }
  }
}
```

This option automatically starts the emulator if it's not running and waits for it to be healthy before starting the MCP server.

**Option 2: Manual Emulator Start**

First, start the Datastore emulator once:

```bash
cd /path/to/datastore-mcp
make emulator-only  # Keeps running in background
```

Then configure Claude Desktop:

```json
{
  "mcpServers": {
    "datastore": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/path/to/datastore-mcp/docker-compose.yml",
        "run",
        "--rm",
        "mcp-server"
      ]
    }
  }
}
```

**Option 3: External Emulator (Custom IP)**

If your emulator runs on a different machine or custom IP:

```json
{
  "mcpServers": {
    "datastore": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/path/to/datastore-mcp/docker-compose.yml",
        "run",
        "--rm",
        "-e", "DATASTORE_EMULATOR_HOST=localhost:8081",
        "-e", "DATASTORE_EMULATOR_HOST_PATH=localhost:8081/datastore",
        "-e", "DATASTORE_HOST=http://localhost:8081",
        "mcp-server"
      ]
    }
  }
}
```

### Using uv with Claude Desktop

```json
{
  "mcpServers": {
    "datastore": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/datastore-mcp",
        "run",
        "datastore-mcp"
      ],
      "env": {
        "DATASTORE_DATASET": "test",
        "DATASTORE_EMULATOR_HOST": "localhost:8081",
        "DATASTORE_EMULATOR_HOST_PATH": "localhost:8081/datastore",
        "DATASTORE_HOST": "http://localhost:8081",
        "DATASTORE_PROJECT_ID": "test"
      }
    }
  }
}
```

## Available Tools

Once connected, the following tools are available to Claude:

- `datastore_get` - Retrieve an entity by key
- `datastore_put` - Create or update an entity
- `datastore_delete` - Delete an entity
- `datastore_query` - Query entities with filters and ordering
- `datastore_batch_get` - Retrieve multiple entities by keys
- `datastore_list_kinds` - List all entity kinds in the namespace

## Example Queries

Ask Claude to:
- "Get the User entity with ID 12345"
- "Query all Products where price > 100, ordered by name"
- "Create a new BlogPost entity with title and content"
- "Delete the Comment entity with ID abc123"
- "List all entity kinds in my datastore"

## Development

### Using Docker (Recommended)

```bash
# Run tests
make test

# Run tests with coverage
docker-compose run --rm test

# Start emulator only for local development
make emulator-only

# Interactive shell in container
make shell
```

### Using Local Python

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/datastore_mcp --cov-report=term-missing

# Run the server
python src/datastore_mcp/server.py
```

## Project Structure

```
datastore-mcp/
├── src/
│   └── datastore_mcp/
│       ├── server.py          # Main MCP server
│       ├── datastore.py       # Datastore client wrapper
│       └── tools.py           # Tool implementations
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md
```

## License

MIT License

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.