icode-mcp-adapter 1.0.3 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icode-mcp-adapter",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "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

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { registerTableTools } from './ToolBuilder.js';
-import { resolveSchemas } from './SchemaAdapter.js';
+import { resolveSchemas as defaultResolveSchemas } from './SchemaAdapter.js';
 
 /**
  * Create an MCP server from a FULL app config (tables already defined).
@@ -23,26 +23,19 @@ export function createMcpServer(config, db) {
 }
 
 /**
- * Create an MCP server from a LIGHTWEIGHT config (auto-resolve columns from DB).
+ * Create an MCP server from a LIGHTWEIGHT config (auto-resolve columns).
  *
- * 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 {Object} config - app config with tables
  * @param {{ query: Function }} db - Pool or SQLService
+ * @param {{ resolveSchemas?: Function }} [opts]
+ *        resolveSchemas: (db, tableConfigs, opts) => Promise<TableSchema[]>
+ *        Defaults to INFORMATION_SCHEMA-based resolver.
+ *        Inject your own to use icode-server's SchemasService or any other source.
  * @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) {
+export async function createMcpServerAuto(config, db, opts = {}) {
+  const resolveSchemas = opts.resolveSchemas || defaultResolveSchemas;
+
   const tables = await resolveSchemas(db, config.tables, {
     cacheKey: config.appName,
   });

package/src/engine/SchemaAdapter.js

@@ -1,11 +1,11 @@
 /**
- * Auto-derives MCP TableSchema from the live database (INFORMATION_SCHEMA).
+ * Auto-derives MCP TableSchema from 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
+ *   - Meta fields: `_created`, `_createdBy`, `_time`, `_by`, `_deleted`, `pk` → readOnly
  *
  * Works with:
  *   - mysql2/promise Pool.query()     (standalone)
@@ -14,7 +14,7 @@
 
 // ── MySQL → MCP type mapping ─────────────────────────────────────────────────
 
-const MYSQL_TYPE_MAP = {
+const DATATYPE_MAP = {
   varchar:    'string',
   char:       'string',
   tinytext:   'string',
@@ -25,6 +25,7 @@ const MYSQL_TYPE_MAP = {
   bigint:     'number',
   smallint:   'number',
   mediumint:  'number',
+  tinyint:    'number',
   float:      'number',
   double:     'number',
   decimal:    'number',
@@ -35,9 +36,8 @@ const MYSQL_TYPE_MAP = {
   enum:       'enum',
 };
 
-// ── icode-server meta fields (auto-managed, always readOnly) ─────────────────
+// ── Meta fields (auto-managed by icode-server, always readOnly) ──────────────
 
-// Meta fields auto-managed by icode-server — always readOnly
 const META_FIELDS = new Set([
   '_created',      // created timestamp (epoch ms)
   '_createdBy',    // who created
@@ -53,21 +53,12 @@ const cache = new Map();
 const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
 
 /**
- * Resolve full TableSchema[] from a lightweight config + live DB.
+ * Resolve full TableSchema[] from config + INFORMATION_SCHEMA.
  *
  * @param {{ query: Function }} db - Pool or SQLService
- * @param {Record<string, TableConfig>} tableConfigs - lightweight per-table config
+ * @param {Record<string, TableConfig>} tableConfigs
  * @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
@@ -78,7 +69,6 @@ export async function resolveSchemas(db, tableConfigs, opts = {}) {
     }
   }
 
-  // Detect current database name
   const [dbRows] = await db.query('SELECT DATABASE() as db');
   const dbName = dbRows[0].db;
 
@@ -99,16 +89,14 @@ export async function resolveSchemas(db, tableConfigs, opts = {}) {
       continue;
     }
 
-    // ── Detect primary key ────────────────────────────────────────────────
-    // icode-server uses `guid` (string), fallback to `pk` (auto-increment)
+    // ── Detect primary key ──────────────────────────────────────────────
     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)
+    // ── Detect soft delete ──────────────────────────────────────────────
     const hasDeletedCol = rows.some(r => r.COLUMN_NAME === '_deleted');
 
     let softDeleteFilter = null;
@@ -119,22 +107,23 @@ export async function resolveSchemas(db, tableConfigs, opts = {}) {
       softDeleteSet = '`_deleted` = 1';
     }
 
-    // ── Build columns ─────────────────────────────────────────────────────
+    // ── Build columns ───────────────────────────────────────────────────
     const columns = rows.map(row => {
       const col = buildColumn(row, pkName);
 
-      // Apply per-column overrides from config
+      // Apply per-column overrides from config (description, filterable)
       if (config.columns?.[row.COLUMN_NAME]) {
-        Object.assign(col, config.columns[row.COLUMN_NAME]);
+        const override = config.columns[row.COLUMN_NAME];
+        if (override.description) col.description = override.description;
+        if (override.filterable) col.filterable = true;
+        if (override.required !== undefined) col.required = override.required;
+        if (override.nullable !== undefined) col.nullable = override.nullable;
       }
 
       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;
 
@@ -178,37 +167,16 @@ function buildColumn(row, pkName) {
     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';
-  }
+  if (row.COLUMN_NAME === pkName) col.readOnly = true;
+  if (row.EXTRA?.includes('auto_increment')) col.readOnly = true;
+  if (row.COLUMN_NAME === '_created') col.autoSet = 'created_at';
+  if (META_FIELDS.has(row.COLUMN_NAME)) col.readOnly = true;
+  if (row.IS_NULLABLE === 'YES') col.nullable = true;
 
-  // 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
@@ -217,14 +185,12 @@ function buildColumn(row, 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);
   }
@@ -232,19 +198,11 @@ function buildColumn(row, pkName) {
   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';
+  return DATATYPE_MAP[row.DATA_TYPE] || 'string';
 }
 
 function parseEnum(columnType) {

package/src/transport/fastifyAdapter.js

@@ -47,11 +47,15 @@ function parseAppParam(param) {
  *        — app configs keyed by appName: { paaal: paaalConfig }
  * @param {(appName: string, env: string) => Promise<{ query: Function }>} opts.getDb
  *        — DB provider function, e.g. (name, env) => getAppDbService(name, env)
+ * @param {(db, tableConfigs, opts) => Promise<TableSchema[]>} [opts.resolveSchemas]
+ *        — Custom schema resolver. Default: INFORMATION_SCHEMA.
+ *        — Inject your own to use SchemasService or any other source.
  * @param {string} [opts.prefix='/v1/mcp']
  * @param {boolean} [opts.public=true]
  */
 export default async function mcpPlugin(fastify, opts = {}) {
   const getDb = opts.getDb;
+  const resolveSchemas = opts.resolveSchemas;
   const prefix = opts.prefix || '/v1/mcp';
   const isPublic = opts.public ?? true;
 
@@ -91,7 +95,7 @@ export default async function mcpPlugin(fastify, opts = {}) {
       } catch (err) {
         return reply.code(400).send({ ok: false, error: err.message || err.sqlMessage || 'Failed to get DB connection' });
       }
-      const server = await createMcpServerAuto(appConfig, db);
+      const server = await createMcpServerAuto(appConfig, db, { resolveSchemas });
 
       const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: () => randomUUID(),