icode-mcp-adapter 1.0.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "icode-mcp-adapter",
+  "version": "1.0.0",
+  "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",
+  "exports": {
+    ".": "./src/engine/McpEngine.js",
+    "./engine": "./src/engine/McpEngine.js",
+    "./tools": "./src/engine/ToolBuilder.js",
+    "./schema": "./src/engine/SchemaAdapter.js",
+    "./fastify": "./src/transport/fastifyAdapter.js",
+    "./types": "./src/engine/types.js"
+  },
+  "scripts": {
+    "test": "node tests/smoke.js",
+    "sandbox": "node tests/sandbox.js",
+    "sandbox:dev": "node --watch tests/sandbox.js",
+    "inspector": "npx @modelcontextprotocol/inspector node tests/sandbox.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25.0"
+  },
+  "peerDependencies": {
+    "mysql2": "^3.0.0"
+  },
+  "devDependencies": {
+    "mysql2": "^3.14.1",
+    "express": "^5.1.0",
+    "dotenv": "^16.5.0"
+  },
+  "files": [
+    "src/engine/",
+    "src/transport/fastifyAdapter.js"
+  ]
+}

package/src/engine/McpEngine.js

@@ -0,0 +1,55 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerTableTools } from './ToolBuilder.js';
+import { resolveSchemas } from './SchemaAdapter.js';
+
+/**
+ * Create an MCP server from a FULL app config (tables already defined).
+ *
+ * @param {import('./types.js').AppConfig} config - with tables[] fully specified
+ * @param {{ query: Function }} db
+ * @returns {McpServer}
+ */
+export function createMcpServer(config, db) {
+  const server = new McpServer({
+    name: `${config.name}-mcp`,
+    version: config.version,
+  });
+
+  for (const table of config.tables) {
+    registerTableTools(server, db, table);
+  }
+
+  return server;
+}
+
+/**
+ * Create an MCP server from a LIGHTWEIGHT config (auto-resolve columns from DB).
+ *
+ * Queries INFORMATION_SCHEMA to discover columns, types, PKs, defaults.
+ * Only needs a simple config listing which tables + operations to expose.
+ *
+ * @param {{ name: string, version?: string, tables: Record<string, import('./SchemaAdapter.js').TableConfig> }} config
+ * @param {{ query: Function }} db - Pool or SQLService
+ * @returns {Promise<McpServer>}
+ *
+ * @example
+ *   const server = await createMcpServerAuto({
+ *     name: 'paaal',
+ *     tables: {
+ *       plans:        { operations: ['list','get','update'], pkType: 'uuid' },
+ *       achievements: { operations: ['list','get','add','update'] },
+ *       actions:      { operations: ['list','get','add','update'] },
+ *     }
+ *   }, db);
+ */
+export async function createMcpServerAuto(config, db) {
+  const tables = await resolveSchemas(db, config.tables, {
+    cacheKey: config.name,
+  });
+
+  return createMcpServer({
+    name: config.name,
+    version: config.version || '1.0.0',
+    tables,
+  }, db);
+}

package/src/engine/SchemaAdapter.js

@@ -0,0 +1,280 @@
+/**
+ * Auto-derives MCP TableSchema from the live database (INFORMATION_SCHEMA).
+ *
+ * Follows icode-server conventions:
+ *   - PK: `guid` (string)
+ *   - Soft delete: `_deleted` (0 = active, 1 = deleted)
+ *   - Timestamp: `_created`
+ *   - Meta fields: `_time`, `_by`, `_createdBy`, `pk`, etc. → readOnly
+ *
+ * Works with:
+ *   - mysql2/promise Pool.query()     (standalone)
+ *   - icode-server SQLService.query() (integrated)
+ */
+
+// ── MySQL → MCP type mapping ─────────────────────────────────────────────────
+
+const MYSQL_TYPE_MAP = {
+  varchar:    'string',
+  char:       'string',
+  tinytext:   'string',
+  text:       'text',
+  mediumtext: 'text',
+  longtext:   'text',
+  int:        'number',
+  bigint:     'number',
+  smallint:   'number',
+  mediumint:  'number',
+  float:      'number',
+  double:     'number',
+  decimal:    'number',
+  date:       'date',
+  datetime:   'date',
+  timestamp:  'date',
+  json:       'text',
+  enum:       'enum',
+};
+
+// ── icode-server meta fields (auto-managed, always readOnly) ─────────────────
+
+// Meta fields auto-managed by icode-server — always readOnly
+const META_FIELDS = new Set([
+  '_created',      // created timestamp (epoch ms)
+  '_createdBy',    // who created
+  '_time',         // last modified timestamp
+  '_by',           // who last modified
+  '_deleted',      // soft delete flag
+  'pk',            // auto-increment secondary key
+]);
+
+// ── Schema cache ─────────────────────────────────────────────────────────────
+
+const cache = new Map();
+const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Resolve full TableSchema[] from a lightweight config + live DB.
+ *
+ * @param {{ query: Function }} db - Pool or SQLService
+ * @param {Record<string, TableConfig>} tableConfigs - lightweight per-table config
+ * @param {{ cacheKey?: string }} [opts]
+ * @returns {Promise<import('./types.js').TableSchema[]>}
+ *
+ * @typedef {Object} TableConfig
+ * @property {('list'|'get'|'add'|'update'|'delete')[]} operations
+ * @property {'auto'|'string'} [pkType]        - override PK type detection
+ * @property {boolean} [softDelete]            - default: auto-detected (_deleted col)
+ * @property {string} [singular]               - override singular derivation
+ * @property {string} [displayName]            - override display name
+ * @property {string} [listOrderBy]            - default: `_created` DESC
+ * @property {Record<string, Partial<import('./types.js').ColumnDef>>} [columns] - per-column overrides
+ */
+export async function resolveSchemas(db, tableConfigs, opts = {}) {
+  // Check cache
+  if (opts.cacheKey) {
+    const cached = cache.get(opts.cacheKey);
+    if (cached && Date.now() - cached.resolvedAt < CACHE_TTL) {
+      return cached.tables;
+    }
+  }
+
+  // Detect current database name
+  const [dbRows] = await db.query('SELECT DATABASE() as db');
+  const dbName = dbRows[0].db;
+
+  const tables = [];
+
+  for (const [tableName, config] of Object.entries(tableConfigs)) {
+    const [rows] = await db.query(
+      `SELECT COLUMN_NAME, DATA_TYPE, COLUMN_TYPE, IS_NULLABLE,
+              COLUMN_DEFAULT, COLUMN_KEY, EXTRA, CHARACTER_MAXIMUM_LENGTH
+       FROM INFORMATION_SCHEMA.COLUMNS
+       WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?
+       ORDER BY ORDINAL_POSITION`,
+      [dbName, tableName],
+    );
+
+    if (!rows.length) {
+      console.warn(`[MCP] Table '${tableName}' not found in '${dbName}', skipping`);
+      continue;
+    }
+
+    // ── Detect primary key ────────────────────────────────────────────────
+    // icode-server uses `guid` (string), fallback to `pk` (auto-increment)
+    const hasGuid = rows.some(r => r.COLUMN_NAME === 'guid');
+    const hasPk = rows.some(r => r.COLUMN_NAME === 'pk');
+    const pkName = config.primaryKey || (hasGuid ? 'guid' : (hasPk ? 'pk' : 'guid'));
+    const pkActualRow = rows.find(r => r.COLUMN_NAME === pkName);
+    const isStringPk = pkActualRow?.DATA_TYPE === 'varchar';
+
+    // ── Detect soft delete ────────────────────────────────────────────────
+    // icode-server standard: _deleted = 0 (not deleted), _deleted = 1 (deleted)
+    const hasDeletedCol = rows.some(r => r.COLUMN_NAME === '_deleted');
+
+    let softDeleteFilter = null;
+    let softDeleteSet = null;
+
+    if (config.softDelete !== false && hasDeletedCol) {
+      softDeleteFilter = '`_deleted` = 0';
+      softDeleteSet = '`_deleted` = 1';
+    }
+
+    // ── Build columns ─────────────────────────────────────────────────────
+    const columns = rows.map(row => {
+      const col = buildColumn(row, pkName);
+
+      // Apply per-column overrides from config
+      if (config.columns?.[row.COLUMN_NAME]) {
+        Object.assign(col, config.columns[row.COLUMN_NAME]);
+      }
+
+      return col;
+    });
+
+    // ── Derive singular name ──────────────────────────────────────────────
+    const singular = config.singular || deriveSingular(tableName);
+
+    // ── Default ORDER BY ──────────────────────────────────────────────────
+    const hasCreated = rows.some(r => r.COLUMN_NAME === '_created');
+    const defaultOrder = hasCreated ? '`_created` DESC' : undefined;
+
+    tables.push({
+      name: tableName,
+      singular,
+      displayName: config.displayName || capitalize(singular),
+      primaryKey: pkName,
+      pkType: config.pkType || (isStringPk ? 'string' : 'auto'),
+      softDelete: !!softDeleteFilter,
+      softDeleteFilter,
+      softDeleteSet,
+      operations: config.operations || ['list', 'get', 'add', 'update'],
+      listOrderBy: config.listOrderBy || defaultOrder,
+      columns,
+      ...(config.customDescriptions && { customDescriptions: config.customDescriptions }),
+    });
+  }
+
+  // Cache result
+  if (opts.cacheKey) {
+    cache.set(opts.cacheKey, { tables, resolvedAt: Date.now() });
+  }
+
+  return tables;
+}
+
+/** Clear cached schemas (e.g., after a migration). */
+export function clearSchemaCache(cacheKey) {
+  if (cacheKey) cache.delete(cacheKey);
+  else cache.clear();
+}
+
+// ── Column builder ───────────────────────────────────────────────────────────
+
+const q = (name) => `\`${name}\``;
+
+function buildColumn(row, pkName) {
+  const col = {
+    name: row.COLUMN_NAME,
+    type: resolveType(row),
+  };
+
+  // Primary key → readOnly
+  if (row.COLUMN_NAME === pkName) {
+    col.readOnly = true;
+  }
+
+  // Auto-increment → readOnly
+  if (row.EXTRA?.includes('auto_increment')) {
+    col.readOnly = true;
+  }
+
+  // _created → autoSet
+  if (row.COLUMN_NAME === '_created') {
+    col.autoSet = 'created_at';
+  }
+
+  // icode-server meta fields → readOnly (auto-managed by the platform)
+  if (META_FIELDS.has(row.COLUMN_NAME)) {
+    col.readOnly = true;
+  }
+
+  // Nullable
+  if (row.IS_NULLABLE === 'YES') {
+    col.nullable = true;
+  }
+
+  // Default value
+  if (row.COLUMN_DEFAULT !== null && row.COLUMN_DEFAULT !== undefined) {
+    col.default = parseDefault(row);
+  }
+
+  // Required: NOT NULL, no default, not auto-set, not PK, not meta
+  if (row.IS_NULLABLE === 'NO'
+    && row.COLUMN_DEFAULT === null
+    && !col.readOnly
+    && !col.autoSet
+    && row.COLUMN_NAME !== pkName) {
+    col.required = true;
+  }
+
+  // Filterable: indexed columns and guid/FK references
+  if (row.COLUMN_KEY === 'MUL'
+    || (row.COLUMN_NAME.endsWith('_id') && row.COLUMN_NAME !== pkName)
+    || (row.COLUMN_NAME === 'guid' && row.COLUMN_NAME !== pkName)) {
+    col.filterable = true;
+  }
+
+  // Enum values
+  if (row.DATA_TYPE === 'enum') {
+    col.enumValues = parseEnum(row.COLUMN_TYPE);
+  }
+
+  return col;
+}
+
+// ── Type resolution ──────────────────────────────────────────────────────────
+
+function resolveType(row) {
+  // tinyint(1) → boolean
+  if (row.COLUMN_TYPE === 'tinyint(1)') return 'boolean';
+
+  // bigint for timestamp columns → timestamp (epoch ms)
+  if (row.DATA_TYPE === 'bigint' && (row.COLUMN_NAME === '_created' || row.COLUMN_NAME === '_time')) return 'timestamp';
+
+  // varchar(36) named guid → string (not uuid — icode guids aren't always uuid format)
+  if (row.COLUMN_NAME === 'guid') return 'string';
+
+  return MYSQL_TYPE_MAP[row.DATA_TYPE] || 'string';
+}
+
+function parseEnum(columnType) {
+  const match = columnType.match(/^enum\((.+)\)$/i);
+  if (!match) return [];
+  return match[1].split(',').map(v => v.trim().replace(/^'|'$/g, ''));
+}
+
+function parseDefault(row) {
+  if (row.COLUMN_TYPE === 'tinyint(1)') {
+    return row.COLUMN_DEFAULT === '1' || row.COLUMN_DEFAULT === 1;
+  }
+  if (['int', 'bigint', 'smallint', 'mediumint'].includes(row.DATA_TYPE)) {
+    return Number(row.COLUMN_DEFAULT);
+  }
+  if (['float', 'double', 'decimal'].includes(row.DATA_TYPE)) {
+    return Number(row.COLUMN_DEFAULT);
+  }
+  return row.COLUMN_DEFAULT;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function deriveSingular(name) {
+  if (name.endsWith('ies')) return name.slice(0, -3) + 'y';
+  if (name.endsWith('ses')) return name.slice(0, -2);
+  if (name.endsWith('s') && !name.endsWith('ss')) return name.slice(0, -1);
+  return name;
+}
+
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/src/engine/ToolBuilder.js

@@ -0,0 +1,295 @@
+import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Dynamic MCP tool generator.
+ *
+ * Follows icode-server conventions:
+ *   - PK: `guid` (string), soft delete: `_deleted`, timestamp: `_created`
+ *
+ * Accepts any db object with a `query(sql, params)` method that returns [rows, fields].
+ *   - mysql2/promise Pool.query()      (standalone)
+ *   - icode-server SQLService.query()  (integrated)
+ */
+
+/** Backtick-quote a MySQL identifier */
+const q = (name) => `\`${name}\``;
+
+/**
+ * Build a Zod schema for a column definition.
+ * @param {import('./types.js').ColumnDef} col
+ * @param {{ forceOptional?: boolean, includeDefault?: boolean }} opts
+ */
+function zodFor(col, opts = {}) {
+  let s;
+  switch (col.type) {
+    case 'number':    s = z.number(); break;
+    case 'boolean':   s = z.boolean(); break;
+    case 'uuid':      s = z.string().uuid(); break;
+    case 'timestamp': s = z.number(); break;
+    case 'enum':      s = z.enum(col.enumValues); break;
+    default:          s = z.string(); break;
+  }
+  if (col.description) s = s.describe(col.description);
+  if (col.nullable)    s = s.nullable();
+  if (opts.forceOptional || !col.required) s = s.optional();
+  if (opts.includeDefault && col.default !== undefined) s = s.default(col.default);
+  return s;
+}
+
+/** Get writable columns (exclude readOnly, autoSet, and primaryKey) */
+function writableCols(table) {
+  return table.columns.filter(c => !c.readOnly && !c.autoSet && c.name !== table.primaryKey);
+}
+
+/** Get filterable columns */
+function filterCols(table) {
+  return table.columns.filter(c => c.filterable);
+}
+
+/** Build PK Zod schema */
+function pkSchema(table) {
+  if (table.pkType === 'string') return z.string().describe(`The ${table.singular} guid`);
+  if (table.pkType === 'auto') return z.number().describe(`The ${table.singular} ID`);
+  return z.string().describe(`The ${table.singular} guid`);
+}
+
+/**
+ * Register all CRUD tools for a table on the MCP server.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {{ query: (sql: string, params: any[]) => Promise<[any[], any]> }} db
+ *        — any object with query(sql, params) → [rows, fields]
+ * @param {import('./types.js').TableSchema} table
+ */
+export function registerTableTools(server, db, table) {
+  const display = table.displayName || table.singular;
+
+  for (const op of table.operations) {
+    switch (op) {
+      case 'list':   regList(server, db, table, display); break;
+      case 'get':    regGet(server, db, table, display); break;
+      case 'add':    regAdd(server, db, table, display); break;
+      case 'update': regUpdate(server, db, table, display); break;
+      case 'delete': regDelete(server, db, table, display); break;
+    }
+  }
+}
+
+// ── LIST ──────────────────────────────────────────────────────────────────────
+
+function regList(server, db, table, display) {
+  const filters = filterCols(table);
+  const inputSchema = {};
+  for (const f of filters) {
+    inputSchema[f.name] = zodFor(f, { forceOptional: true });
+  }
+
+  server.registerTool(`list_${table.name}`, {
+    title: `List ${display}s`,
+    description: table.customDescriptions?.list
+      || `List all ${table.name} with optional filters.`,
+    inputSchema,
+  }, async (args) => {
+    try {
+      const where = [];
+      const vals = [];
+
+      if (table.softDeleteFilter) where.push(table.softDeleteFilter);
+
+      for (const f of filters) {
+        if (args[f.name] !== undefined && args[f.name] !== null) {
+          where.push(`${q(f.name)} = ?`);
+          vals.push(args[f.name]);
+        }
+      }
+
+      let sql = `SELECT * FROM ${q(table.name)}`;
+      if (where.length) sql += ` WHERE ${where.join(' AND ')}`;
+      if (table.listOrderBy) sql += ` ORDER BY ${table.listOrderBy}`;
+
+      const [rows] = await db.query(sql, vals);
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ [table.name]: rows }) }],
+        structuredContent: { [table.name]: rows },
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
+    }
+  });
+}
+
+// ── GET ───────────────────────────────────────────────────────────────────────
+
+function regGet(server, db, table, display) {
+  server.registerTool(`get_${table.singular}`, {
+    title: `Get ${display}`,
+    description: table.customDescriptions?.get
+      || `Get a single ${table.singular} by ID.`,
+    inputSchema: { [table.primaryKey]: pkSchema(table) },
+  }, async (args) => {
+    try {
+      const [rows] = await db.query(
+        `SELECT * FROM ${q(table.name)} WHERE ${q(table.primaryKey)} = ? LIMIT 1`,
+        [args[table.primaryKey]],
+      );
+      const row = rows[0] || null;
+      return {
+        content: [{ type: 'text', text: JSON.stringify(row) }],
+        structuredContent: row,
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
+    }
+  });
+}
+
+// ── ADD ───────────────────────────────────────────────────────────────────────
+
+function regAdd(server, db, table, display) {
+  const cols = writableCols(table);
+  const inputSchema = {};
+  for (const c of cols) {
+    inputSchema[c.name] = zodFor(c, { includeDefault: true });
+  }
+
+  server.registerTool(`add_${table.singular}`, {
+    title: `Add ${display}`,
+    description: table.customDescriptions?.add
+      || `Create a new ${table.singular}.`,
+    inputSchema,
+  }, async (args) => {
+    try {
+      const insertCols = [];
+      const insertVals = [];
+      const placeholders = [];
+
+      // Auto-set columns (_created)
+      for (const c of table.columns) {
+        if (c.autoSet === 'created_at') {
+          insertCols.push(q(c.name));
+          insertVals.push(Date.now());
+          placeholders.push('?');
+        }
+      }
+
+      // String PK (guid) — generate if not provided by caller
+      let generatedGuid;
+      if (table.pkType === 'string') {
+        generatedGuid = randomUUID();
+        insertCols.push(q(table.primaryKey));
+        insertVals.push(generatedGuid);
+        placeholders.push('?');
+      }
+
+      // User-provided columns
+      for (const c of cols) {
+        if (args[c.name] !== undefined) {
+          insertCols.push(q(c.name));
+          insertVals.push(args[c.name]);
+          placeholders.push('?');
+        }
+      }
+
+      const sql = `INSERT INTO ${q(table.name)} (${insertCols.join(', ')}) VALUES (${placeholders.join(', ')})`;
+      const [result] = await db.query(sql, insertVals);
+
+      // Fetch the inserted row
+      const pkVal = table.pkType === 'string' ? generatedGuid : result.insertId;
+      const [rows] = await db.query(
+        `SELECT * FROM ${q(table.name)} WHERE ${q(table.primaryKey)} = ?`,
+        [pkVal],
+      );
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(rows[0]) }],
+        structuredContent: rows[0],
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
+    }
+  });
+}
+
+// ── UPDATE ────────────────────────────────────────────────────────────────────
+
+function regUpdate(server, db, table, display) {
+  const cols = writableCols(table);
+  const inputSchema = { [table.primaryKey]: pkSchema(table) };
+  for (const c of cols) {
+    inputSchema[c.name] = zodFor(c, { forceOptional: true });
+  }
+
+  server.registerTool(`update_${table.singular}`, {
+    title: `Update ${display}`,
+    description: table.customDescriptions?.update
+      || `Update fields on an existing ${table.singular}.`,
+    inputSchema,
+  }, async (args) => {
+    try {
+      const pkVal = args[table.primaryKey];
+      const setClauses = [];
+      const vals = [];
+
+      for (const c of cols) {
+        if (args[c.name] !== undefined) {
+          setClauses.push(`${q(c.name)} = ?`);
+          vals.push(args[c.name]);
+        }
+      }
+
+      if (!setClauses.length) {
+        return { content: [{ type: 'text', text: 'No fields to update.' }] };
+      }
+
+      vals.push(pkVal);
+      await db.query(
+        `UPDATE ${q(table.name)} SET ${setClauses.join(', ')} WHERE ${q(table.primaryKey)} = ?`,
+        vals,
+      );
+
+      const [rows] = await db.query(
+        `SELECT * FROM ${q(table.name)} WHERE ${q(table.primaryKey)} = ?`,
+        [pkVal],
+      );
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(rows[0]) }],
+        structuredContent: rows[0],
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
+    }
+  });
+}
+
+// ── DELETE ────────────────────────────────────────────────────────────────────
+
+function regDelete(server, db, table, display) {
+  server.registerTool(`delete_${table.singular}`, {
+    title: `Delete ${display}`,
+    description: table.customDescriptions?.delete
+      || `Delete a ${table.singular}.`,
+    inputSchema: { [table.primaryKey]: pkSchema(table) },
+  }, async (args) => {
+    try {
+      const pkVal = args[table.primaryKey];
+
+      if (table.softDeleteSet) {
+        await db.query(
+          `UPDATE ${q(table.name)} SET ${table.softDeleteSet} WHERE ${q(table.primaryKey)} = ?`,
+          [pkVal],
+        );
+      } else {
+        await db.query(
+          `DELETE FROM ${q(table.name)} WHERE ${q(table.primaryKey)} = ?`,
+          [pkVal],
+        );
+      }
+
+      return { content: [{ type: 'text', text: `${display} deleted successfully.` }] };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
+    }
+  });
+}

package/src/engine/types.js

@@ -0,0 +1,46 @@
+/**
+ * @typedef {'string'|'number'|'boolean'|'text'|'date'|'enum'|'uuid'|'timestamp'} ColumnType
+ *
+ * @typedef {Object} ColumnDef
+ * @property {string} name           - Column name in the database
+ * @property {ColumnType} type       - Column data type
+ * @property {string[]} [enumValues] - Allowed values for enum type
+ * @property {boolean} [required]    - Required for add operation (default: false)
+ * @property {boolean} [nullable]    - Allows null values
+ * @property {*} [default]           - Default value for add (used in Zod schema)
+ * @property {string} [description]  - Tool parameter description shown to AI
+ * @property {'created_at'} [autoSet] - Auto-populated on insert, excluded from inputs
+ * @property {boolean} [readOnly]    - Excluded from add/update inputs
+ * @property {boolean} [filterable]  - Available as a list filter parameter
+ *
+ * @typedef {Object} TableSchema
+ * @property {string} name           - Table name (e.g., 'achievements')
+ * @property {string} singular       - Singular form (e.g., 'achievement')
+ * @property {string} [displayName]  - Human-readable (e.g., 'Achievement')
+ * @property {string} primaryKey     - Primary key column name
+ * @property {'auto'|'uuid'} pkType  - Auto-increment or UUID
+ * @property {boolean} [softDelete]  - Use active=0 instead of DELETE (default: true)
+ * @property {ColumnDef[]} columns
+ * @property {('list'|'get'|'add'|'update'|'delete')[]} operations
+ * @property {string} [listOrderBy]  - Default ORDER BY clause (use backticks for reserved words)
+ * @property {Object} [customDescriptions] - Override tool descriptions per operation
+ *
+ * @typedef {Object} DbConfig
+ * @property {string} host
+ * @property {string} user
+ * @property {string} password
+ * @property {string} database
+ * @property {number} [port]
+ * @property {Object} [ssl]
+ * @property {string} [ssl.ca]       - Base64 encoded CA cert
+ * @property {boolean} [ssl.rejectUnauthorized]
+ *
+ * @typedef {Object} AppConfig
+ * @property {string} name           - App identifier (e.g., 'paaal')
+ * @property {string} displayName    - Human-readable (e.g., 'PAAAL Coach')
+ * @property {string} version
+ * @property {DbConfig} db
+ * @property {TableSchema[]} tables
+ */
+
+export {};

package/src/transport/fastifyAdapter.js

@@ -0,0 +1,112 @@
+/**
+ * Fastify plugin for icode-server integration.
+ *
+ * Usage in instacode.js:
+ *
+ *   import mcpPlugin from 'icode-mcp-adapter/fastify';
+ *   import paaalConfig from './plugins/mcp/configs/paaal.config.js';
+ *
+ *   await app.register(mcpPlugin, {
+ *     apps: { paaal: paaalConfig },
+ *     getDb: (appName, env) => getAppDbService(appName, env),
+ *   });
+ *
+ * Routes:
+ *   POST   /v1/mcp/:appName        — MCP protocol endpoint
+ *   DELETE /v1/mcp/:appName        — Session termination
+ *   GET    /v1/mcp/:appName/health — Health check
+ */
+
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { randomUUID } from 'node:crypto';
+import { createMcpServerAuto } from '../engine/McpEngine.js';
+
+const sessions = new Map();
+
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {Object} opts
+ * @param {Record<string, import('../engine/types.js').AppConfig>} opts.apps
+ *        — app configs keyed by name: { paaal: paaalConfig, myapp: myappConfig }
+ * @param {(appName: string, env: string) => Promise<{ query: Function }>} opts.getDb
+ *        — DB provider function, e.g. (name, env) => getAppDbService(name, env)
+ * @param {string} [opts.prefix='/v1/mcp']
+ *        — route prefix (default: /v1/mcp)
+ * @param {boolean} [opts.public=true]
+ *        — route visibility for AuthGate (default: public)
+ */
+export default async function mcpPlugin(fastify, opts = {}) {
+  const apps = new Map(Object.entries(opts.apps || {}));
+  const getDb = opts.getDb;
+  const prefix = opts.prefix || '/v1/mcp';
+  const isPublic = opts.public ?? true;
+
+  if (!getDb) throw new Error('icode-mcp-adapter: opts.getDb is required');
+  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) => {
+    const { appName } = req.params;
+    const appConfig = apps.get(appName);
+    if (!appConfig) {
+      return reply.code(404).send({ ok: false, error: `App '${appName}' not registered` });
+    }
+
+    const sessionId = req.headers['mcp-session-id'];
+
+    // Existing session
+    if (sessionId && sessions.has(sessionId)) {
+      await sessions.get(sessionId).transport.handleRequest(req.raw, reply.raw, req.body);
+      return reply.hijack();
+    }
+
+    // New session (must be initialize request)
+    if (!sessionId && isInitializeRequest(req.body)) {
+      const db = await getDb(appName, appConfig.dbEnv || 'dev');
+      const server = await createMcpServerAuto(appConfig, db);
+
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        onsessioninitialized: (id) => sessions.set(id, { transport, server }),
+      });
+      transport.onclose = () => {
+        if (transport.sessionId) sessions.delete(transport.sessionId);
+      };
+
+      await server.connect(transport);
+      await transport.handleRequest(req.raw, reply.raw, req.body);
+      return reply.hijack();
+    }
+
+    return reply.code(400).send({
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'Invalid session or missing initialization' },
+      id: null,
+    });
+  });
+
+  // ── DELETE — Session termination ───────────────────────────────────────
+  fastify.delete(`${prefix}/:appName`, {
+    config: { public: isPublic },
+  }, async (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();
+  });
+
+  // ── GET — Health check ─────────────────────────────────────────────────
+  fastify.get(`${prefix}/:appName/health`, {
+    config: { public: isPublic },
+  }, async (req) => {
+    const { appName } = req.params;
+    const appConfig = apps.get(appName);
+    if (!appConfig) return { ok: false, error: 'Unknown app' };
+    return { ok: true, app: appName, tables: Object.keys(appConfig.tables) };
+  });
+}