# Kolkata Puja Tourist MCP Server

An open-source **Model Context Protocol (MCP) server** that provides structured Kolkata Durga Puja tourism information to AI assistants. The server exposes pandal, metro, route, restaurant, and restaurant-opening-hours tools so an AI chatbot can answer tourist queries using the project's curated datasets and external routing services.

**Developed at JANTRAM LAB, under the guidance of Dr. Ritesh Sarkhel.**

## Overview

The **Kolkata Puja Tourist MCP Server** is designed as the tool/data layer behind an AI tourist assistant.

```text
Tourist
   ↓
AI Chatbot / LLM
   ↓
MCP Client
   ↓
Kolkata Puja Tourist MCP Server
   ├── Pandal Dataset
   ├── Metro Dataset
   ├── Restaurant Dataset
   ├── OpenStreetMap
   └── OSRM Routing Service
```

The project focuses on making Kolkata Durga Puja information accessible to an AI assistant through well-defined MCP tools rather than implementing the chatbot itself.

## Problem

During Durga Puja, tourists may need to answer questions such as:

- Which pandals are in a particular area?
- Which pandals are close to another pandal?
- Which metro station is nearest to a pandal?
- What is the route between two or more pandals?
- Which restaurants are nearby?
- Is a restaurant listed as open at a particular date and time?
- How can a multi-stop Puja visit be planned?

The MCP server provides structured functions for these tasks so an MCP-compatible AI assistant can access the project's tourism data and services.

## Features

- Search and retrieve Durga Puja pandal information.
- Find pandals within a specified radius.
- Find pandals near a named pandal using the exact coordinates stored in the dataset.
- Find the nearest Metro station to a location or named pandal.
- Calculate driving routes between pandals.
- Create a multi-stop driving route in the order supplied by the user.
- Search for restaurants.
- Find restaurants near a location or named pandal.
- Check restaurant opening hours for a specified date and time.
- Expose project datasets as MCP resources.
- Integrate with Claude Desktop through a local MCP server.
- Validate dataset structure, IDs, and coordinates at startup.
- Provide clearer OSRM/network error reporting.
- Include automated tests for core MCP functionality.

## Technology Stack

- **Python**
- **MCP Python SDK**
- **Claude Desktop** for AI-client integration and testing
- **OpenStreetMap (OSM)** for open geographic, restaurant, and metro data
- **OSRM** for driving-route calculation
- **JSON** datasets for project data
- **Pytest** for automated testing

## Project Structure

```text
kolkata-puja-mcp/
│
├── src/
│   ├── server.py
│   └── client.py
│
├── data/
│   ├── pandals_2026.json
│   ├── metro_stations.json
│   └── restaurants.json
│
├── tests/
│   ├── test_server.py
│   └── test_named_location_tools.py
│
├── README.md
├── evaluation.md
├── requirements.txt
├── requirements-dev.txt
├── .gitignore
└── LICENSE
```

## MCP Tools

The current server exposes **12 MCP tools**.

| Tool | Purpose |
|---|---|
| `get_pandal_details` | Returns dataset-backed details for a specific pandal. |
| `search_pandals` | Searches the pandal dataset by name, area, address, or zone. |
| `find_nearby_pandals` | Finds pandals within a specified radius of latitude/longitude. |
| `find_nearby_pandals_by_name` | Finds pandals near a named pandal using its exact dataset coordinates. |
| `get_nearest_metro` | Finds the nearest Metro station to a geographic coordinate. |
| `get_nearest_metro_by_pandal` | Finds the nearest Metro station using a pandal's exact dataset coordinates. |
| `get_route_between_pandals` | Calculates a driving route between two pandals using OSRM. |
| `plan_puja_route` | Calculates a multi-stop driving route through supplied pandal IDs in the given order. |
| `search_restaurants` | Searches the restaurant dataset by name, area, address, or cuisine. |
| `find_nearby_restaurants` | Finds restaurants near a geographic coordinate. |
| `find_nearby_restaurants_by_pandal` | Finds restaurants near a named pandal using its exact dataset coordinates. |
| `get_restaurant_availability` | Checks whether a restaurant is listed as open at a specified date/time using recorded opening hours. |

## MCP Resources

The server exposes **3 MCP resources**:

| Resource | Description |
|---|---|
| `puja://2026/pandals` | 2026 Kolkata Durga Puja pandal dataset. |
| `puja://transport` | Metro station geographic dataset used by the server. |
| `puja://restaurants` | Restaurant dataset with recorded opening hours and provenance information. |

## Data Sources

### Pandal Data

The 2026 pandal dataset currently contains records identified as `P001` through `P021`.

The dataset source is recorded as:

```text
PujoKolkata 2026
```

The project retains source/provenance information with the dataset and does not present the pandal records as a complete or universally official list of all Kolkata pandals.

Popularity-based ranking is **not currently implemented** because the current dataset does not contain a reliable popularity field.

### Metro Data

Metro station data was collected from **OpenStreetMap** using Overpass-style geographic queries and cleaned for use by the MCP server.

The current cleaned dataset represents physical station records and merges obvious duplicate interchange entries where appropriate.

Metro/nearby distances calculated by the server are **straight-line geographic distances** from station coordinates. They are not walking distances.

### Restaurant Data

Restaurant data was collected from **OpenStreetMap** and includes fields such as:

- Restaurant name
- Latitude/longitude
- Opening hours
- Address, when available
- Cuisine, when available
- Source
- OSM license/provenance information
- Check date, when present in the source data

OpenStreetMap data is licensed under the **Open Database License (ODbL)**. See the attribution section below.

Restaurant opening-hours checks are based on recorded dataset values and are **not live restaurant status or reservation availability**.

## Installation

### 1. Clone the repository

```bash
git clone <YOUR_GITHUB_REPOSITORY_URL>
cd kolkata-puja-mcp
```

### 2. Create a virtual environment

Windows PowerShell:

```powershell
python -m venv .venv
.venv\\Scripts\\Activate.ps1
```

Windows Command Prompt:

```cmd
python -m venv .venv
.venv\\Scripts\\activate
```

Linux/macOS:

```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 3. Install runtime dependencies

```bash
pip install -r requirements.txt
```

### 4. Install development/test dependencies

```bash
pip install -r requirements-dev.txt
```

## Running the MCP Server

The server can be launched using the MCP command-line interface:

```bash
mcp run src/server.py
```

The server uses **stdio** transport, so it normally waits for an MCP client rather than displaying a conventional web-server page.

## Running the MCP Client

The included client can be started with:

```bash
python src/client.py
```

The client connects to the local MCP server and can list and call available tools and resources.

## Claude Desktop Integration

The project has been tested with Claude Desktop using a local MCP configuration.

A typical configuration is:

```json
{
  "mcpServers": {
    "kolkata-puja": {
      "command": "D:\\kolkata-puja-mcp\\.venv\\Scripts\\mcp.exe",
      "args": [
        "run",
        "D:\\kolkata-puja-mcp\\src\\server.py"
      ]
    }
  }
}
```

Change the paths to match the local installation.

After restarting Claude Desktop, the `kolkata-puja` MCP server should appear in the connected/local MCP tools area.

For controlled MCP evaluation, Web Search can be disabled so that responses are based on the connected project context rather than competing web-search results.

### Natural-language usage

The intended user experience does **not** require a tourist to mention MCP or tool names. A tourist can ask ordinary questions such as:

```text
What Durga Puja pandals are within 2 km of Deshapriya Park?
```

The AI client may decide whether to invoke an MCP tool or use available MCP resource context. Tool invocation is model/client-selected and is not guaranteed for every query.

## Example Tourist Queries

```text
Show me Durga Puja pandals in Kalighat.
```

```text
Tell me about Deshapriya Park.
```

```text
What pandals are within 2 km of Deshapriya Park?
```

```text
Which metro station is nearest to Deshapriya Park?
```

```text
Find restaurants near Deshapriya Park.
```

```text
Is Prema Vilas open at 8 PM on September 22, 2026?
```

```text
Give me a driving route from Deshapriya Park to Hindustan Park.
```

```text
Plan a driving route through Deshapriya Park, Hindustan Park, and Ekdalia Evergreen Club.
```

## Testing and Evaluation

### Automated Tests

The final project includes automated tests covering:

- Pandal lookup
- Unknown pandal handling
- Pandal search
- Nearby pandal search
- Named-pandal nearby search
- Metro lookup
- Named-pandal Metro lookup
- Route handling
- Multi-stop route handling
- Restaurant search
- Nearby restaurant search
- Named-pandal restaurant search
- Restaurant opening-hours evaluation
- Unknown restaurant handling
- Dataset validation
- Duplicate-ID validation
- Coordinate validation
- Routing error handling

Final automated test result:

```text
24 passed
```

### Natural-language Evaluation

The MVP was also evaluated through Claude Desktop using natural-language tourist queries.

The evaluation covered:

- Pandal search and details
- Nearby pandals
- Nearest Metro
- Driving routes
- Multi-stop routing
- Restaurant search
- Nearby restaurants
- Timestamp-based restaurant opening-hours checks
- Combined multi-tool tourist queries
- Unknown records
- Grounding behavior

See [`evaluation.md`](evaluation.md) for the detailed evaluation report.

### Important Evaluation Observation

Two concepts should be distinguished:

1. **Answer correctness**
2. **Explicit MCP tool invocation**

An MCP-compatible LLM may sometimes answer correctly from available MCP resource context without explicitly calling a matching tool. The tools remain available and function correctly when invoked.

The final evaluation confirmed that the MCP tools themselves are functioning correctly, while model-side tool selection can vary by query and conversational context.

## Data and Geographic Semantics

### Nearby and Metro distance

Nearby-pandal, nearby-restaurant, and nearest-Metro calculations use **straight-line geographic distance** based on coordinates.

These values are not walking distances or road distances.

### Routing

OSRM currently uses its **driving** profile.

Therefore:

- route distances are driving-route distances
- route durations are driving-time estimates
- walking routes are not implemented
- cycling routes are not implemented
- public-transit routing is not implemented

### Named-location handling

When a user names a pandal, the named-location tools resolve that pandal against the project's dataset and use the stored coordinates rather than estimating coordinates from general knowledge.

## Known Limitations

### 1. Pandal popularity

Popularity/ranking is **not currently implemented**. The server must not invent popularity scores or claims that are not present in the dataset.

### 2. Dataset scope

The current MVP uses curated project datasets. Coverage may not represent every Kolkata Durga Puja pandal, restaurant, or all Metro metadata.

### 3. Restaurant availability

Restaurant opening-hour checks use recorded `opening_hours` values. They do not provide live operational status or reservation availability.

### 4. Opening-hours parser

The current parser supports a practical subset of common OpenStreetMap `opening_hours` expressions. More complex schedules may return `unknown`.

### 5. Routing profile

Routing currently uses OSRM's driving profile only.

### 6. Route optimization

`plan_puja_route` follows the order supplied by the caller. It does not automatically optimize stop order.

### 7. Live information

The current MVP does not provide:

- Live crowd information
- Live restaurant status
- Live restaurant reservations
- Live Metro service status
- Real-time road-closure information

### 8. Automatic current location

The geographic tools accept coordinates. Automatic access to a tourist's live GPS location is not implemented inside the MCP server.

### 9. LLM tool selection

The LLM/client decides when to invoke an MCP tool. A matching tool being available does not guarantee explicit tool invocation for every natural-language query.

## Future Improvements

Possible extensions include:

- Add a reliable, sourced popularity metric for pandals.
- Add more verified pandal records.
- Add richer pandal metadata such as themes and visiting information when reliable sources are available.
- Add Metro line information and interchange metadata.
- Add walking and public-transport routing.
- Improve multi-stop route optimization.
- Implement more complete OSM `opening_hours` parsing.
- Integrate live restaurant availability where an appropriate API is available.
- Add richer tourist itinerary planning.
- Add stronger application-level response-grounding safeguards.
- Add CI checks for Python syntax and dataset validity.

## OpenStreetMap Attribution

This project uses data from **OpenStreetMap**.

OpenStreetMap data is available under the **Open Database License (ODbL)**.

For more information:

```text
https://www.openstreetmap.org/copyright
```

The project should retain appropriate attribution and comply with ODbL requirements when redistributing or using derived OSM data.

## Project Status

**Status: Functional MVP**

The current implementation provides:

- MCP server architecture
- 12 MCP tools
- 3 MCP resources
- Pandal, Metro, and restaurant datasets
- Dataset validation
- OSRM driving-route integration
- Restaurant opening-hours evaluation
- Named-location geographic tools
- Claude Desktop integration
- Automated testing with 24 passing tests
- Evaluation documentation

The main explicitly unimplemented feature from the original project requirements is **popularity-based pandal ranking**, because a reliable popularity data source has not yet been added.