@cityjson/cj-mcp 0.1.0

package/specs/index.json

@@ -0,0 +1,128 @@
+{
+  "version": "2.0.1",
+  "source": "https://www.cityjson.org/specs/2.0.1/",
+  "generated_at": "2025-12-20T12:19:52.522Z",
+  "chapters": [
+    {
+      "id": "profile-and-date",
+      "title": "Living Standard,\n    20 December 2025",
+      "path": "chapters/profile-and-date.md",
+      "order": 1,
+      "sections": []
+    },
+    {
+      "id": "cityjson-object",
+      "title": "1. CityJSON Object",
+      "path": "chapters/cityjson-object.md",
+      "order": 2,
+      "sections": []
+    },
+    {
+      "id": "the-different-city-objects",
+      "title": "2. The different City Objects",
+      "path": "chapters/the-different-city-objects.md",
+      "order": 3,
+      "sections": [
+        "2-1-attributes-for-all-city-objects",
+        "2-2-bridge",
+        "2-3-building",
+        "2-4-cityfurniture",
+        "2-5-cityobjectgroup",
+        "2-6-genericcityobject",
+        "2-7-landuse",
+        "2-8-otherconstruction",
+        "2-9-plantcover",
+        "2-10-solitaryvegetationobject",
+        "2-11-tinrelief",
+        "2-12-transportation",
+        "2-13-tunnel",
+        "2-14-waterbody"
+      ]
+    },
+    {
+      "id": "geometry-objects",
+      "title": "3. Geometry Objects",
+      "path": "chapters/geometry-objects.md",
+      "order": 4,
+      "sections": [
+        "3-1-coordinates-of-the-vertices",
+        "3-2-arrays-to-represent-boundaries",
+        "3-3-semantics-of-geometric-primitives",
+        "3-4-geometry-templates"
+      ]
+    },
+    {
+      "id": "transform-object",
+      "title": "4. Transform Object",
+      "path": "chapters/transform-object.md",
+      "order": 5,
+      "sections": []
+    },
+    {
+      "id": "metadata",
+      "title": "5. Metadata",
+      "path": "chapters/metadata.md",
+      "order": 6,
+      "sections": [
+        "5-1-geographicalextent-bbox",
+        "5-2-identifier",
+        "5-3-pointofcontact",
+        "5-4-referencedate",
+        "5-5-referencesystem-crs",
+        "5-6-title"
+      ]
+    },
+    {
+      "id": "appearance-object",
+      "title": "6. Appearance Object",
+      "path": "chapters/appearance-object.md",
+      "order": 7,
+      "sections": [
+        "6-1-geometry-object-having-material-s",
+        "6-2-geometry-object-having-texture-s",
+        "6-3-material-object",
+        "6-4-texture-object",
+        "6-5-vertices-texture-object"
+      ]
+    },
+    {
+      "id": "handling-large-files",
+      "title": "7. Handling large files",
+      "path": "chapters/handling-large-files.md",
+      "order": 8,
+      "sections": [
+        "7-1-decomposing-an-area-into-parts-tiles",
+        "7-2-text-sequences-and-streaming-with-cityjsonfeature"
+      ]
+    },
+    {
+      "id": "extensions",
+      "title": "8. Extensions",
+      "path": "chapters/extensions.md",
+      "order": 9,
+      "sections": [
+        "8-1-using-an-extension-in-a-cityjson-file",
+        "8-2-the-extension-file",
+        "8-3-case-1-adding-new-properties-at-the-root-of-a-document",
+        "8-4-case-2-defining-attributes-for-existing-city-objects",
+        "8-5-case-3-defining-a-new-semantic-object",
+        "8-6-case-4-creating-and-or-extending-new-city-objects",
+        "8-7-rules-to-follow-to-define-new-city-objects"
+      ]
+    },
+    {
+      "id": "cityjson-schemas",
+      "title": "9. CityJSON schemas",
+      "path": "chapters/cityjson-schemas.md",
+      "order": 10,
+      "sections": []
+    },
+    {
+      "id": "citygml-v30-implementation-details",
+      "title": "10. CityGML v3.0 implementation details",
+      "path": "chapters/citygml-v30-implementation-details.md",
+      "order": 11,
+      "sections": []
+    }
+  ]
+}

package/src/config.ts

@@ -0,0 +1,47 @@
+/**
+ * Configuration management
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_HTTP_PORT, SERVER_NAME, SERVER_VERSION } from "./constants.js";
+
+export interface ServerConfig {
+  name: string;
+  version: string;
+  specsPath: string;
+  transport: "stdio" | "http";
+  httpPort: number;
+}
+
+/**
+ * Find project root by looking for pnpm-workspace.yaml
+ */
+function findProjectRoot(startDir: string): string {
+  let current = startDir;
+  while (current !== "/" && !existsSync(resolve(current, "pnpm-workspace.yaml"))) {
+    current = dirname(current);
+  }
+  return current;
+}
+
+/**
+ * Load configuration from environment variables
+ */
+export function loadConfig(): ServerConfig {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const projectRoot = findProjectRoot(__dirname);
+
+  const specsPath = process.env.CITYJSON_SPECS_PATH || resolve(projectRoot, "specs");
+  const transport = (process.env.TRANSPORT as "stdio" | "http") || "stdio";
+  const httpPort = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : DEFAULT_HTTP_PORT;
+
+  return {
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+    specsPath,
+    transport,
+    httpPort,
+  };
+}

package/src/constants.ts

@@ -0,0 +1,7 @@
+/**
+ * Server constants
+ */
+
+export const SERVER_NAME = "cityjson-spec-mcp-server";
+export const SERVER_VERSION = "0.1.0";
+export const DEFAULT_HTTP_PORT = 3000;

package/src/index.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Entry point for MCP server
+ * Supports both stdio and HTTP transports
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+
+async function main(): Promise<void> {
+  const config = loadConfig();
+  const server = createServer(config);
+
+  if (config.transport === "stdio") {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("CityJSON Spec MCP Server running on stdio");
+    console.error(`Specs path: ${config.specsPath}`);
+  } else {
+    // HTTP transport - dynamically import to avoid loading express in stdio mode
+    const express = await import("express");
+    const { StreamableHTTPServerTransport } = await import(
+      "@modelcontextprotocol/sdk/server/streamableHttp.js"
+    );
+
+    const app = express.default();
+    app.use(express.json());
+
+    app.post("/mcp", async (req, res) => {
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+      });
+      res.on("close", () => transport.close());
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    });
+
+    // Health check endpoint for Cloud Run
+    app.get("/", (_req, res) => {
+      res.status(200).json({ status: "ok", service: "cityjson-spec-mcp" });
+    });
+
+    app.get("/health", (_req, res) => {
+      res.status(200).json({ status: "ok" });
+    });
+
+    app.listen(config.httpPort, () => {
+      console.error(`CityJSON Spec MCP Server running on http://localhost:${config.httpPort}`);
+      console.error(`Specs path: ${config.specsPath}`);
+    });
+  }
+}
+
+main().catch((error) => {
+  console.error("Failed to start server:", error);
+  process.exit(1);
+});

package/src/schemas/tool-schemas.ts

@@ -0,0 +1,26 @@
+/**
+ * Zod schemas for tool inputs
+ */
+
+import { z } from "zod";
+
+export const ReadOutlineInputSchema = z
+  .object({
+    include_sections: z
+      .boolean()
+      .default(true)
+      .describe("Include section headings within each chapter"),
+  })
+  .strict();
+
+export const ReadChapterInputSchema = z
+  .object({
+    chapter: z
+      .string()
+      .min(1)
+      .describe("Chapter identifier (e.g., 'metadata', 'city-objects', 'geometry-objects')"),
+  })
+  .strict();
+
+export type ReadOutlineInput = z.infer<typeof ReadOutlineInputSchema>;
+export type ReadChapterInput = z.infer<typeof ReadChapterInputSchema>;

package/src/server.ts

@@ -0,0 +1,38 @@
+/**
+ * MCP Server initialization and tool registration
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServerConfig } from "./config.js";
+import { ReadChapterInputSchema, ReadOutlineInputSchema } from "./schemas/tool-schemas.js";
+import { ChapterIndexService } from "./services/chapter-index.js";
+import { SpecLoader } from "./services/spec-loader.js";
+import { handleReadChapter, handleReadOutline } from "./tools/index.js";
+
+export function createServer(config: ServerConfig): McpServer {
+  const server = new McpServer(
+    { name: config.name, version: config.version },
+    { capabilities: { tools: {} } },
+  );
+
+  const indexService = new ChapterIndexService(config.specsPath);
+  const specLoader = new SpecLoader(config.specsPath);
+
+  // Register cityjson_read_spec_outline
+  server.tool(
+    "cityjson_read_spec_outline",
+    "Returns the table of contents for the CityJSON specification, including all chapters and their sections",
+    ReadOutlineInputSchema.shape,
+    async (params) => handleReadOutline(params, indexService),
+  );
+
+  // Register cityjson_read_spec_chapter
+  server.tool(
+    "cityjson_read_spec_chapter",
+    "Returns the full specification content for a specific chapter in Markdown format",
+    ReadChapterInputSchema.shape,
+    async (params) => handleReadChapter(params, specLoader, indexService),
+  );
+
+  return server;
+}

package/src/services/chapter-index.ts

@@ -0,0 +1,37 @@
+/**
+ * Chapter index service - manages the index.json file
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Chapter, ChapterIndex } from "../types.js";
+
+export class ChapterIndexService {
+  private index: ChapterIndex | null = null;
+  private specsPath: string;
+
+  constructor(specsPath: string) {
+    this.specsPath = specsPath;
+  }
+
+  async loadIndex(): Promise<ChapterIndex> {
+    if (this.index) {
+      return this.index;
+    }
+
+    const indexPath = join(this.specsPath, "index.json");
+    const content = await readFile(indexPath, "utf-8");
+    this.index = JSON.parse(content) as ChapterIndex;
+    return this.index;
+  }
+
+  async getChapterById(id: string): Promise<Chapter | undefined> {
+    const index = await this.loadIndex();
+    return index.chapters.find((c) => c.id === id);
+  }
+
+  async listChapterIds(): Promise<string[]> {
+    const index = await this.loadIndex();
+    return index.chapters.map((c) => c.id);
+  }
+}

package/src/services/spec-loader.ts

@@ -0,0 +1,31 @@
+/**
+ * Spec loader service - loads chapter Markdown files
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export class SpecLoader {
+  private cache: Map<string, string> = new Map();
+  private specsPath: string;
+
+  constructor(specsPath: string) {
+    this.specsPath = specsPath;
+  }
+
+  async loadChapter(chapterId: string): Promise<string> {
+    // Check cache first
+    const cached = this.cache.get(chapterId);
+    if (cached) {
+      return cached;
+    }
+
+    // Read from file
+    const chapterPath = join(this.specsPath, "chapters", `${chapterId}.md`);
+    const content = await readFile(chapterPath, "utf-8");
+
+    // Cache and return
+    this.cache.set(chapterId, content);
+    return content;
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Tool registration index
+ */
+
+export { handleReadOutline } from "./read-outline.js";
+export { handleReadChapter } from "./read-chapter.js";

package/src/tools/read-chapter.ts

@@ -0,0 +1,74 @@
+/**
+ * Implementation of cityjson_read_spec_chapter tool
+ */
+
+import type { ReadChapterInput } from "../schemas/tool-schemas.js";
+import type { ChapterIndexService } from "../services/chapter-index.js";
+import type { SpecLoader } from "../services/spec-loader.js";
+import type { ToolResult } from "../types.js";
+
+/**
+ * Normalize chapter ID for flexible matching:
+ * - lowercase
+ * - trim whitespace
+ * - replace spaces/underscores with hyphens
+ * - remove special characters
+ */
+function normalizeChapterId(id: string): string {
+  return id
+    .toLowerCase()
+    .trim()
+    .replace(/[\s_]+/g, "-") // spaces/underscores to hyphens
+    .replace(/[^a-z0-9-]/g, "") // remove special chars
+    .replace(/-+/g, "-") // collapse multiple hyphens
+    .replace(/^-|-$/g, ""); // trim leading/trailing hyphens
+}
+
+export async function handleReadChapter(
+  params: ReadChapterInput,
+  specLoader: SpecLoader,
+  indexService: ChapterIndexService,
+): Promise<ToolResult> {
+  const validChapters = await indexService.listChapterIds();
+  const normalizedInput = normalizeChapterId(params.chapter);
+
+  // Find matching chapter (exact or normalized match)
+  const matchedChapter = validChapters.find(
+    (chapterId) =>
+      chapterId === params.chapter || normalizeChapterId(chapterId) === normalizedInput,
+  );
+
+  if (!matchedChapter) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Chapter '${
+            params.chapter
+          }' not found. Valid chapters: ${validChapters.join(", ")}`,
+        },
+      ],
+    };
+  }
+
+  try {
+    const content = await specLoader.loadChapter(matchedChapter);
+
+    return {
+      content: [{ type: "text", text: content }],
+    };
+  } catch (error) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Error loading chapter '${matchedChapter}': ${
+            error instanceof Error ? error.message : "Unknown error"
+          }`,
+        },
+      ],
+    };
+  }
+}

package/src/tools/read-outline.ts

@@ -0,0 +1,44 @@
+/**
+ * Implementation of cityjson_read_spec_outline tool
+ */
+
+import type { ReadOutlineInput } from "../schemas/tool-schemas.js";
+import type { ChapterIndexService } from "../services/chapter-index.js";
+import type { ToolResult } from "../types.js";
+
+export async function handleReadOutline(
+  params: ReadOutlineInput,
+  indexService: ChapterIndexService,
+): Promise<ToolResult> {
+  try {
+    const index = await indexService.loadIndex();
+
+    const result = {
+      version: index.version,
+      total_chapters: index.chapters.length,
+      chapters: params.include_sections
+        ? index.chapters
+        : index.chapters.map((c) => ({
+            id: c.id,
+            title: c.title,
+            order: c.order,
+          })),
+    };
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  } catch (error) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Error loading specification index: ${
+            error instanceof Error ? error.message : "Unknown error"
+          }`,
+        },
+      ],
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Type definitions for mcp-server
+ */
+
+export interface Chapter {
+  id: string;
+  title: string;
+  path: string;
+  order: number;
+  sections: string[];
+}
+
+export interface ChapterIndex {
+  version: string;
+  source: string;
+  generated_at: string;
+  chapters: Chapter[];
+}
+
+export interface ToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  isError?: boolean;
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}

package/vite.config.ts

@@ -0,0 +1,47 @@
+import { resolve } from "node:path";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, "src/index.ts"),
+      formats: ["es"],
+      fileName: "index",
+    },
+    rollupOptions: {
+      external: [
+        // Node.js built-ins
+        /^node:/,
+        "http",
+        "http2",
+        "https",
+        "stream",
+        "crypto",
+        "fs",
+        "path",
+        "url",
+        "util",
+        "buffer",
+        "events",
+        "net",
+        "tls",
+        "os",
+        "zlib",
+        "child_process",
+        // External packages - externalize all dependencies
+        "@modelcontextprotocol/sdk",
+        /^@modelcontextprotocol\/sdk\/.*/,
+        "express",
+        "zod",
+        /^@hono\/.*/,
+        "hono",
+      ],
+    },
+    target: "node20",
+    outDir: "dist",
+    // Don't minify for Node.js
+    minify: false,
+    // Disable SSR-related optimizations
+    ssr: true,
+  },
+});