icode-mcp-adapter 1.0.0 → 1.0.1

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.1",
   "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",