palaryn 0.1.0 → 0.3.2

package/src/mcp/tool-definitions.ts

@@ -0,0 +1,562 @@
+import { randomUUID } from 'crypto';
+import { ToolCall, ToolCallArgs, ToolInfo } from '../types/tool-call';
+import { MCPBridgeConfig } from './bridge';
+
+// ---------------------------------------------------------------------------
+// MCP tool definition type (subset needed for tools/list)
+// ---------------------------------------------------------------------------
+
+export interface MCPToolDefinition {
+  name: string;
+  description?: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+  annotations?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// MCPToolHandler interface
+// ---------------------------------------------------------------------------
+
+export interface MCPToolHandler {
+  definition: MCPToolDefinition;
+  buildToolCall(args: Record<string, unknown>, bridgeConfig: Required<MCPBridgeConfig>): ToolCall;
+}
+
+// ---------------------------------------------------------------------------
+// Shared helper: build a ToolCall from common parameters
+// ---------------------------------------------------------------------------
+
+export function buildToolCallHelper(params: {
+  toolName: string;
+  capability: ToolInfo['capability'];
+  args: ToolCallArgs;
+  constraints?: { timeout_ms?: number; max_cost_usd?: number };
+  context?: { purpose?: string; labels?: string[] };
+  bridgeConfig: Required<MCPBridgeConfig>;
+}): ToolCall {
+  const toolCall: ToolCall = {
+    tool_call_id: randomUUID(),
+    task_id: params.bridgeConfig.task_id || randomUUID(),
+    workspace_id: params.bridgeConfig.workspace_id,
+    actor: { ...params.bridgeConfig.actor },
+    source: { ...params.bridgeConfig.source },
+    tool: {
+      name: params.toolName,
+      version: '1.0.0',
+      capability: params.capability,
+    },
+    args: params.args,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Add constraints if any are specified
+  if (params.constraints?.timeout_ms != null || params.constraints?.max_cost_usd != null) {
+    toolCall.constraints = {};
+    if (params.constraints.timeout_ms != null) {
+      toolCall.constraints.timeout_ms = params.constraints.timeout_ms;
+    }
+    if (params.constraints.max_cost_usd != null) {
+      toolCall.constraints.max_cost_usd = params.constraints.max_cost_usd;
+    }
+  }
+
+  // Add context if any is specified
+  if (params.context?.purpose || params.context?.labels) {
+    toolCall.context = {};
+    if (params.context.purpose) {
+      toolCall.context.purpose = params.context.purpose;
+    }
+    if (params.context.labels) {
+      toolCall.context.labels = params.context.labels;
+    }
+  }
+
+  return toolCall;
+}
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Map an HTTP method to a ToolInfo capability level.
+ */
+function methodToCapability(method: string): ToolInfo['capability'] {
+  switch (method.toUpperCase()) {
+    case 'GET':
+    case 'HEAD':
+    case 'OPTIONS':
+      return 'read';
+    case 'POST':
+    case 'PUT':
+    case 'PATCH':
+      return 'write';
+    case 'DELETE':
+      return 'delete';
+    default:
+      return 'write';
+  }
+}
+
+/**
+ * Attempt to parse a body string as JSON, falling back to the raw string.
+ */
+function parseBody(body: string): unknown {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return body;
+  }
+}
+
+/**
+ * Extract common HTTP constraints and context from MCP args.
+ */
+function extractHttpMeta(args: Record<string, unknown>) {
+  return {
+    constraints: {
+      timeout_ms: typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined,
+      max_cost_usd: typeof args.max_cost_usd === 'number' ? args.max_cost_usd : undefined,
+    },
+    context: {
+      purpose: typeof args.purpose === 'string' ? args.purpose : undefined,
+      labels: Array.isArray(args.labels) ? args.labels : undefined,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// HTTP Tool Handlers
+// ---------------------------------------------------------------------------
+
+const httpRequestHandler: MCPToolHandler = {
+  definition: {
+    name: 'http_request',
+    description:
+      'Execute an HTTP request through the Palaryn gateway. ' +
+      'Supports all HTTP methods. The request goes through policy evaluation, ' +
+      'DLP scanning, budget checks, and rate limiting before execution.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'The target URL for the HTTP request' },
+        method: {
+          type: 'string',
+          enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
+          description: 'HTTP method (defaults to GET)',
+        },
+        headers: {
+          type: 'object',
+          additionalProperties: { type: 'string' },
+          description: 'HTTP headers as key-value pairs',
+        },
+        body: {
+          type: 'string',
+          description: 'Request body (typically JSON string for POST/PUT/PATCH)',
+        },
+        timeout_ms: { type: 'number', description: 'Request timeout in milliseconds' },
+        max_cost_usd: {
+          type: 'number',
+          description: 'Maximum cost budget for this request in USD',
+        },
+        purpose: {
+          type: 'string',
+          description: 'Description of why this request is being made',
+        },
+        labels: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Classification labels for the request',
+        },
+      },
+      required: ['url'],
+    },
+    annotations: {
+      title: 'HTTP Request',
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: true,
+    },
+  },
+
+  buildToolCall(args: Record<string, unknown>, bridgeConfig: Required<MCPBridgeConfig>): ToolCall {
+    const method = (typeof args.method === 'string' ? args.method : 'GET').toUpperCase();
+    const capability = methodToCapability(method);
+    const { constraints, context } = extractHttpMeta(args);
+
+    return buildToolCallHelper({
+      toolName: 'http.request',
+      capability,
+      args: {
+        method,
+        url: args.url as string,
+        headers: args.headers as Record<string, string> | undefined,
+        body: typeof args.body === 'string' ? parseBody(args.body) : undefined,
+      },
+      constraints,
+      context,
+      bridgeConfig,
+    });
+  },
+};
+
+const httpGetHandler: MCPToolHandler = {
+  definition: {
+    name: 'http_get',
+    description:
+      'Execute an HTTP GET request through the Palaryn gateway. ' +
+      'Shorthand for http_request with method=GET. The request goes through ' +
+      'policy evaluation, DLP scanning, budget checks, and rate limiting.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'The target URL for the GET request' },
+        headers: {
+          type: 'object',
+          additionalProperties: { type: 'string' },
+          description: 'HTTP headers as key-value pairs',
+        },
+        timeout_ms: { type: 'number', description: 'Request timeout in milliseconds' },
+        max_cost_usd: {
+          type: 'number',
+          description: 'Maximum cost budget for this request in USD',
+        },
+        purpose: {
+          type: 'string',
+          description: 'Description of why this request is being made',
+        },
+        labels: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Classification labels for the request',
+        },
+      },
+      required: ['url'],
+    },
+    annotations: {
+      title: 'HTTP GET',
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: true,
+    },
+  },
+
+  buildToolCall(args: Record<string, unknown>, bridgeConfig: Required<MCPBridgeConfig>): ToolCall {
+    const { constraints, context } = extractHttpMeta(args);
+
+    return buildToolCallHelper({
+      toolName: 'http.get',
+      capability: 'read',
+      args: {
+        method: 'GET',
+        url: args.url as string,
+        headers: args.headers as Record<string, string> | undefined,
+      },
+      constraints,
+      context,
+      bridgeConfig,
+    });
+  },
+};
+
+const httpPostHandler: MCPToolHandler = {
+  definition: {
+    name: 'http_post',
+    description:
+      'Execute an HTTP POST request through the Palaryn gateway. ' +
+      'Shorthand for http_request with method=POST. The request goes through ' +
+      'policy evaluation, DLP scanning, budget checks, and rate limiting.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'The target URL for the POST request' },
+        headers: {
+          type: 'object',
+          additionalProperties: { type: 'string' },
+          description: 'HTTP headers as key-value pairs',
+        },
+        body: { type: 'string', description: 'Request body (typically a JSON string)' },
+        timeout_ms: { type: 'number', description: 'Request timeout in milliseconds' },
+        max_cost_usd: {
+          type: 'number',
+          description: 'Maximum cost budget for this request in USD',
+        },
+        purpose: {
+          type: 'string',
+          description: 'Description of why this request is being made',
+        },
+        labels: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Classification labels for the request',
+        },
+      },
+      required: ['url'],
+    },
+    annotations: {
+      title: 'HTTP POST',
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: true,
+    },
+  },
+
+  buildToolCall(args: Record<string, unknown>, bridgeConfig: Required<MCPBridgeConfig>): ToolCall {
+    const { constraints, context } = extractHttpMeta(args);
+
+    return buildToolCallHelper({
+      toolName: 'http.post',
+      capability: 'write',
+      args: {
+        method: 'POST',
+        url: args.url as string,
+        headers: args.headers as Record<string, string> | undefined,
+        body: typeof args.body === 'string' ? parseBody(args.body) : undefined,
+      },
+      constraints,
+      context,
+      bridgeConfig,
+    });
+  },
+};
+
+// ---------------------------------------------------------------------------
+// File Tool Handlers
+// ---------------------------------------------------------------------------
+
+const fileReadHandler: MCPToolHandler = {
+  definition: {
+    name: 'file_read',
+    description:
+      'Read a file from the sandboxed filesystem through the Palaryn gateway. ' +
+      'The request goes through policy evaluation, DLP scanning, and audit logging.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Path to the file to read (relative to sandbox root)' },
+        encoding: {
+          type: 'string',
+          description: 'File encoding (defaults to utf-8)',
+          enum: ['utf-8', 'ascii', 'base64', 'hex', 'binary'],
+        },
+      },
+      required: ['path'],
+    },
+    annotations: {
+      title: 'File Read',
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false,
+    },
+  },
+
+  buildToolCall(args: Record<string, unknown>, bridgeConfig: Required<MCPBridgeConfig>): ToolCall {
+    return buildToolCallHelper({
+      toolName: 'file.read',
+      capability: 'read',
+      args: {
+        path: args.path as string,
+        encoding: typeof args.encoding === 'string' ? args.encoding : undefined,
+      },
+      bridgeConfig,
+    });
+  },
+};
+
+const fileWriteHandler: MCPToolHandler = {
+  definition: {
+    name: 'file_write',
+    description:
+      'Write content to a file in the sandboxed filesystem through the Palaryn gateway. ' +
+      'The request goes through policy evaluation, DLP scanning, and audit logging.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Path to the file to write (relative to sandbox root)' },
+        content: { type: 'string', description: 'Content to write to the file' },
+        append: { type: 'boolean', description: 'Append to file instead of overwriting (defaults to false)' },
+      },
+      required: ['path', 'content'],
+    },
+    annotations: {
+      title: 'File Write',
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: false,
+    },
+  },
+
+  buildToolCall(args: Record<string, unknown>, bridgeConfig: Required<MCPBridgeConfig>): ToolCall {
+    return buildToolCallHelper({
+      toolName: 'file.write',
+      capability: 'write',
+      args: {
+        path: args.path as string,
+        content: args.content as string,
+        append: typeof args.append === 'boolean' ? args.append : undefined,
+      },
+      bridgeConfig,
+    });
+  },
+};
+
+const fileListHandler: MCPToolHandler = {
+  definition: {
+    name: 'file_list',
+    description:
+      'List files and directories in the sandboxed filesystem through the Palaryn gateway. ' +
+      'The request goes through policy evaluation and audit logging.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Directory path to list (relative to sandbox root)' },
+        recursive: { type: 'boolean', description: 'List files recursively (defaults to false)' },
+        pattern: { type: 'string', description: 'Glob pattern to filter files (e.g. "*.json")' },
+      },
+      required: ['path'],
+    },
+    annotations: {
+      title: 'File List',
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false,
+    },
+  },
+
+  buildToolCall(args: Record<string, unknown>, bridgeConfig: Required<MCPBridgeConfig>): ToolCall {
+    return buildToolCallHelper({
+      toolName: 'file.list',
+      capability: 'read',
+      args: {
+        path: args.path as string,
+        recursive: typeof args.recursive === 'boolean' ? args.recursive : undefined,
+        pattern: typeof args.pattern === 'string' ? args.pattern : undefined,
+      },
+      bridgeConfig,
+    });
+  },
+};
+
+// ---------------------------------------------------------------------------
+// SQL Tool Handlers
+// ---------------------------------------------------------------------------
+
+const sqlQueryHandler: MCPToolHandler = {
+  definition: {
+    name: 'sql_query',
+    description:
+      'Execute a SQL query through the Palaryn gateway. ' +
+      'The request goes through policy evaluation, DLP scanning, budget checks, and audit logging. ' +
+      'Query restrictions (read-only mode, blocked tables) are enforced by the gateway.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'SQL query to execute' },
+        params: {
+          type: 'array',
+          items: {},
+          description: 'Parameterized query values (positional $1, $2, etc.)',
+        },
+      },
+      required: ['query'],
+    },
+    annotations: {
+      title: 'SQL Query',
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: false,
+    },
+  },
+
+  buildToolCall(args: Record<string, unknown>, bridgeConfig: Required<MCPBridgeConfig>): ToolCall {
+    return buildToolCallHelper({
+      toolName: 'sql.query',
+      capability: 'read',
+      args: {
+        query: args.query as string,
+        params: Array.isArray(args.params) ? args.params : undefined,
+      },
+      bridgeConfig,
+    });
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Shell Tool Handlers
+// ---------------------------------------------------------------------------
+
+const shellExecHandler: MCPToolHandler = {
+  definition: {
+    name: 'shell_exec',
+    description:
+      'Execute a shell command through the Palaryn gateway. ' +
+      'The request goes through policy evaluation, DLP scanning, and audit logging. ' +
+      'Only commands in the allowed list can be executed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: 'Command to execute' },
+        args: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Command arguments',
+        },
+        cwd: { type: 'string', description: 'Working directory for command execution' },
+        timeout_ms: { type: 'number', description: 'Command timeout in milliseconds' },
+      },
+      required: ['command'],
+    },
+    annotations: {
+      title: 'Shell Execute',
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: false,
+    },
+  },
+
+  buildToolCall(mcpArgs: Record<string, unknown>, bridgeConfig: Required<MCPBridgeConfig>): ToolCall {
+    return buildToolCallHelper({
+      toolName: 'shell.exec',
+      capability: 'write',
+      args: {
+        command: mcpArgs.command as string,
+        args: Array.isArray(mcpArgs.args) ? mcpArgs.args : undefined,
+        cwd: typeof mcpArgs.cwd === 'string' ? mcpArgs.cwd : undefined,
+      },
+      constraints: {
+        timeout_ms: typeof mcpArgs.timeout_ms === 'number' ? mcpArgs.timeout_ms : undefined,
+      },
+      bridgeConfig,
+    });
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Validation helpers (used by HTTP tools to check required args)
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns an error string if the url arg is missing/invalid, or null if valid.
+ */
+export function validateUrlArg(args: Record<string, unknown>): string | null {
+  if (!args.url || typeof args.url !== 'string') {
+    return 'Missing required argument: url';
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Tool group exports
+// ---------------------------------------------------------------------------
+
+export const HTTP_TOOLS: MCPToolHandler[] = [httpRequestHandler, httpGetHandler, httpPostHandler];
+export const FILE_TOOLS: MCPToolHandler[] = [fileReadHandler, fileWriteHandler, fileListHandler];
+export const SQL_TOOLS: MCPToolHandler[] = [sqlQueryHandler];
+export const SHELL_TOOLS: MCPToolHandler[] = [shellExecHandler];
+
+/** Default tools registered when no config overrides are applied. */
+export const ALL_DEFAULT_TOOLS: MCPToolHandler[] = [...HTTP_TOOLS];