@svadmin/mcp 0.4.30 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/mcp",
-  "version": "0.4.30",
+  "version": "0.6.0",
   "description": "MCP (Model Context Protocol) server — expose svadmin DataProvider as tools for AI agents",
   "type": "module",
   "sideEffects": false,
@@ -20,7 +20,8 @@
     }
   },
   "peerDependencies": {
-    "@svadmin/core": "^0.69.3"
+    "@svadmin/core": "^0.71.0",
+    "@svadmin/devtools": "^0.6.0"
   },
   "license": "MIT",
   "publishConfig": {
@@ -40,6 +41,9 @@
   "peerDependenciesMeta": {
     "@svadmin/core": {
       "optional": true
+    },
+    "@svadmin/devtools": {
+      "optional": true
     }
   }
 }

package/src/governance.ts

@@ -0,0 +1,116 @@
+/**
+ * @svadmin/mcp/governance
+ *
+ * Pure, filesystem-free rule engine for the SVAdmin Vibe Coding governance
+ * checks. The MCP tool and `scripts/check-vibe-governance.ts` both delegate to
+ * this module so agents and CI enforce exactly the same rules.
+ */
+
+export type GovernanceRuleId = 'no-unmanaged-fetch' | 'escape-hatch-discipline';
+
+export interface GovernanceSource {
+  /** Path used in reports and error messages */
+  path: string;
+  /** Full source text of the file */
+  content: string;
+}
+
+export interface GovernanceViolation {
+  file: string;
+  line: number;
+  rule: GovernanceRuleId;
+  message: string;
+  remediation: string;
+}
+
+export interface VibeGovernanceReport {
+  passed: boolean;
+  totalFilesScanned: number;
+  rulesChecked: GovernanceRuleId[];
+  violations: GovernanceViolation[];
+  summary: string;
+}
+
+export interface VibeGovernanceOptions {
+  /**
+   * Strict mode: a `@vibe-escape` annotation only suppresses a violation when it
+   * carries a non-empty reason. Non-strict mode honours any annotation but still
+   * reports annotations that are missing a reason.
+   */
+  strict?: boolean;
+}
+
+const ESCAPE_MARKER = /@vibe-escape\b/u;
+const ESCAPE_REASON = /@vibe-escape\s*:\s*(\S.*)$/u;
+const COMMENT_PREFIX = /^(?:\/\/|\/\*|\*)/u;
+const NETWORK_CALL = [/[^.\w]fetch\s*\(/u, /(?:^|[^.\w])axios\s*[.(]/u];
+
+function escapeSuppression(lines: string[], strict: boolean): boolean {
+  for (const line of lines) {
+    if (!ESCAPE_MARKER.test(line)) continue;
+    if (!strict) return true;
+    if (ESCAPE_REASON.test(line)) return true;
+  }
+  return false;
+}
+
+/**
+ * Scans in-memory sources for architectural violations.
+ *
+ * Rules:
+ * 1. `no-unmanaged-fetch` — view code must not call `fetch()` / `axios` directly
+ *    unless the file documents `// @vibe-escape: <reason>`.
+ * 2. `escape-hatch-discipline` — every `@vibe-escape` marker must carry a reason.
+ */
+export function scanVibeGovernance(
+  sources: GovernanceSource[],
+  options: VibeGovernanceOptions = {},
+): VibeGovernanceReport {
+  const strict = options.strict ?? false;
+  const violations: GovernanceViolation[] = [];
+
+  for (const source of sources) {
+    const lines = source.content.split(/\r?\n/u);
+    const suppressed = escapeSuppression(lines, strict);
+
+    lines.forEach((line, index) => {
+      const lineNumber = index + 1;
+      const trimmed = line.trim();
+
+      if (ESCAPE_MARKER.test(line) && !ESCAPE_REASON.test(line)) {
+        violations.push({
+          file: source.path,
+          line: lineNumber,
+          rule: 'escape-hatch-discipline',
+          message: `Escape hatch annotation is missing a reason: "${trimmed}"`,
+          remediation: 'Use "// @vibe-escape: <reason>" so reviewers and agents can justify the bypass.',
+        });
+      }
+
+      if (suppressed) return;
+      if (COMMENT_PREFIX.test(trimmed)) return;
+      if (ESCAPE_MARKER.test(line)) return;
+      if (!NETWORK_CALL.some(pattern => pattern.test(line))) return;
+
+      violations.push({
+        file: source.path,
+        line: lineNumber,
+        rule: 'no-unmanaged-fetch',
+        message: `Direct unmanaged network call detected: "${trimmed}"`,
+        remediation:
+          'Use standard DataProvider hooks (useList, useOne, useCreate, useUpdate) or add "// @vibe-escape: <reason>" if an external API call is intended.',
+      });
+    });
+  }
+
+  const passed = violations.length === 0;
+  return {
+    passed,
+    totalFilesScanned: sources.length,
+    rulesChecked: ['no-unmanaged-fetch', 'escape-hatch-discipline'],
+    violations,
+    summary: passed
+      ? `Vibe Governance passed! Scanned ${sources.length} files with zero architectural violations.`
+      : `Vibe Governance failed with ${violations.length} violation(s) across ${sources.length} scanned files.`,
+  };
+}

package/src/index.ts

@@ -25,6 +25,18 @@ import { definedOptions } from '@svadmin/core/options';
  */
 
 import type { DataProvider, ResourceDefinition } from '@svadmin/core';
+import { inferResource } from '@svadmin/core/inferencer';
+import { scanVibeGovernance, type GovernanceSource } from './governance';
+import { inferFromJSONSchema, inferFromDatabaseColumns } from '@svadmin/core/inferencer-schema';
+import {
+  buildResourcePatch,
+  buildSelfHealingReport,
+  type DevtoolsAppDiagnostics,
+  type DevtoolsCollector,
+  type DevtoolsDiagnostic,
+  type DevtoolsSnapshot,
+  type ResourcePatchAction,
+} from '@svadmin/devtools';
 
 // ─── Types ───────────────────────────────────────────────────
 
@@ -41,6 +53,14 @@ export interface MCPServerOptions {
   version?: string;
   /** When true, only expose read operations (getList, getOne, getMany) */
   readOnly?: boolean;
+  /** Optional DevTools collector instance to expose runtime diagnostics to Agent */
+  collector?: DevtoolsCollector;
+  /** Optional custom diagnostics provider function */
+  getDiagnostics?: () =>
+    | DevtoolsAppDiagnostics
+    | DevtoolsSnapshot
+    | DevtoolsDiagnostic[]
+    | Promise<DevtoolsAppDiagnostics | DevtoolsSnapshot | DevtoolsDiagnostic[]>;
 }
 
 /** MCP Tool definition following the Model Context Protocol spec */
@@ -217,6 +237,118 @@ function generateTools(options: MCPServerOptions): MCPTool[] {
     });
   }
 
+  // Diagnostics and self-healing tools
+  tools.push({
+    name: 'svadmin_getDiagnostics',
+    description:
+      'Fetch current SVAdmin runtime diagnostics, including health status, configured providers, active resources, and error events.',
+    readOnly: true,
+    concurrent: true,
+    destructive: false,
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  });
+
+  tools.push({
+    name: 'svadmin_getSelfHealingPrompt',
+    description:
+      'Get an AI-ready self-healing diagnosis report from runtime errors captured by SVAdmin DevTools, with structured root causes and suggested code fixes.',
+    readOnly: true,
+    concurrent: true,
+    destructive: false,
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  });
+
+  tools.push({
+    name: 'svadmin_getManifest',
+    description:
+      'Get the active SVAdmin application manifest including registered resources, fields, operations, and data provider metadata.',
+    readOnly: true,
+    concurrent: true,
+    destructive: false,
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  });
+
+  tools.push({
+    name: 'svadmin_generateResource',
+    description:
+      'Zero-hallucination code generator for SVAdmin. Infers ResourceDefinition, TypeBox validation, and complete Svelte 5 AutoTable/AutoForm component snippets from sample records, JSON Schema, or database column definitions.',
+    readOnly: true,
+    concurrent: true,
+    destructive: false,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resource: { type: 'string', description: 'Name of the resource to generate (e.g. "orders", "users")' },
+        sourceType: {
+          type: 'string',
+          enum: ['sampleData', 'jsonSchema', 'databaseColumns'],
+          description: 'Type of input payload',
+        },
+        payload: { type: 'string', description: 'JSON-serialized payload matching the sourceType' },
+        idKey: { type: 'string', description: 'Primary key name (defaults to "id")' },
+        label: { type: 'string', description: 'Human-readable resource label' },
+      },
+      required: ['resource', 'sourceType', 'payload'],
+    },
+  });
+
+  tools.push({
+    name: 'svadmin_applyResourcePatch',
+    description:
+      'Applies a structured writeback patch derived from the Visual Inspector (Click-to-Edit), generating verified code snippets and agent prompts to update ResourceDefinitions, column visibility, or field properties.',
+    readOnly: true,
+    concurrent: true,
+    destructive: false,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resource: { type: 'string', description: 'Resource name to patch' },
+        action: {
+          type: 'string',
+          enum: ['updateField', 'toggleColumnVisibility', 'updateColumnTitle', 'updatePageSize', 'reorderColumns'],
+          description: 'Patch action to perform',
+        },
+        field: { type: 'string', description: 'Field name targeted' },
+        column: { type: 'string', description: 'Column name targeted' },
+        value: { type: 'string', description: 'JSON-serialized or string patch value' },
+        targetComponent: { type: 'string', description: 'Component context (e.g. AutoTable, AutoForm)' },
+      },
+      required: ['resource', 'action'],
+    },
+  });
+
+  tools.push({
+    name: 'svadmin_verifyGovernance',
+    description:
+      'Runs the SVAdmin Vibe Coding architectural governance check on the supplied sources, verifying data provider isolation (no unmanaged fetch/axios) and escape-hatch annotation discipline. Returns the same verdict as `bun run check:vibe-governance`.',
+    readOnly: true,
+    concurrent: true,
+    destructive: false,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        files: {
+          type: 'string',
+          description: 'JSON-serialized array of { path, content } sources to scan (for example the files an agent just edited).',
+        },
+        strict: {
+          type: 'boolean',
+          description: 'Require every @vibe-escape annotation to carry a non-empty reason before it suppresses a violation.',
+        },
+      },
+      required: ['files'],
+    },
+  });
+
   return tools;
 }
 
@@ -228,7 +360,15 @@ async function handleToolCall(
   options: MCPServerOptions,
 ): Promise<unknown> {
   const resource = args['resource'] as string;
-  if (resource && !options.resources.includes(resource)) {
+  const dataCrudTools = [
+    'svadmin_getList',
+    'svadmin_getOne',
+    'svadmin_getMany',
+    'svadmin_create',
+    'svadmin_update',
+    'svadmin_delete',
+  ];
+  if (dataCrudTools.includes(toolName) && resource && !options.resources.includes(resource)) {
     throw new Error(`Unauthorized resource access: ${resource} is not exposed.`);
   }
   const dp = options.dataProvider;
@@ -296,6 +436,149 @@ async function handleToolCall(
       });
     }
 
+    case 'svadmin_getDiagnostics': {
+      if (options.collector) {
+        return options.collector.snapshot();
+      }
+      if (options.getDiagnostics) {
+        return await options.getDiagnostics();
+      }
+      return {
+        status: 'healthy',
+        resources: options.resources,
+        dataProvider: options.dataProvider.getApiUrl?.() ?? 'configured',
+        message: 'No DevTools collector attached. Basic provider info returned.',
+      };
+    }
+
+    case 'svadmin_getSelfHealingPrompt': {
+      let diags: DevtoolsDiagnostic[] = [];
+      if (options.collector) {
+        diags = options.collector.snapshot().diagnostics;
+      } else if (options.getDiagnostics) {
+        const res = await options.getDiagnostics();
+        if (Array.isArray(res)) {
+          diags = res;
+        } else if (res && typeof res === 'object') {
+          if ('snapshot' in res && res.snapshot) {
+            diags = (res.snapshot as DevtoolsSnapshot).diagnostics;
+          } else if ('diagnostics' in res && Array.isArray((res as { diagnostics: unknown }).diagnostics)) {
+            diags = (res as { diagnostics: DevtoolsDiagnostic[] }).diagnostics;
+          }
+        }
+      }
+      return buildSelfHealingReport(diags);
+    }
+
+    case 'svadmin_getManifest': {
+      return {
+        resources: options.resourceDefinitions ?? options.resources.map((name) => ({ name })),
+        capabilities: {
+          apiUrl: options.dataProvider.getApiUrl?.() ?? undefined,
+          readOnly: !!options.readOnly,
+          hasCollector: !!options.collector,
+        },
+      };
+    }
+
+    case 'svadmin_generateResource': {
+      const resource = args['resource'] as string;
+      const sourceType = args['sourceType'] as 'sampleData' | 'jsonSchema' | 'databaseColumns';
+      const rawPayload = args['payload'] as string;
+      const idKey = (args['idKey'] as string) ?? 'id';
+      const label = args['label'] as string | undefined;
+
+      const parsedPayload = typeof rawPayload === 'string' ? JSON.parse(rawPayload) : rawPayload;
+      let result;
+
+      if (sourceType === 'sampleData') {
+        result = inferResource(resource, Array.isArray(parsedPayload) ? parsedPayload : [parsedPayload], definedOptions({
+          primaryKey: idKey,
+          label,
+        }));
+      } else if (sourceType === 'jsonSchema') {
+        result = inferFromJSONSchema(resource, parsedPayload, definedOptions({
+          primaryKey: idKey,
+          label,
+        }));
+      } else if (sourceType === 'databaseColumns') {
+        result = inferFromDatabaseColumns(resource, parsedPayload, definedOptions({
+          primaryKey: idKey,
+          label,
+        }));
+      } else {
+        throw new Error(`Invalid sourceType: ${sourceType}`);
+      }
+
+      return {
+        resource: result.resource,
+        code: result.code,
+        typeboxCode: result.typeboxCode,
+        componentCode: result.componentCode,
+        review: result.review,
+      };
+    }
+
+    case 'svadmin_applyResourcePatch': {
+      const resource = args['resource'] as string;
+      const action = args['action'] as ResourcePatchAction;
+      const field = args['field'] as string | undefined;
+      const column = args['column'] as string | undefined;
+      const targetComponent = args['targetComponent'] as string | undefined;
+      let value = args['value'];
+      if (typeof value === 'string') {
+        try {
+          value = JSON.parse(value);
+        } catch {
+          // Keep as string
+        }
+      }
+
+      return buildResourcePatch({
+        resource,
+        action,
+        value,
+        ...definedOptions({
+          field,
+          column,
+          targetComponent,
+        }),
+      });
+    }
+
+    case 'svadmin_verifyGovernance': {
+      const strict = Boolean(args['strict']);
+      const rawFiles = args['files'];
+      const parsed: unknown = typeof rawFiles === 'string' ? JSON.parse(rawFiles) : rawFiles;
+      if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error('svadmin_verifyGovernance requires a non-empty files array of { path, content } sources.');
+      }
+
+      const sources: GovernanceSource[] = parsed.map((entry: unknown, index: number) => {
+        const candidate = entry as { path?: unknown; content?: unknown } | null;
+        if (
+          candidate === null ||
+          typeof candidate !== 'object' ||
+          typeof candidate.path !== 'string' ||
+          typeof candidate.content !== 'string'
+        ) {
+          throw new Error(`svadmin_verifyGovernance: files[${index}] must be an object with string path and content.`);
+        }
+        return { path: candidate.path, content: candidate.content };
+      });
+
+      const report = scanVibeGovernance(sources, { strict });
+      return {
+        governancePassed: report.passed,
+        status: report.passed ? 'compliant' : 'violations',
+        strictMode: strict,
+        rulesChecked: report.rulesChecked,
+        filesScanned: report.totalFilesScanned,
+        violations: report.violations,
+        summary: report.summary,
+      };
+    }
+
     default:
       throw new Error(`Unknown tool: ${toolName}`);
   }
@@ -326,6 +609,15 @@ async function handleToolCall(
 /**
  * Projects an MCP tool into the standard allowlisted schema while preserving metadata and safety flags.
  */
+export { scanVibeGovernance } from './governance';
+export type {
+  GovernanceRuleId,
+  GovernanceSource,
+  GovernanceViolation,
+  VibeGovernanceOptions,
+  VibeGovernanceReport,
+} from './governance';
+
 export function projectMCPToolSchema(tool: MCPTool): MCPTool {
   return {
     name: tool.name,