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:

{
  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

npm install icode-mcp-adapter @modelcontextprotocol/sdk zod

Usage in icode-server

// 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

// 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

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

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

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 for step-by-step setup, nginx config, Claude Desktop connection, and architecture details.