mcpfoundry 0.1.0 → 0.1.1

package/README.md

@@ -56,10 +56,27 @@ mcpfoundry create \
 | `--input` | Path to an OpenAPI spec, JSON or YAML (openapi mode) |
 | `--output` | Output directory (required) |
 | `--lang` | `nodejs` (default) or `python` |
+| `--transport` | `stdio` (default) or `http` |
+| `--port` | Port for the `http` transport (default `3000`) |
 | `--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) |
 
+### Transports
+
+By default the server runs over **stdio** — the standard way clients (Claude
+Desktop, Claude Code, etc.) launch a local MCP server. Pass `--transport http`
+to generate a server that listens on `http://localhost:<port>/mcp` instead
+(Streamable HTTP via Express for Node, FastMCP for Python):
+
+```bash
+mcpfoundry create --type openapi --input ./openapi.yaml --output ./srv --transport http --port 3000
+```
+
+With `--secure` + `--transport http`, the JWT guard verifies an
+`Authorization: Bearer <token>` header on **every request** (returns `401` on
+failure); with stdio it verifies `ZTAI_AUTH_TOKEN` once at startup.
+
 `--input` accepts a local path **or a URL**, in JSON or YAML.
 
 ### Preview before generating
@@ -80,9 +97,10 @@ mcpfoundry create --type openapi --input ./openapi.yaml --dry-run
 
 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.
+1. **JWT Guard** — verifies a short-lived HS256 token (`ZTAI_AUTH_TOKEN` at
+   startup over stdio, or an `Authorization: Bearer` header per request over
+   HTTP) against `JWT_SECRET`. Invalid or missing tokens are rejected 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

package/dist/cli.js

@@ -25,6 +25,8 @@ program
     .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("--transport <transport>", "transport: stdio | http", "stdio")
+    .option("--port <port>", "port for the http transport", "3000")
     .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)
@@ -34,6 +36,7 @@ Examples:
   $ 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 ./http-server --transport http --port 3000
   $ mcpfoundry create --type openapi --input ./api.json --output /tmp/x --dry-run
 `)
     .action(async (opts) => {
@@ -50,6 +53,14 @@ async function run(opts) {
     if (lang !== "nodejs" && lang !== "python") {
         throw new Error(`Unsupported --lang "${opts.lang}". Use nodejs or python.`);
     }
+    const transport = opts.transport;
+    if (transport !== "stdio" && transport !== "http") {
+        throw new Error(`Unsupported --transport "${opts.transport}". Use stdio or http.`);
+    }
+    const port = Number(opts.port);
+    if (transport === "http" && (!Number.isInteger(port) || port < 1 || port > 65535)) {
+        throw new Error(`Invalid --port "${opts.port}". Use an integer between 1 and 65535.`);
+    }
     if (!opts.dryRun && !opts.output) {
         throw new Error("--output is required (or use --dry-run to preview).");
     }
@@ -98,6 +109,9 @@ async function run(opts) {
         sourceType,
         secure: Boolean(opts.secure),
         isDatabase: sourceType === "database",
+        transport,
+        port,
+        isHttp: transport === "http",
     };
     logger_1.logger.info(`Compiling ${tools.length} tool(s) into a ${lang} MCP server…`);
     await (0, compiler_1.compile)(context, outputDir, Boolean(opts.force));
@@ -119,7 +133,7 @@ function printDryRun(tools) {
 }
 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.success(`Forged ${logger_1.logger.bold(ctx.projectName)} — ${ctx.tools.length} MCP tool(s), ${ctx.lang}, ${ctx.transport} transport${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:");
@@ -130,9 +144,13 @@ function printSummary(ctx, outputDir) {
     }
     else {
         logger_1.logger.plain(`  cd ${outputDir}`);
-        logger_1.logger.plain("  pip install -e .");
+        logger_1.logger.plain("  pip install -r requirements.txt");
         logger_1.logger.plain("  python server.py");
     }
+    if (ctx.isHttp) {
+        logger_1.logger.plain();
+        logger_1.logger.plain(`  Serves MCP over HTTP at ${logger_1.logger.bold(`http://localhost:${ctx.port}/mcp`)} (override with PORT env).`);
+    }
     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.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpfoundry",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Forge production-ready MCP (Model Context Protocol) servers from databases or OpenAPI specs, with an optional ZTAI zero-trust security shield.",
   "keywords": [
     "mcp",

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

@@ -1,4 +1,8 @@
 # Environment for {{projectName}} (generated by mcpfoundry)
+{{#if isHttp}}
+# Port for the HTTP transport (overrides the compiled-in default {{port}}).
+PORT={{port}}
+{{/if}}
 {{#if isDatabase}}
 # Connection string used by the generated tool handlers.
 DATABASE_URL=
@@ -7,8 +11,12 @@ DATABASE_URL=
 # --- 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
+{{#if isHttp}}
+# HTTP transport: clients send `Authorization: Bearer <JWT>` on every request.
+{{else}}
 # Short-lived JWT presented over stdio. Invalid/missing => server refuses to start.
 ZTAI_AUTH_TOKEN=
+{{/if}}
 # Optional deception canary. When set, tool output carries a traceable marker.
 ZTAI_CANARY_ID=
 {{/if}}

package/templates/nodejs/README.md.hbs

@@ -2,7 +2,7 @@
 
 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.
+It exposes **{{tools.length}} tool(s)** over {{#if isHttp}}HTTP (streamable){{else}}stdio{{/if}}.
 
 ## Quick start
 
@@ -18,6 +18,31 @@ For development with auto-reload:
 npm run dev
 ```
 
+{{#if isHttp}}
+## Transport: HTTP
+
+This server listens on `http://localhost:{{port}}/mcp` (override the port with the
+`PORT` env var). Point an MCP client at that URL, or smoke-test it:
+
+```bash
+curl -s http://localhost:{{port}}/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+{{#if secure}}  -H "Authorization: Bearer $ZTAI_AUTH_TOKEN" \
+{{/if}}  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+{{else}}
+## Transport: stdio
+
+This server talks JSON-RPC over stdin/stdout — the standard way clients (Claude
+Desktop, Claude Code, etc.) launch a local MCP server. Configure your client to
+run `node /abs/path/to/dist/index.js`, or test it with the inspector:
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+{{/if}}
+
 ## Tools
 
 {{#each tools}}
@@ -33,8 +58,7 @@ data source.
 
 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.
+1. **JWT Guard** — {{#if isHttp}}every request must carry `Authorization: Bearer <HS256 JWT>`, verified against `JWT_SECRET`; failures return `401`.{{else}}on startup it verifies a short-lived HS256 token from `ZTAI_AUTH_TOKEN` against `JWT_SECRET`. A missing/invalid token aborts boot.{{/if}}
 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`).

package/templates/nodejs/package.json.hbs

@@ -14,14 +14,16 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.4.0",
-    "zod": "^3.23.8"{{#if secure}},
+    "zod": "^3.23.8"{{#if isHttp}},
+    "express": "^4.19.2"{{/if}}{{#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/node": "^20.14.0"{{#if isHttp}},
+    "@types/express": "^4.17.21"{{/if}}{{#if secure}},
     "@types/jsonwebtoken": "^9.0.6"{{/if}}{{#if isDatabase}},
     "@types/pg": "^8.11.6"{{/if}}
   }

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

@@ -1,25 +1,70 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+{{#if isHttp}}
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+{{else}}
 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();
+import { tools } from "./tools.js";
+{{#if secure}}import { {{#if isHttp}}verifyAuthHeader{{else}}verifyStartupToken{{/if}} } from "./security.js";
 {{/if}}
+function createServer(): McpServer {
   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);
   }
+  return server;
+}
+
+async function main(): Promise<void> {
+{{#if isHttp}}
+  const app = express();
+  app.use(express.json());
 
+  app.post("/mcp", async (req, res) => {
+{{#if secure}}
+    // ZTAI Security Shield: verify the Bearer token on every request.
+    try {
+      verifyAuthHeader(req.headers.authorization);
+    } catch (err) {
+      res.status(401).json({
+        jsonrpc: "2.0",
+        error: { code: -32001, message: (err as Error).message },
+        id: null,
+      });
+      return;
+    }
+{{/if}}
+    // Stateless: a fresh server + transport per request.
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    res.on("close", () => {
+      void transport.close();
+      void server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  });
+
+  const port = Number(process.env.PORT ?? {{port}});
+  app.listen(port, () => {
+    console.error(
+      `[{{projectName}}] MCP server listening on http://localhost:${port}/mcp with ${tools.length} tool(s).`,
+    );
+  });
+{{else}}
+{{#if secure}}
+  // ZTAI Security Shield: verify the short-lived auth token before serving tools.
+  verifyStartupToken();
+{{/if}}
+  const server = createServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error(
     `[{{projectName}}] MCP server running over stdio with ${tools.length} tool(s).`,
   );
+{{/if}}
 }
 
 main().catch((err) => {

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

@@ -1,4 +1,8 @@
 # Environment for {{projectName}} (generated by mcpfoundry)
+{{#if isHttp}}
+# Port for the HTTP transport (compiled-in default is {{port}}).
+PORT={{port}}
+{{/if}}
 {{#if isDatabase}}
 # Connection string used by the generated tool handlers.
 DATABASE_URL=
@@ -7,8 +11,12 @@ DATABASE_URL=
 # --- 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
+{{#if isHttp}}
+# HTTP transport: clients send `Authorization: Bearer <JWT>` on every request.
+{{else}}
 # Short-lived JWT presented over stdio. Invalid/missing => server refuses to start.
 ZTAI_AUTH_TOKEN=
+{{/if}}
 # Optional deception canary. When set, tool output carries a traceable marker.
 ZTAI_CANARY_ID=
 {{/if}}

package/templates/python/README.md.hbs

@@ -2,7 +2,7 @@
 
 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.
+It exposes **{{tools.length}} tool(s)** over {{#if isHttp}}HTTP (streamable){{else}}stdio{{/if}}.
 
 ## Quick start
 
@@ -17,6 +17,18 @@ python server.py
 > Prefer packaging? `pip install -e .` also works (uses `pyproject.toml`), but
 > requires a recent `pip`/`setuptools`.
 
+{{#if isHttp}}
+## Transport: HTTP
+
+This server listens on `http://localhost:{{port}}/mcp` (override with the `PORT`
+env var). Point an MCP client at that URL.
+{{else}}
+## Transport: stdio
+
+This server talks JSON-RPC over stdin/stdout. Configure your MCP client to run
+`python /abs/path/to/server.py`.
+{{/if}}
+
 ## Tools
 
 {{#each tools}}
@@ -32,8 +44,7 @@ data source.
 
 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.
+1. **JWT Guard** — {{#if isHttp}}every request must carry `Authorization: Bearer <HS256 JWT>`, verified against `JWT_SECRET` by a FastMCP middleware.{{else}}on startup it verifies a short-lived HS256 token from `ZTAI_AUTH_TOKEN` against `JWT_SECRET`. A missing/invalid token aborts boot.{{/if}}
 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`).

package/templates/python/server.py.hbs

@@ -13,11 +13,35 @@ import jwt
 {{/if}}
 from fastmcp import FastMCP
 from pydantic import Field
-
-mcp = FastMCP({{json projectName}})
+{{#if secure}}{{#if isHttp}}
+from fastmcp.server.dependencies import get_http_request
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+{{/if}}{{/if}}
 {{#if secure}}
-
 # --- ZTAI Security Shield (opt-in) ---
+{{#if isHttp}}
+
+def verify_auth_header(authorization: str | None) -> dict[str, Any]:
+    """Verify a Bearer JWT (HS256) from the Authorization header (per request)."""
+    secret = os.environ.get("JWT_SECRET")
+    if not secret:
+        raise RuntimeError("ZTAI Shield: JWT_SECRET is not set.")
+    if not authorization or not authorization.lower().startswith("bearer "):
+        raise RuntimeError("ZTAI Shield: missing Bearer token.")
+    token = authorization.split(" ", 1)[1]
+    try:
+        return jwt.decode(token, secret, algorithms=["HS256"])
+    except jwt.PyJWTError as exc:
+        raise RuntimeError(f"ZTAI Shield: invalid token ({exc}). Connection dropped.") from exc
+
+
+class ZtaiAuthMiddleware(Middleware):
+    """Reject any request whose Authorization header fails JWT verification."""
+
+    async def on_request(self, context: MiddlewareContext, call_next):
+        verify_auth_header(get_http_request().headers.get("authorization"))
+        return await call_next(context)
+{{else}}
 
 def verify_startup_token() -> dict[str, Any]:
     """Verify the short-lived HS256 token before serving any tools.
@@ -37,7 +61,7 @@ def verify_startup_token() -> dict[str, Any]:
         raise RuntimeError(
             f"ZTAI Shield: invalid ZTAI_AUTH_TOKEN ({exc}). Connection dropped."
         ) from exc
-
+{{/if}}
 
 def apply_canary(text: str) -> str:
     """Append a traceable deception marker when ZTAI_CANARY_ID is set."""
@@ -48,6 +72,11 @@ def apply_canary(text: str) -> str:
     return f"{text}\n<!-- ztai-canary-{seed} -->"
 {{/if}}
 
+mcp = FastMCP({{json projectName}})
+{{#if secure}}{{#if isHttp}}
+mcp.add_middleware(ZtaiAuthMiddleware())
+{{/if}}{{/if}}
+
 {{#each tools}}
 @mcp.tool()
 def {{this.name}}(
@@ -64,10 +93,14 @@ def {{this.name}}(
 
 {{/each}}
 def main() -> None:
-{{#if secure}}
+{{#if secure}}{{#unless isHttp}}
     verify_startup_token()
-{{/if}}
+{{/unless}}{{/if}}
+{{#if isHttp}}
+    mcp.run(transport="http", port=int(os.environ.get("PORT", {{port}})))
+{{else}}
     mcp.run()
+{{/if}}
 
 
 if __name__ == "__main__":