da-mcp: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

DA MCP is a remote Model Context Protocol (MCP) server for Document Authoring (DA). It provides LLM assistants with direct access to DA management operations via Cloudflare Workers with streamable HTTP transport.

Architecture flow: MCP Client → Cloudflare Worker (17 tools) → DA Admin API (admin.da.live) or AEM (HLX6) Admin API (api.aem.live); legacy preview/publish calls go to the Helix admin API (admin.hlx.page) instead

Development Commands

npm run dev              # Local development with hot reload (http://localhost:8787)
npm run lint             # ESLint check
npm run test             # Run Vitest tests
npm run test:watch       # Run tests in watch mode
npm run type-check       # TypeScript type checking without emit
npm run deploy           # Deploy to production Cloudflare Workers
npm run deploy:ci        # Deploy to CI environment with versioned config
npm run deploy:production # Deploy to production with versioned config

Local endpoints:

• Health: http://localhost:8787/health
• MCP: http://localhost:8787/mcp

Test with MCP Inspector: Connect to http://localhost:8787/mcp with Authorization: Bearer YOUR_DA_TOKEN header.

Code Structure

src/
├── index.ts           # Cloudflare Worker entry point, token extraction, health check
├── mcp/
│   ├── server.ts      # McpServer factory with registerTool() + Zod schemas (one per tool)
│   └── handlers.ts    # Tool implementation handlers (one per tool)
├── da-admin/
│   ├── client.ts      # DA Admin API HTTP client with token pass-through
│   └── types.ts       # TypeScript interfaces for API responses
└── utils/
    └── path.ts        # Path normalization utilities

Key Patterns

• Token pass-through: Authorization header extracted in index.ts, passed to DAAdminClient, forwarded to DA Admin API
• SDK transport: WebStandardStreamableHTTPServerTransport (stateless, per-request) handles MCP protocol — fresh McpServer + transport created per request
• Tool registration: Each tool registered via server.registerTool() with a Zod inputSchema in server.ts; business logic lives in handlers.ts
• FormData for content: Create/update/copy/move operations use FormData with Blob for file content
• Copy/move API: Endpoint is /copy|move/{org}/{repo}/{sourcePath}; body is FormData with destination = /{org}/{repo}/{destinationPath}
• Empty responses: client.ts reads body as text first; returns {} for empty/no-content responses (204 etc.)
• 30-second timeout: All API requests have AbortController timeout
• Path normalization: All handlers normalize paths via src/utils/path.ts before passing to client; .html extension auto-added where needed for source file operations, but stripped for preview/publish (see below) since those are page/URL paths, not source file paths
• Preview/live on legacy DA: admin.da.live has no preview/live routes of its own — DAAdminClient.previewContent/unpreviewContent/publishContent/unpublishContent call the Helix admin API (admin.hlx.page) directly via global fetch() instead of the daadminService binding, always targeting the main ref. Preview POST calls additionally send x-content-source-authorization alongside Authorization.
• Preview/live paths have no file extension: on both legacy and HLX6, da_preview_content/da_unpreview_content/da_publish_content/da_unpublish_content strip any extension from the given path via stripFileExtension() (src/utils/path.ts) before calling the client — AEM Edge Delivery preview/live URLs are always extensionless page routes.