Metadata-Version: 2.4
Name: 3dcitydb-mcp-server
Version: 0.1.1
Summary: MCP server for natural-language querying of 3DCityDB v5 semantic city models
Project-URL: Homepage, https://github.com/tum-gis/3dcitydb-mcp-server
Project-URL: Documentation, https://github.com/tum-gis/3dcitydb-mcp-server#readme
Project-URL: Issues, https://github.com/tum-gis/3dcitydb-mcp-server/issues
Project-URL: Repository, https://github.com/tum-gis/3dcitydb-mcp-server
Project-URL: Changelog, https://github.com/tum-gis/3dcitydb-mcp-server/blob/main/CHANGELOG.md
Author-email: Khaoula Kanna <khaoula.kanna@tum.de>
License-Expression: Apache-2.0
License-File: LICENCE
Keywords: 3d-city-models,3dcitydb,citygml,gis,llm,mcp,model-context-protocol,spatial-database
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: sqlglot>=23.0
Requires-Dist: starlette>=0.36.0
Requires-Dist: uvicorn>=0.27.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# 3DCityDB MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives AI assistants (Claude Code, Claude Desktop, and any MCP-compatible client) direct, intelligent access to **3DCityDB v5** semantic city models.

It dynamically resolves object classes, properties, codelists, and generic attributes from the database so the AI can answer spatial questions, write and execute SQL queries, and reason about CityGML data — without any manual prompt engineering.

## Features

- **Dynamic schema resolution** — walks the CityGML class hierarchy to discover available object classes and their properties
- **Property filtering** — only includes properties that actually exist in the database (CityGML schema → 3DCityDB instance → populated attributes)
- **Codelist resolution** — fetches code meanings only for codes present in the DB
- **Generic attribute enrichment** — automatic categorical detection for generic attributes
- **Read-only query execution** — `run_query` enforces SELECT-only; writes are blocked
- **Prompt assembly** — `assemble_prompt` orchestrates all tools into a complete system prompt in one call

## Prerequisites

- Python 3.10+
- A running **3DCityDB v5** PostgreSQL instance with PostGIS

## Installation

```bash
pip install 3dcitydb-mcp-server
```

Or, to install from source for development:

```bash
git clone https://github.com/tum-gis/3dcitydb-mcp-server.git
cd 3dcitydb-mcp-server/mcp-server
pip install -e .
```

## Configuration

Copy the example environment file and edit it:

```bash
# Linux / macOS
cp .env.example .env

# Windows (PowerShell)
Copy-Item .env.example .env
```

Then fill in your 3DCityDB connection details:

```env
# --- 3DCityDB PostgreSQL connection ---
CITYDB_HOST=localhost
CITYDB_PORT=5432
CITYDB_NAME=citydb
CITYDB_USER=postgres
CITYDB_PASSWORD=your_password_here
CITYDB_SCHEMA=citydb

# --- Query behaviour (optional) ---
CATEGORICAL_THRESHOLD=20
SAMPLE_VALUES_COUNT=5
```

The server loads `.env` automatically by searching upward from the working directory, so no extra setup is needed.

## Running

### 1. Verify your installation

```bash
3dcitydb-doctor
```

Checks Python version, all required packages, database connectivity, PostGIS/SFCGAL extensions, and 3DCityDB v5 schema. Exits 0 if all critical checks pass.

### 2. Connect to Claude Code (recommended)

From your project directory (where your `.env` lives):

```bash
claude mcp add 3dcitydb -- 3dcitydb-mcp
```

Then start a session:

```bash
claude
```

The MCP server starts automatically. Use `/mcp` inside the session to confirm it is connected.

### 3. Connect to Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "3dcitydb": {
      "command": "3dcitydb-mcp",
      "cwd": "/path/to/your/project"
    }
  }
}
```

### 4. SSE transport (remote / production)

```bash
3dcitydb-mcp-sse --host 0.0.0.0 --port 8080
```

Clients connect via: `http://your-server:8080/sse`  
Health check: `http://your-server:8080/health`

### 5. Docker

```bash
docker build -t 3dcitydb-mcp .
docker run -p 8080:8080 --env-file .env 3dcitydb-mcp
```

## Available MCP Tools

### Static (cached per session)
| Tool | Description |
|------|-------------|
| `get_database_schema` | 3DCityDB v5 table structures and foreign key relationships |
| `get_query_guidelines` | SQL best practices and optimization tips for 3DCityDB |

### Dynamic (called at session start)
| Tool | Description |
|------|-------------|
| `scan_objectclasses` | Discover available object classes with full hierarchy |
| `resolve_properties(objectclass_id)` | Resolve properties with codelists for a given class |
| `get_generic_attributes` | Generic attributes with categorical detection |
| `get_db_context_snapshot` | SRS, bounding box, feature counts, statistics |
| `get_lod_config` | Available Levels of Detail in the database |
| `get_examples(objectclass_ids)` | SQL examples filtered to existing object classes |

### Runtime (per query)
| Tool | Description |
|------|-------------|
| `run_query(sql)` | Execute read-only SQL (SELECT/WITH only) against 3DCityDB |
| `get_session_context` | Session management |
| `update_module_selection` | Narrow scope to specific object classes |
| `get_history` | Conversation history for a session |
| `submit_feedback` | Log query feedback |

### Assembly
| Tool | Description |
|------|-------------|
| `assemble_prompt` | Orchestrates all tools into a complete system prompt |

## Architecture

```
  Claude Code / Claude Desktop / any MCP client
                      |
               MCP Protocol (stdio / SSE)
                      |
       +--------------+--------------+
       |   3DCityDB MCP Server       |
       |   assemble_prompt()         |
       |   scan_objectclasses()      |
       |   run_query()               |
       +--------------+--------------+
                      |
                 3DCityDB v5
               (PostgreSQL + PostGIS)
```

## License

The 3DCityDB MCP server is distributed under the Apache License 2.0. See LICENCE for more information.
