icode-mcp-adapter 1.0.10 → 1.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icode-mcp-adapter",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Dynamic MCP server adapter — auto-generates CRUD tools from schema configs. Plugs into icode-server via Fastify or runs standalone.",
   "type": "module",
   "main": "src/engine/McpEngine.js",

package/src/engine/McpEngine.js

@@ -12,9 +12,9 @@ import { resolveSchemas as defaultResolveSchemas } from './SchemaAdapter.js';
  */
 export function createMcpServer(config, db, identity, newGuid, writer) {
   const server = new McpServer({
-    name: `${config.appName}-mcp`,
+    name: config.serverName || `${config.appName}-mcp`,
     version: config.version,
-  });
+  }, config.instructions ? { instructions: config.instructions } : undefined);
 
   for (const table of config.tables) {
     registerTableTools(server, db, table, identity, newGuid, writer);
@@ -39,13 +39,15 @@ export async function createMcpServerAuto(config, db, opts = {}) {
   const resolveSchemas = opts.resolveSchemas || defaultResolveSchemas;
 
   const tables = await resolveSchemas(db, config.tables, {
-    cacheKey: `${config.appName}--${config.env || 'prod'}`,
+    cacheKey: config.cacheKey || `${config.appName}--${config.env || 'prod'}`,
     ownerColumn: config.ownerColumn,
   });
 
   return createMcpServer({
     appName: config.appName,
+    serverName: config.serverName,
     version: config.version || '1.0.0',
+    instructions: config.instructions,
     tables,
   }, db, opts.identity, opts.newGuid, opts.writer);
 }

package/src/engine/SchemaAdapter.js

@@ -45,6 +45,13 @@ const META_FIELDS = new Set([
   '_by',           // who last modified
   '_deleted',      // soft delete flag
   'pk',            // auto-increment secondary key
+  '_tenantId',     // tenant marker (stamped by the host writer)
+  '_tzo',          // timezone offset
+  '_vno',          // version number
+  '_tag',          // internal tagging
+  'org',           // org partition
+  'settings',      // per-row system settings json
+  'entitytype',    // entity type marker (system-set)
 ]);
 
 // ── Schema cache ─────────────────────────────────────────────────────────────

package/src/engine/types.js

@@ -40,9 +40,20 @@
  * @property {string} name           - App identifier (e.g., 'paaal')
  * @property {string} displayName    - Human-readable (e.g., 'PAAAL Coach')
  * @property {string} version
+ * @property {string} [instructions] - Agent-facing usage guidance, sent to clients in the MCP initialize response
  * @property {DbConfig} db
  * @property {string} [ownerColumn]  - App-wide default owner column for row-level scoping (per-table `ownerColumn` overrides)
  * @property {TableSchema[]} tables
+ * @property {Record<string, SubServer>} [servers] - Optional grouped views over the app.
+ *           The root URL stays the INDEX server (all app-level tables + instructions);
+ *           each key is additionally served at /:appName/<key> as its own MCP server,
+ *           inheriting from the app config and overriding what it declares.
+ *
+ * @typedef {Object} SubServer
+ * @property {string} [instructions] - Overrides the app-level instructions for this sub-server
+ * @property {Object} [tables]       - Overrides the app-level tables (same shape; a table may
+ *           appear in several sub-servers with different operations). Omit to inherit all.
+ * @property {string|null} [ownerColumn] - Overrides the app-level owner column
  */
 
 export {};

package/src/transport/fastifyAdapter.js

@@ -13,13 +13,18 @@
  *   });
  *
  * Route param format:
- *   /v1/mcp/paaal--dev   → appName: 'paaal', env: 'dev'
- *   /v1/mcp/paaal        → appName: 'paaal', env: 'prod' (default)
+ *   /v1/mcp/paaal--dev        → appName: 'paaal', env: 'dev'
+ *   /v1/mcp/paaal             → appName: 'paaal', env: 'prod' (default)
+ *   /v1/mcp/paaal--dev/manage → sub-server 'manage' (when the config defines servers.manage)
  *
- * Routes:
- *   POST   /v1/mcp/:appName        — MCP protocol endpoint
- *   DELETE /v1/mcp/:appName        — Session termination
- *   GET    /v1/mcp/:appName/health — Health check
+ * The root URL is always the app's INDEX server (all app-level tables + instructions).
+ * Sub-servers are optional grouped views over it — each inherits from the app config
+ * and overrides what it declares (tables, instructions, ownerColumn).
+ *
+ * Routes (the /:sub variants serve apps whose config defines `servers`):
+ *   POST   /v1/mcp/:appName[/:sub]        — MCP protocol endpoint
+ *   DELETE /v1/mcp/:appName[/:sub]        — Session termination
+ *   GET    /v1/mcp/:appName[/:sub]/health — Health check
  */
 
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -104,22 +109,37 @@ export default async function mcpPlugin(fastify, opts = {}) {
     }
   }
 
-  // Build lookup: key = "appName--env" (or "appName--prod" for default)
+  // Build lookup: key = "appName--env" (or "appName--prod" for default).
+  // The root key is the app's INDEX server — all app-level tables + instructions.
+  // Each `servers` entry is additionally served at "appName--env/sub" as its own
+  // MCP server, inheriting from the app config and overriding what it declares
+  // (tables, instructions, ownerColumn) — grouped tools per agent.
   const apps = new Map();
   for (const config of Object.values(opts.apps || {})) {
-    const key = `${config.appName}--${config.env || 'prod'}`;
-    apps.set(key, config);
+    const base = `${config.appName}--${config.env || 'prod'}`;
+    apps.set(base, config);
+    for (const [sub, server] of Object.entries(config.servers || {})) {
+      apps.set(`${base}/${sub}`, {
+        appName: config.appName,
+        env: config.env,
+        version: config.version,
+        ownerColumn: server.ownerColumn !== undefined ? server.ownerColumn : config.ownerColumn,
+        instructions: server.instructions || config.instructions,
+        tables: server.tables || config.tables,
+        serverName: `${config.appName}-${sub}-mcp`,
+        cacheKey: `${base}--${sub}`,
+      });
+    }
   }
   if (!apps.size) throw new Error('icode-mcp-adapter: opts.apps is required (at least one app)');
 
   // ── POST — MCP protocol endpoint ───────────────────────────────────────
-  fastify.post(`${prefix}/:appName`, {
-    config: { public: isPublic },
-  }, async (req, reply) => {
+  async function handleMcpPost(req, reply) {
     const { appName, env } = parseAppParam(req.params.appName);
-    const appConfig = apps.get(`${appName}--${env}`);
+    const key = req.params.sub ? `${appName}--${env}/${req.params.sub}` : `${appName}--${env}`;
+    const appConfig = apps.get(key);
     if (!appConfig) {
-      return reply.code(404).send({ ok: false, error: `App '${appName}/${env}' not registered` });
+      return reply.code(404).send({ ok: false, error: `App '${key}' not registered` });
     }
 
     const sessionId = req.headers['mcp-session-id'];
@@ -176,19 +196,23 @@ export default async function mcpPlugin(fastify, opts = {}) {
       error: { code: -32000, message: 'Invalid session or missing initialization' },
       id: null,
     });
-  });
+  }
+
+  fastify.post(`${prefix}/:appName`, { config: { public: isPublic } }, handleMcpPost);
+  fastify.post(`${prefix}/:appName/:sub`, { config: { public: isPublic } }, handleMcpPost);
 
   // ── DELETE — Session termination ───────────────────────────────────────
-  fastify.delete(`${prefix}/:appName`, {
-    config: { public: isPublic },
-  }, async (req, reply) => {
+  async function handleMcpDelete(req, reply) {
     const sessionId = req.headers['mcp-session-id'];
     if (sessionId && sessions.has(sessionId)) {
       await sessions.get(sessionId).transport.close();
       sessions.delete(sessionId);
     }
     return reply.code(200).send();
-  });
+  }
+
+  fastify.delete(`${prefix}/:appName`, { config: { public: isPublic } }, handleMcpDelete);
+  fastify.delete(`${prefix}/:appName/:sub`, { config: { public: isPublic } }, handleMcpDelete);
 
   // ── GET — Health check ─────────────────────────────────────────────────
   fastify.get(`${prefix}/:appName/health`, {
@@ -197,6 +221,18 @@ export default async function mcpPlugin(fastify, opts = {}) {
     const { appName, env } = parseAppParam(req.params.appName);
     const appConfig = apps.get(`${appName}--${env}`);
     if (!appConfig) return { ok: false, error: `App '${appName}/${env}' not registered` };
-    return { ok: true, app: appName, env, tables: Object.keys(appConfig.tables) };
+    const out = { ok: true, app: appName, env, tables: Object.keys(appConfig.tables) };
+    if (appConfig.servers) out.servers = Object.keys(appConfig.servers);
+    return out;
+  });
+
+  fastify.get(`${prefix}/:appName/:sub/health`, {
+    config: { public: isPublic },
+  }, async (req) => {
+    const { appName, env } = parseAppParam(req.params.appName);
+    const key = `${appName}--${env}/${req.params.sub}`;
+    const appConfig = apps.get(key);
+    if (!appConfig) return { ok: false, error: `App '${key}' not registered` };
+    return { ok: true, app: appName, env, server: req.params.sub, tables: Object.keys(appConfig.tables) };
   });
 }