@enfyra/mcp-server 0.0.94 → 0.0.96

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.94",
+  "version": "0.0.96",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-examples.js

@@ -47,6 +47,47 @@ export default nextConfig`,
           'If you add Next middleware/proxy for auth gating, server-side checks may call the Enfyra API origin directly while forwarding the incoming Cookie header.',
         ],
       },
+      {
+        name: 'Angular dev proxy for REST and Socket.IO',
+        code: `// src/proxy.conf.json
+{
+  "/enfyra/**": {
+    "target": "https://demo.enfyra.io/api",
+    "secure": true,
+    "changeOrigin": true,
+    "pathRewrite": {
+      "^/enfyra": ""
+    }
+  },
+  "/socket.io/**": {
+    "target": "https://demo.enfyra.io/api/ws",
+    "secure": true,
+    "changeOrigin": true,
+    "ws": true
+  }
+}
+
+// angular.json
+{
+  "projects": {
+    "app": {
+      "architect": {
+        "serve": {
+          "options": {
+            "proxyConfig": "src/proxy.conf.json"
+          }
+        }
+      }
+    }
+  }
+}`,
+        notes: [
+          'Browser code still calls /enfyra/login, /enfyra/me, /enfyra/logout, and /enfyra/<table>.',
+          'The /enfyra proxy strips the prefix before forwarding to the Enfyra API origin.',
+          'The /socket.io proxy forwards to the Enfyra app bridge /ws/socket.io while keeping the browser transport path as /socket.io.',
+          'Restart ng serve after changing proxy.conf.json.',
+        ],
+      },
       {
         name: 'Password login and current user fetch',
         code: `await fetch("/enfyra/login", {
@@ -153,6 +194,85 @@ onUnmounted(() => {
           'Disconnect the singleton socket when the current user/session clears.',
         ],
       },
+      {
+        name: 'Angular HttpClient auth service and route guard',
+        code: `// app.config.ts
+import { ApplicationConfig, inject } from "@angular/core"
+import { provideRouter, CanActivateFn, Router } from "@angular/router"
+import { HttpInterceptorFn, provideHttpClient, withInterceptors } from "@angular/common/http"
+import { catchError, map, of } from "rxjs"
+
+import { routes } from "./app.routes"
+import { EnfyraAuthService } from "./enfyra-auth.service"
+
+export const enfyraCredentialsInterceptor: HttpInterceptorFn = (req, next) => {
+  if (!req.url.startsWith("/enfyra/")) return next(req)
+  return next(req.clone({ withCredentials: true }))
+}
+
+export const requireUserGuard: CanActivateFn = () => {
+  const auth = inject(EnfyraAuthService)
+  const router = inject(Router)
+
+  return auth.loadMe().pipe(
+    map(user => user ? true : router.createUrlTree(["/login"])),
+    catchError(() => of(router.createUrlTree(["/login"])))
+  )
+}
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(withInterceptors([enfyraCredentialsInterceptor])),
+    provideRouter(routes)
+  ]
+}
+
+// enfyra-auth.service.ts
+import { Injectable, signal } from "@angular/core"
+import { HttpClient } from "@angular/common/http"
+import { Observable, tap } from "rxjs"
+
+type EnfyraUser = { id: string | number; email?: string }
+
+@Injectable({ providedIn: "root" })
+export class EnfyraAuthService {
+  readonly user = signal<EnfyraUser | null>(null)
+
+  constructor(private readonly http: HttpClient) {}
+
+  login(email: string, password: string): Observable<unknown> {
+    return this.http.post("/enfyra/login", { email, password, remember: true }).pipe(
+      tap(() => this.loadMe().subscribe())
+    )
+  }
+
+  loadMe(): Observable<EnfyraUser | null> {
+    return this.http.get<EnfyraUser | null>("/enfyra/me").pipe(
+      tap(user => this.user.set(user))
+    )
+  }
+
+  logout(): Observable<unknown> {
+    return this.http.post("/enfyra/logout", {}).pipe(
+      tap(() => this.user.set(null))
+    )
+  }
+
+  startGoogleOAuth(returnPath = "/") {
+    const redirect = new URL(returnPath, window.location.origin)
+    const url = new URL("/enfyra/auth/google", window.location.origin)
+    url.searchParams.set("redirect", redirect.toString())
+    url.searchParams.set("cookieBridgePrefix", "/enfyra")
+    window.location.href = url.toString()
+  }
+}`,
+        notes: [
+          'Use HttpClient with a credentials interceptor for /enfyra/* calls so cookies are sent consistently.',
+          'The guard is only for user experience; Enfyra route permissions and server-side owner checks remain authoritative.',
+          'Keep the current user in an Angular service or store; do not read JWTs from cookies or URLs.',
+          'OAuth starts at the app proxy path and returns through the cookie bridge before the Angular route loads /enfyra/me.',
+        ],
+      },
       {
         name: 'Next client provider for authenticated realtime',
         code: `"use client"
@@ -243,6 +363,64 @@ export function useRealtime() {
           'Disconnect the singleton socket when the current user/session clears.',
         ],
       },
+      {
+        name: 'Angular singleton Socket.IO realtime service',
+        code: `// enfyra-realtime.service.ts
+import { Injectable, computed, effect, signal } from "@angular/core"
+import { io, Socket } from "socket.io-client"
+
+import { EnfyraAuthService } from "./enfyra-auth.service"
+
+@Injectable({ providedIn: "root" })
+export class EnfyraRealtimeService {
+  private socket: Socket | null = null
+  private readonly connected = signal(false)
+  readonly isConnected = computed(() => this.connected())
+
+  constructor(private readonly auth: EnfyraAuthService) {
+    effect(() => {
+      const user = this.auth.user()
+      if (user) this.connect()
+      else this.disconnect()
+    })
+  }
+
+  connect() {
+    if (this.socket) return this.socket
+
+    this.socket = io("/chat", {
+      path: "/socket.io",
+      withCredentials: true,
+      reconnection: true,
+      reconnectionAttempts: Infinity,
+      reconnectionDelay: 2000,
+      reconnectionDelayMax: 30000
+    })
+
+    this.socket.on("connect", () => this.connected.set(true))
+    this.socket.on("disconnect", () => this.connected.set(false))
+    return this.socket
+  }
+
+  disconnect() {
+    this.socket?.disconnect()
+    this.socket = null
+    this.connected.set(false)
+  }
+
+  onMessage(handler: (event: unknown) => void) {
+    const activeSocket = this.connect()
+    activeSocket.on("chat:message", handler)
+    return () => activeSocket.off("chat:message", handler)
+  }
+}`,
+        notes: [
+          'Create one app-level Socket.IO connection after auth is known.',
+          'Use the websocket namespace path from live metadata, such as /chat, and keep the transport path as /socket.io.',
+          'Components subscribe with onMessage and call the returned cleanup function in ngOnDestroy.',
+          'Do not create a new socket per routed component.',
+        ],
+      },
       {
         name: 'OAuth provider setup values',
         code: `// Enfyra OAuth config row, stored in enfyra_oauth_config.

package/src/lib/mcp-instructions.js

@@ -33,6 +33,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Validate behavior with `test_rest_endpoint`, `run_admin_test`, `test_flow_step`, or the route-specific tool before claiming a dynamic feature works.',
     '',
     '### Core Contracts',
+    '- Tool JSON responses use `responseFormat: "json+columnar-v1"`. Any array of objects is encoded as `{ format: "columnar-v1", columns: [...], rows: [[...]], rowCount }`; read each row value by matching `columns[index]` to `rows[n][index]`. Do not guess object keys inside `rows`.',
     '- `query_table` and `get_all_routes` require explicit intent: pass `limit` for bounded reads or `all: true` for a complete list. Do not invent arbitrary limits such as 30 or 50.',
     '- Read tools are minimal by default. Pass explicit `fields`; use metadata inspection before guessing field/relation names. Field exclusion mode exists: `fields=-compiledCode`, and `fields=id,-compiledCode` still means all readable fields except `compiledCode`.',
     '- Mutations return ids/status by default. Re-read with `find_one_record` or `query_table` and explicit `fields` when the saved row matters.',

package/src/lib/response-format.js

@@ -0,0 +1,117 @@
+const RESPONSE_FORMAT = 'json+columnar-v1';
+const COLUMNAR_FORMAT = 'columnar-v1';
+
+function isPlainObject(value) {
+  if (!value || typeof value !== 'object') return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function valueForColumn(record, column) {
+  return Object.prototype.hasOwnProperty.call(record, column) ? record[column] : null;
+}
+
+function collectColumns(records) {
+  const columns = [];
+  const seen = new Set();
+  for (const record of records) {
+    for (const key of Object.keys(record)) {
+      if (seen.has(key)) continue;
+      seen.add(key);
+      columns.push(key);
+    }
+  }
+  return columns;
+}
+
+function toColumnar(value, seen = new WeakSet()) {
+  if (Array.isArray(value)) {
+    if (value.length > 0 && value.every(isPlainObject)) {
+      const columns = collectColumns(value);
+      return {
+        format: COLUMNAR_FORMAT,
+        columns,
+        rows: value.map((record) => columns.map((column) => toColumnar(valueForColumn(record, column), seen))),
+        rowCount: value.length,
+      };
+    }
+    return value.map((item) => toColumnar(item, seen));
+  }
+
+  if (!isPlainObject(value)) return value;
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+
+  const output = {};
+  for (const [key, entry] of Object.entries(value)) {
+    output[key] = toColumnar(entry, seen);
+  }
+  seen.delete(value);
+  return output;
+}
+
+export function formatJsonPayload(payload) {
+  const formatted = toColumnar(payload);
+  if (!isPlainObject(formatted)) {
+    return {
+      responseFormat: RESPONSE_FORMAT,
+      value: formatted,
+    };
+  }
+  if (formatted.responseFormat === RESPONSE_FORMAT) return formatted;
+  return {
+    responseFormat: RESPONSE_FORMAT,
+    ...formatted,
+  };
+}
+
+export function jsonContent(payload, { pretty = false } = {}) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(formatJsonPayload(payload), null, pretty ? 2 : 0),
+    }],
+  };
+}
+
+function tryParseJson(text) {
+  if (typeof text !== 'string') return null;
+  const trimmed = text.trim();
+  if (!trimmed || !/^[\[{]/.test(trimmed)) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+function formatContentItem(item) {
+  if (!item || item.type !== 'text') return item;
+  const parsed = tryParseJson(item.text);
+  if (!parsed) return item;
+  return {
+    ...item,
+    text: JSON.stringify(formatJsonPayload(parsed)),
+  };
+}
+
+export function formatToolResult(result) {
+  if (!result || !Array.isArray(result.content)) return result;
+  return {
+    ...result,
+    content: result.content.map(formatContentItem),
+  };
+}
+
+export function installColumnarToolFormatter(server) {
+  const registerTool = server.tool.bind(server);
+  server.tool = (name, description, schema, handler) => {
+    if (typeof handler !== 'function') {
+      return registerTool(name, description, schema, handler);
+    }
+    return registerTool(name, description, schema, async (...args) => {
+      const result = await handler(...args);
+      return formatToolResult(result);
+    });
+  };
+}

package/src/mcp-server-entry.mjs

@@ -23,6 +23,7 @@ import { getExamples, listExampleCategories } from './lib/mcp-examples.js';
 import { registerTableTools } from './lib/table-tools.js';
 import { prepareRecordMutation, validateScriptSourceIfPresent } from './lib/mutation-guards.js';
 import { validateMainTableRoutePath } from './lib/route-guards.js';
+import { installColumnarToolFormatter, jsonContent } from './lib/response-format.js';
 import {
   findRoutePermission,
   mergeMethodNames,
@@ -192,6 +193,21 @@ function getMetadataDatabaseContext(metadata, tables) {
 
 function summarizeTable(table) {
   if (!table) return null;
+  const relationFkColumnNames = new Set((table.relations || []).flatMap((relation) => {
+    const propertyName = relation.propertyName;
+    return propertyName
+      ? [
+          `${propertyName}Id`,
+          `${propertyName}_id`,
+          relation.fkCol,
+          relation.fkColumn,
+          relation.foreignKeyColumn,
+        ].filter(Boolean).map((name) => String(name).toLowerCase())
+      : [];
+  }));
+  const modelFacingColumns = (table.columns || []).filter((column) => (
+    column.isPrimary || !relationFkColumnNames.has(String(column.name || '').toLowerCase())
+  ));
   return {
     id: table.id ?? table._id,
     name: table.name,
@@ -199,7 +215,7 @@ function summarizeTable(table) {
     primaryKey: getPrimaryColumn(table)?.name || null,
     validateBody: table.validateBody,
     graphqlEnabled: table.graphqlEnabled,
-    columns: (table.columns || []).map((column) => ({
+    columns: modelFacingColumns.map((column) => ({
       id: column.id ?? column._id,
       name: column.name,
       type: column.type,
@@ -209,6 +225,7 @@ function summarizeTable(table) {
       isUpdatable: column.isUpdatable !== false,
       isEncrypted: column.isEncrypted === true,
     })),
+    hiddenRelationColumnCount: (table.columns || []).length - modelFacingColumns.length,
     relations: (table.relations || []).map((relation) => ({
       id: relation.id ?? relation._id,
       propertyName: relation.propertyName,
@@ -391,10 +408,6 @@ function collectPartialErrors(results) {
     .map(([name, result]) => ({ name, error: result.error }));
 }
 
-function jsonContent(payload, { pretty = false } = {}) {
-  return { content: [{ type: 'text', text: JSON.stringify(payload, null, pretty ? 2 : 0) }] };
-}
-
 async function getMetadataTables() {
   const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
   return {
@@ -600,6 +613,7 @@ const server = new McpServer(
     instructions: buildMcpServerInstructions(ENFYRA_API_URL),
   },
 );
+installColumnarToolFormatter(server);
 
 // ============================================================================
 // METADATA TOOLS
@@ -844,12 +858,21 @@ server.tool(
     tableName: z.string().optional().describe('Optional table name to summarize query fields and relation/deep capabilities.'),
   },
   async ({ tableName }) => {
-    const metadata = await discoveryFetch('/metadata');
-    const routesResult = await discoveryFetch('/enfyra_route?fields=path,mainTable.name,availableMethods.*,publicMethods.*,isEnabled&limit=1000');
-    const tables = normalizeTables(metadata);
+    const metadata = tableName
+      ? await discoveryFetch(`/metadata/${encodeURIComponent(tableName)}`)
+      : null;
+    const routesResult = tableName
+      ? await discoveryFetch('/enfyra_route?fields=path,mainTable.name,availableMethods.*,publicMethods.*,isEnabled&limit=1000')
+      : { data: [] };
+    const tableFromMetadata = tableName && !metadata?.error
+      ? metadata?.data?.table || metadata?.data || metadata?.table || metadata
+      : null;
+    const tables = tableName
+      ? (tableFromMetadata ? [tableFromMetadata] : [])
+      : [];
     const routes = summarizeRoutes(routesResult);
     const table = tableName ? tables.find((item) => item.name === tableName) : null;
-    const primaryKey = table ? getPrimaryColumn(table)?.name || 'id' : inferPrimaryKeyContext(tables).dominantPrimaryKey || 'id';
+    const primaryKey = table ? getPrimaryColumn(table)?.name || 'id' : 'id';
     const tableRoutes = tableName
       ? routes.filter((route) => route.mainTable === tableName)
       : [];
@@ -885,7 +908,9 @@ server.tool(
         ],
       },
       backendNotes: {
-        primaryKey: 'SQL commonly uses id; Mongo uses _id. Use table metadata primary column when available.',
+        primaryKey: tableName
+          ? 'Use this table metadata primary column when available.'
+          : 'SQL commonly uses id; Mongo uses _id. Use table metadata primary column when available.',
         relationNames: 'API relation operations use relation propertyName, not physical FK column names.',
         relationCascadeFkContract: 'When creating relations through create_table/create_relation/enfyra_table PATCH, never provide fkCol/fkColumn/foreignKeyColumn/sourceColumn/targetColumn/junction*Column. These are physical implementation details derived by Enfyra and hidden from app schema/forms.',
         graphql: 'GraphQL query args also accept filter/sort/page/limit, but GraphQL requires Bearer auth and table enablement via enfyra_graphql.',