# Italian Cities MCP Server

A Model Context Protocol (MCP) server for managing Italian cities with CRUD operations backed by Elasticsearch.

## Architecture

The project consists of three main components:

1. **Elasticsearch Database**: Stores Italian cities data with a simple schema (city name only)
2. **CRUD API Server**: Express.js REST API for managing cities
3. **MCP Server**: MCP interface that communicates with the CRUD API to provide tools for AI assistants

```
┌─────────────────┐
│   MCP Server    │
│  (stdio mode)   │
└────────┬────────┘
         │ HTTP
         ▼
┌─────────────────┐
│   CRUD API      │
│  (Express.js)   │
└────────┬────────┘
         │ REST
         ▼
┌─────────────────┐
│ Elasticsearch   │
│   (Database)    │
└─────────────────┘
```

## Prerequisites

- Node.js 20+
- Docker and Docker Compose
- npm or yarn

## Installation

1. Clone the repository and install dependencies:

```bash
npm install
```

2. Create environment file:

```bash
cp .env.example .env
```

3. Build the TypeScript code:

```bash
npm run build
```

## Running with Docker

### Start all services (Elasticsearch + CRUD API)

```bash
npm run docker:up
```

This will:
- Start Elasticsearch on port 9200
- Start the CRUD API on port 3000
- Create the index and initialize the database with 30 Italian cities

### Check logs

```bash
npm run docker:logs
```

### Stop services

```bash
npm run docker:down
```

## Running Locally (Development)

### Option 1: Docker for Elasticsearch only

1. Start only Elasticsearch:

```bash
docker-compose up -d elasticsearch
```

2. Run the CRUD API in development mode:

```bash
npm run dev:api
```

### Option 2: All local (requires local Elasticsearch)

Ensure Elasticsearch is running locally on port 9200, then:

```bash
npm run dev:api
```

## CRUD API Endpoints

The API server runs on `http://localhost:3000` by default.

### Health Check

```bash
GET /health
```

### Cities Endpoints

- **Create a city**
  ```bash
  POST /api/cities
  Content-Type: application/json

  {"nome": "Venezia"}
  ```

- **Get all cities**
  ```bash
  GET /api/cities
  ```

- **Get city by ID**
  ```bash
  GET /api/cities/:id
  ```

- **Search cities by name**
  ```bash
  GET /api/cities/search/:name
  ```

- **Update a city**
  ```bash
  PUT /api/cities/:id
  Content-Type: application/json

  {"nome": "Venezia Mestre"}
  ```

- **Delete a city**
  ```bash
  DELETE /api/cities/:id
  ```

## MCP Server

### Running the MCP Server

For development (with auto-reload):

```bash
npm run dev:mcp
```

For production:

```bash
npm run start:mcp
```

### Configuring in 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": {
    "varolio-cities": {
      "command": "node",
      "args": [
        "/absolute/path/to/varolio/dist/mcp-server/index.js"
      ]
    }
  }
}
```

Or for development with tsx:

```json
{
  "mcpServers": {
    "varolio-cities": {
      "command": "npx",
      "args": [
        "tsx",
        "/absolute/path/to/varolio/src/mcp-server/index.ts"
      ]
    }
  }
}
```

**Important**: Ensure the CRUD API server is running before using the MCP server.

## MCP Tools

The MCP server provides the following tools:

### 1. `create_city`
Create a new Italian city in the database.

**Parameters:**
- `nome` (string, required): Name of the Italian city

**Example:**
```
Create a new city called "Siena"
```

### 2. `list_cities`
List all Italian cities in the database.

**Example:**
```
Show me all cities in the database
```

### 3. `get_city`
Get a specific Italian city by ID.

**Parameters:**
- `id` (string, required): ID of the city

**Example:**
```
Get the city with ID "abc123"
```

### 4. `search_cities`
Search for Italian cities by name (supports fuzzy matching).

**Parameters:**
- `name` (string, required): Name or partial name to search

**Example:**
```
Search for cities named "Milan"
```

### 5. `update_city`
Update an existing Italian city name.

**Parameters:**
- `id` (string, required): ID of the city to update
- `nome` (string, required): New name for the city

**Example:**
```
Update city with ID "abc123" to "Milano"
```

### 6. `delete_city`
Delete an Italian city from the database.

**Parameters:**
- `id` (string, required): ID of the city to delete

**Example:**
```
Delete the city with ID "abc123"
```

## Database Initialization

The database is automatically initialized with 30 major Italian cities when the CRUD API starts for the first time. Cities include: Roma, Milano, Napoli, Torino, Palermo, Genova, Bologna, Firenze, and more.

To manually reinitialize the database:

```bash
npm run init:db
```

## Project Structure

```
varolio/
├── src/
│   ├── types/              # TypeScript type definitions
│   ├── elasticsearch/      # Elasticsearch client and utilities
│   ├── crud-api/           # Express.js REST API
│   └── mcp-server/         # MCP server implementation
├── data/
│   └── init-cities.json    # Initial cities data
├── docker-compose.yml      # Docker orchestration
├── Dockerfile              # Node.js backend container
├── package.json            # Dependencies and scripts
└── tsconfig.json           # TypeScript configuration
```

## Environment Variables

- `ELASTICSEARCH_HOST`: Elasticsearch host URL (default: http://localhost:9200)
- `ELASTICSEARCH_INDEX`: Index name for cities (default: citta_italiane)
- `API_PORT`: CRUD API port (default: 3000)
- `API_HOST`: CRUD API host (default: localhost)
- `NODE_ENV`: Node environment (default: development)

## Development

### Watch mode for API
```bash
npm run dev:api
```

### Watch mode for MCP server
```bash
npm run dev:mcp
```

### Build TypeScript
```bash
npm run build
```

## License

MIT