# CityJSON Specification MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with structured access to the [CityJSON specification](https://www.cityjson.org/specs/2.0.1/). Instead of feeding entire specifications to LLMs, this server enables AI to fetch specific chapters on demand.

## 📺 Demo


https://github.com/user-attachments/assets/91f0bd61-a313-441c-8def-4e07b8d125be


## 🚀 Quick Start

### Remote Server (Recommended)

Connect directly to the hosted server - no installation required:

```
https://your-cloud-run-url.run.app/mcp
```

Alternatively, use the community-hosted instance (subject to availability and resource constraints):

```
https://cj-mcp-264879243442.europe-west4.run.app/mcp
```

### Local Installation

Run locally using npx:

```bash
npx @cityjson/cj-mcp@latest
```

Or install globally:

```bash
npm install -g @cityjson/cj-mcp@latest
cityjson-spec-mcp
```

## 🛠️ Installation

<details>
<summary>Cursor</summary>

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "cityjson-spec": {
      "command": "npx",
      "args": ["-y", "@cityjson/cj-mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary>Claude Desktop</summary>

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "cityjson-spec": {
      "command": "npx",
      "args": ["-y", "@cityjson/cj-mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary>VS Code</summary>

Add to your VS Code settings:

```json
{
  "mcp": {
    "servers": {
      "cityjson-spec": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@cityjson/cj-mcp@latest"]
      }
    }
  }
}
```

</details>

<details>
<summary>Windsurf</summary>

Add to your Windsurf MCP config:

```json
{
  "mcpServers": {
    "cityjson-spec": {
      "command": "npx",
      "args": ["-y", "@cityjson/cj-mcp@latest"]
    }
  }
}
```

</details>

## 🔨 Available Tools

### `cityjson_read_spec_outline`

Returns the specification outline with all chapters and sections.

**Parameters:**

- `include_sections` (boolean, optional): Include section headings within each chapter. Default: `true`

**Example Response:**

```json
{
  "version": "2.0.1",
  "total_chapters": 12,
  "chapters": [
    {
      "id": "introduction",
      "title": "Introduction",
      "order": 1,
      "sections": ["overview", "design-goals", "file-extension"]
    }
  ]
}
```

### `cityjson_read_spec_chapter`

Returns the full Markdown content for a specific chapter.

**Parameters:**

- `chapter` (string, required): Chapter identifier (e.g., `"metadata"`, `"city-objects"`)

**Example:**

```json
{
  "chapter": "metadata"
}
```

## 💻 Development

```bash
# Clone with submodules
git clone --recurse-submodules https://github.com/cityjson/cityjson-spec-mcp.git
cd cityjson-spec-mcp

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Convert specification (requires uv/bikeshed)
pnpm convert-spec

# Start MCP server (stdio mode)
pnpm start:stdio

# Start MCP server (HTTP mode)
pnpm start:http

# Lint and format
pnpm lint
pnpm lint:fix
```

## 📦 Project Structure

```
cityjson-spec-mcp/
├── packages/
│   ├── spec-converter/     # Bikeshed → Markdown converter
│   └── mcp-server/         # MCP server implementation
├── specs/                  # Generated specification files
│   ├── index.json          # Chapter metadata index
│   └── chapters/           # Individual chapter Markdown files
├── vendor/
│   └── cityjson-specs/     # Git submodule (CityJSON spec repo)
└── Dockerfile              # Container for Cloud Run deployment
```

## 📄 License

MIT

## 🔗 Resources

- [CityJSON Official Website](https://www.cityjson.org)
- [CityJSON Specification](https://www.cityjson.org/specs/2.0.1/)
- [Model Context Protocol](https://modelcontextprotocol.io/)