cj-mcp: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server that provides AI assistants with structured access to the CityJSON specification. The project converts the CityJSON Bikeshed specification into chapter-separated Markdown files and exposes them through MCP tools for efficient LLM consumption.

Architecture

Monorepo Structure

This project uses a pnpm workspace monorepo with two main packages:

1. spec-converter: Converts Bikeshed (.bs) → HTML → Markdown chapters
2. mcp-server: Serves specification chapters via MCP protocol

Key Design Principles

• On-Demand Loading: AI fetches specific chapters instead of entire spec
• Two-Stage Conversion: Bikeshed → HTML (via uvx) → Markdown (via Turndown)
• Multi-Transport: Supports both stdio (local) and HTTP (remote) modes
• Chapter-Based: Specification split into digestible chapters with metadata

Project Structure

cityjson-spec-mcp/
├── package.json                # Root workspace config
├── pnpm-workspace.yaml         # Workspace definition
├── biome.json                  # Linter/formatter config
├── tsconfig.base.json          # Shared TypeScript config
├── vendor/
│   └── cityjson-specs/         # Git submodule (CityJSON spec repo)
├── 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
└── scripts/
    └── convert-spec.ts         # Conversion orchestration

Development Commands

# Install dependencies (uses pnpm)
pnpm install

# Build all packages
pnpm build

# Build specific package
pnpm --filter mcp-server build
pnpm --filter spec-converter build

# Convert specification (Bikeshed → Markdown)
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
pnpm format

# Development mode with watch
pnpm dev