@creately/rdm-mcp 0.1.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@creately/rdm-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for RDM — parse, validate, render, and manipulate diagrams via AI agents",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "rdm-mcp": "src/index.ts"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun run --watch src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@creately/rdm-core": "workspace:*"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/creately/rdm",
+    "directory": "packages/rdm-mcp"
+  }
+}

package/src/index.ts

@@ -0,0 +1,97 @@
+/**
+ * RDM MCP Server
+ *
+ * Provides 8 tools for agents to interact with RDM diagrams:
+ *   rdm_read     — Full .rdm text (rich context)
+ *   rdm_summary  — Lightweight: node count, types, relationships
+ *   rdm_write    — Write/update .rdm file
+ *   rdm_render   — Get SVG of current diagram
+ *   rdm_validate — Check for errors with line numbers
+ *   rdm_schema   — Domain schema: valid fields, relationships, examples
+ *   rdm_from_csv — Generate .rdm from structured data file
+ *   rdm_init     — Analyze project, generate conventions
+ *
+ * Supports both stdio and HTTP transport.
+ *
+ * Usage:
+ *   bun run packages/rdm-mcp/src/index.ts              # stdio mode
+ *   bun run packages/rdm-mcp/src/index.ts --http 3100   # HTTP mode
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { rdmReadTool, executeRdmRead } from './tools/rdm_read.js';
+import { rdmSummaryTool, executeRdmSummary } from './tools/rdm_summary.js';
+import { rdmWriteTool, executeRdmWrite } from './tools/rdm_write.js';
+import { rdmRenderTool, executeRdmRender } from './tools/rdm_render.js';
+import { rdmValidateTool, executeRdmValidate } from './tools/rdm_validate.js';
+import { rdmSchemaTool, executeRdmSchema } from './tools/rdm_schema.js';
+import { rdmFromCsvTool, executeRdmFromCsv } from './tools/rdm_from_csv.js';
+import { rdmInitTool, executeRdmInit } from './tools/rdm_init.js';
+
+const ALL_TOOLS = [
+  rdmReadTool,
+  rdmSummaryTool,
+  rdmWriteTool,
+  rdmRenderTool,
+  rdmValidateTool,
+  rdmSchemaTool,
+  rdmFromCsvTool,
+  rdmInitTool,
+];
+
+const TOOL_EXECUTORS: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+  rdm_read: executeRdmRead,
+  rdm_summary: executeRdmSummary,
+  rdm_write: executeRdmWrite,
+  rdm_render: executeRdmRender,
+  rdm_validate: executeRdmValidate,
+  rdm_schema: executeRdmSchema,
+  rdm_from_csv: executeRdmFromCsv,
+  rdm_init: executeRdmInit,
+};
+
+async function main() {
+  const server = new Server(
+    { name: 'rdm-mcp', version: '0.1.0' },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: ALL_TOOLS,
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const executor = TOOL_EXECUTORS[name];
+
+    if (!executor) {
+      return {
+        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+        isError: true,
+      };
+    }
+
+    try {
+      const result = await executor(args ?? {});
+      return {
+        content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result, null, 2) }],
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+        isError: true,
+      };
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/src/tools/rdm_from_csv.ts

@@ -0,0 +1,316 @@
+/**
+ * rdm_from_csv — Generate .rdm from CSV data
+ */
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, dirname, basename } from 'path';
+
+export const rdmFromCsvTool = {
+  name: 'rdm_from_csv',
+  description:
+    'Generate an .rdm file from a CSV data file. Automatically maps columns ' +
+    'to RDM fields based on the target domain (orgchart, genogram, process).',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      csvPath: {
+        type: 'string',
+        description: 'Path to the CSV file',
+      },
+      domain: {
+        type: 'string',
+        enum: ['orgchart', 'genogram', 'process'],
+        description: 'Target diagram domain',
+      },
+      outputPath: {
+        type: 'string',
+        description: 'Output .rdm file path (defaults to same directory as CSV)',
+      },
+      columnMapping: {
+        type: 'object',
+        description:
+          'Optional manual column mapping: { csvColumn: rdmField }. ' +
+          'If not provided, columns are auto-mapped by name.',
+      },
+    },
+    required: ['csvPath', 'domain'],
+  },
+};
+
+export async function executeRdmFromCsv(args: Record<string, unknown>): Promise<unknown> {
+  const csvPath = resolve(String(args.csvPath ?? ''));
+  const domain = String(args.domain ?? 'orgchart');
+  const columnMapping = (args.columnMapping as Record<string, string>) ?? {};
+
+  if (!existsSync(csvPath)) {
+    return { error: `CSV file not found: ${csvPath}` };
+  }
+
+  const csvContent = readFileSync(csvPath, 'utf-8');
+  const rows = parseSimpleCsv(csvContent);
+
+  if (rows.length < 2) {
+    return { error: 'CSV must have at least a header row and one data row' };
+  }
+
+  const headers = rows[0];
+  const data = rows.slice(1);
+
+  // Auto-map columns if no explicit mapping
+  const mapping = Object.keys(columnMapping).length > 0
+    ? columnMapping
+    : autoMapColumns(headers, domain);
+
+  let rdmText: string;
+
+  switch (domain) {
+    case 'orgchart':
+      rdmText = generateOrgchartRdm(headers, data, mapping, csvPath);
+      break;
+    case 'genogram':
+      rdmText = generateGenogramRdm(headers, data, mapping, csvPath);
+      break;
+    case 'process':
+      rdmText = generateProcessRdm(headers, data, mapping, csvPath);
+      break;
+    default:
+      return { error: `Unsupported domain: ${domain}` };
+  }
+
+  const outputPath = args.outputPath
+    ? resolve(String(args.outputPath))
+    : csvPath.replace(/\.csv$/i, '.rdm');
+
+  const dir = dirname(outputPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  writeFileSync(outputPath, rdmText, 'utf-8');
+
+  return {
+    outputPath,
+    domain,
+    rowCount: data.length,
+    columnMapping: mapping,
+    written: true,
+  };
+}
+
+function parseSimpleCsv(content: string): string[][] {
+  return content
+    .trim()
+    .split('\n')
+    .map((line) =>
+      line.split(',').map((cell) => cell.trim().replace(/^["']|["']$/g, ''))
+    );
+}
+
+function autoMapColumns(headers: string[], domain: string): Record<string, string> {
+  const mapping: Record<string, string> = {};
+  const normalized = headers.map((h) => h.toLowerCase().trim());
+
+  if (domain === 'orgchart') {
+    const nameCol = normalized.findIndex((h) => ['name', 'employee', 'person', 'full_name', 'fullname'].includes(h));
+    const titleCol = normalized.findIndex((h) => ['title', 'role', 'job_title', 'position'].includes(h));
+    const deptCol = normalized.findIndex((h) => ['department', 'dept', 'division', 'team'].includes(h));
+    const managerCol = normalized.findIndex((h) => ['manager', 'reports_to', 'reportsto', 'supervisor', 'boss'].includes(h));
+    const levelCol = normalized.findIndex((h) => ['level', 'rank', 'grade'].includes(h));
+
+    if (nameCol >= 0) mapping[headers[nameCol]] = 'name';
+    if (titleCol >= 0) mapping[headers[titleCol]] = 'title';
+    if (deptCol >= 0) mapping[headers[deptCol]] = 'department';
+    if (managerCol >= 0) mapping[headers[managerCol]] = 'reportsTo';
+    if (levelCol >= 0) mapping[headers[levelCol]] = 'level';
+  } else if (domain === 'genogram') {
+    const nameCol = normalized.findIndex((h) => ['name', 'person', 'full_name'].includes(h));
+    const sexCol = normalized.findIndex((h) => ['sex', 'gender'].includes(h));
+    const bornCol = normalized.findIndex((h) => ['born', 'birth', 'birthday', 'dob', 'birth_date'].includes(h));
+    const statusCol = normalized.findIndex((h) => ['status', 'alive'].includes(h));
+
+    if (nameCol >= 0) mapping[headers[nameCol]] = 'name';
+    if (sexCol >= 0) mapping[headers[sexCol]] = 'sex';
+    if (bornCol >= 0) mapping[headers[bornCol]] = 'born';
+    if (statusCol >= 0) mapping[headers[statusCol]] = 'status';
+  } else if (domain === 'process') {
+    const nameCol = normalized.findIndex((h) => ['step', 'task', 'name', 'activity'].includes(h));
+    const assigneeCol = normalized.findIndex((h) => ['assignee', 'owner', 'responsible', 'role'].includes(h));
+    const durationCol = normalized.findIndex((h) => ['duration', 'days', 'time'].includes(h));
+
+    if (nameCol >= 0) mapping[headers[nameCol]] = 'name';
+    if (assigneeCol >= 0) mapping[headers[assigneeCol]] = 'assignee';
+    if (durationCol >= 0) mapping[headers[durationCol]] = 'duration';
+  }
+
+  return mapping;
+}
+
+function toId(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_|_$/g, '')
+    .slice(0, 30);
+}
+
+function generateOrgchartRdm(
+  headers: string[],
+  data: string[][],
+  mapping: Record<string, string>,
+  csvPath: string
+): string {
+  const reverseMap: Record<string, number> = {};
+  for (const [col, field] of Object.entries(mapping)) {
+    const idx = headers.indexOf(col);
+    if (idx >= 0) reverseMap[field] = idx;
+  }
+
+  const title = basename(csvPath, '.csv').replace(/[-_]/g, ' ');
+  const lines: string[] = [
+    '---',
+    'type: orgchart',
+    `title: "${title}"`,
+    '---',
+    '',
+    `org ${title.replace(/[^a-zA-Z0-9]/g, '')} {`,
+  ];
+
+  // Build name→id map for reportsTo references
+  const nameToId: Record<string, string> = {};
+  for (const row of data) {
+    const name = reverseMap.name !== undefined ? row[reverseMap.name] : row[0];
+    if (name) nameToId[name] = toId(name);
+  }
+
+  for (const row of data) {
+    const name = reverseMap.name !== undefined ? row[reverseMap.name] : row[0];
+    if (!name) continue;
+
+    const id = toId(name);
+    const props: string[] = [];
+
+    if (reverseMap.title !== undefined && row[reverseMap.title]) {
+      props.push(`    title: "${row[reverseMap.title]}"`);
+    }
+    if (reverseMap.department !== undefined && row[reverseMap.department]) {
+      props.push(`    department: "${row[reverseMap.department]}"`);
+    }
+    if (reverseMap.level !== undefined && row[reverseMap.level]) {
+      props.push(`    level: ${row[reverseMap.level]}`);
+    }
+    if (reverseMap.reportsTo !== undefined && row[reverseMap.reportsTo]) {
+      const managerId = nameToId[row[reverseMap.reportsTo]] || toId(row[reverseMap.reportsTo]);
+      props.push(`    reportsTo: ${managerId}`);
+    }
+
+    lines.push(`  position ${id} "${name}" {`);
+    lines.push(...props);
+    lines.push('  }');
+  }
+
+  lines.push('}');
+  return lines.join('\n') + '\n';
+}
+
+function generateGenogramRdm(
+  headers: string[],
+  data: string[][],
+  mapping: Record<string, string>,
+  csvPath: string
+): string {
+  const reverseMap: Record<string, number> = {};
+  for (const [col, field] of Object.entries(mapping)) {
+    const idx = headers.indexOf(col);
+    if (idx >= 0) reverseMap[field] = idx;
+  }
+
+  const title = basename(csvPath, '.csv').replace(/[-_]/g, ' ');
+  const lines: string[] = [
+    '---',
+    'type: genogram',
+    `title: "${title}"`,
+    '---',
+    '',
+    `genogram ${title.replace(/[^a-zA-Z0-9]/g, '')} {`,
+    '  generation 1 {',
+  ];
+
+  for (const row of data) {
+    const name = reverseMap.name !== undefined ? row[reverseMap.name] : row[0];
+    if (!name) continue;
+
+    const id = toId(name);
+    const props: string[] = [];
+
+    if (reverseMap.sex !== undefined && row[reverseMap.sex]) {
+      props.push(`    sex: ${row[reverseMap.sex].toLowerCase()}`);
+    }
+    if (reverseMap.born !== undefined && row[reverseMap.born]) {
+      props.push(`    born: ${row[reverseMap.born]}`);
+    }
+    if (reverseMap.status !== undefined && row[reverseMap.status]) {
+      props.push(`    status: ${row[reverseMap.status].toLowerCase()}`);
+    }
+
+    lines.push(`    person ${id} "${name}" {`);
+    lines.push(...props.map((p) => '  ' + p));
+    lines.push('    }');
+  }
+
+  lines.push('  }');
+  lines.push('}');
+  return lines.join('\n') + '\n';
+}
+
+function generateProcessRdm(
+  headers: string[],
+  data: string[][],
+  mapping: Record<string, string>,
+  csvPath: string
+): string {
+  const reverseMap: Record<string, number> = {};
+  for (const [col, field] of Object.entries(mapping)) {
+    const idx = headers.indexOf(col);
+    if (idx >= 0) reverseMap[field] = idx;
+  }
+
+  const title = basename(csvPath, '.csv').replace(/[-_]/g, ' ');
+  const lines: string[] = [
+    '---',
+    'type: process',
+    `title: "${title}"`,
+    '---',
+    '',
+    `process ${title.replace(/[^a-zA-Z0-9]/g, '')} {`,
+  ];
+
+  const taskIds: string[] = [];
+
+  for (const row of data) {
+    const name = reverseMap.name !== undefined ? row[reverseMap.name] : row[0];
+    if (!name) continue;
+
+    const id = toId(name);
+    taskIds.push(id);
+    const props: string[] = ['    type: task'];
+
+    if (reverseMap.assignee !== undefined && row[reverseMap.assignee]) {
+      props.push(`    assignee: "${row[reverseMap.assignee]}"`);
+    }
+    if (reverseMap.duration !== undefined && row[reverseMap.duration]) {
+      props.push(`    duration: ${row[reverseMap.duration]}`);
+    }
+
+    lines.push(`  ${id} "${name}" {`);
+    lines.push(...props);
+    lines.push('  }');
+  }
+
+  // Add flow connections
+  if (taskIds.length > 1) {
+    lines.push('');
+    lines.push('  ' + taskIds.join(' -> '));
+  }
+
+  lines.push('}');
+  return lines.join('\n') + '\n';
+}

package/src/tools/rdm_init.ts

@@ -0,0 +1,146 @@
+/**
+ * rdm_init — Analyze project and generate RDM conventions
+ */
+import { readdirSync, readFileSync, existsSync, statSync } from 'fs';
+import { resolve, join, extname, relative } from 'path';
+
+export const rdmInitTool = {
+  name: 'rdm_init',
+  description:
+    'Analyze the current project directory to discover existing .rdm files, ' +
+    'CSV data sources, and configuration. Generates project-level RDM conventions ' +
+    'suitable for appending to CLAUDE.md.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      projectDir: {
+        type: 'string',
+        description: 'Project root directory to analyze (defaults to cwd)',
+      },
+    },
+  },
+};
+
+export async function executeRdmInit(args: Record<string, unknown>): Promise<unknown> {
+  const projectDir = resolve(String(args.projectDir ?? process.cwd()));
+
+  if (!existsSync(projectDir)) {
+    return { error: `Directory not found: ${projectDir}` };
+  }
+
+  // Scan for .rdm files
+  const rdmFiles = findFiles(projectDir, '.rdm', 5);
+
+  // Scan for CSV files
+  const csvFiles = findFiles(projectDir, '.csv', 3);
+
+  // Analyze existing .rdm files
+  const rdmAnalysis = rdmFiles.map((f) => {
+    const content = readFileSync(f, 'utf-8');
+    const typeMatch = content.match(/type:\s*(\w+)/);
+    const titleMatch = content.match(/title:\s*"([^"]+)"/);
+    return {
+      path: relative(projectDir, f),
+      type: typeMatch?.[1] ?? 'unknown',
+      title: titleMatch?.[1] ?? 'untitled',
+      lines: content.split('\n').length,
+    };
+  });
+
+  // Detect dominant diagram type
+  const typeCounts: Record<string, number> = {};
+  for (const r of rdmAnalysis) {
+    typeCounts[r.type] = (typeCounts[r.type] || 0) + 1;
+  }
+  const dominantType = Object.entries(typeCounts).sort((a, b) => b[1] - a[1])[0]?.[0] ?? 'orgchart';
+
+  // Generate conventions markdown
+  const conventions = generateConventions(rdmAnalysis, csvFiles.map((f) => relative(projectDir, f)), dominantType);
+
+  return {
+    projectDir,
+    rdmFileCount: rdmFiles.length,
+    csvFileCount: csvFiles.length,
+    rdmFiles: rdmAnalysis,
+    csvFiles: csvFiles.map((f) => relative(projectDir, f)),
+    dominantDiagramType: dominantType,
+    typeCounts,
+    conventions,
+  };
+}
+
+function findFiles(dir: string, ext: string, maxDepth: number, depth = 0): string[] {
+  if (depth > maxDepth) return [];
+
+  const results: string[] = [];
+
+  try {
+    const entries = readdirSync(dir);
+
+    for (const entry of entries) {
+      if (entry.startsWith('.') || entry === 'node_modules' || entry === 'dist') continue;
+
+      const fullPath = join(dir, entry);
+      try {
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          results.push(...findFiles(fullPath, ext, maxDepth, depth + 1));
+        } else if (extname(entry) === ext) {
+          results.push(fullPath);
+        }
+      } catch {
+        // Permission error, skip
+      }
+    }
+  } catch {
+    // Directory not readable
+  }
+
+  return results;
+}
+
+function generateConventions(
+  rdmFiles: Array<{ path: string; type: string; title: string }>,
+  csvFiles: string[],
+  dominantType: string
+): string {
+  const lines: string[] = [
+    '## RDM Conventions',
+    '',
+    `Primary diagram type: \`${dominantType}\``,
+    '',
+  ];
+
+  if (rdmFiles.length > 0) {
+    lines.push('### Existing Diagrams');
+    for (const f of rdmFiles.slice(0, 10)) {
+      lines.push(`- \`${f.path}\` — ${f.type}: ${f.title}`);
+    }
+    if (rdmFiles.length > 10) {
+      lines.push(`- ... and ${rdmFiles.length - 10} more`);
+    }
+    lines.push('');
+  }
+
+  if (csvFiles.length > 0) {
+    lines.push('### Data Sources');
+    for (const f of csvFiles.slice(0, 5)) {
+      lines.push(`- \`${f}\` — potential diagram data source`);
+    }
+    lines.push('');
+  }
+
+  lines.push('### Naming Rules');
+  lines.push('- File names: kebab-case with .rdm extension');
+  lines.push('- Node IDs: snake_case (e.g., `vp_eng`, `dad`)');
+  lines.push('- Display names: Quoted strings with proper names');
+  lines.push('');
+
+  lines.push('### Workflow');
+  lines.push('1. Generate .rdm file with `/rdm` skill');
+  lines.push('2. View with `bun run rdm-canvas <file.rdm>`');
+  lines.push('3. Edit in browser or text editor — changes sync bidirectionally');
+  lines.push('');
+
+  return lines.join('\n');
+}

package/src/tools/rdm_read.ts

@@ -0,0 +1,41 @@
+/**
+ * rdm_read — Read full .rdm file content
+ */
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+export const rdmReadTool = {
+  name: 'rdm_read',
+  description:
+    'Read the full content of an .rdm file. Returns the complete RDM markup ' +
+    'including frontmatter, structure, layout, and style blocks. ' +
+    'Use rdm_summary for a lightweight overview instead.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Path to the .rdm file to read',
+      },
+    },
+    required: ['path'],
+  },
+};
+
+export async function executeRdmRead(args: Record<string, unknown>): Promise<unknown> {
+  const filePath = resolve(String(args.path ?? ''));
+
+  if (!existsSync(filePath)) {
+    return { error: `File not found: ${filePath}` };
+  }
+
+  const content = readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n').length;
+
+  return {
+    path: filePath,
+    content,
+    lines,
+    sizeBytes: Buffer.byteLength(content, 'utf-8'),
+  };
+}

package/src/tools/rdm_render.ts

@@ -0,0 +1,58 @@
+/**
+ * rdm_render — Render an .rdm file to SVG
+ */
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { RdmService } from '@creately/rdm-core';
+
+const rdmService = new RdmService();
+
+export const rdmRenderTool = {
+  name: 'rdm_render',
+  description:
+    'Render an .rdm file to SVG. Returns the SVG markup for visual validation. ' +
+    'Use this to check what a diagram looks like.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Path to the .rdm file to render',
+      },
+      rdmText: {
+        type: 'string',
+        description: 'RDM text to render directly (alternative to path)',
+      },
+    },
+  },
+};
+
+export async function executeRdmRender(args: Record<string, unknown>): Promise<unknown> {
+  let rdmText: string;
+
+  if (args.rdmText) {
+    rdmText = String(args.rdmText);
+  } else if (args.path) {
+    const filePath = resolve(String(args.path));
+    if (!existsSync(filePath)) {
+      return { error: `File not found: ${filePath}` };
+    }
+    rdmText = readFileSync(filePath, 'utf-8');
+  } else {
+    return { error: 'Either path or rdmText must be provided' };
+  }
+
+  const result = rdmService.render(rdmText);
+
+  if (!result.success) {
+    return {
+      error: 'Render failed',
+      errors: result.errors,
+    };
+  }
+
+  return {
+    svg: result.svg,
+    svgLength: result.svg?.length ?? 0,
+  };
+}

package/src/tools/rdm_schema.ts

@@ -0,0 +1,135 @@
+/**
+ * rdm_schema — Domain schema: valid fields, relationships, examples
+ *
+ * Returns structured schema information for a given RDM domain type.
+ * Agents use this to generate correct RDM without guessing field names.
+ */
+
+interface FieldDef {
+  name: string;
+  type: string;
+  values?: string[];
+  description?: string;
+  required?: boolean;
+}
+
+interface DomainSchema {
+  domain: string;
+  description: string;
+  nodeTypes: Record<string, { fields: FieldDef[] }>;
+  relationships: Array<{ syntax: string; description: string }>;
+  structure: string;
+  example: string;
+}
+
+const SCHEMAS: Record<string, DomainSchema> = {
+  genogram: {
+    domain: 'genogram',
+    description: 'Family relationship diagrams for clinical, genealogical, or social contexts.',
+    nodeTypes: {
+      person: {
+        fields: [
+          { name: 'sex', type: 'enum', values: ['male', 'female'], required: true },
+          { name: 'born', type: 'date', description: 'Birth date (YYYY or YYYY-MM-DD)' },
+          { name: 'died', type: 'date', description: 'Death date' },
+          { name: 'status', type: 'enum', values: ['living', 'deceased'] },
+          { name: 'health', type: 'array', description: 'List of health conditions' },
+          { name: 'occupation', type: 'string' },
+          { name: 'education', type: 'string' },
+          { name: 'causeOfDeath', type: 'string' },
+          { name: 'adopted', type: 'boolean' },
+          { name: 'twin', type: 'enum', values: ['identical', 'fraternal'] },
+        ],
+      },
+    },
+    relationships: [
+      { syntax: 'married person1 -- person2 { since: YYYY }', description: 'Marriage' },
+      { syntax: 'divorced person1 -- person2 { since: YYYY }', description: 'Divorce' },
+      { syntax: 'child parent1, parent2 -> child_id', description: 'Parent-child (two parents)' },
+      { syntax: 'child parent1 -> child_id', description: 'Parent-child (single parent)' },
+      { syntax: 'twins monozygotic parent1, parent2 -> twin1, twin2', description: 'Identical twins' },
+      { syntax: 'twins dizygotic parent1, parent2 -> twin1, twin2', description: 'Fraternal twins' },
+      { syntax: 'close person1 -- person2', description: 'Emotional: close relationship' },
+      { syntax: 'conflict person1 -- person2', description: 'Emotional: conflict' },
+      { syntax: 'cutoff person1 -- person2', description: 'Emotional: cutoff' },
+    ],
+    structure: 'genogram Name {\n  generation N {\n    person id "Name" { sex: male, born: 1980 }\n    married p1 -- p2 { since: 2005 }\n    child p1, p2 -> child_id\n  }\n}',
+    example: '---\ntype: genogram\ntitle: "Sample Family"\n---\n\ngenogram Sample {\n  generation 1 {\n    person gf "John" { sex: male, born: 1940 }\n    person gm "Mary" { sex: female, born: 1942 }\n    married gf -- gm { since: 1962 }\n  }\n  generation 2 {\n    person dad "Bob" { sex: male, born: 1965 }\n    child gf, gm -> dad\n  }\n}',
+  },
+  orgchart: {
+    domain: 'orgchart',
+    description: 'Organizational hierarchy diagrams with positions and reporting relationships.',
+    nodeTypes: {
+      position: {
+        fields: [
+          { name: 'title', type: 'string', description: 'Job title', required: true },
+          { name: 'department', type: 'string' },
+          { name: 'level', type: 'number', description: 'Hierarchy level (1 = top)' },
+          { name: 'reportsTo', type: 'reference', description: 'ID of reporting-to position' },
+          { name: 'location', type: 'string' },
+          { name: 'status', type: 'enum', values: ['active', 'vacant', 'planned'] },
+        ],
+      },
+    },
+    relationships: [
+      { syntax: 'reportsTo: parent_id', description: 'Reporting relationship (in position props)' },
+      { syntax: 'team name under parent_id { ... }', description: 'Team grouping' },
+    ],
+    structure: 'org Name {\n  position id "Display Name" {\n    title: "...", department: "...", level: N\n    reportsTo: parent_id\n  }\n  team name under parent_id { ... }\n}',
+    example: '---\ntype: orgchart\ntitle: "Engineering"\n---\n\norg Engineering {\n  position ceo "Alice" { title: "CEO", level: 1 }\n  position vp "Bob" { title: "VP Eng", level: 2, reportsTo: ceo }\n}',
+  },
+  process: {
+    domain: 'process',
+    description: 'Business process and workflow diagrams with tasks and flows.',
+    nodeTypes: {
+      task: {
+        fields: [
+          { name: 'type', type: 'enum', values: ['task', 'start', 'end', 'decision', 'gateway'], required: true },
+          { name: 'assignee', type: 'string', description: 'Role or person responsible' },
+          { name: 'duration', type: 'number', description: 'Duration in days' },
+          { name: 'sla', type: 'number', description: 'SLA deadline in days' },
+          { name: 'priority', type: 'enum', values: ['low', 'medium', 'high', 'critical'] },
+        ],
+      },
+    },
+    relationships: [
+      { syntax: 'task1 -> task2', description: 'Sequential flow' },
+      { syntax: 'task1 -> task2 -> task3', description: 'Chained flow' },
+    ],
+    structure: 'process Name {\n  task_id "Display Name" { type: task, assignee: "Role" }\n  task1 -> task2 -> task3\n}',
+    example: '---\ntype: process\ntitle: "Approval"\n---\n\nprocess Approval {\n  submit "Submit" { type: task, assignee: "Requester" }\n  review "Review" { type: task, assignee: "Manager", sla: 2 }\n  submit -> review\n}',
+  },
+};
+
+export const rdmSchemaTool = {
+  name: 'rdm_schema',
+  description:
+    'Get the RDM schema for a diagram domain (genogram, orgchart, process). ' +
+    'Returns valid node types, fields, relationships, and syntax examples. ' +
+    'Use this before generating RDM to ensure correct syntax.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      domain: {
+        type: 'string',
+        enum: ['genogram', 'orgchart', 'process'],
+        description: 'The diagram domain to get schema for',
+      },
+    },
+    required: ['domain'],
+  },
+};
+
+export async function executeRdmSchema(args: Record<string, unknown>): Promise<unknown> {
+  const domain = String(args.domain ?? '').toLowerCase();
+  const schema = SCHEMAS[domain];
+
+  if (!schema) {
+    return {
+      error: `Unknown domain "${domain}". Valid: ${Object.keys(SCHEMAS).join(', ')}`,
+      availableDomains: Object.keys(SCHEMAS),
+    };
+  }
+
+  return schema;
+}

package/src/tools/rdm_summary.ts

@@ -0,0 +1,82 @@
+/**
+ * rdm_summary — Lightweight summary of an .rdm file (~200 tokens)
+ */
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { RdmService } from '@creately/rdm-core';
+
+const rdmService = new RdmService();
+
+export const rdmSummaryTool = {
+  name: 'rdm_summary',
+  description:
+    'Get a lightweight summary of an .rdm file (~200 tokens). ' +
+    'Returns node count, edge count, diagram type, and top-level structure. ' +
+    'Use this first to understand what a diagram contains before reading the full content.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Path to the .rdm file',
+      },
+    },
+    required: ['path'],
+  },
+};
+
+export async function executeRdmSummary(args: Record<string, unknown>): Promise<unknown> {
+  const filePath = resolve(String(args.path ?? ''));
+
+  if (!existsSync(filePath)) {
+    return { error: `File not found: ${filePath}` };
+  }
+
+  const content = readFileSync(filePath, 'utf-8');
+  const result = rdmService.parseAndValidate(content);
+
+  if (!result.success || !result.document) {
+    return {
+      path: filePath,
+      valid: false,
+      errorCount: result.errors.length,
+      errors: result.errors.slice(0, 3),
+    };
+  }
+
+  const doc = result.document;
+  const nodeCount = countType(doc.structure.declarations, 'node');
+  const edgeCount = countType(doc.structure.declarations, 'edge');
+  const groupCount = countType(doc.structure.declarations, 'group');
+  const genCount = countType(doc.structure.declarations, 'generation');
+
+  // Collect top-level IDs
+  const topIds: string[] = [];
+  for (const decl of doc.structure.declarations) {
+    if ('id' in decl && decl.id) topIds.push(decl.id as string);
+  }
+
+  return {
+    path: filePath,
+    valid: true,
+    type: doc.meta.type,
+    title: doc.meta.title,
+    nodeCount,
+    edgeCount,
+    groupCount,
+    generationCount: genCount,
+    warningCount: result.warnings.length,
+    topLevelIds: topIds.slice(0, 20),
+    hasLayout: (doc.layout?.length ?? 0) > 0,
+    hasStyle: (doc.style?.length ?? 0) > 0,
+  };
+}
+
+function countType(declarations: Array<{ type: string; declarations?: any[] }>, type: string): number {
+  let count = 0;
+  for (const d of declarations) {
+    if (d.type === type) count++;
+    if (d.declarations) count += countType(d.declarations, type);
+  }
+  return count;
+}

package/src/tools/rdm_validate.ts

@@ -0,0 +1,60 @@
+/**
+ * rdm_validate — Validate RDM text and return diagnostics
+ */
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { RdmService } from '@creately/rdm-core';
+
+const rdmService = new RdmService();
+
+export const rdmValidateTool = {
+  name: 'rdm_validate',
+  description:
+    'Validate an .rdm file or RDM text. Returns parse errors and warnings ' +
+    'with line numbers. Use this to check correctness before applying changes.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Path to the .rdm file to validate',
+      },
+      rdmText: {
+        type: 'string',
+        description: 'RDM text to validate directly (alternative to path)',
+      },
+    },
+  },
+};
+
+export async function executeRdmValidate(args: Record<string, unknown>): Promise<unknown> {
+  let rdmText: string;
+
+  if (args.rdmText) {
+    rdmText = String(args.rdmText);
+  } else if (args.path) {
+    const filePath = resolve(String(args.path));
+    if (!existsSync(filePath)) {
+      return { error: `File not found: ${filePath}` };
+    }
+    rdmText = readFileSync(filePath, 'utf-8');
+  } else {
+    return { error: 'Either path or rdmText must be provided' };
+  }
+
+  const result = rdmService.parseAndValidate(rdmText);
+
+  return {
+    valid: result.success,
+    errors: result.errors.map((e) => ({
+      code: e.code,
+      message: e.message,
+      line: e.line,
+      column: e.column,
+    })),
+    warnings: result.warnings.map((w) => ({
+      code: w.code,
+      message: w.message,
+    })),
+  };
+}

package/src/tools/rdm_write.ts

@@ -0,0 +1,107 @@
+/**
+ * rdm_write — Write or update an .rdm file
+ */
+import { writeFileSync, existsSync, readFileSync, mkdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { RdmService } from '@creately/rdm-core';
+
+const rdmService = new RdmService();
+
+export const rdmWriteTool = {
+  name: 'rdm_write',
+  description:
+    'Write or update an .rdm file. Can write a full document or merge a fragment ' +
+    'into an existing file. Validates the content before writing.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Path to write the .rdm file',
+      },
+      content: {
+        type: 'string',
+        description: 'Full RDM document text (with frontmatter) to write',
+      },
+      fragment: {
+        type: 'string',
+        description:
+          'RDM fragment to merge into an existing file. ' +
+          'If both content and fragment are provided, content takes priority.',
+      },
+    },
+    required: ['path'],
+  },
+};
+
+export async function executeRdmWrite(args: Record<string, unknown>): Promise<unknown> {
+  const filePath = resolve(String(args.path ?? ''));
+  const content = args.content as string | undefined;
+  const fragment = args.fragment as string | undefined;
+
+  if (!content && !fragment) {
+    return { error: 'Either content or fragment must be provided' };
+  }
+
+  let rdmText: string;
+
+  if (content) {
+    rdmText = content;
+  } else {
+    // Merge fragment into existing file
+    if (!existsSync(filePath)) {
+      return { error: `File not found for fragment merge: ${filePath}. Use content param for new files.` };
+    }
+
+    const existing = readFileSync(filePath, 'utf-8');
+    const parsed = rdmService.parseAndValidate(existing);
+    if (!parsed.success || !parsed.document) {
+      return { error: `Existing file has parse errors: ${parsed.errors.map((e) => e.message).join('; ')}` };
+    }
+
+    // Simple merge: insert fragment before the closing brace of the structure block
+    const lastBrace = existing.lastIndexOf('}');
+    if (lastBrace === -1) {
+      return { error: 'Cannot find structure block closing brace in existing file' };
+    }
+
+    rdmText = existing.slice(0, lastBrace) + '\n  ' + fragment!.trim() + '\n' + existing.slice(lastBrace);
+  }
+
+  // Validate before writing
+  const validation = rdmService.parseAndValidate(rdmText);
+  if (!validation.success) {
+    return {
+      error: 'Validation failed — not written',
+      errors: validation.errors,
+    };
+  }
+
+  // Ensure directory exists
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  writeFileSync(filePath, rdmText, 'utf-8');
+
+  const nodeCount = countType(validation.document!.structure.declarations, 'node');
+  const edgeCount = countType(validation.document!.structure.declarations, 'edge');
+
+  return {
+    path: filePath,
+    written: true,
+    nodeCount,
+    edgeCount,
+    sizeBytes: Buffer.byteLength(rdmText, 'utf-8'),
+  };
+}
+
+function countType(declarations: Array<{ type: string; declarations?: any[] }>, type: string): number {
+  let count = 0;
+  for (const d of declarations) {
+    if (d.type === type) count++;
+    if (d.declarations) count += countType(d.declarations, type);
+  }
+  return count;
+}