# MCP Datastore Server

A Model Context Protocol (MCP) server that provides access to Google Firestore in Datastore mode.

## Features

This MCP server exposes the following tools for interacting with Google Cloud Datastore:

### Entity Operations
- **datastore_get**: Get an entity by kind and key
- **datastore_insert**: Insert a new entity
- **datastore_update**: Update an existing entity
- **datastore_upsert**: Insert or update an entity
- **datastore_delete**: Delete an entity by kind and key

### Query Operations
- **datastore_query**: Query entities with filters and ordering
- **datastore_runAggregationQuery**: Run aggregation queries (count, sum, avg)
- **datastore_listKinds**: List all entity kinds (types) in the Datastore

### Key Operations
- **datastore_allocateIds**: Allocate IDs for incomplete keys
- **datastore_createKey**: Create a complete or incomplete key

### Transaction Operations
- **datastore_runInTransaction**: Execute multiple operations in a transaction

## Setup

### Prerequisites

1. A Google Cloud project with Datastore API enabled
2. Service account credentials with appropriate Datastore permissions

### Installation

```bash
npm install
npm run build
```

### Configuration

Set the following environment variables:

```bash
# Path to your service account JSON key file
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

# Your Google Cloud project ID
export GOOGLE_CLOUD_PROJECT=your-project-id
```

Or you can provide them when running the server:
```bash
GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json GOOGLE_CLOUD_PROJECT=your-project-id npm start
```

## Usage

### Running the Server

```bash
npm start
```

### Using with Claude Desktop

Add this to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "datastore": {
      "command": "node",
      "args": [
        "d:\\projects\\mcp-datastore\\build\\index.js"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "C:\\path\\to\\service-account-key.json",
        "GOOGLE_CLOUD_PROJECT": "your-project-id"
      }
    }
  }
}
```

## Tool Examples

### Get an Entity

```javascript
{
  "kind": "User",
  "keyId": "12345"
}
```

### Insert an Entity

```javascript
{
  "kind": "User",
  "data": {
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30
  }
}
```

### Query Entities

```javascript
{
  "kind": "User",
  "filters": [
    {
      "property": "age",
      "operator": ">",
      "value": 25
    }
  ],
  "orderBy": [
    {
      "property": "name",
      "descending": false
    }
  ],
  "limit": 10
}
```

### Run Aggregation Query

```javascript
{
  "kind": "Order",
  "aggregations": [
    {
      "type": "count",
      "alias": "total_orders"
    },
    {
      "type": "sum",
      "property": "amount",
      "alias": "total_amount"
    }
  ]
}
```

### List Entity Kinds

```javascript
{
  "namespace": "optional-namespace"  // Optional: specify namespace to list kinds from
}
```

This returns all entity kinds (types) in your Datastore, including both user-defined kinds and system metadata kinds (prefixed with `__Stat_`).

## License

MIT