CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Essential Commands
6 
7### Development Commands
8```bash
9# Build the MCP server for prod (requires a URL or local file path for the OpenAPI spec)
10yarn nx build mcp-server --specUrl=https://demo.dotcms.com/api/openapi.json
11 
12# Development mode with hot reload
13yarn nx serve mcp-server
14 
15# Regenerate spec only (requires a URL or local file path)
16yarn nx generate-spec mcp-server -- https://demo.dotcms.com/api/openapi.json
17 
18# Run tests
19yarn nx test mcp-server
20 
21# Run linting
22yarn nx lint mcp-server
23```
24 
25### Environment Setup
26 
27Configure the MCP server via the `env` block in your MCP client config:
28 
29```json
30{
31  "mcpServers": {
32    "dotcms": {
33      "command": "node",
34      "args": [
35        "/Users/fmontes/Developer/dotcms/core/core-web/dist/apps/mcp-server/stdio.js"
36      ],
37      "env": {
38        "DOTCMS_URL": "http://localhost:8080",
39        "AUTH_TOKEN": "eyJ0eXAiOiJKV1Qi..."
40      }
41    }
42  }
43}
44```
45 
46| Variable | Required | Description |
47|---|---|---|
48| `DOTCMS_URL` | Yes | Base URL of the dotCMS instance |
49| `AUTH_TOKEN` | Yes | JWT Bearer token (generate in dotCMS → User Tools → API Tokens) |
50| `SANDBOX_TIMEOUT` | No | Sandbox execution timeout in ms (default: `15000`) |
51 
52## Architecture Overview
53 
54This is a **Model Context Protocol (MCP) server** for dotCMS, built with [xmcp](https://xmcp.dev) (rspack-based framework). The server provides AI assistants with two tools to interact with dotCMS: **search** (explore API spec) and **execute** (make API calls).
55 
56### Core Architecture
57 
58**Framework**: xmcp auto-discovers tools from `src/tools/`. Each tool exports `schema`, `metadata`, and a default handler function.
59 
60**Entry Point**: xmcp generates the entry point at build time (`dist/stdio.js`).
61 
62**Build Pipeline**:
631. `generate-spec` — fetches the OpenAPI spec from a dotCMS instance, processes it into `src/generated/spec.json` (dereferences $refs, filters to relevant endpoints)
642. `xmcp build` — bundles everything with rspack into `dist/`
65 
66**Tool Layer** (`src/tools/`):
67- `search.ts` — Explore the OpenAPI spec via sandbox-executed JavaScript
68- `execute.ts` — Make authenticated API calls via sandbox-executed JavaScript
69 
70**Library Layer** (`src/lib/`):
71- `executor.ts` — Orchestrates sandbox creation and adapter injection
72- `http-client.ts` — Authenticated HTTP adapter (tokens injected by main thread, never in sandbox)
73- `spec.ts` — Loads the pre-processed OpenAPI spec
74- `types.ts` — TypeScript interfaces for adapters, sandbox config, execution context
75- `sandbox/index.ts` — Runtime detection factory (`createSandbox`)
76- `sandbox/interface.ts` — Sandbox interface definition
77- `sandbox/bun-worker.ts` — Bun Web Worker sandbox
78- `sandbox/node-worker.ts` — Node.js `worker_threads` sandbox
79 
80### Key Patterns
81 
82**Dual-Runtime Sandbox**: User code runs in Workers with automatic runtime detection. On Bun, uses native Web Workers (`Blob` + `URL.createObjectURL`). On Node.js, uses `worker_threads` (`new Worker(code, { eval: true })`). Runtime is detected via `typeof globalThis.Bun`. API tokens are never exposed to the sandbox — the main thread handles authentication via the adapter pattern.
83 
84**Adapter Pattern**: The executor bridges sandbox code to the main thread:
85- Sandbox calls `api.request(...)` which posts a message to the main thread
86- Main thread executes the actual HTTP call with injected auth
87- Result is posted back to the sandbox
88 
89**Build-time Spec Processing**: `scripts/generate-spec.ts` fetches the OpenAPI spec from a URL (or reads a local file), dereferences it, filters to allowed endpoint prefixes, strips response schemas, and handles circular references. The developer must provide the spec URL or file path when running `generate-spec`.
90 
91### Type System
92 
93All interfaces are in `src/lib/types.ts`:
94- `Adapter` / `AdapterMethod` — for extending sandbox capabilities
95- `SandboxConfig` / `SandboxResult` — sandbox execution parameters and results
96- `ExecutionContext` — adapters + variables passed to sandbox
97 
98## MCP Tools Available
99 
100### Search Tool
101**Purpose**: Explore the dotCMS REST API specification
102**Sandbox globals**: `spec` (the dereferenced OpenAPI spec object)
103**Read-only**: Yes — no side effects
104 
105### Execute Tool
106**Purpose**: Make authenticated API calls to dotCMS
107**Sandbox globals**: `api` (HTTP adapter), `pick`, `table`, `count`, `sum`, `first` (helpers)
108**Side effects**: Yes — can create/modify/delete content
109 
110## Development Guidelines
111 
112### Adding New Tools
1131. Create a new `.ts` file in `src/tools/`
1142. Export `schema` (Zod object), `metadata` (ToolMetadata), and a default handler
1153. xmcp auto-discovers it — no registration needed
116 
117### Adding New Adapters
1181. Implement the `Adapter` interface from `src/lib/types.ts`
1192. Register it on the executor in the tool handler
1203. Specify adapter names in `execute()` options
121 
122### Testing
123- Tests use Jest with Node.js environment
124- Test files should follow `*.spec.ts` naming convention
125- `generate-spec` target runs before tests (spec.json must exist)
126 
127## Configuration
128 
129The server is configured as an Nx application with:
130- **Build**: `nx:run-commands` executor running `xmcp build`
131- **Dev**: `nx:run-commands` running `xmcp dev` (hot reload)
132- **Test**: `@nx/jest:jest` executor
133- **Lint**: `@nx/eslint:lint` executor
134- **Output**: `dist/apps/mcp-server/stdio.js`
135