# 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
