# Hong Kong Catholic Mass Schedule MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides Hong Kong Catholic mass schedule data, deployed as a stateless [Cloudflare Worker](https://workers.cloudflare.com/).

This server allows AI assistants (such as Claude) to look up mass times, find churches by region or language, and get detailed parish information for the Catholic Diocese of Hong Kong.

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `search_churches` | Search and filter churches by region, mass language, and/or day of the week |
| `get_church_details` | Get full details of a specific church by its ID or name |
| `find_mass_by_time` | Find masses happening at or around a specific time on a given day |
| `list_regions` | List all regions in the Diocese with their church counts |

### Tool Examples

**search_churches**
- Find all churches in Kowloon: `{ "region": "Kowloon" }`
- Find churches with English Sunday mass: `{ "language": "English", "day": "Sunday" }`

**get_church_details**
- By ID: `{ "query": "cathedral-of-the-immaculate-conception" }`
- By name: `{ "query": "rosary" }`

**find_mass_by_time**
- Sunday morning masses around 10am: `{ "day": "Sunday", "time": "10:00" }`
- English masses on Sunday: `{ "day": "Sunday", "language": "English" }`

**list_regions**
- No parameters required: `{}`

## Setup and Local Development

### Prerequisites

- Node.js 18+
- npm

### Install Dependencies

```bash
npm install
```

### Run Locally

```bash
npm run dev
```

The server will start at `http://localhost:8787`. The MCP endpoint is available at `http://localhost:8787/mcp`.

### Type Checking

```bash
npm run typecheck
```

### Build (Dry Run)

```bash
npm run build
```

## Connecting to AI Assistants

### Claude Desktop

Add this to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "hk-catholic-mass-schedule": {
      "url": "https://hk-catholic-mass-schedule-mcp.<your-subdomain>.workers.dev/mcp"
    }
  }
}
```

### Cursor

In Cursor settings, add an MCP server with the URL:

```
https://hk-catholic-mass-schedule-mcp.<your-subdomain>.workers.dev/mcp
```

### Local Development

For local testing, use:

```json
{
  "mcpServers": {
    "hk-catholic-mass-schedule": {
      "url": "http://localhost:8787/mcp"
    }
  }
}
```

## Deploy to Cloudflare Workers

```bash
npx wrangler deploy
```

This will deploy the worker to your Cloudflare account. Make sure you have authenticated with `npx wrangler login` first.

## Data Coverage

The server includes static data for **47 churches** across all 4 regions of the Catholic Diocese of Hong Kong:

- **Hong Kong Island** - 13 churches
- **Kowloon** - 14 churches
- **New Territories** - 17 churches
- **Outlying Islands** - 3 churches

Mass schedule data includes:
- Sunday masses (multiple time slots, various languages)
- Weekday masses (Monday through Saturday)
- Saturday vigil masses
- Confession times

Languages covered: Cantonese, English, Mandarin, Filipino, Korean

## Data Source and Disclaimer

Mass schedule data is sourced from the **Catholic Diocese of Hong Kong** ([https://catholic.org.hk](https://catholic.org.hk)).

**Important:** Schedule data is static and may not reflect the latest changes. Mass times can change due to holidays, special celebrations, or parish decisions. Please always verify with the parish directly before attending.

## License

MIT License - see [LICENSE](LICENSE) for details.