MCP 服务器

Italian Cities MCP Server

Provides CRUD tools for managing a database of Italian cities backed by Elasticsearch. It enables AI assistants to search, create, update, and delete city records through a standardized Model Context Protocol interface.

README

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:

Elasticsearch Database: Stores Italian cities data with a simple schema (city name only)
CRUD API Server: Express.js REST API for managing cities
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

Clone the repository and install dependencies:

npm install

Create environment file:

cp .env.example .env

Build the TypeScript code:

npm run build

Running with Docker

Start all services (Elasticsearch + CRUD API)

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

npm run docker:logs

Stop services

npm run docker:down

Running Locally (Development)

Option 1: Docker for Elasticsearch only

Start only Elasticsearch:

docker-compose up -d elasticsearch

Run the CRUD API in development mode:

npm run dev:api

Option 2: All local (requires local Elasticsearch)

Ensure Elasticsearch is running locally on port 9200, then:

npm run dev:api

CRUD API Endpoints

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

Health Check

GET /health

Cities Endpoints

Create a city

POST /api/cities
Content-Type: application/json

{"nome": "Venezia"}

Get all cities
```
GET /api/cities
```
Get city by ID
```
GET /api/cities/:id
```
Search cities by name
```
GET /api/cities/search/:name
```

Update a city

PUT /api/cities/:id
Content-Type: application/json

{"nome": "Venezia Mestre"}

Delete a city
```
DELETE /api/cities/:id
```

MCP Server

Running the MCP Server

For development (with auto-reload):

npm run dev:mcp

For production:

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

{
  "mcpServers": {
    "varolio-cities": {
      "command": "node",
      "args": [
        "/absolute/path/to/varolio/dist/mcp-server/index.js"
      ]
    }
  }
}

Or for development with tsx:

{
  "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:

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