@enfyra/mcp-server 0.0.95 → 0.0.97

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.95",
+  "version": "0.0.97",
   "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,9 +33,11 @@ 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.',
+    '- Dynamic repository reads use `filter`, not `where`: `@REPOS.table.find({ filter: {...} })`, `#table.find({ filter: {...} })`, and `exists(filter)`.',
     '- Use `enfyra_user` as the user table. Model record links as real relations using relation `propertyName` values, not physical FK fields like `userId`, `conversationId`, `senderId`, or `memberId` in generated DB code.',
     '- Do not call internal/no-route system tables such as `enfyra_column` or `enfyra_session` through generic CRUD. Use table/column/relation tools and route-backed tables discovered from metadata.',
     '- Custom API paths use `create_route` without `mainTableId`; `create_table` is only for new persisted data.',

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,
@@ -407,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 {
@@ -616,6 +613,7 @@ const server = new McpServer(
     instructions: buildMcpServerInstructions(ENFYRA_API_URL),
   },
 );
+installColumnarToolFormatter(server);
 
 // ============================================================================
 // METADATA TOOLS