mcpfoundry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcpfoundry contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# mcpfoundry
+
+> Forge production-ready **MCP (Model Context Protocol) servers** from your existing data — a database or an OpenAPI spec — in seconds.
+
+`mcpfoundry` is a zero-friction CLI that introspects a data source and scaffolds a
+clean, self-contained, runnable MCP server. Generated servers always ship with
+**parameter validation** (Zod / Pydantic). An **optional** zero-trust
+**ZTAI Security Shield** (JWT guard + deception canary) can be layered in with a
+single `--secure` flag — recommended, never forced.
+
+## Install
+
+```bash
+npm install -g mcpfoundry
+# or run ad-hoc:
+npx mcpfoundry create --help
+```
+
+## Usage
+
+### From an OpenAPI / Swagger spec
+
+Every endpoint becomes a typed MCP tool:
+
+```bash
+mcpfoundry create \
+  --type openapi \
+  --input ./openapi.json \
+  --output ./my-mcp-server \
+  --lang nodejs
+```
+
+### From a database
+
+Tables are introspected and turned into CRUD tools:
+
+```bash
+mcpfoundry create \
+  --type database \
+  --provider postgres \
+  --uri "postgresql://user:pass@localhost:5432/mydb" \
+  --output ./my-mcp-server \
+  --lang python
+```
+
+> Postgres is fully supported today. MySQL and MongoDB are stubbed and open for
+> [contributions](./CONTRIBUTING.md).
+
+### Flags
+
+| Flag | Description |
+| --- | --- |
+| `--type` | `database` or `openapi` (required) |
+| `--provider` | `postgres` \| `mysql` \| `mongodb` (database mode) |
+| `--uri` | DB connection string (database mode) |
+| `--input` | Path to an OpenAPI spec, JSON or YAML (openapi mode) |
+| `--output` | Output directory (required) |
+| `--lang` | `nodejs` (default) or `python` |
+| `--secure` | Embed the optional ZTAI Security Shield |
+| `--force` | Overwrite a non-empty output directory |
+| `--dry-run` | Preview the tools that would be generated, then exit (no files written) |
+
+`--input` accepts a local path **or a URL**, in JSON or YAML.
+
+### Preview before generating
+
+```bash
+mcpfoundry create --type openapi --input ./openapi.yaml --dry-run
+```
+
+```
+✔ Dry run — 4 tool(s) would be generated:
+  • list_pets(limit?: integer)
+  • create_pet(name: string, tag?: string)
+  • get_pet_by_id(pet_id: integer)
+  • delete_pet(pet_id: integer)
+```
+
+## The optional ZTAI Security Shield (`--secure`)
+
+When you pass `--secure`, every generated server additionally enforces:
+
+1. **JWT Guard** — verifies a short-lived HS256 token (`ZTAI_AUTH_TOKEN` over
+   stdio, or `Authorization: Bearer` over SSE) against `JWT_SECRET`. Invalid or
+   missing tokens drop the connection before any tool runs.
+2. **Parameter hardening** — strict Zod/Pydantic schemas (this is on even
+   *without* `--secure`, because it's just good hygiene).
+3. **Deception Canary** — when `ZTAI_CANARY_ID` is set, tool output carries a
+   subtle, traceable marker to help detect adversarial exfiltration.
+
+Without `--secure` you still get a perfectly good, vendor-neutral MCP server.
+
+## Architecture — the Template-Compiler pattern
+
+```
+src/
+  cli.ts          # arg parsing + orchestration
+  parsers/        # data source -> normalized IR (ToolSpec[])
+  compiler.ts     # IR + Handlebars templates -> generated project
+  types.ts        # the shared IR
+templates/
+  nodejs/         # @modelcontextprotocol/sdk + Zod
+  python/         # FastMCP + Pydantic
+```
+
+Parsers and templates are decoupled by a normalized intermediate representation,
+so **adding a new language is just a new `templates/<lang>/` folder** — no engine
+changes. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Develop
+
+```bash
+npm install
+npm run build
+node dist/cli.js create --type openapi --input examples/petstore.openapi.json --output /tmp/petstore-mcp
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const commander_1 = require("commander");
+const database_1 = require("./parsers/database");
+const openapi_1 = require("./parsers/openapi");
+const compiler_1 = require("./compiler");
+const logger_1 = require("./utils/logger");
+const program = new commander_1.Command();
+program
+    .name("mcpfoundry")
+    .description("Forge production-ready MCP servers from databases or OpenAPI specs.")
+    .version("0.1.0")
+    .showHelpAfterError("(add --help for usage)");
+program
+    .command("create")
+    .description("Generate an MCP server from a data source.")
+    .requiredOption("--type <type>", "source type: database | openapi")
+    .option("--provider <provider>", "database provider: postgres | mysql | mongodb")
+    .option("--uri <uri>", "database connection string (for --type database)")
+    .option("--input <path>", "OpenAPI/Swagger spec — file path OR URL, JSON or YAML")
+    .option("--output <dir>", "output directory for the generated server")
+    .option("--lang <lang>", "target language: nodejs | python", "nodejs")
+    .option("--secure", "embed the optional ZTAI Security Shield (JWT guard + deception canary)", false)
+    .option("--force", "overwrite a non-empty output directory", false)
+    .option("--dry-run", "preview the tools that would be generated, then exit", false)
+    .addHelpText("after", `
+Examples:
+  $ mcpfoundry create --type openapi --input ./openapi.yaml --output ./my-server
+  $ mcpfoundry create --type openapi --input https://petstore3.swagger.io/api/v3/openapi.json --output ./petstore
+  $ mcpfoundry create --type database --provider postgres --uri "$DATABASE_URL" --output ./db-server --lang python
+  $ mcpfoundry create --type openapi --input ./api.json --output ./secure-server --secure
+  $ mcpfoundry create --type openapi --input ./api.json --output /tmp/x --dry-run
+`)
+    .action(async (opts) => {
+    try {
+        await run(opts);
+    }
+    catch (err) {
+        logger_1.logger.error(err.message);
+        process.exit(1);
+    }
+});
+async function run(opts) {
+    const lang = opts.lang;
+    if (lang !== "nodejs" && lang !== "python") {
+        throw new Error(`Unsupported --lang "${opts.lang}". Use nodejs or python.`);
+    }
+    if (!opts.dryRun && !opts.output) {
+        throw new Error("--output is required (or use --dry-run to preview).");
+    }
+    let tools;
+    let sourceType;
+    if (opts.type === "database") {
+        if (!opts.provider)
+            throw new Error("--provider is required for --type database.");
+        if (!opts.uri)
+            throw new Error("--uri is required for --type database.");
+        sourceType = "database";
+        logger_1.logger.info(`Introspecting ${opts.provider} database…`);
+        tools = await (0, database_1.introspectDatabase)(opts.provider, opts.uri);
+    }
+    else if (opts.type === "openapi") {
+        if (!opts.input)
+            throw new Error("--input is required for --type openapi.");
+        sourceType = "openapi";
+        logger_1.logger.info(`Parsing OpenAPI spec at ${opts.input}…`);
+        tools = await (0, openapi_1.parseOpenApi)(opts.input);
+    }
+    else {
+        throw new Error(`Unsupported --type "${opts.type ?? ""}". Use database or openapi.`);
+    }
+    if (tools.length === 0) {
+        throw new Error("No tools were generated from the source — nothing to scaffold.");
+    }
+    // Required params first: Python disallows a non-default arg after a defaulted
+    // one, and it reads better everywhere else too. Stable within each group.
+    for (const tool of tools) {
+        tool.params = [
+            ...tool.params.filter((p) => p.required),
+            ...tool.params.filter((p) => !p.required),
+        ];
+    }
+    if (opts.dryRun) {
+        printDryRun(tools);
+        return;
+    }
+    const outputDir = node_path_1.default.resolve(opts.output);
+    const projectName = node_path_1.default.basename(outputDir);
+    const context = {
+        projectName,
+        tools,
+        lang,
+        sourceType,
+        secure: Boolean(opts.secure),
+        isDatabase: sourceType === "database",
+    };
+    logger_1.logger.info(`Compiling ${tools.length} tool(s) into a ${lang} MCP server…`);
+    await (0, compiler_1.compile)(context, outputDir, Boolean(opts.force));
+    printSummary(context, outputDir);
+}
+function printDryRun(tools) {
+    logger_1.logger.plain();
+    logger_1.logger.success(`Dry run — ${tools.length} tool(s) would be generated:`);
+    logger_1.logger.plain();
+    for (const t of tools) {
+        const params = t.params
+            .map((p) => `${p.name}${p.required ? "" : "?"}: ${p.type}`)
+            .join(", ");
+        logger_1.logger.plain(`  • ${logger_1.logger.bold(t.name)}(${params})`);
+        logger_1.logger.plain(`      ${logger_1.logger.dim(t.description)}`);
+    }
+    logger_1.logger.plain();
+    logger_1.logger.plain(logger_1.logger.dim("No files written. Drop --dry-run to generate."));
+}
+function printSummary(ctx, outputDir) {
+    logger_1.logger.plain();
+    logger_1.logger.success(`Forged ${logger_1.logger.bold(ctx.projectName)} — ${ctx.tools.length} MCP tool(s), ${ctx.lang}${ctx.secure ? ", ZTAI Security Shield enabled" : ""}.`);
+    logger_1.logger.plain(`  ${logger_1.logger.dim(outputDir)}`);
+    logger_1.logger.plain();
+    logger_1.logger.plain("Next steps:");
+    if (ctx.lang === "nodejs") {
+        logger_1.logger.plain(`  cd ${outputDir}`);
+        logger_1.logger.plain("  npm install");
+        logger_1.logger.plain("  npm run build && npm start");
+    }
+    else {
+        logger_1.logger.plain(`  cd ${outputDir}`);
+        logger_1.logger.plain("  pip install -e .");
+        logger_1.logger.plain("  python server.py");
+    }
+    if (!ctx.secure) {
+        logger_1.logger.plain();
+        logger_1.logger.warn("Generated a standard MCP server. For zero-trust auth + a deception canary, re-run with --secure, or front it with the ZTAI firewall.");
+    }
+}
+program.parseAsync(process.argv);

package/dist/compiler.js

@@ -0,0 +1,125 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compile = compile;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const handlebars_1 = __importDefault(require("handlebars"));
+const naming_1 = require("./utils/naming");
+/** Templates ship alongside the compiled engine: dist/compiler.js -> ../templates. */
+const TEMPLATES_ROOT = node_path_1.default.join(__dirname, "..", "templates");
+let helpersRegistered = false;
+function registerHelpers() {
+    if (helpersRegistered)
+        return;
+    // Emit a JSON-encoded literal (safe string keys, escaped values).
+    handlebars_1.default.registerHelper("json", (value) => new handlebars_1.default.SafeString(JSON.stringify(value ?? null)));
+    handlebars_1.default.registerHelper("pascalCase", (s) => (0, naming_1.pascalCase)(String(s ?? "")));
+    handlebars_1.default.registerHelper("camelCase", (s) => (0, naming_1.camelCase)(String(s ?? "")));
+    handlebars_1.default.registerHelper("eq", (a, b) => a === b);
+    // Language-specific type mappers used inside the templates.
+    handlebars_1.default.registerHelper("zodType", (p) => new handlebars_1.default.SafeString(zodType(p)));
+    handlebars_1.default.registerHelper("pydanticType", (p) => new handlebars_1.default.SafeString(pydanticType(p)));
+    // Full Python function parameter, e.g.
+    //   name: Annotated[str, Field(description="...")]
+    //   tag: str | None = None
+    handlebars_1.default.registerHelper("pyParam", (p) => new handlebars_1.default.SafeString(pyParam(p)));
+    // Python dict literal of the call args, e.g. {"name": name, "tag": tag}.
+    handlebars_1.default.registerHelper("pyArgsDict", (params) => {
+        const entries = (params ?? [])
+            .map((p) => `${JSON.stringify(p.name)}: ${p.name}`)
+            .join(", ");
+        return new handlebars_1.default.SafeString(`{${entries}}`);
+    });
+    helpersRegistered = true;
+}
+/** Map an IR ParamSpec to a Zod expression for Node.js parameter hardening. */
+function zodType(p) {
+    const base = {
+        string: "z.string()",
+        number: "z.number()",
+        integer: "z.number().int()",
+        boolean: "z.boolean()",
+        object: "z.record(z.any())",
+        array: "z.array(z.any())",
+    };
+    let expr = base[p.type] ?? "z.any()";
+    if (p.description)
+        expr += `.describe(${JSON.stringify(p.description)})`;
+    if (!p.required)
+        expr += ".optional()";
+    return expr;
+}
+/** Map an IR ParamSpec to a Python type annotation for Pydantic hardening. */
+function pydanticType(p) {
+    const base = {
+        string: "str",
+        number: "float",
+        integer: "int",
+        boolean: "bool",
+        object: "dict[str, Any]",
+        array: "list[Any]",
+    };
+    const t = base[p.type] ?? "Any";
+    return p.required ? t : `${t} | None`;
+}
+/** Render a full Python function parameter (type + optional Field + default). */
+function pyParam(p) {
+    const type = pydanticType(p);
+    const annotated = p.description
+        ? `Annotated[${type}, Field(description=${JSON.stringify(p.description)})]`
+        : type;
+    return p.required ? `${p.name}: ${annotated}` : `${p.name}: ${annotated} = None`;
+}
+function walk(dir) {
+    const out = [];
+    for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+        const full = node_path_1.default.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...walk(full));
+        else
+            out.push(full);
+    }
+    return out;
+}
+/**
+ * Render the selected language template against the compile context and write
+ * the result to the output directory. The engine is fully data-driven: adding a
+ * new language means adding a `templates/<lang>/` folder, no engine changes.
+ */
+async function compile(ctx, outputDir, force) {
+    registerHelpers();
+    const templateDir = node_path_1.default.join(TEMPLATES_ROOT, ctx.lang);
+    if (!node_fs_1.default.existsSync(templateDir)) {
+        throw new Error(`No templates found for lang "${ctx.lang}" (looked in ${templateDir}).`);
+    }
+    if (node_fs_1.default.existsSync(outputDir) &&
+        node_fs_1.default.readdirSync(outputDir).length > 0 &&
+        !force) {
+        throw new Error(`Output directory ${outputDir} is not empty. Re-run with --force to overwrite.`);
+    }
+    node_fs_1.default.mkdirSync(outputDir, { recursive: true });
+    for (const abs of walk(templateDir)) {
+        const rel = node_path_1.default.relative(templateDir, abs);
+        const isTemplate = rel.endsWith(".hbs");
+        const outRel = isTemplate ? rel.slice(0, -".hbs".length) : rel;
+        // Dotfile convention: npm strips files literally named `.gitignore` from
+        // published packages, so they are stored as `_gitignore` and the leading
+        // underscore is restored to a dot on output.
+        const dir = node_path_1.default.dirname(outRel);
+        const base = node_path_1.default.basename(outRel).replace(/^_/, ".");
+        const outPath = node_path_1.default.join(outputDir, dir, base);
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(outPath), { recursive: true });
+        const raw = node_fs_1.default.readFileSync(abs, "utf8");
+        const content = isTemplate
+            ? handlebars_1.default.compile(raw, { noEscape: true })(ctx)
+            : raw;
+        // A template that renders to nothing (e.g. a fully `{{#if secure}}`-gated
+        // file in a non-secure build) is intentionally omitted from the output.
+        if (isTemplate && content.trim() === "")
+            continue;
+        node_fs_1.default.writeFileSync(outPath, content);
+    }
+}

package/dist/parsers/database.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.introspectDatabase = introspectDatabase;
+const pg_1 = require("pg");
+const naming_1 = require("../utils/naming");
+const NOT_IMPLEMENTED = "introspection is not yet implemented — contributions welcome! See CONTRIBUTING.md to add a provider.";
+/**
+ * Connect to a database, introspect its schema, and emit CRUD MCP tools.
+ * Only Postgres is implemented today; MySQL/MongoDB are intentionally stubbed
+ * with a friendly pointer so the community can extend them.
+ */
+async function introspectDatabase(provider, uri) {
+    switch (provider) {
+        case "postgres":
+            return introspectPostgres(uri);
+        case "mysql":
+            throw new Error(`MySQL ${NOT_IMPLEMENTED}`);
+        case "mongodb":
+            throw new Error(`MongoDB ${NOT_IMPLEMENTED}`);
+        default:
+            throw new Error(`Unknown provider "${provider}". Supported: postgres (mysql, mongodb coming soon).`);
+    }
+}
+async function introspectPostgres(uri) {
+    const client = new pg_1.Client({ connectionString: uri });
+    try {
+        await client.connect();
+    }
+    catch (err) {
+        throw new Error(`Could not connect to Postgres (${err.message}). ` +
+            `Check the --uri host/port/credentials and that the database is reachable.`);
+    }
+    try {
+        const columnsRes = await client.query(`SELECT table_name, column_name, data_type, is_nullable
+         FROM information_schema.columns
+        WHERE table_schema = 'public'
+        ORDER BY table_name, ordinal_position`);
+        const pkRes = await client.query(`SELECT kcu.table_name, kcu.column_name
+         FROM information_schema.table_constraints tc
+         JOIN information_schema.key_column_usage kcu
+           ON tc.constraint_name = kcu.constraint_name
+          AND tc.table_schema = kcu.table_schema
+        WHERE tc.constraint_type = 'PRIMARY KEY'
+          AND tc.table_schema = 'public'`);
+        const primaryKeys = new Map();
+        for (const row of pkRes.rows) {
+            if (!primaryKeys.has(row.table_name)) {
+                primaryKeys.set(row.table_name, new Set());
+            }
+            primaryKeys.get(row.table_name).add(row.column_name);
+        }
+        const tables = new Map();
+        for (const row of columnsRes.rows) {
+            const pk = primaryKeys.get(row.table_name);
+            const col = {
+                name: (0, naming_1.sanitizeIdentifier)(row.column_name),
+                type: mapPgType(row.data_type),
+                nullable: row.is_nullable === "YES",
+                isPrimaryKey: pk?.has(row.column_name) ?? false,
+            };
+            if (!tables.has(row.table_name))
+                tables.set(row.table_name, []);
+            tables.get(row.table_name).push(col);
+        }
+        const tools = [];
+        for (const [table, columns] of tables) {
+            tools.push(...buildCrudTools(table, columns));
+        }
+        return tools;
+    }
+    finally {
+        await client.end();
+    }
+}
+function buildCrudTools(table, columns) {
+    const safeTable = (0, naming_1.sanitizeIdentifier)(table);
+    const keyCols = columns.filter((c) => c.isPrimaryKey);
+    const nonKeyCols = columns.filter((c) => !c.isPrimaryKey);
+    const keyParams = keyCols.map((c) => ({
+        name: c.name,
+        type: c.type,
+        required: true,
+        description: (0, naming_1.cleanDescription)(`Primary key (${c.name}) of ${table}`),
+    }));
+    const tools = [];
+    // list_<table>: always available.
+    tools.push({
+        name: `list_${safeTable}`,
+        description: `List rows from the ${table} table.`,
+        params: [
+            { name: "limit", type: "integer", required: false, description: "Max rows to return." },
+            { name: "offset", type: "integer", required: false, description: "Rows to skip." },
+        ],
+        source: "database",
+        operation: "list",
+        table,
+    });
+    // create_<table>: always available.
+    tools.push({
+        name: `create_${safeTable}`,
+        description: `Insert a new row into the ${table} table.`,
+        params: nonKeyCols.map((c) => ({
+            name: c.name,
+            type: c.type,
+            required: !c.nullable,
+        })),
+        source: "database",
+        operation: "create",
+        table,
+    });
+    // get/update/delete need a primary key to address a single row.
+    if (keyCols.length > 0) {
+        tools.push({
+            name: `get_${safeTable}`,
+            description: `Fetch a single ${table} row by primary key.`,
+            params: keyParams,
+            source: "database",
+            operation: "get",
+            table,
+        });
+        tools.push({
+            name: `update_${safeTable}`,
+            description: `Update a ${table} row by primary key.`,
+            params: [
+                ...keyParams,
+                ...nonKeyCols.map((c) => ({
+                    name: c.name,
+                    type: c.type,
+                    required: false,
+                })),
+            ],
+            source: "database",
+            operation: "update",
+            table,
+        });
+        tools.push({
+            name: `delete_${safeTable}`,
+            description: `Delete a ${table} row by primary key.`,
+            params: keyParams,
+            source: "database",
+            operation: "delete",
+            table,
+        });
+    }
+    return tools;
+}
+function mapPgType(dataType) {
+    const t = dataType.toLowerCase();
+    if (/(int|serial|bigint|smallint)/.test(t))
+        return "integer";
+    if (/(numeric|decimal|real|double)/.test(t))
+        return "number";
+    if (t === "boolean")
+        return "boolean";
+    if (/json/.test(t))
+        return "object";
+    if (t.includes("array"))
+        return "array";
+    return "string";
+}

package/dist/parsers/openapi.js

@@ -0,0 +1,83 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOpenApi = parseOpenApi;
+const swagger_parser_1 = __importDefault(require("@apidevtools/swagger-parser"));
+const naming_1 = require("../utils/naming");
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete"];
+/**
+ * Ingest an OpenAPI / Swagger document (JSON or YAML; SwaggerParser handles
+ * both, plus $ref dereferencing) and map every operation to one MCP tool.
+ */
+async function parseOpenApi(input) {
+    // dereference resolves all $ref pointers so we can read schemas inline.
+    let api;
+    try {
+        api = await swagger_parser_1.default.dereference(input);
+    }
+    catch (err) {
+        throw new Error(`Could not read OpenAPI spec "${input}" (${err.message}). ` +
+            `Check the path/URL is reachable and the document is valid JSON or YAML.`);
+    }
+    const paths = api.paths ?? {};
+    const tools = [];
+    for (const [routePath, pathItem] of Object.entries(paths)) {
+        for (const method of HTTP_METHODS) {
+            const op = pathItem?.[method];
+            if (!op)
+                continue;
+            const name = (0, naming_1.sanitizeIdentifier)(op.operationId || `${method}_${routePath}`);
+            const params = [];
+            // Path / query / header / cookie parameters.
+            for (const prm of op.parameters ?? []) {
+                params.push({
+                    name: (0, naming_1.sanitizeIdentifier)(prm.name),
+                    type: jsonSchemaType(prm.schema?.type),
+                    required: Boolean(prm.required),
+                    description: (0, naming_1.cleanDescription)(prm.description),
+                });
+            }
+            // JSON request body properties.
+            const bodySchema = op.requestBody?.content?.["application/json"]?.schema ?? undefined;
+            if (bodySchema?.properties) {
+                const required = new Set(bodySchema.required ?? []);
+                for (const [propName, propSchema] of Object.entries(bodySchema.properties)) {
+                    params.push({
+                        name: (0, naming_1.sanitizeIdentifier)(propName),
+                        type: jsonSchemaType(propSchema?.type),
+                        required: required.has(propName),
+                        description: (0, naming_1.cleanDescription)(propSchema?.description),
+                    });
+                }
+            }
+            tools.push({
+                name,
+                description: (0, naming_1.cleanDescription)(op.summary || op.description) ||
+                    `${method.toUpperCase()} ${routePath}`,
+                params: (0, naming_1.dedupeByName)(params),
+                source: "openapi",
+                method: method.toUpperCase(),
+                path: routePath,
+            });
+        }
+    }
+    return tools;
+}
+function jsonSchemaType(type) {
+    switch (type) {
+        case "integer":
+            return "integer";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "array":
+            return "array";
+        case "object":
+            return "object";
+        default:
+            return "string";
+    }
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Shared intermediate representation (IR) that every parser emits and the
+ * compiler engine consumes. Keeping a normalized IR is what lets the
+ * Template-Compiler pattern stay language-agnostic: parsers know nothing about
+ * the target language, and templates know nothing about the source.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/logger.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+/**
+ * Minimal colored terminal logger. Everything goes to stderr so that stdout
+ * stays clean for potential machine consumption / piping.
+ */
+const c = {
+    reset: "\x1b[0m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+    gray: "\x1b[90m",
+    bold: "\x1b[1m",
+};
+exports.logger = {
+    info: (msg) => console.error(`${c.cyan}›${c.reset} ${msg}`),
+    success: (msg) => console.error(`${c.green}✔${c.reset} ${msg}`),
+    warn: (msg) => console.error(`${c.yellow}⚠${c.reset} ${msg}`),
+    error: (msg) => console.error(`${c.red}✖${c.reset} ${msg}`),
+    plain: (msg = "") => console.error(msg),
+    bold: (msg) => `${c.bold}${msg}${c.reset}`,
+    dim: (msg) => `${c.gray}${msg}${c.reset}`,
+};

package/dist/utils/naming.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Identifier sanitization helpers. Source names (table names, OpenAPI paths,
+ * operationIds, column names) cannot be trusted to be valid identifiers in the
+ * target language, so everything is normalized before it reaches a template.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeIdentifier = sanitizeIdentifier;
+exports.pascalCase = pascalCase;
+exports.camelCase = camelCase;
+exports.cleanDescription = cleanDescription;
+exports.dedupeByName = dedupeByName;
+/**
+ * Convert any source name into a clean, language-safe `snake_case` identifier.
+ * camelCase and ACRONYMBoundaries are split so `getPetById` -> `get_pet_by_id`
+ * (conventional MCP tool naming) rather than the ugly `getpetbyid`.
+ */
+function sanitizeIdentifier(raw) {
+    let s = String(raw)
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2") // camelCase boundary
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2") // ACRONYMWord boundary
+        .replace(/[^A-Za-z0-9]+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .toLowerCase();
+    if (!s)
+        s = "tool";
+    if (/^[0-9]/.test(s))
+        s = `_${s}`;
+    return s;
+}
+function pascalCase(raw) {
+    const parts = sanitizeIdentifier(raw).split("_").filter(Boolean);
+    const out = parts.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("");
+    return out || "Tool";
+}
+function camelCase(raw) {
+    const p = pascalCase(raw);
+    return p.charAt(0).toLowerCase() + p.slice(1);
+}
+/** Collapse whitespace so descriptions are safe as inline comments/docstrings. */
+function cleanDescription(raw) {
+    if (!raw)
+        return "";
+    return String(raw).replace(/\s+/g, " ").trim();
+}
+/** Drop duplicate params (same sanitized name) which would break codegen. */
+function dedupeByName(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        if (seen.has(item.name))
+            continue;
+        seen.add(item.name);
+        out.push(item);
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "mcpfoundry",
+  "version": "0.1.0",
+  "description": "Forge production-ready MCP (Model Context Protocol) servers from databases or OpenAPI specs, with an optional ZTAI zero-trust security shield.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "scaffold",
+    "generator",
+    "openapi",
+    "postgres",
+    "ai",
+    "security"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "mcpfoundry": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^10.1.0",
+    "commander": "^12.1.0",
+    "handlebars": "^4.7.8",
+    "pg": "^8.11.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.9.0",
+    "@types/node": "^20.14.0",
+    "@types/pg": "^8.11.6",
+    "eslint": "^9.9.0",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FidarOrg/mcpfoundry.git"
+  },
+  "bugs": {
+    "url": "https://github.com/FidarOrg/mcpfoundry/issues"
+  },
+  "homepage": "https://github.com/FidarOrg/mcpfoundry#readme"
+}

package/templates/nodejs/.env.example.hbs

@@ -0,0 +1,14 @@
+# Environment for {{projectName}} (generated by mcpfoundry)
+{{#if isDatabase}}
+# Connection string used by the generated tool handlers.
+DATABASE_URL=
+{{/if}}
+{{#if secure}}
+# --- ZTAI Security Shield ---
+# Shared HMAC secret used to verify the ZTAI auth token (HS256). Change in prod.
+JWT_SECRET=dev-secret-key-change-in-production-12345
+# Short-lived JWT presented over stdio. Invalid/missing => server refuses to start.
+ZTAI_AUTH_TOKEN=
+# Optional deception canary. When set, tool output carries a traceable marker.
+ZTAI_CANARY_ID=
+{{/if}}

package/templates/nodejs/README.md.hbs

@@ -0,0 +1,56 @@
+# {{projectName}}
+
+An MCP (Model Context Protocol) server generated by [mcpfoundry](https://www.npmjs.com/package/mcpfoundry) from a **{{sourceType}}** source.
+
+It exposes **{{tools.length}} tool(s)** over stdio.
+
+## Quick start
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+For development with auto-reload:
+
+```bash
+npm run dev
+```
+
+## Tools
+
+{{#each tools}}
+- `{{this.name}}` — {{this.description}}
+{{/each}}
+
+Each tool validates its parameters with [Zod](https://zod.dev) before any handler
+logic runs. The handlers currently contain `TODO` stubs — wire them to your real
+data source.
+
+{{#if secure}}
+## ZTAI Security Shield (enabled)
+
+This server was generated with `--secure`, so it enforces:
+
+1. **JWT Guard** — on startup it verifies a short-lived HS256 token from
+   `ZTAI_AUTH_TOKEN` against `JWT_SECRET`. A missing/invalid token aborts boot.
+2. **Parameter hardening** — Zod schemas reject malformed input.
+3. **Deception canary** — set `ZTAI_CANARY_ID` to append a traceable marker to
+   tool output (see `src/security.ts`).
+
+Copy `.env.example` to `.env` and fill in the values:
+
+```bash
+cp .env.example .env
+```
+{{else}}
+## Security
+
+This is a standard MCP server. For zero-trust auth (JWT guard) and a deception
+canary, regenerate with `mcpfoundry ... --secure`, or place it behind the ZTAI
+firewall.
+{{/if}}
+
+---
+Generated by mcpfoundry.

package/templates/nodejs/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env
+*.log
+.DS_Store

package/templates/nodejs/package.json.hbs

@@ -0,0 +1,28 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "MCP server generated by mcpfoundry.",
+  "type": "module",
+  "bin": {
+    "{{projectName}}": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.4.0",
+    "zod": "^3.23.8"{{#if secure}},
+    "jsonwebtoken": "^9.0.2"{{/if}}{{#if isDatabase}},
+    "pg": "^8.11.5"{{/if}}
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "tsx": "^4.16.0",
+    "@types/node": "^20.14.0"{{#if secure}},
+    "@types/jsonwebtoken": "^9.0.6"{{/if}}{{#if isDatabase}},
+    "@types/pg": "^8.11.6"{{/if}}
+  }
+}

package/templates/nodejs/src/index.ts.hbs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { tools } from "./tools.js";
+{{#if secure}}import { verifyStartupToken } from "./security.js";
+{{/if}}
+async function main(): Promise<void> {
+{{#if secure}}
+  // ZTAI Security Shield: verify the short-lived auth token before serving tools.
+  verifyStartupToken();
+{{/if}}
+  const server = new McpServer({ name: {{json projectName}}, version: "0.1.0" });
+
+  for (const tool of tools) {
+    server.tool(tool.name, tool.description, tool.schema, tool.handler);
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(
+    `[{{projectName}}] MCP server running over stdio with ${tools.length} tool(s).`,
+  );
+}
+
+main().catch((err) => {
+  console.error("Fatal error starting MCP server:", err);
+  process.exit(1);
+});

package/templates/nodejs/src/security.ts.hbs

@@ -0,0 +1,66 @@
+{{#if secure}}
+/**
+ * ZTAI Security Shield (opt-in, generated by mcpfoundry --secure).
+ *
+ * Three mechanisms, mirroring the ZTAI firewall's conventions:
+ *   1. JWT Guard           — verify a short-lived HS256 token before serving.
+ *   2. (Parameter hardening lives in tools.ts via Zod — always on.)
+ *   3. Deception Canary    — append a traceable marker to tool output.
+ */
+import crypto from "node:crypto";
+import jwt from "jsonwebtoken";
+
+export interface ZtaiTokenPayload {
+  agentId?: string;
+  orgId?: string;
+  iat?: number;
+  exp?: number;
+}
+
+/**
+ * stdio transport: there are no per-request headers, so the short-lived token
+ * is read from ZTAI_AUTH_TOKEN and verified once at startup. A missing/invalid
+ * token throws, which drops the connection before any tool can be reached.
+ */
+export function verifyStartupToken(): ZtaiTokenPayload {
+  const secret = process.env.JWT_SECRET;
+  const token = process.env.ZTAI_AUTH_TOKEN;
+  if (!secret) {
+    throw new Error("ZTAI Shield: JWT_SECRET is not set. Refusing to start.");
+  }
+  if (!token) {
+    throw new Error("ZTAI Shield: ZTAI_AUTH_TOKEN is missing. Refusing to start.");
+  }
+  try {
+    return jwt.verify(token, secret, { algorithms: ["HS256"] }) as ZtaiTokenPayload;
+  } catch (err) {
+    throw new Error(
+      `ZTAI Shield: invalid ZTAI_AUTH_TOKEN (${(err as Error).message}). Connection dropped.`,
+    );
+  }
+}
+
+/**
+ * SSE/HTTP transport: verify a Bearer token from the Authorization header.
+ * Wire this into your HTTP layer if you swap StdioServerTransport for SSE.
+ */
+export function verifyAuthHeader(authorization?: string): ZtaiTokenPayload {
+  const secret = process.env.JWT_SECRET;
+  if (!secret) throw new Error("ZTAI Shield: JWT_SECRET is not set.");
+  const match = /^Bearer\s+(.+)$/i.exec(authorization ?? "");
+  if (!match) throw new Error("ZTAI Shield: missing Bearer token.");
+  return jwt.verify(match[1], secret, { algorithms: ["HS256"] }) as ZtaiTokenPayload;
+}
+
+/**
+ * Deception Canary Anchor. When ZTAI_CANARY_ID is set, append a subtle,
+ * deterministic marker derived from it so adversarial exfiltration of tool
+ * output can be traced downstream. No-op when the env var is unset.
+ */
+export function applyCanary(text: string): string {
+  const canaryId = process.env.ZTAI_CANARY_ID;
+  if (!canaryId) return text;
+  const seed = crypto.createHash("sha256").update(canaryId).digest("hex").slice(0, 16);
+  return `${text}\n<!-- ztai-canary-${seed} -->`;
+}
+{{/if}}

package/templates/nodejs/src/tools.ts.hbs

@@ -0,0 +1,34 @@
+import { z } from "zod";
+{{#if secure}}import { applyCanary } from "./security.js";
+{{/if}}
+/**
+ * Tools generated by mcpfoundry from a {{sourceType}} source.
+ * Each tool ships a Zod schema (parameter hardening, always on) and a handler
+ * stub — fill in the TODO with your real query / request logic.
+ */
+export interface ForgeTool {
+  name: string;
+  description: string;
+  schema: Record<string, z.ZodTypeAny>;
+  handler: (args: any) => Promise<{ content: { type: "text"; text: string }[] }>;
+}
+
+export const tools: ForgeTool[] = [
+{{#each tools}}
+  {
+    name: {{json this.name}},
+    description: {{json this.description}},
+    schema: {
+{{#each this.params}}
+      {{this.name}}: {{{zodType this}}},
+{{/each}}
+    },
+    handler: async (args) => {
+      // TODO: implement {{#if this.operation}}{{this.operation}} on "{{this.table}}"{{else}}{{this.method}} {{this.path}}{{/if}}.
+      const result = { tool: {{json this.name}}, args };
+      const text = JSON.stringify(result, null, 2);
+      return { content: [{ type: "text", text: {{#if ../secure}}applyCanary(text){{else}}text{{/if}} }] };
+    },
+  },
+{{/each}}
+];

package/templates/nodejs/tsconfig.json.hbs

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": false
+  },
+  "include": ["src/**/*"]
+}

package/templates/python/.env.example.hbs

@@ -0,0 +1,14 @@
+# Environment for {{projectName}} (generated by mcpfoundry)
+{{#if isDatabase}}
+# Connection string used by the generated tool handlers.
+DATABASE_URL=
+{{/if}}
+{{#if secure}}
+# --- ZTAI Security Shield ---
+# Shared HMAC secret used to verify the ZTAI auth token (HS256). Change in prod.
+JWT_SECRET=dev-secret-key-change-in-production-12345
+# Short-lived JWT presented over stdio. Invalid/missing => server refuses to start.
+ZTAI_AUTH_TOKEN=
+# Optional deception canary. When set, tool output carries a traceable marker.
+ZTAI_CANARY_ID=
+{{/if}}

package/templates/python/README.md.hbs

@@ -0,0 +1,51 @@
+# {{projectName}}
+
+An MCP (Model Context Protocol) server generated by [mcpfoundry](https://www.npmjs.com/package/mcpfoundry) from a **{{sourceType}}** source, built on [FastMCP](https://github.com/jlowin/fastmcp).
+
+It exposes **{{tools.length}} tool(s)** over stdio.
+
+## Quick start
+
+Requires **Python 3.10+**.
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+python server.py
+```
+
+> Prefer packaging? `pip install -e .` also works (uses `pyproject.toml`), but
+> requires a recent `pip`/`setuptools`.
+
+## Tools
+
+{{#each tools}}
+- `{{this.name}}` — {{this.description}}
+{{/each}}
+
+Each tool validates its parameters with a Pydantic model before any handler
+logic runs. The handlers currently contain `TODO` stubs — wire them to your real
+data source.
+
+{{#if secure}}
+## ZTAI Security Shield (enabled)
+
+This server was generated with `--secure`, so it enforces:
+
+1. **JWT Guard** — on startup it verifies a short-lived HS256 token from
+   `ZTAI_AUTH_TOKEN` against `JWT_SECRET`. A missing/invalid token aborts boot.
+2. **Parameter hardening** — Pydantic models reject malformed input.
+3. **Deception canary** — set `ZTAI_CANARY_ID` to append a traceable marker to
+   tool output (see `apply_canary` in `server.py`).
+
+Copy `.env.example` to `.env` and fill in the values.
+{{else}}
+## Security
+
+This is a standard MCP server. For zero-trust auth (JWT guard) and a deception
+canary, regenerate with `mcpfoundry ... --secure`, or place it behind the ZTAI
+firewall.
+{{/if}}
+
+---
+Generated by mcpfoundry.

package/templates/python/_gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+build/
+dist/
+.env
+.DS_Store

package/templates/python/pyproject.toml.hbs

@@ -0,0 +1,25 @@
+[project]
+name = "{{projectName}}"
+version = "0.1.0"
+description = "MCP server generated by mcpfoundry."
+requires-python = ">=3.10"
+dependencies = [
+  "fastmcp>=2.0.0",
+  "pydantic>=2.0.0",
+{{#if secure}}
+  "pyjwt>=2.8.0",
+{{/if}}
+{{#if isDatabase}}
+  "psycopg[binary]>=3.1.0",
+{{/if}}
+]
+
+[project.scripts]
+{{projectName}} = "server:main"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ["server"]

package/templates/python/requirements.txt.hbs

@@ -0,0 +1,5 @@
+fastmcp>=2.0.0
+pydantic>=2.0.0
+{{#if secure}}pyjwt>=2.8.0
+{{/if}}{{#if isDatabase}}psycopg[binary]>=3.1.0
+{{/if}}

package/templates/python/server.py.hbs

@@ -0,0 +1,74 @@
+"""{{projectName}} — an MCP server generated by mcpfoundry from a {{sourceType}} source.
+
+Each tool validates its parameters with Pydantic (parameter hardening, always
+on) and contains a TODO stub — wire it to your real data source.
+"""
+import json
+import os
+from typing import Annotated, Any
+{{#if secure}}
+import hashlib
+
+import jwt
+{{/if}}
+from fastmcp import FastMCP
+from pydantic import Field
+
+mcp = FastMCP({{json projectName}})
+{{#if secure}}
+
+# --- ZTAI Security Shield (opt-in) ---
+
+def verify_startup_token() -> dict[str, Any]:
+    """Verify the short-lived HS256 token before serving any tools.
+
+    stdio has no per-request headers, so the token comes from ZTAI_AUTH_TOKEN
+    and is verified once at startup. Missing/invalid => the server refuses to run.
+    """
+    secret = os.environ.get("JWT_SECRET")
+    token = os.environ.get("ZTAI_AUTH_TOKEN")
+    if not secret:
+        raise RuntimeError("ZTAI Shield: JWT_SECRET is not set. Refusing to start.")
+    if not token:
+        raise RuntimeError("ZTAI Shield: ZTAI_AUTH_TOKEN is missing. Refusing to start.")
+    try:
+        return jwt.decode(token, secret, algorithms=["HS256"])
+    except jwt.PyJWTError as exc:
+        raise RuntimeError(
+            f"ZTAI Shield: invalid ZTAI_AUTH_TOKEN ({exc}). Connection dropped."
+        ) from exc
+
+
+def apply_canary(text: str) -> str:
+    """Append a traceable deception marker when ZTAI_CANARY_ID is set."""
+    canary_id = os.environ.get("ZTAI_CANARY_ID")
+    if not canary_id:
+        return text
+    seed = hashlib.sha256(canary_id.encode()).hexdigest()[:16]
+    return f"{text}\n<!-- ztai-canary-{seed} -->"
+{{/if}}
+
+{{#each tools}}
+@mcp.tool()
+def {{this.name}}(
+{{#each this.params}}
+    {{{pyParam this}}},
+{{/each}}
+) -> str:
+    """{{this.description}}"""
+    # TODO: implement {{#if this.operation}}{{this.operation}} on "{{this.table}}"{{else}}{{this.method}} {{this.path}}{{/if}}.
+    args = {{{pyArgsDict this.params}}}
+    result = json.dumps({"tool": {{json this.name}}, "args": args}, indent=2)
+    return {{#if ../secure}}apply_canary(result){{else}}result{{/if}}
+
+
+{{/each}}
+def main() -> None:
+{{#if secure}}
+    verify_startup_token()
+{{/if}}
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()