@creately/rdm-mcp 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creately/rdm-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for RDM — parse, validate, render, and manipulate diagrams via AI agents",
   "type": "module",
   "main": "src/index.ts",
@@ -13,7 +13,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "@creately/rdm-core": "workspace:*"
+    "@creately/rdm-core": ">=0.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -1,7 +1,8 @@
 /**
  * RDM MCP Server
  *
- * Provides 8 tools for agents to interact with RDM diagrams:
+ * Provides 9 tools for agents to interact with RDM diagrams:
+ *   rdm_guide    — Complete generation guide with syntax and examples
  *   rdm_read     — Full .rdm text (rich context)
  *   rdm_summary  — Lightweight: node count, types, relationships
  *   rdm_write    — Write/update .rdm file
@@ -33,8 +34,10 @@ 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';
+import { rdmGuideTool, executeRdmGuide } from './tools/rdm_guide.js';
 
 const ALL_TOOLS = [
+  rdmGuideTool,
   rdmReadTool,
   rdmSummaryTool,
   rdmWriteTool,
@@ -46,6 +49,7 @@ const ALL_TOOLS = [
 ];
 
 const TOOL_EXECUTORS: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+  rdm_guide: executeRdmGuide,
   rdm_read: executeRdmRead,
   rdm_summary: executeRdmSummary,
   rdm_write: executeRdmWrite,
@@ -58,7 +62,7 @@ const TOOL_EXECUTORS: Record<string, (args: Record<string, unknown>) => Promise<
 
 async function main() {
   const server = new Server(
-    { name: 'rdm-mcp', version: '0.1.0' },
+    { name: 'rdm-mcp', version: '0.2.0' },
     { capabilities: { tools: {} } }
   );
 

package/src/tools/rdm_guide.ts

@@ -0,0 +1,76 @@
+/**
+ * rdm_guide — Returns the RDM generation guide for agents.
+ *
+ * Provides the complete syntax guide, domain types, and examples
+ * so agents can generate valid RDM without needing a local CLAUDE.md.
+ */
+
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+let cachedGuide: string | null = null;
+
+function loadGuide(): string {
+  if (cachedGuide) return cachedGuide;
+
+  // Try to load CLAUDE.md from the repo root (3 levels up from tools/)
+  const toolDir = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    resolve(toolDir, '../../../../CLAUDE.md'),
+    resolve(toolDir, '../../../CLAUDE.md'),
+  ];
+
+  for (const path of candidates) {
+    try {
+      cachedGuide = readFileSync(path, 'utf-8');
+      return cachedGuide;
+    } catch {
+      // continue
+    }
+  }
+
+  // Fallback inline guide
+  cachedGuide = `# RDM Generation Guide
+
+RDM (Rich Diagram Markup) is a text-based format for diagrams.
+
+## Supported Types
+- genogram — Family trees with clinical data
+- orgchart — Organizational hierarchies
+- flowchart — Simple step-by-step flows
+- process — BPMN workflows with events and gateways
+- table — Grid diagrams (SWOT, kanban, RACI, BMC, etc.)
+
+## Basic Structure
+\`\`\`
+---
+type: <diagram-type>
+title: "<Title>"
+---
+
+<block-keyword> <Name> {
+  <declarations>
+}
+\`\`\`
+
+Use rdm_schema tool to get detailed syntax for each domain type.
+Use rdm_validate to check your generated files.
+`;
+  return cachedGuide;
+}
+
+export const rdmGuideTool = {
+  name: 'rdm_guide',
+  description:
+    'Get the complete RDM generation guide with syntax templates and examples for all diagram types. ' +
+    'Call this first when you need to generate RDM diagrams.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {},
+  },
+};
+
+export async function executeRdmGuide(_args: Record<string, unknown>): Promise<unknown> {
+  return { guide: loadGuide() };
+}

package/src/tools/rdm_schema.ts

@@ -80,12 +80,14 @@ const SCHEMAS: Record<string, DomainSchema> = {
   },
   process: {
     domain: 'process',
-    description: 'Business process and workflow diagrams with tasks and flows.',
+    description: 'Business process, workflow, and BPMN diagrams with tasks, gateways, and flows.',
     nodeTypes: {
       task: {
         fields: [
-          { name: 'type', type: 'enum', values: ['task', 'start', 'end', 'decision', 'gateway'], required: true },
+          { name: 'type', type: 'enum', values: ['task', 'start', 'end', 'gateway', 'start-event', 'end-event', 'intermediate-event', 'timer-event', 'message-event', 'exclusive-gateway', 'parallel-gateway', 'inclusive-gateway', 'user-task', 'service-task', 'script-task', 'send-task', 'receive-task', 'sub-process', 'data-object', 'data-store'], required: true },
+          { name: 'label', type: 'string', description: 'Display label for the node' },
           { name: 'assignee', type: 'string', description: 'Role or person responsible' },
+          { name: 'trigger', type: 'enum', values: ['message', 'timer', 'error', 'signal', 'conditional', 'terminate'], description: 'Event trigger type (for events)' },
           { 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'] },
@@ -94,17 +96,81 @@ const SCHEMAS: Record<string, DomainSchema> = {
     },
     relationships: [
       { syntax: 'task1 -> task2', description: 'Sequential flow' },
-      { syntax: 'task1 -> task2 -> task3', description: 'Chained flow' },
+      { syntax: 'task1 -> task2 { label: "Yes" }', description: 'Labeled flow (for gateways)' },
+      { syntax: 'task1 -> task2 { type: "message" }', description: 'Message flow (cross-pool)' },
     ],
-    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}',
+    structure: 'process Name {\n  node_id { type: "node-type", label: "Display" }\n  source -> target\n  source -> target { label: "Condition" }\n}',
+    example: '---\ntype: process\ntitle: "Payment"\n---\n\nprocess Payment {\n  start { type: "start-event", trigger: "message" }\n  validate { type: "service-task", label: "Validate" }\n  check { type: "exclusive-gateway", label: "Valid?" }\n  pay { type: "service-task", label: "Process" }\n  done { type: "end-event" }\n\n  start -> validate\n  validate -> check\n  check -> pay { label: "Yes" }\n  pay -> done\n}',
+  },
+  flowchart: {
+    domain: 'flowchart',
+    description: 'Simple flowchart diagrams with steps, decisions, and flows.',
+    nodeTypes: {
+      step: {
+        fields: [
+          { name: 'type', type: 'enum', values: ['process', 'decision', 'start', 'end', 'subprocess', 'document', 'database'] },
+        ],
+      },
+    },
+    relationships: [
+      { syntax: 'flow source -> target', description: 'Sequential flow' },
+      { syntax: 'flow source -> target { label: "Yes" }', description: 'Labeled flow' },
+    ],
+    structure: 'flowchart Name {\n  start begin "Start"\n  step id "Label" { type: process }\n  end done "End"\n  flow begin -> id\n  flow id -> done\n}',
+    example: '---\ntype: flowchart\ntitle: "Approval"\n---\n\nflowchart Approval {\n  start begin "Start"\n  step submit "Submit Request" { type: process }\n  step check "Approved?" { type: decision }\n  end done "Done"\n\n  flow begin -> submit\n  flow submit -> check\n  flow check -> done { label: "Yes" }\n}',
+  },
+  table: {
+    domain: 'table',
+    description: 'Grid-based diagrams: SWOT, kanban, retro, RACI, business model canvas, comparison matrices, and custom tables.',
+    nodeTypes: {
+      sticky: { fields: [
+        { name: 'cell', type: 'string', description: 'Cell label to place this item in', required: true },
+        { name: 'assignee', type: 'string' },
+        { name: 'color', type: 'string' },
+      ] },
+      card: { fields: [
+        { name: 'cell', type: 'string', description: 'Cell label to place this item in', required: true },
+        { name: 'assignee', type: 'string' },
+        { name: 'points', type: 'number' },
+        { name: 'priority', type: 'enum', values: ['low', 'medium', 'high', 'critical'] },
+      ] },
+      text: { fields: [
+        { name: 'cell', type: 'string', required: true },
+      ] },
+    },
+    relationships: [],
+    structure: '@type table\n@title "Title"\n\ntable <schema> "Display Name" { layout: stack }\n\nsticky id "Content" { cell: "Cell Name" }',
+    example: '@type table\n@title "Product SWOT"\n\ntable swot "SWOT Analysis" { layout: stack }\n\nsticky s1 "Strong brand" { cell: "Strengths" }\nsticky w1 "Limited budget" { cell: "Weaknesses" }\nsticky o1 "AI trend" { cell: "Opportunities" }\nsticky t1 "Regulations" { cell: "Threats" }',
+  },
+  'change-summary': {
+    domain: 'change-summary',
+    description: 'Architecture change impact diagrams showing modules, decisions, and notes.',
+    nodeTypes: {
+      module: { fields: [
+        { name: 'status', type: 'enum', values: ['new', 'modified', 'affected', 'deleted'] },
+        { name: 'files', type: 'array', description: 'List of affected file paths' },
+        { name: 'description', type: 'string' },
+      ] },
+      note: { fields: [
+        { name: 'description', type: 'string' },
+      ] },
+      decision: { fields: [
+        { name: 'risk', type: 'enum', values: ['high', 'medium', 'low'] },
+        { name: 'description', type: 'string' },
+      ] },
+    },
+    relationships: [
+      { syntax: 'module1 -> module2 : dependency', description: 'Module dependency' },
+    ],
+    structure: 'change-summary Name {\n  module id "Name" { status: modified, files: ["path"] }\n  note id "Text"\n  decision id "Text" { risk: medium }\n  id1 -> id2 : dependency\n}',
+    example: '---\ntype: change-summary\ntitle: "Auth Refactor"\n---\n\nchange-summary AuthRefactor {\n  module auth "Auth Service" { status: modified, files: ["src/auth/service.ts"] }\n  module users "User Model" { status: affected }\n  decision d1 "Switch to JWT" { risk: medium }\n  auth -> users : dependency\n}',
   },
 };
 
 export const rdmSchemaTool = {
   name: 'rdm_schema',
   description:
-    'Get the RDM schema for a diagram domain (genogram, orgchart, process). ' +
+    'Get the RDM schema for a diagram domain. ' +
     'Returns valid node types, fields, relationships, and syntax examples. ' +
     'Use this before generating RDM to ensure correct syntax.',
   inputSchema: {
@@ -112,7 +178,7 @@ export const rdmSchemaTool = {
     properties: {
       domain: {
         type: 'string',
-        enum: ['genogram', 'orgchart', 'process'],
+        enum: ['genogram', 'orgchart', 'process', 'flowchart', 'table', 'change-summary'],
         description: 'The diagram domain to get schema for',
       },
     },