@cityjson/cj-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { existsSync } from "node:fs";
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+const SERVER_NAME = "cityjson-spec-mcp-server";
+const SERVER_VERSION = "0.1.0";
+const DEFAULT_HTTP_PORT = 3e3;
+function findProjectRoot(startDir) {
+  let current = startDir;
+  while (current !== "/" && !existsSync(resolve(current, "pnpm-workspace.yaml"))) {
+    current = dirname(current);
+  }
+  return current;
+}
+function loadConfig() {
+  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 || "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
+  };
+}
+const ReadOutlineInputSchema = z.object({
+  include_sections: z.boolean().default(true).describe("Include section headings within each chapter")
+}).strict();
+const ReadChapterInputSchema = z.object({
+  chapter: z.string().min(1).describe("Chapter identifier (e.g., 'metadata', 'city-objects', 'geometry-objects')")
+}).strict();
+class ChapterIndexService {
+  index = null;
+  specsPath;
+  constructor(specsPath) {
+    this.specsPath = specsPath;
+  }
+  async loadIndex() {
+    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);
+    return this.index;
+  }
+  async getChapterById(id) {
+    const index = await this.loadIndex();
+    return index.chapters.find((c) => c.id === id);
+  }
+  async listChapterIds() {
+    const index = await this.loadIndex();
+    return index.chapters.map((c) => c.id);
+  }
+}
+class SpecLoader {
+  cache = /* @__PURE__ */ new Map();
+  specsPath;
+  constructor(specsPath) {
+    this.specsPath = specsPath;
+  }
+  async loadChapter(chapterId) {
+    const cached = this.cache.get(chapterId);
+    if (cached) {
+      return cached;
+    }
+    const chapterPath = join(this.specsPath, "chapters", `${chapterId}.md`);
+    const content = await readFile(chapterPath, "utf-8");
+    this.cache.set(chapterId, content);
+    return content;
+  }
+}
+async function handleReadOutline(params, indexService) {
+  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"}`
+        }
+      ]
+    };
+  }
+}
+function normalizeChapterId(id) {
+  return id.toLowerCase().trim().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+async function handleReadChapter(params, specLoader, indexService) {
+  const validChapters = await indexService.listChapterIds();
+  const normalizedInput = normalizeChapterId(params.chapter);
+  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"}`
+        }
+      ]
+    };
+  }
+}
+function createServer(config) {
+  const server = new McpServer(
+    { name: config.name, version: config.version },
+    { capabilities: { tools: {} } }
+  );
+  const indexService = new ChapterIndexService(config.specsPath);
+  const specLoader = new SpecLoader(config.specsPath);
+  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)
+  );
+  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;
+}
+async function main() {
+  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 {
+    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: void 0,
+        enableJsonResponse: true
+      });
+      res.on("close", () => transport.close());
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    });
+    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/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@cityjson/cj-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for querying CityJSON specification chapters",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "cj-mcp": "dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cityjson/cj-mcp"
+  },
+  "homepage": "https://github.com/cityjson/cj-mcp",
+  "bugs": {
+    "url": "https://github.com/cityjson/cj-mcp/issues"
+  },
+  "license": "MIT",
+  "keywords": ["mcp", "cityjson", "model-context-protocol", "3d-city-models"],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "start:stdio": "node dist/index.js",
+    "start:http": "TRANSPORT=http node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0",
+    "express": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.10.2",
+    "vite": "^6.0.0",
+    "vite-node": "^2.0.0"
+  }
+}

package/specs/chapters/appearance-object.md

@@ -0,0 +1,186 @@
+## 6\. Appearance Object[](#appearance-object)
+
+Both textures and materials are supported in CityJSON, and the same mechanisms used in CityGML are reused, so the conversion back-and-forth is easy. The material is represented with the [X3D](http://www.web3d.org/documents/specifications/19775-1/V3.2/Part01/components/shape.html#Material) specifications, as is the case for CityGML. For the texture, the [COLLADA standard](https://www.khronos.org/collada/) is reused, as is the case for CityGML. However:
+
+*   the CityGML class `GeoreferencedTexture` is not supported.
+    
+*   the CityGML class `TexCoordGen` is not supported, ie one must specify the UV coordinates in the texture files.
+    
+*   the major difference is that in CityGML each Material/Texture object keeps a list of the primitives using it, while in CityJSON it is the opposite: if a primitive has a Material/Texture then it is stated with the primitive (with a link to it).
+    
+
+An Appearance Object is a JSON object that
+
+*   **may** have one member with the name `"materials"`, whose value is an array of Material Objects.
+    
+*   **may** have one member with the name `"textures"`, whose value is an array of Texture Objects.
+    
+*   **may** have one member with the name `"vertices-texture"`, whose value is an array of coordinates of each so-called UV vertex of the city model.
+    
+*   **may** have one member with the name `"default-theme-texture"`, whose value is the name of the default theme for the appearance (a string). This can be used if geometries have more than one textures, so that a viewer displays the default one.
+    
+*   **may** have one member with the name `"default-theme-material"`, whose value is the name of the default theme for the material (a string). This can be used if geometries have more than one textures, so that a viewer displays the default one.
+    
+
+"appearance": {
+  "materials": \[\],
+  "textures":\[\],
+  "vertices-texture": \[\],
+  "default-theme-texture": "myDefaultTheme1",
+  "default-theme-material": "myDefaultTheme2"
+}
+
+### 6.1. Geometry Object having material(s)[](#geometry-object-having-material-s)
+
+Each surface in a Geometry Object can have one or more materials assigned to it. To store the material of a surface, a Geometry Object may have a member `"material"`. The value of this member is a collection of key-value pairs, where the key is the _theme_ of the material, and the value is one JSON object that **must** contain either:
+
+*   one member `"values"`. The value is a hierarchy of arrays with integers. Each integer refers to the position (0-based) in the `"materials"` member of the `"appearance"` member of the CityJSON object. If a surface has no material, then `null` should be used in the array. The depth of the array depends on the Geometry object, and is equal to the depth of the `"boundary"` array minus 2, because each surface (`[[]]`) gets one material.
+    
+*   one member `"value"`. The value is one integer referring to the position (0-based) in the `"materials"` member of the `"appearance"` member of the CityJSON object. This is used because often the materials are used to colour full objects, and repetition of materials is not necessary.
+    
+
+In the following example, the Solid has 4 surfaces, and there are 2 themes ("irradiation" and "irradiation-2"). These could represent, for instance, the different colours based on different scenarios of an solar irradiation analysis. Notice that the last surface gets no material (for both themes), thus `null` is used.
+
+{
+  "type": "Solid",
+  "lod": "2.1",
+  "boundaries": \[
+    \[ \[\[0, 3, 2, 1\]\], \[\[4, 5, 6, 7\]\], \[\[0, 1, 5, 4\]\], \[\[1, 2, 6, 5\]\] \] 
+  \],
+  "material": {
+    "irradiation": { 
+      "values": \[\[0, 0, 1, null\]\] 
+    },
+    "irradiation-2": { 
+      "values": \[\[2, 2, 1, null\]\] 
+    }
+  }
+}
+
+### 6.2. Geometry Object having texture(s)[](#geometry-object-having-texture-s)
+
+To store the texture(s) of a surface, a Geometry Object may have a member with the name `"texture"`. Its value is a collection of key-value pairs, where the key is the _theme_ of the textures, and the value is one JSON object that must contain one member `"values"`, which is a hierarchy of arrays with integers. For each ring of each surface, the first value refers to the position (0-based) in the `"textures"` member of the `"appearance"` member of the CityJSON object. The other indices refer to the UV positions of the corresponding vertices (as listed in the `"boundaries"` member of the geometry). Therefore, each array representing a ring has one more value than the number of vertices in the ring.
+
+The depth of the array depends on the Geometry object, and is equal to the depth of the `"boundary"` array.
+
+In the following example, the Solid has 4 surfaces, and there are 2 themes: "winter-textures" and "summer-textures" could for instance represent the textures during winter and summer. Notice that the last 2 surfaces of the first theme gets no texture, thus the value `null` is used.
+
+{
+  "type": "Solid",
+  "lod": "2.2",
+  "boundaries": \[
+    \[ \[\[0, 3, 2, 1\]\], \[\[4, 5, 6, 7\]\], \[\[0, 1, 5, 4\]\], \[\[1, 2, 6, 5\]\] \] 
+  \],
+  "texture": {
+    "winter-textures": {
+      "values": \[
+        \[ \[\[0, 10, 23, 22, 21\]\], \[\[0, 1, 2, 6, 5\]\], \[\[null\]\], \[\[null\]\] \]                  
+      \]
+    },
+    "summer-textures": {
+      "values": \[
+        \[ 
+          \[\[1, 10, 23, 22, 21\]\], 
+          \[\[1, 1, 2, 6, 5\]\], 
+          \[\[1, 66, 12, 64, 5\]\], 
+          \[\[2, 99, 21, 16, 25\]\] 
+        \]                  
+      \]      
+    }
+  }     
+}        
+
+### 6.3. Material Object[](#material-object)
+
+A Material Object:
+
+*   **must** have one member with the name `"name"`, whose value is a string identifying the material.
+    
+*   **may** have the following members (their meaning is explained [there](http://www.web3d.org/documents/specifications/19775-1/V3.2/Part01/components/shape.html#Material)):
+    
+    1.  `"ambientIntensity"`. The value is a number between 0.0 and 1.0.
+        
+    2.  `"diffuseColor"`. The value is an array with 3 numbers between 0.0 and 1.0 (RGB colour).
+        
+    3.  `"emissiveColor"`. The value is an array with 3 numbers between 0.0 and 1.0 (RGB colour).
+        
+    4.  `"specularColor"`. The value is an array with 3 numbers between 0.0 and 1.0 (RGB colour).
+        
+    5.  `"shininess"`. The whose value is a number between 0.0 and 1.0.
+        
+    6.  `"transparency"`. The value is a number between 0.0 and 1.0 (1.0 being completely transparent).
+        
+    7.  `"isSmooth"`. The value is a Boolean value, is defined in CityGML as a hint for normal interpolation. If this boolean flag is set to true, vertex normals should be used for shading (Gouraud shading). Otherwise, normals should be constant for a surface patch (flat shading).
+        
+
+> **Note:** If only `"name"` is defined for the Material Object, then it is up to the application that reads the CityJSON file to attach a material definition to the `"name"`. This might not always be possible. Therefore, it is advised to define as many from the optional members as needed for fully displaying the material.
+
+"materials": \[
+  {
+    "name": "roofandground",
+    "ambientIntensity":  0.2000,
+    "diffuseColor":  \[0.9000, 0.1000, 0.7500\],
+    "emissiveColor": \[0.9000, 0.1000, 0.7500\],
+    "specularColor": \[0.9000, 0.1000, 0.7500\],
+    "shininess": 0.2,
+    "transparency": 0.5,
+    "isSmooth": false
+  },
+  {
+    "name": "wall",
+    "ambientIntensity":  0.4000,
+    "diffuseColor":  \[0.1000, 0.1000, 0.9000\],
+    "emissiveColor": \[0.1000, 0.1000, 0.9000\],
+    "specularColor": \[0.9000, 0.1000, 0.7500\],
+    "shininess": 0.0,
+    "transparency": 0.5,
+    "isSmooth": true
+  }            
+\]
+
+### 6.4. Texture Object[](#texture-object)
+
+A Texture Object:
+
+*   **must** have one member with the name `"type"`. The value is a string with either "PNG" or "JPG" as value.
+    
+*   **must** have one member with the name `"image"`. The value is a string with the name of the file. This file can be a URL (eg `"http://www.someurl.org/filename.jpg"`), a relative path (eg `"appearances/myroof.jpg"`), or an absolute path (eg `"/home/elvis/mycityjson/appearances/myroof.jpg"`).
+    
+*   **may** have one member with the name `"wrapMode"`. The value can be any of the following: `"none"`, `"wrap"`, `"mirror"`, `"clamp"`, or `"border"`.
+    
+*   **may** have one member with the name `"textureType"`. The value can be any of the following: `"unknown"`, `"specific"`, or `"typical"`.
+    
+*   **may** have one member with the name `"borderColor"`. The value is an array with 4 numbers between 0.0 and 1.0 (RGBA colour).
+    
+
+"textures": \[
+  {
+    "type": "PNG",
+    "image": "http://www.someurl.org/filename.jpg"
+  },
+  {
+    "type": "JPG",
+    "image": "appearances/myroof.jpg",
+    "wrapMode": "wrap",
+    "textureType": "unknown",
+    "borderColor": \[0.0, 0.1, 0.2, 1.0\]
+  }      
+\]
+
+### 6.5. Vertices-texture Object[](#vertices-texture-object)
+
+An Appearance Object may have one member with the name `"vertices-texture"`. Its value is an array of the _(u,v)_ coordinates of the vertices used for texturing surfaces. Their position in this array (0-based) is used by the `"texture"` member of the Geometry Objects.
+
+*   the array of vertices may be empty.
+    
+*   one vertex must be an array with exactly 2 values, representing the _(u,v)_ coordinates.
+    
+*   vertices may be repeated
+    
+
+"vertices-texture": \[
+  \[0.0, 0.5\],
+  \[1.0, 0.0\],
+  \[1.0, 1.0\],
+  \[0.0, 1.0\]
+\]

package/specs/chapters/citygml-v30-implementation-details.md

@@ -0,0 +1,7 @@
+## 10\. CityGML v3.0 implementation details[](#citygml-v30-implementation-details)
+
+CityJSON v2.0 is a partial implementation of the [CityGML v3.0 data model](https://docs.ogc.org/is/20-010/20-010.html), although not all extension modules have been implemented. CityJSON v2.0 consistently implements actions #1, #2, and #3 of the profiling mechanism specified in [Section 2.1 of the CityGML v3.0 Conceptual Model](https://docs.ogc.org/is/20-010/20-010.html#toc10).
+
+The details of which modules are supported are available at [https://www.cityjson.org/citygml/v30/](https://www.cityjson.org/citygml/v30/).
+
+* * *

package/specs/chapters/cityjson-object.md

@@ -0,0 +1,62 @@
+## 1\. CityJSON Object[](#cityjson-object)
+
+A CityJSON object represents one 3D city model of a given area, this model may contain features of different types, as defined in the CityGML data model.
+
+A CityJSON object:
+
+*   is a JSON object.
+    
+*   **must** have one member with the name `"type"`. The value must be `"CityJSON"`.
+    
+*   **must** have one member with the name `"version"`. The value must be a string with the version (X.Y) of the CityJSON object. Observe that while schemas can have a version with patch version (X.Y.Z), a CityJSON object points only to the minor version (X.Y), and for validation the latest schema of that minor version should be used.
+    
+*   **must** have one member with the name `"transform"`. The value is a JSON object describing how to _decompress_ the integer coordinates of the geometries to obtain real-world coordinates. See [§ 4 Transform Object](#transform-object) for details.
+    
+*   **must** have one member with the name `"CityObjects"`. The value of this member is a collection of key-value pairs, where the key is the ID of the object, and the value is one City Object. The ID of a City Object should be unique (within one CityJSON Object). See [§ 2 The different City Objects](#the-different-city-objects) for details.
+    
+*   **must** have one member with the name `"vertices"`. The value is an array representing the coordinates of each vertex of the city model. See [§ 3.1 Coordinates of the vertices](#coordinates-of-the-vertices).
+    
+*   **may** have one member with the name `"metadata"`. The value may be a JSON object describing the coordinate reference system used, the extent of the dataset, its creator, etc. See [§ 5 Metadata](#metadata) for details.
+    
+*   **may** have one member with the name `"extensions"`, which is used if there are Extensions used in the file. See [§ 8 Extensions](#extensions) for details.
+    
+*   **may** have one member with the name `"appearance"`. The value may contain JSON objects representing the textures and/or materials of surfaces. See [§ 6 Appearance Object](#appearance-object) for details.
+    
+*   **may** have one member with the name `"geometry-templates"`, the value is a JSON object containing the templates that can be reused by different City Objects (usually for trees). This is equivalent to the concept of "implicit geometries" in CityGML. See [§ 3.4 Geometry templates](#geometry-templates) for details.
+    
+*   **may** have other members, and their value is not prescribed. Because these are not standard members in CityJSON, they might be ignored by parsers.
+    
+
+> **Note:** **Suggested convention:** A file containing one CityJSON object may have the extension `'.city.json'`
+
+The minimal valid CityJSON object is:
+
+{
+  "type": "CityJSON",
+  "version": "2.0",
+  "transform": {
+    "scale": \[1.0, 1.0, 1.0\],
+    "translate": \[0.0, 0.0, 0.0\]
+  },
+  "CityObjects": {},
+  "vertices": \[\]
+}
+
+An "empty" but complete CityJSON object will look like this:
+
+{
+  "type": "CityJSON",
+  "version": "2.0",
+  "extensions": {},
+  "transform": {
+    "scale": \[1.0, 1.0, 1.0\],
+    "translate": \[0.0, 0.0, 0.0\]
+  },
+  "metadata": {},
+  "CityObjects": {},
+  "vertices": \[\],
+  "appearance": {},
+  "geometry-templates": {}
+}
+
+> **Note:** While the order of the CityJSON member values should preferably be as above, not all JSON generators support this, therefore the order is not prescribed.

package/specs/chapters/cityjson-schemas.md

@@ -0,0 +1,3 @@
+## 9\. CityJSON schemas[](#cityjson-schemas)
+
+The [JSON schemas](https://json-schema.org/) of the specifications are publicly available at [https://cityjson.org/schemas/](https://cityjson.org/schemas/).