@rsconcept/rstool-mcp 0.1.6 → 0.3.1

package/src/server.ts

@@ -1,16 +1,18 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import {
   CallToolRequestSchema,
-  ListToolsRequestSchema
-} from '@modelcontextprotocol/sdk/types.js';
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
 
-import { RSToolAgent } from '@rsconcept/rstool';
+import { RSToolAgent } from "@rsconcept/rstool";
 
-import { TOOL_DEFINITIONS, type ToolDefinition } from './tools';
+import { TOOL_DEFINITIONS, type ToolDefinition } from "./tools";
 
 export interface BuildRSToolMcpServerOptions {
   /** Pre-built RSToolAgent. Defaults to a fresh in-memory instance. */
   tool?: RSToolAgent;
+  /** Persist sessions to this directory (also reads RSTOOL_PERSISTENCE_DIR when set). */
+  persistenceDir?: string;
   /** Server name advertised to MCP clients. */
   name?: string;
   /** Server version advertised to MCP clients. */
@@ -33,59 +35,68 @@ export interface BuildRSToolMcpServerOptions {
  * await server.connect(new StdioServerTransport());
  * ```
  */
-export function buildRSToolMcpServer(options: BuildRSToolMcpServerOptions = {}): McpServer {
-  const tool = options.tool ?? new RSToolAgent();
+export function buildRSToolMcpServer(
+  options: BuildRSToolMcpServerOptions = {},
+): McpServer {
+  const persistenceDir =
+    options.persistenceDir ?? process.env.RSTOOL_PERSISTENCE_DIR;
+  const tool =
+    options.tool ??
+    new RSToolAgent(persistenceDir ? { persistenceDir } : undefined);
   const server = new McpServer(
     {
-      name: options.name ?? 'rstool-mcp',
-      version: options.version ?? '0.1.0'
+      name: options.name ?? "rstool-mcp",
+      version: options.version ?? "0.1.0",
     },
     {
       capabilities: {
-        tools: {}
-      }
-    }
+        tools: {},
+      },
+    },
   );
 
   const definitionByName = new Map<string, ToolDefinition>(
-    TOOL_DEFINITIONS.map(definition => [definition.name, definition])
+    TOOL_DEFINITIONS.map((definition) => [definition.name, definition]),
   );
 
   server.server.setRequestHandler(ListToolsRequestSchema, () =>
     Promise.resolve({
-      tools: TOOL_DEFINITIONS.map(definition => ({
+      tools: TOOL_DEFINITIONS.map((definition) => ({
         name: definition.name,
         description: definition.description,
-        inputSchema: definition.inputSchema
-      }))
-    })
+        inputSchema: definition.inputSchema,
+      })),
+    }),
   );
 
-  server.server.setRequestHandler(CallToolRequestSchema, async request => {
+  server.server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const definition = definitionByName.get(request.params.name);
     if (!definition) {
       return {
         isError: true,
         content: [
           {
-            type: 'text' as const,
-            text: `Unknown rstool tool: ${request.params.name}`
-          }
-        ]
+            type: "text" as const,
+            text: `Unknown rstool tool: ${request.params.name}`,
+          },
+        ],
       };
     }
 
     try {
-      const result = await definition.invoke(tool, request.params.arguments ?? {});
+      const result = await definition.invoke(
+        tool,
+        request.params.arguments ?? {},
+      );
       const text =
-        typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+        typeof result === "string" ? result : JSON.stringify(result, null, 2);
       return {
         content: [
           {
-            type: 'text' as const,
-            text
-          }
-        ]
+            type: "text" as const,
+            text,
+          },
+        ],
       };
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
@@ -93,10 +104,10 @@ export function buildRSToolMcpServer(options: BuildRSToolMcpServerOptions = {}):
         isError: true,
         content: [
           {
-            type: 'text' as const,
-            text: `rstool error in ${definition.name}: ${message}`
-          }
-        ]
+            type: "text" as const,
+            text: `rstool error in ${definition.name}: ${message}`,
+          },
+        ],
       };
     }
   });

package/src/tools.ts

@@ -1,286 +1,350 @@
 /**
  * MCP tool definitions for the @rsconcept/rstool contract.
- *
- * Schemas are intentionally permissive (additionalProperties: true) where the rstool input
- * is structurally rich (e.g. ConstituentaDraft, SessionState). The wrapped RSToolAgent
- * validates inputs at runtime and returns deterministic error responses.
  */
 
-import { type RSToolAgent } from '@rsconcept/rstool';
+import { type RSToolAgent } from "@rsconcept/rstool";
 
 export interface ToolDefinition {
   name: string;
   description: string;
   inputSchema: {
-    type: 'object';
+    type: "object";
     properties: Record<string, unknown>;
     required?: string[];
     additionalProperties?: boolean;
   };
-  invoke: (tool: RSToolAgent, args: Record<string, unknown>) => unknown | Promise<unknown>;
+  invoke: (
+    tool: RSToolAgent,
+    args: Record<string, unknown>,
+  ) => unknown | Promise<unknown>;
 }
 
 const sessionId = {
-  type: 'string',
-  description: 'Session identifier returned from create_session or import_session.'
+  type: "string",
+  description: "Session id. Omit to use the current active session.",
 };
 
-export const TOOL_DEFINITIONS: ToolDefinition[] = [
-  {
-    name: 'ping',
-    description: 'Liveness check; returns {pong: true} and the active rstool contract version.',
-    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-    invoke: tool => ({ pong: true, contractVersion: tool.contractVersion })
+const agentPatchSchema = {
+  type: "object",
+  description:
+    "Agent-friendly constituent patch. id and cstType are optional; cstType is inferred from alias prefixes X/C/S/D/A/F/P.",
+  properties: {
+    id: { type: "number" },
+    alias: { type: "string" },
+    cstType: { type: "string" },
+    definitionFormal: { type: "string" },
+    term: { type: "string" },
+    definitionText: { type: "string" },
+    convention: { type: "string" },
   },
+  required: ["alias"],
+};
+
+function optionalSessionId(args: Record<string, unknown>): string | undefined {
+  const value = args.sessionId;
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function omitSessionId(args: Record<string, unknown>): Record<string, unknown> {
+  const { sessionId: _sessionId, ...rest } = args;
+  return rest;
+}
+
+export const TOOL_DEFINITIONS: ToolDefinition[] = [
   {
-    name: 'list_methods',
-    description: 'List all rstool methods exposed as MCP tools.',
-    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-    invoke: () => TOOL_DEFINITIONS.map(definition => definition.name)
+    name: "ping",
+    description:
+      "Liveness check; returns {pong: true} and the active rstool contract version.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    invoke: (tool) => ({ pong: true, contractVersion: tool.contractVersion }),
   },
   {
-    name: 'create_session',
-    description:
-      'Create a fresh in-memory rstool session. Returns a SessionHandle with sessionId and initial revision.',
+    name: "list_methods",
+    description: "List all rstool methods exposed as MCP tools.",
     inputSchema: {
-      type: 'object',
-      properties: {
-        initial: {
-          type: 'object',
-          description: 'Optional partial SessionState seed (alias, title, constituents, etc.).',
-          additionalProperties: true
-        }
-      },
-      additionalProperties: false
+      type: "object",
+      properties: {},
+      additionalProperties: false,
     },
-    invoke: (tool, args) => tool.createSession(args.initial as never)
+    invoke: () => TOOL_DEFINITIONS.map((definition) => definition.name),
   },
   {
-    name: 'add_or_update_constituenta',
+    name: "ensure_session",
     description:
-      'Upsert a single constituent in the session. Provide alias, cstType, definitionFormal (may be ""), and optional term/definitionText/convention.',
+      "Return the current active session, or create one if none exists. Optional initial seed is used only when creating.",
     inputSchema: {
-      type: 'object',
+      type: "object",
       properties: {
-        sessionId,
-        input: {
-          type: 'object',
-          description: 'AddOrUpdateConstituentaInput. Required keys: alias, cstType, definitionFormal.',
-          additionalProperties: true
-        }
+        initial: {
+          type: "object",
+          properties: {
+            alias: { type: "string" },
+            title: { type: "string" },
+            comment: { type: "string" },
+          },
+          additionalProperties: true,
+        },
       },
-      required: ['sessionId', 'input']
+      additionalProperties: false,
     },
-    invoke: (tool, args) =>
-      tool.addOrUpdateConstituenta(String(args.sessionId), args.input as never)
+    invoke: (tool, args) => tool.ensureSession(args.initial as never),
   },
   {
-    name: 'analyze_expression',
+    name: "create_session",
     description:
-      'Run parser + semantic analysis on a scratch RSLang expression in the session context. Returns typification, valueClass, success flag and diagnostics.',
+      "Create a fresh in-memory rstool session and set it as the current active session.",
     inputSchema: {
-      type: 'object',
+      type: "object",
       properties: {
-        sessionId,
-        input: {
-          type: 'object',
-          description: 'AnalyzeExpressionInput. Required keys: expression, cstType.',
+        initial: {
+          type: "object",
+          description:
+            "Optional partial SessionState seed (alias, title, comment).",
           properties: {
-            expression: { type: 'string' },
-            cstType: { type: 'string' },
-            alias: { type: 'string' }
+            alias: { type: "string" },
+            title: { type: "string" },
+            comment: { type: "string" },
           },
-          required: ['expression', 'cstType'],
-          additionalProperties: true
-        }
+          additionalProperties: false,
+        },
       },
-      required: ['sessionId', 'input']
+      additionalProperties: false,
     },
-    invoke: (tool, args) =>
-      tool.analyzeExpression(String(args.sessionId), args.input as never)
+    invoke: (tool, args) => tool.createSession(args.initial as never),
   },
   {
-    name: 'get_form_state',
-    description: 'Return the full SessionState (constituents, revision, alias, title, etc.).',
+    name: "set_current_session",
+    description: "Set the active session by id.",
     inputSchema: {
-      type: 'object',
+      type: "object",
       properties: { sessionId },
-      required: ['sessionId']
+      required: ["sessionId"],
     },
-    invoke: (tool, args) => tool.getFormState(String(args.sessionId))
+    invoke: (tool, args) => tool.setCurrentSession(String(args.sessionId)),
   },
   {
-    name: 'list_diagnostics',
+    name: "get_current_session",
+    description: "Return the current active session, or null if none exists.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    invoke: (tool) => tool.getCurrentSession(),
+  },
+  {
+    name: "apply_schema_patch",
     description:
-      'List diagnostics across the session, optionally filtered by constituentId / severity / classes.',
+      "Preferred schema edit path. Batch patch with inferred ids and cstType, dependency ordering, and compact summary.",
     inputSchema: {
-      type: 'object',
+      type: "object",
       properties: {
         sessionId,
-        filters: {
-          type: 'object',
-          description: 'Optional ListDiagnosticsFilters object.',
-          additionalProperties: true
-        }
+        initial: {
+          type: "object",
+          properties: {
+            alias: { type: "string" },
+            title: { type: "string" },
+            comment: { type: "string" },
+          },
+          additionalProperties: true,
+        },
+        items: { type: "array", items: agentPatchSchema },
+        mode: { type: "string", enum: ["atomic", "best_effort"] },
+        commitMessage: { type: "string" },
       },
-      required: ['sessionId']
+      required: ["items"],
     },
     invoke: (tool, args) =>
-      tool.listDiagnostics(String(args.sessionId), args.filters as never)
+      tool.applySchemaPatch(
+        omitSessionId(args) as never,
+        optionalSessionId(args),
+      ),
   },
   {
-    name: 'commit_step',
-    description: 'Record a session revision with an optional human-readable message.',
+    name: "get_session_state",
+    description:
+      "Return session state. detail=summary (default): compact metadata, aliases, diagnostics. detail=full: complete SessionState clone.",
     inputSchema: {
-      type: 'object',
+      type: "object",
       properties: {
         sessionId,
-        message: { type: 'string' }
+        detail: { type: "string", enum: ["summary", "full"] },
       },
-      required: ['sessionId']
     },
     invoke: (tool, args) =>
-      tool.commitStep(String(args.sessionId), args.message as string | undefined)
+      tool.getSessionState(
+        (args.detail as "summary" | "full" | undefined) ?? "summary",
+        optionalSessionId(args),
+      ),
   },
   {
-    name: 'export_session',
-    description: 'Serialize the session to a JSON string suitable for import_session.',
+    name: "analyze_expression",
+    description:
+      "Parse and type-check a scratch expression without saving it. Does not record diagnostics unless recordDiagnostics=true.",
     inputSchema: {
-      type: 'object',
-      properties: { sessionId },
-      required: ['sessionId']
+      type: "object",
+      properties: {
+        sessionId,
+        expression: { type: "string" },
+        cstType: { type: "string" },
+        recordDiagnostics: { type: "boolean" },
+      },
+      required: ["expression", "cstType"],
     },
-    invoke: (tool, args) => tool.exportSession(String(args.sessionId))
+    invoke: (tool, args) =>
+      tool.analyzeExpression(
+        omitSessionId(args) as never,
+        optionalSessionId(args),
+      ),
   },
   {
-    name: 'import_session',
+    name: "list_diagnostics",
     description:
-      'Import a session previously produced by export_session. Returns a fresh SessionHandle pointing at the restored state.',
+      "List active diagnostics for the session (one record set per constituent, not a historical log).",
     inputSchema: {
-      type: 'object',
+      type: "object",
       properties: {
-        payload: { type: 'string', description: 'JSON payload from export_session.' }
+        sessionId,
+        constituentId: { type: "number" },
       },
-      required: ['payload']
     },
-    invoke: (tool, args) => tool.importSession(String(args.payload))
+    invoke: (tool, args) => {
+      const constituentId = args.constituentId;
+      const filters =
+        typeof constituentId === "number" ? { constituentId } : undefined;
+      return tool.listDiagnostics(filters, optionalSessionId(args));
+    },
   },
   {
-    name: 'set_constituenta_value',
+    name: "commit_step",
     description:
-      'Bind or assign a value to a single interpretable constituent (basic, constant, structure). Inferrable constituents (term, axiom, statement) cannot be set directly.',
+      "Record a session revision with an optional human-readable message.",
     inputSchema: {
-      type: 'object',
+      type: "object",
       properties: {
         sessionId,
-        input: {
-          type: 'object',
-          description: 'SetConstituentaValueInput. Required keys: target (id), value.',
-          additionalProperties: true
-        }
+        message: { type: "string" },
       },
-      required: ['sessionId', 'input']
     },
     invoke: (tool, args) =>
-      tool.setConstituentaValue(String(args.sessionId), args.input as never)
+      tool.commitStep(
+        args.message as string | undefined,
+        optionalSessionId(args),
+      ),
   },
   {
-    name: 'set_constituenta_values',
-    description: 'Batch variant of set_constituenta_value: assign values to multiple interpretable constituents.',
+    name: "export_session",
+    description:
+      "Serialize the session to a JSON string suitable for import_data with kind=session.",
     inputSchema: {
-      type: 'object',
-      properties: {
-        sessionId,
-        input: {
-          type: 'object',
-          description: 'SetConstituentaValuesInput. Required keys: values (list of {target, value}).',
-          additionalProperties: true
-        }
-      },
-      required: ['sessionId', 'input']
+      type: "object",
+      properties: { sessionId },
     },
-    invoke: (tool, args) =>
-      tool.setConstituentaValues(String(args.sessionId), args.input as never)
+    invoke: (tool, args) => tool.exportSession(optionalSessionId(args)),
   },
   {
-    name: 'clear_constituenta_values',
-    description: 'Clear current values for one or more constituents and reset dependents to NOT_PROCESSED.',
+    name: "export_portal",
+    description:
+      "Export Portal Load-from-JSON payload. kind=schema|model; format=json (default string) or object.",
     inputSchema: {
-      type: 'object',
+      type: "object",
       properties: {
         sessionId,
-        input: {
-          type: 'object',
-          description: 'ClearConstituentaValuesInput. Required keys: targets (list of ids).',
-          additionalProperties: true
-        }
+        kind: { type: "string", enum: ["schema", "model"] },
+        format: { type: "string", enum: ["json", "object"] },
       },
-      required: ['sessionId', 'input']
+      required: ["kind"],
     },
     invoke: (tool, args) =>
-      tool.clearConstituentaValues(String(args.sessionId), args.input as never)
+      tool.exportPortal(omitSessionId(args) as never, optionalSessionId(args)),
   },
   {
-    name: 'get_model_state',
-    description: 'Return the SessionModelState — current values and evaluation statuses for every constituent.',
+    name: "import_data",
+    description:
+      "Import a session from export_session JSON, Portal schema JSON, or GET /api/rsforms/:id/details. kind=auto (default) detects the shape.",
     inputSchema: {
-      type: 'object',
-      properties: { sessionId },
-      required: ['sessionId']
+      type: "object",
+      properties: {
+        payload: {
+          description:
+            "JSON string or parsed object (session export, Portal schema, or rsform details).",
+        },
+        kind: {
+          type: "string",
+          enum: ["auto", "session", "portal-schema", "portal-details"],
+        },
+      },
+      required: ["payload"],
     },
-    invoke: (tool, args) => tool.getModelState(String(args.sessionId))
+    invoke: (tool, args) =>
+      tool.importData(args.payload as string | object, args.kind as never),
   },
   {
-    name: 'evaluate_expression',
+    name: "set_model_values",
     description:
-      'Evaluate a scratch RSLang expression against the current bindings without storing it. Returns value + evaluation status.',
+      "Set and/or clear interpretable model bindings. Pass set[] for bindings and clear[] for constituent ids to reset.",
     inputSchema: {
-      type: 'object',
+      type: "object",
       properties: {
         sessionId,
-        input: {
-          type: 'object',
-          description: 'EvaluateExpressionInput. Required keys: expression. Optional: cstType, alias.',
-          properties: {
-            expression: { type: 'string' },
-            cstType: { type: 'string' },
-            alias: { type: 'string' }
+        set: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              target: { type: "number" },
+              type: { type: "string" },
+              value: {},
+            },
+            required: ["target", "value"],
           },
-          required: ['expression'],
-          additionalProperties: true
-        }
+        },
+        clear: { type: "array", items: { type: "number" } },
       },
-      required: ['sessionId', 'input']
     },
     invoke: (tool, args) =>
-      tool.evaluateExpression(String(args.sessionId), args.input as never)
+      tool.setModelValues(
+        omitSessionId(args) as never,
+        optionalSessionId(args),
+      ),
   },
   {
-    name: 'evaluate_constituenta',
-    description: 'Evaluate a stored derived constituent (term, axiom, statement) using the current bindings.',
+    name: "get_model_state",
+    description: "Return the SessionModelState.",
     inputSchema: {
-      type: 'object',
+      type: "object",
+      properties: { sessionId },
+    },
+    invoke: (tool, args) => tool.getModelState(optionalSessionId(args)),
+  },
+  {
+    name: "evaluate",
+    description:
+      "Evaluate a scratch expression (expression + cstType) or a stored constituent (constituentId).",
+    inputSchema: {
+      type: "object",
       properties: {
         sessionId,
-        input: {
-          type: 'object',
-          description: 'EvaluateConstituentaInput. Required keys: target (id).',
-          additionalProperties: true
-        }
+        expression: { type: "string" },
+        cstType: { type: "string" },
+        constituentId: { type: "number" },
       },
-      required: ['sessionId', 'input']
     },
     invoke: (tool, args) =>
-      tool.evaluateConstituenta(String(args.sessionId), args.input as never)
+      tool.evaluate(omitSessionId(args) as never, optionalSessionId(args)),
   },
   {
-    name: 'recalculate_model',
-    description: 'Recompute every interpretable / inferrable constituent using current bindings. Returns the updated SessionModelState.',
+    name: "recalculate_model",
+    description: "Recompute every inferrable constituent.",
     inputSchema: {
-      type: 'object',
+      type: "object",
       properties: { sessionId },
-      required: ['sessionId']
     },
-    invoke: (tool, args) => tool.recalculateModel(String(args.sessionId))
-  }
+    invoke: (tool, args) => tool.recalculateModel(optionalSessionId(args)),
+  },
 ];