icode-mcp-adapter 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,131 @@
+# icode-mcp-adapter
+
+Dynamic MCP server adapter for icode-server. Auto-generates CRUD tools from your existing database tables — column metadata resolved from `INFORMATION_SCHEMA` at runtime.
+
+## What it does
+
+Given a lightweight config like this:
+
+```js
+{
+  name: 'myapp',
+  dbEnv: 'dev',
+  tables: {
+    users:  { operations: ['list', 'get', 'add', 'update'] },
+    orders: { operations: ['list', 'get', 'add', 'update', 'delete'] },
+  },
+}
+```
+
+It auto-generates MCP tools: `list_users`, `get_user`, `add_user`, `update_user`, `list_orders`, `get_order`, `add_order`, `update_order`, `delete_order` — with proper Zod input schemas, SQL queries, and error handling.
+
+No manual column definitions. The adapter reads your DB schema and figures out types, PKs, required fields, enums, defaults, and soft delete.
+
+## icode-server conventions
+
+- **Primary key**: `guid` (string), fallback to `pk`
+- **Soft delete**: `_deleted = 0` (active) / `_deleted = 1` (deleted)
+- **Timestamps**: `_created`, `_time` (epoch ms, auto-managed)
+- **Meta fields**: `_created`, `_createdBy`, `_time`, `_by`, `_deleted`, `pk` — all readOnly
+
+## Install
+
+```bash
+npm install icode-mcp-adapter @modelcontextprotocol/sdk zod
+```
+
+## Usage in icode-server
+
+```js
+// instacode.js
+import mcpPlugin from 'icode-mcp-adapter/fastify';
+import { getAppDbService } from './services/connectionService.mjs';
+import paaalConfig from './plugins/mcp/configs/paaal.config.js';
+
+await app.register(mcpPlugin, {
+  apps: { paaal: paaalConfig },
+  getDb: (appName, env) => getAppDbService(appName, env),
+});
+```
+
+This registers:
+- `POST /v1/mcp/:appName` — MCP protocol endpoint
+- `DELETE /v1/mcp/:appName` — session termination
+- `GET /v1/mcp/:appName/health` — health check
+
+## App config format
+
+```js
+// plugins/mcp/configs/myapp.config.js
+export default {
+  name: 'myapp',
+  displayName: 'My App',
+  version: '1.0.0',
+  dbEnv: 'dev',
+  tables: {
+    users: {
+      operations: ['list', 'get', 'add', 'update', 'delete'],
+      listOrderBy: '`_created` DESC',
+      columns: {
+        email: { description: 'User email address' },
+      },
+    },
+  },
+};
+```
+
+### Table options
+
+| Option | Default | Description |
+|---|---|---|
+| `operations` | `['list','get','add','update']` | Which CRUD tools to generate |
+| `pkType` | auto-detected | `'string'` (guid) or `'auto'` (int) |
+| `softDelete` | auto (true if `_deleted` exists) | Soft delete via `_deleted` flag |
+| `singular` | auto-derived (`users`→`user`) | Tool name prefix: `add_user` |
+| `listOrderBy` | `_created DESC` | SQL ORDER BY clause |
+| `columns` | `{}` | Per-column overrides (description, type, filterable) |
+
+### Auto-detection from INFORMATION_SCHEMA
+
+| DB trait | Detected as |
+|---|---|
+| `guid` column | `primaryKey: 'guid'`, `pkType: 'string'` |
+| `_deleted` column | soft delete: `WHERE _deleted = 0`, delete sets `_deleted = 1` |
+| `_created` | autoSet (epoch ms), readOnly |
+| `_time`, `_by`, `_createdBy`, `pk` | readOnly (meta fields) |
+| `tinyint(1)` | boolean |
+| `ENUM(...)` | enum with parsed values |
+| `IS_NULLABLE = 'NO'` + no default | required |
+| `COLUMN_KEY = 'MUL'` or `*_id` | filterable |
+
+## Plugin options
+
+```js
+await app.register(mcpPlugin, {
+  apps: { ... },           // required — app configs keyed by name
+  getDb: (name, env) => {}, // required — returns db with .query()
+  prefix: '/v1/mcp',       // optional — route prefix (default: /v1/mcp)
+  public: true,             // optional — route visibility for AuthGate (default: true)
+});
+```
+
+## Exports
+
+```js
+import { createMcpServer, createMcpServerAuto } from 'icode-mcp-adapter/engine';
+import { resolveSchemas, clearSchemaCache } from 'icode-mcp-adapter/schema';
+import { registerTableTools } from 'icode-mcp-adapter/tools';
+import mcpPlugin from 'icode-mcp-adapter/fastify';
+```
+
+## Testing
+
+```bash
+npm test              # smoke test (no DB required)
+npm run sandbox       # Express server on :3000 (needs .env with DB creds)
+npm run inspector     # MCP Inspector UI (needs .env with DB creds)
+```
+
+## Full integration guide
+
+See [INTEGRATION.md](./INTEGRATION.md) for step-by-step setup, nginx config, Claude Desktop connection, and architecture details.

package/package.json

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

@@ -11,7 +11,7 @@ import { resolveSchemas } from './SchemaAdapter.js';
  */
 export function createMcpServer(config, db) {
   const server = new McpServer({
-    name: `${config.name}-mcp`,
+    name: `${config.appName}-mcp`,
     version: config.version,
   });
 
@@ -44,11 +44,11 @@ export function createMcpServer(config, db) {
  */
 export async function createMcpServerAuto(config, db) {
   const tables = await resolveSchemas(db, config.tables, {
-    cacheKey: config.name,
+    cacheKey: config.appName,
   });
 
   return createMcpServer({
-    name: config.name,
+    appName: config.appName,
     version: config.version || '1.0.0',
     tables,
   }, db);

package/src/transport/fastifyAdapter.js

@@ -11,6 +11,10 @@
  *     getDb: (appName, env) => getAppDbService(appName, env),
  *   });
  *
+ * Route param format:
+ *   /v1/mcp/paaal--dev   → appName: 'paaal', env: 'dev'
+ *   /v1/mcp/paaal        → appName: 'paaal', env: 'prod' (default)
+ *
  * Routes:
  *   POST   /v1/mcp/:appName        — MCP protocol endpoint
  *   DELETE /v1/mcp/:appName        — Session termination
@@ -24,35 +28,51 @@ import { createMcpServerAuto } from '../engine/McpEngine.js';
 
 const sessions = new Map();
 
+/**
+ * Parse route param: "paaal--dev" → { appName: "paaal", env: "dev" }
+ *                    "paaal"      → { appName: "paaal", env: "prod" }
+ */
+function parseAppParam(param) {
+  const parts = param.split('--');
+  return {
+    appName: parts[0],
+    env: parts[1] || 'prod',
+  };
+}
+
 /**
  * @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 }
+ *        — 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 {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');
+
+  // Build lookup: key = "appName--env" (or "appName--prod" for default)
+  const apps = new Map();
+  for (const config of Object.values(opts.apps || {})) {
+    const key = `${config.appName}--${config.env || 'prod'}`;
+    apps.set(key, config);
+  }
   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);
+    const { appName, env } = parseAppParam(req.params.appName);
+    const appConfig = apps.get(`${appName}--${env}`);
     if (!appConfig) {
-      return reply.code(404).send({ ok: false, error: `App '${appName}' not registered` });
+      return reply.code(404).send({ ok: false, error: `App '${appName}/${env}' not registered` });
     }
 
     const sessionId = req.headers['mcp-session-id'];
@@ -65,7 +85,12 @@ export default async function mcpPlugin(fastify, opts = {}) {
 
     // New session (must be initialize request)
     if (!sessionId && isInitializeRequest(req.body)) {
-      const db = await getDb(appName, appConfig.dbEnv || 'dev');
+      let db;
+      try {
+        db = await getDb(appName, env);
+      } catch (err) {
+        return reply.code(400).send({ ok: false, error: `No DB config for ${appName}/${env}` });
+      }
       const server = await createMcpServerAuto(appConfig, db);
 
       const transport = new StreamableHTTPServerTransport({
@@ -104,9 +129,9 @@ export default async function mcpPlugin(fastify, opts = {}) {
   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) };
+    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) };
   });
 }