Copy Comet MCP server POC to core repo

copy-project-files.js

@@ -36,11 +36,11 @@ const files = [
     },
     {
         file: "demo/api/block-meta.json",
-        targetDir: ["demo/admin", "demo/site"],
+        targetDir: ["demo/admin", "demo/site", "demo/mcp-server"],
     },
     {
         file: "demo/api/schema.gql",
-        targetDir: ["demo/admin", "demo/site"],
+        targetDir: ["demo/admin", "demo/site", "demo/mcp-server"],
     },
     {
         file: "demo/api/src/comet-config.json",

demo/mcp-server/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+schema.gql
+block-meta.json
+*.generated.ts

demo/mcp-server/README.md

@@ -0,0 +1,98 @@
+# Comet Demo MCP Server
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the Comet demo API's page tree, page content,
+and DAM operations as tools and resources over the Model Context Protocol. It lets an MCP client (e.g. Claude
+Code, Claude Desktop) read and edit demo CMS content via natural language.
+
+It talks to the demo API over GraphQL, so the demo API must be running and reachable.
+
+## Tools
+
+| Tool                               | Description                                             |
+| ---------------------------------- | ------------------------------------------------------- |
+| `list_page_tree_nodes`             | List page tree nodes in a scope (published only)        |
+| `get_page_tree_node`               | Get a single page tree node by ID (published only)      |
+| `get_page_tree_node_by_path`       | Look up a page tree node by URL path                    |
+| `get_page`                         | Get a page document (content, SEO, stage) by ID         |
+| `check_slug_availability`          | Check whether a slug is available under a parent        |
+| `create_page_tree_node`            | Create a new page tree node                             |
+| `update_page_tree_node`            | Update a node's name, slug, and `hideInMenu`            |
+| `save_page`                        | Save page content (content blocks, SEO, stage)          |
+| `update_page_tree_node_visibility` | Publish, unpublish, or archive a node                   |
+| `list_dam_files`                   | List files in the Digital Asset Management (DAM) system |
+| `get_dam_file`                     | Get a single DAM file by ID                             |
+| `delete_page_tree_node`            | Permanently delete an archived node and its document    |
+
+## Resources
+
+| Resource      | URI                   | Description                                                          |
+| ------------- | --------------------- | -------------------------------------------------------------------- |
+| `block-types` | `comet://block-types` | Lightweight TypeScript interfaces for all content blocks (preferred) |
+| `block-meta`  | `comet://block-meta`  | Full block schema metadata (field kinds, nullability, enums)         |
+
+## Prerequisites
+
+- The demo API running and reachable (see the repository root [`AGENTS.md`](../../AGENTS.md)).
+- `@comet/cli` built (it is built as part of the normal monorepo setup).
+- `schema.gql` and `block-meta.json` present in this folder. They are symlinks to `demo/api`, created by the
+  root `copy-project-files` script (run automatically during setup, or manually via `pnpm run copy-project-files`).
+
+## Build
+
+From the repository root:
+
+```bash
+pnpm --filter comet-demo-mcp-server run build
+```
+
+This generates GraphQL types (`gql:types`) and block-type interfaces (`generate-block-types`), then bundles the
+server to `dist/index.js` with `tsup`.
+
+## Configuration
+
+The server reads the following environment variables (with development defaults):
+
+| Variable                              | Default                     | Description                             |
+| ------------------------------------- | --------------------------- | --------------------------------------- |
+| `API_URL`                             | `http://localhost:4000`     | Base URL of the demo API                |
+| `API_BASIC_AUTH_SYSTEM_USER_PASSWORD` | `aPasswordWith16Characters` | Password for the basic-auth system user |
+
+> **Warning:** Authentication uses the basic-auth system user, which has full access to the API. This is intended
+> for local development and testing only — it is **not** production-ready and must be replaced by a user-based
+> authentication method before any non-local use.
+
+## Usage with an MCP client
+
+MCP clients spawn the server over stdio. After building, register it with a command like:
+
+```json
+{
+    "mcpServers": {
+        "comet-demo": {
+            "command": "node",
+            "args": ["demo/mcp-server/dist/index.js"],
+            "env": {
+                "API_URL": "http://localhost:4000",
+                "API_BASIC_AUTH_SYSTEM_USER_PASSWORD": "aPasswordWith16Characters"
+            }
+        }
+    }
+}
+```
+
+Use an absolute path to `dist/index.js` if the client's working directory differs from the repository root.
+
+## Development
+
+- GraphQL operations live next to their tool in `*.gql.ts` files; queries are validated against `schema.gql` at
+  build time via GraphQL Code Generator.
+- Generated files (`*.generated.ts`, `blocks.generated.ts`), the build output (`dist/`), and the `schema.gql` /
+  `block-meta.json` symlinks are git-ignored.
+
+Run linting from the repository root:
+
+```bash
+pnpm --filter comet-demo-mcp-server run lint
+# auto-fix:
+pnpm --filter comet-demo-mcp-server run lint:fix
+```

demo/mcp-server/codegen.ts

@@ -0,0 +1,52 @@
+import { CodegenConfig } from "@graphql-codegen/cli";
+
+const config: CodegenConfig = {
+    schema: "schema.gql",
+    generates: {
+        "./src/graphql.generated.ts": {
+            plugins: ["typescript"],
+            config: {
+                avoidOptionals: {
+                    field: true,
+                },
+                enumsAsTypes: true,
+                namingConvention: "keep",
+                scalars: {
+                    DateTime: "string",
+                    Date: "string",
+                    LocalDate: "string",
+                    JSON: "unknown",
+                    JSONObject: "Record<string, unknown>",
+                },
+                typesPrefix: "GQL",
+            },
+        },
+        "./src/": {
+            documents: ["./src/**/!(*.generated).{tsx,ts}"],
+            preset: "near-operation-file",
+            presetConfig: {
+                extension: ".generated.ts",
+                baseTypesPath: "graphql.generated.ts",
+            },
+            config: {
+                avoidOptionals: {
+                    field: true,
+                },
+                enumsAsTypes: true,
+                namingConvention: "keep",
+                scalars: {
+                    DateTime: "string",
+                    Date: "string",
+                    LocalDate: "string",
+                    JSON: "unknown",
+                    JSONObject: "Record<string, unknown>",
+                },
+                typesPrefix: "GQL",
+            },
+            plugins: ["typescript-operations"],
+        },
+    },
+    ignoreNoDocuments: true,
+};
+
+export default config;

demo/mcp-server/eslint.config.mjs

@@ -0,0 +1,16 @@
+import eslintConfigCore from "@comet/eslint-config/core.js";
+
+/** @type {import("eslint")} */
+const config = [
+    {
+        ignores: ["dist/**", "src/**/*.generated.ts", "block-meta.json"],
+    },
+    ...eslintConfigCore,
+    {
+        rules: {
+            "@comet/no-other-module-relative-import": "off",
+        },
+    },
+];
+
+export default config;

demo/mcp-server/package.json

@@ -0,0 +1,45 @@
+{
+    "name": "comet-demo-mcp-server",
+    "version": "1.0.0",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "build": "run-s gql:types generate-block-types && tsup",
+        "generate-block-types": "comet generate-block-types --output-file blocks.generated.ts",
+        "gql:types": "graphql-codegen",
+        "lint": "run-s gql:types generate-block-types && run-p lint:prettier lint:eslint lint:tsc",
+        "lint:ci": "pnpm run lint",
+        "lint:eslint": "eslint --max-warnings 0 src/ '**/*.json' --no-warn-ignored",
+        "lint:fix": "run-p lint:fix:eslint lint:fix:prettier",
+        "lint:fix:eslint": "pnpm run lint:eslint --fix",
+        "lint:fix:prettier": "pnpm run lint:prettier --write",
+        "lint:prettier": "pnpm exec prettier --check '*.{ts,js,json,md,yml,yaml}'",
+        "lint:tsc": "tsc --project .",
+        "start": "node dist/index.js"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.27.1",
+        "graphql": "^16.14.0",
+        "graphql-request": "^7.1.2",
+        "zod": "^3.25.7"
+    },
+    "devDependencies": {
+        "@babel/core": "^7.29.0",
+        "@comet/cli": "workspace:*",
+        "@comet/eslint-config": "workspace:*",
+        "@graphql-codegen/cli": "^5.0.7",
+        "@graphql-codegen/near-operation-file-preset": "^3.1.0",
+        "@graphql-codegen/typescript": "^4.1.6",
+        "@graphql-codegen/typescript-operations": "^4.6.1",
+        "@parcel/watcher": "^2.5.6",
+        "@types/node": "^24.12.4",
+        "eslint": "^9.39.4",
+        "npm-run-all2": "^8.0.4",
+        "prettier": "^3.6.2",
+        "tsup": "^8.5.1",
+        "typescript": "^5.9.3"
+    },
+    "engines": {
+        "node": "24"
+    }
+}

demo/mcp-server/src/client.ts

@@ -0,0 +1,16 @@
+import { GraphQLClient } from "graphql-request";
+
+// TODO:
+// This authentication method is not PRODUCTION ready and needs to be replaced by a user based authentication method. It
+// is only intended for development and testing purposes.
+//
+// The system user has full access to the API.
+const API_URL = process.env.API_URL ?? "http://localhost:4000";
+const API_PASSWORD = process.env.API_BASIC_AUTH_SYSTEM_USER_PASSWORD ?? "aPasswordWith16Characters";
+const AUTH_HEADER = `Basic ${Buffer.from(`system-user:${API_PASSWORD}`).toString("base64")}`;
+
+export const client = new GraphQLClient(`${API_URL}/api/graphql`, {
+    headers: {
+        Authorization: AUTH_HEADER,
+    },
+});

demo/mcp-server/src/index.ts

@@ -0,0 +1,57 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { registerBlockMetaResource } from "./resources/blockMeta/blockMeta";
+import { registerBlockTypesResource } from "./resources/blockTypes/blockTypes";
+import { registerCheckSlugAvailability } from "./tools/checkSlugAvailability/checkSlugAvailability";
+import { registerCreatePageTreeNode } from "./tools/createPageTreeNode/createPageTreeNode";
+import { registerDeletePageTreeNode } from "./tools/deletePageTreeNode/deletePageTreeNode";
+import { registerGetDamFile } from "./tools/getDamFile/getDamFile";
+import { registerGetPage } from "./tools/getPage/getPage";
+import { registerGetPageTreeNode } from "./tools/getPageTreeNode/getPageTreeNode";
+import { registerGetPageTreeNodeByPath } from "./tools/getPageTreeNodeByPath/getPageTreeNodeByPath";
+import { registerListDamFiles } from "./tools/listDamFiles/listDamFiles";
+import { registerListPageTreeNodes } from "./tools/listPageTreeNodes/listPageTreeNodes";
+import { registerSavePage } from "./tools/savePage/savePage";
+import { registerUpdatePageTreeNode } from "./tools/updatePageTreeNode/updatePageTreeNode";
+import { registerUpdatePageTreeNodeVisibility } from "./tools/updatePageTreeNodeVisibility/updatePageTreeNodeVisibility";
+
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+
+const server = new McpServer({
+    name: "comet-demo",
+    version: "1.0.0",
+});
+
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+
+registerListPageTreeNodes(server);
+registerGetPageTreeNode(server);
+registerGetPageTreeNodeByPath(server);
+registerGetPage(server);
+registerCheckSlugAvailability(server);
+registerCreatePageTreeNode(server);
+registerUpdatePageTreeNode(server);
+registerSavePage(server);
+registerUpdatePageTreeNodeVisibility(server);
+registerListDamFiles(server);
+registerGetDamFile(server);
+registerDeletePageTreeNode(server);
+
+// ---------------------------------------------------------------------------
+// Resources
+// ---------------------------------------------------------------------------
+
+registerBlockMetaResource(server);
+registerBlockTypesResource(server);
+
+// ---------------------------------------------------------------------------
+// Start server
+// ---------------------------------------------------------------------------
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

demo/mcp-server/src/resources/blockMeta/blockMeta.ts

@@ -0,0 +1,23 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BLOCK_META_PATH = resolve(__dirname, "../block-meta.json");
+
+export function registerBlockMetaResource(server: McpServer): void {
+    server.registerResource(
+        "block-meta",
+        "comet://block-meta",
+        {
+            description:
+                "Full block schema metadata — field definitions, types, enums, and nesting for all CMS content blocks (~3000 lines). IMPORTANT: Prefer the lightweight 'block-types' resource (comet://block-types) instead — it provides the same structural information in ~450 lines of TypeScript interfaces, which is sufficient to construct valid save_page inputs. Only use this resource if you need detailed field-level metadata (e.g. kinds, nullability) beyond what block-types provides. Fields named 'draftContent' with kind 'Json' contain Draft.js editor format (from the draft-js library).",
+        },
+        async () => {
+            const content = await readFile(BLOCK_META_PATH, "utf-8");
+            return { contents: [{ uri: "comet://block-meta", text: content, mimeType: "application/json" }] };
+        },
+    );
+}

demo/mcp-server/src/resources/blockTypes/blockTypes.ts

@@ -0,0 +1,23 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BLOCK_TYPES_PATH = resolve(__dirname, "../blocks.generated.ts");
+
+export function registerBlockTypesResource(server: McpServer): void {
+    server.registerResource(
+        "block-types",
+        "comet://block-types",
+        {
+            description:
+                "Lightweight TypeScript interfaces describing the shape of all CMS content blocks. PREFER this over block-meta — it is much smaller (~450 lines vs ~3000 lines) and provides the exact same structural information needed to construct valid save_page inputs. Fields named 'draftContent' of type 'unknown' contain Draft.js editor format (from the draft-js library).",
+        },
+        async () => {
+            const content = await readFile(BLOCK_TYPES_PATH, "utf-8");
+            return { contents: [{ uri: "comet://block-types", text: content, mimeType: "text/plain" }] };
+        },
+    );
+}

demo/mcp-server/src/schemas.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+export const scopeSchema = z
+    .object({
+        domain: z.string().default("main"),
+        language: z.string().default("en"),
+    })
+    .default({ domain: "main", language: "en" });
+
+export const damScopeSchema = z
+    .object({
+        domain: z.string().default("main"),
+    })
+    .default({ domain: "main" });

demo/mcp-server/src/tools/checkSlugAvailability/checkSlugAvailability.gql.ts

@@ -0,0 +1,7 @@
+import { gql } from "graphql-request";
+
+export const checkSlugAvailabilityQuery = gql`
+    query CheckSlug($slug: String!, $scope: PageTreeNodeScopeInput!, $parentId: ID) {
+        pageTreeNodeSlugAvailable(slug: $slug, scope: $scope, parentId: $parentId)
+    }
+`;