@mostajs/orm-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+@mostajs/orm-mcp
+
+Copyright (C) 2026 Dr Hamid MADANI <drmdh@msn.com>
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License along
+with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial / proprietary licensing of @mostajs/orm, contact drmdh@msn.com.

package/README.md

@@ -0,0 +1,66 @@
+# @mostajs/orm-mcp
+
+> MCP server for **[@mostajs/orm](https://www.npmjs.com/package/@mostajs/orm)** — lets AI dev tools (Claude, Cursor, Cline…) **generate `EntitySchema`s, lint them (24 rules), and produce SQL migrations** directly from a prompt.
+
+[![npm](https://img.shields.io/npm/v/@mostajs/orm-mcp.svg)](https://www.npmjs.com/package/@mostajs/orm-mcp)
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `mostajs_generate_schema` | Build a typed `EntitySchema` (TS) from an entity name + fields (+ relations). Runs the validator on the result. |
+| `mostajs_validate` | Lint one or more `EntitySchema`s with the built-in conceptual validator (24 rules). |
+| `mostajs_create_migration` | Diff two schema sets → SQL migration (`diffSchemas` + `generateMigrationSQL`). |
+
+All three reuse `@mostajs/orm`'s public API — no logic is reinvented.
+
+## Use it (hosted)
+
+A public instance runs at **`https://orm-mcp.amia.fr/mcp`** (Streamable HTTP). Add it to your MCP client:
+
+```jsonc
+{
+  "mcpServers": {
+    "mostajs-orm": { "url": "https://orm-mcp.amia.fr/mcp" }
+  }
+}
+```
+
+Clients that only speak stdio can bridge it:
+
+```bash
+npx mcp-remote https://orm-mcp.amia.fr/mcp
+```
+
+> Visiting `https://orm-mcp.amia.fr/mcp` in a browser returns a JSON-RPC `405` — that is expected (MCP is POST-only). The human-readable info page is the root `/`.
+
+## Run it (local, stdio)
+
+```bash
+npx @mostajs/orm-mcp        # stdio transport — the AI tool spawns this process
+```
+
+Local MCP config (Claude Desktop / Cursor / Cline):
+
+```jsonc
+{
+  "mcpServers": {
+    "mostajs-orm": { "command": "npx", "args": ["-y", "@mostajs/orm-mcp"] }
+  }
+}
+```
+
+In stdio mode, `mostajs_validate` also accepts a `sourceRoot` to enable cross-file rules (it reads the local filesystem — disabled on the hosted server for safety).
+
+## Run it (self-hosted HTTP)
+
+```bash
+PORT=14510 npx @mostajs/orm-mcp        # or: npx @mostajs/orm-mcp --http
+```
+
+Serves the MCP endpoint at `/mcp` (POST) and a health/info page at `/`.
+
+## License
+
+**AGPL-3.0-or-later** — © Dr Hamid MADANI. Commercial licensing for `@mostajs/orm`: drmdh@msn.com.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * @mostajs/orm-mcp — Model Context Protocol server exposing @mostajs/orm's
+ * schema tooling to AI dev tools (Claude, Cursor, Cline…).
+ *
+ * Tools:
+ *   - mostajs_generate_schema  : build an EntitySchema (TS) from name + fields
+ *   - mostajs_validate         : lint EntitySchemas with the 24-rule validator
+ *   - mostajs_create_migration : diff two schema sets → SQL migration
+ *
+ * All three REUSE @mostajs/orm's public API (validateSchemas, diffSchemas,
+ * generateMigrationSQL) — no logic is reinvented here.
+ *
+ * Transports:
+ *   - stdio (default)          : local use; the AI tool spawns this process.
+ *   - Streamable HTTP (--http  : remote/hosted (e.g. https://orm-mcp.amia.fr/mcp),
+ *     or PORT env set)           behind a reverse proxy.
+ *
+ * Security: the `sourceRoot` option of `mostajs_validate` reads the filesystem.
+ * It is ALLOWED in stdio mode (runs on the user's machine) but DISABLED in HTTP
+ * mode (a hosted server must not read arbitrary server paths).
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { z } from 'zod';
+import { diffSchemas, generateMigrationSQL } from '@mostajs/orm';
+import { validateSchemas } from '@mostajs/orm/validator';
+const VERSION = '0.1.0';
+const TOOL_NAMES = ['mostajs_generate_schema', 'mostajs_validate', 'mostajs_create_migration'];
+const FIELD_TYPES = ['string', 'text', 'number', 'boolean', 'date', 'json', 'array'];
+const RELATION_TYPES = ['one-to-one', 'one-to-many', 'many-to-one', 'many-to-many'];
+const ON_DELETE = ['cascade', 'set-null', 'restrict', 'no-action'];
+const fieldShape = z.object({
+    name: z.string(),
+    type: z.enum(FIELD_TYPES),
+    required: z.boolean().optional(),
+    unique: z.boolean().optional(),
+    default: z.any().optional(),
+});
+const relationShape = z.object({
+    name: z.string(),
+    target: z.string(),
+    type: z.enum(RELATION_TYPES),
+    required: z.boolean().optional(),
+    mappedBy: z.string().optional(),
+    onDelete: z.enum(ON_DELETE).optional(),
+});
+function buildSchema(input) {
+    const fields = {};
+    for (const f of input.fields) {
+        fields[f.name] = {
+            type: f.type,
+            ...(f.required ? { required: true } : {}),
+            ...(f.unique ? { unique: true } : {}),
+            ...(f.default !== undefined ? { default: f.default } : {}),
+        };
+    }
+    const relations = {};
+    for (const r of input.relations ?? []) {
+        relations[r.name] = {
+            target: r.target,
+            type: r.type,
+            ...(r.required ? { required: true } : {}),
+            ...(r.mappedBy ? { mappedBy: r.mappedBy } : {}),
+            ...(r.onDelete ? { onDelete: r.onDelete } : {}),
+        };
+    }
+    return {
+        name: input.name,
+        collection: input.collection ?? `${input.name.toLowerCase()}s`,
+        fields,
+        relations,
+        indexes: [],
+        timestamps: input.timestamps ?? true,
+        ...(input.softDelete ? { softDelete: true } : {}),
+    };
+}
+function toTypeScript(schema) {
+    return (`import type { EntitySchema } from '@mostajs/orm';\n\n` +
+        `export const ${schema.name}Schema: EntitySchema = ${JSON.stringify(schema, null, 2)};\n`);
+}
+/**
+ * Build a fresh McpServer with the three tools.
+ * @param allowFsAccess  if false, `mostajs_validate.sourceRoot` is ignored
+ *                       (hosted HTTP mode — never read the server's filesystem).
+ */
+function createServer(allowFsAccess) {
+    const server = new McpServer({ name: 'mostajs-orm', version: VERSION });
+    server.tool('mostajs_generate_schema', 'Generate a @mostajs/orm EntitySchema (TypeScript) from an entity name + fields (+ optional relations). Returns ready-to-paste TS and runs the 24-rule validator on the result.', {
+        name: z.string().describe('Entity name in PascalCase, e.g. "Post"'),
+        collection: z.string().optional().describe('Table/collection name; defaults to lowercased name + "s"'),
+        fields: z.array(fieldShape).describe('Field definitions'),
+        relations: z.array(relationShape).optional().describe('Relations to other entities'),
+        timestamps: z.boolean().optional().describe('Auto-manage createdAt/updatedAt (default true)'),
+        softDelete: z.boolean().optional().describe('Enable soft delete (deletedAt + auto-filter)'),
+    }, async (args) => {
+        const schema = buildSchema(args);
+        const report = await validateSchemas([schema]);
+        const ts = toTypeScript(schema);
+        const findings = report.findings.length
+            ? report.findings.map((f) => `- [${f.severity}] ${f.ruleId}: ${f.message}`).join('\n')
+            : '- none';
+        return {
+            content: [
+                { type: 'text', text: `${ts}\n/* Validator — ${report.findings.length} finding(s):\n${findings}\n*/` },
+            ],
+        };
+    });
+    server.tool('mostajs_validate', 'Lint one or more @mostajs/orm EntitySchemas with the built-in conceptual validator (24 rules). Pass schemas as JSON. (sourceRoot cross-file rules are only available in local/stdio mode.)', {
+        schemas: z.array(z.any()).describe('Array of EntitySchema objects (JSON)'),
+        sourceRoot: z.string().optional().describe('Project src root for cross-file rules — IGNORED on the hosted server'),
+    }, async ({ schemas, sourceRoot }) => {
+        const useRoot = allowFsAccess && sourceRoot ? { sourceRoot } : undefined;
+        const report = await validateSchemas(schemas, useRoot);
+        const note = !allowFsAccess && sourceRoot
+            ? '\n\n(note: sourceRoot was ignored — cross-file rules require the local stdio server)'
+            : '';
+        return { content: [{ type: 'text', text: JSON.stringify(report, null, 2) + note }] };
+    });
+    server.tool('mostajs_create_migration', 'Diff two sets of @mostajs/orm EntitySchemas and produce SQL migration statements (diffSchemas + generateMigrationSQL).', {
+        oldSchemas: z.array(z.any()).describe('Previous EntitySchema[] (JSON) — [] for a fresh database'),
+        newSchemas: z.array(z.any()).describe('Target EntitySchema[] (JSON)'),
+    }, async ({ oldSchemas, newSchemas }) => {
+        const ops = diffSchemas(oldSchemas, newSchemas);
+        const sql = generateMigrationSQL(ops);
+        return {
+            content: [{ type: 'text', text: sql.length ? sql.join('\n') : '-- no schema changes detected' }],
+        };
+    });
+    return server;
+}
+// --- stdio transport (local) ------------------------------------------------
+async function startStdio() {
+    const server = createServer(/* allowFsAccess */ true);
+    await server.connect(new StdioServerTransport());
+    // stdout is reserved for the protocol — log to stderr only.
+    console.error(`@mostajs/orm-mcp v${VERSION} on stdio (tools: ${TOOL_NAMES.join(', ')})`);
+}
+// --- Streamable HTTP transport (hosted, e.g. orm-mcp.amia.fr) ----------------
+async function startHttp(port) {
+    const { default: express } = await import('express');
+    const app = express();
+    app.use(express.json({ limit: '1mb' }));
+    // Minimal CORS (lets browser-based MCP clients connect).
+    app.use((req, res, next) => {
+        res.header('Access-Control-Allow-Origin', '*');
+        res.header('Access-Control-Allow-Headers', 'Content-Type, mcp-session-id, mcp-protocol-version');
+        res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+        if (req.method === 'OPTIONS') {
+            res.sendStatus(204);
+            return;
+        }
+        next();
+    });
+    // Human/health endpoint.
+    app.get('/', (_req, res) => {
+        res.json({
+            name: '@mostajs/orm-mcp',
+            version: VERSION,
+            transport: 'streamable-http',
+            endpoint: '/mcp',
+            tools: TOOL_NAMES,
+            docs: 'https://mostajs.dev',
+        });
+    });
+    // Stateless MCP endpoint: a fresh server + transport per request.
+    app.post('/mcp', async (req, res) => {
+        const server = createServer(/* allowFsAccess */ false);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on('close', () => {
+            transport.close();
+            server.close();
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch {
+            if (!res.headersSent) {
+                res.status(500).json({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal error' }, id: null });
+            }
+        }
+    });
+    // Stateless server: no server-initiated streams / sessions.
+    const notAllowed = (_req, res) => res.status(405).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Method not allowed (stateless server)' }, id: null });
+    app.get('/mcp', notAllowed);
+    app.delete('/mcp', notAllowed);
+    app.listen(port, () => {
+        console.error(`@mostajs/orm-mcp v${VERSION} on http://localhost:${port}/mcp (tools: ${TOOL_NAMES.join(', ')})`);
+    });
+}
+// --- Boot -------------------------------------------------------------------
+const httpMode = process.argv.includes('--http') || !!process.env.PORT;
+if (httpMode) {
+    await startHttp(Number(process.env.PORT) || 8930);
+}
+else {
+    await startStdio();
+}

package/llms.txt

@@ -0,0 +1,34 @@
+# @mostajs/orm-mcp — fiche LLM
+> Serveur MCP exposant le tooling schéma de @mostajs/orm aux IA de dev.
+
+- Version: 0.1.0 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
+- Instance hébergée: https://orm-mcp.amia.fr/mcp (Streamable HTTP). Health humain: https://orm-mcp.amia.fr/
+
+## RÔLE
+Donne aux IA (Claude, Cursor, Cline…) trois outils pour travailler avec @mostajs/orm
+sans relire son code. Réutilise l'API publique de l'ORM (validateSchemas, diffSchemas,
+generateMigrationSQL) — aucune logique réimplémentée.
+
+## OUTILS (MCP tools)
+- `mostajs_generate_schema(name, fields[], collection?, relations[]?, timestamps?, softDelete?)`
+  → EntitySchema TypeScript prêt à coller, déjà passé au validator (24 règles).
+  - field = { name, type: string|text|number|boolean|date|json|array, required?, unique?, default? }
+  - relation = { name, target, type: one-to-one|one-to-many|many-to-one|many-to-many, required?, mappedBy?, onDelete? }
+- `mostajs_validate(schemas[], sourceRoot?)`
+  → rapport { schemaCount, findings[], countBySeverity, countByRule, durationMs }.
+  `sourceRoot` (règles cross-file R005/R007/R008/R019…) actif UNIQUEMENT en mode stdio local ;
+  ignoré sur le serveur HTTP hébergé (sécurité : pas de lecture FS arbitraire).
+- `mostajs_create_migration(oldSchemas[], newSchemas[])`
+  → instructions SQL de migration (diffSchemas + generateMigrationSQL). oldSchemas=[] pour une base neuve.
+
+## TRANSPORTS
+- stdio (défaut) : `npx @mostajs/orm-mcp` — l'outil IA lance le process. FS autorisé (local).
+- Streamable HTTP : `--http` ou `PORT` env → endpoint POST `/mcp`, health `GET /`. FS désactivé.
+
+## CONNEXION CLIENT
+- HTTP hébergé : `{ "mcpServers": { "mostajs-orm": { "url": "https://orm-mcp.amia.fr/mcp" } } }`
+- stdio local : `{ "mcpServers": { "mostajs-orm": { "command": "npx", "args": ["-y","@mostajs/orm-mcp"] } } }`
+- pont stdio→HTTP : `npx mcp-remote https://orm-mcp.amia.fr/mcp`
+
+## DÉPENDANCES
+@modelcontextprotocol/sdk, @mostajs/orm (>=2.5.1), express, zod. Aucun secret, sans état.

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@mostajs/orm-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for @mostajs/orm — lets AI dev tools (Claude, Cursor, Cline) generate EntitySchemas, lint them (24 rules), and produce SQL migrations.",
+  "license": "AGPL-3.0-or-later",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "type": "module",
+  "bin": {
+    "mostajs-orm-mcp": "dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "llms.txt",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mostajs",
+    "orm",
+    "schema",
+    "migration",
+    "validator",
+    "ai-tools",
+    "code-generation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apolocine/mosta-orm-mcp.git"
+  },
+  "homepage": "https://mostajs.dev",
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@mostajs/orm": "^2.5.1",
+    "express": "^4.21.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/apolocine"
+  }
+}