mcpmake 0.1.0 → 0.2.0

package/dist/emitter/templates/prompts.ts.hbs

@@ -1,22 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-
-export function registerAllPrompts(server: McpServer): void {
-{{#each prompts}}
-  server.prompt(
-    '{{name}}',
-    `{{{description}}}`,
-    () => ({
-      messages: [
-        {
-          role: 'user' as const,
-          content: {
-            type: 'text' as const,
-            text: `{{{template}}}`,
-          },
-        },
-      ],
-    }),
-  );
-
-{{/each}}
-}

package/dist/emitter/templates/readme.md.hbs

@@ -1,123 +0,0 @@
-# {{serverName}}
-
-MCP server generated by [mcpmake](https://github.com/starkyru/mcpmake).
-
-## Setup
-
-```bash
-npm install
-cp .env.example .env  # fill in your credentials
-npm run build
-```
-
-## Running
-
-```bash
-# stdio transport (for Claude Desktop)
-npm start
-
-# Development mode (auto-reload)
-npm run dev
-```
-
-{{#if (eq transport "http")}}
-## HTTP Transport
-
-Run the server over HTTP instead of stdio:
-
-```bash
-TRANSPORT=http PORT=3000 npm start
-```
-
-The MCP endpoint is available at `http://localhost:3000/mcp`.
-
-| Endpoint | Description |
-|----------|-------------|
-| `POST /mcp` | MCP protocol (JSON-RPC) |
-| `GET /health` | Health check (returns 200 OK) |
-| `GET /ready` | Readiness check (503 during startup/shutdown) |
-{{#if hasOAuth}}
-| `GET /.well-known/oauth-authorization-server` | OAuth Authorization Server Metadata (RFC 8414) |
-{{/if}}
-
-### Session mode (MCP 2026-07-28)
-
-The server is **stateless by default** (no `Mcp-Session-Id`) so any request can
-hit any instance. Set `MCP_STATEFUL=true` to keep per-session mode if a client
-needs resumable streams. A `server/discover` preflight is supported, and the
-`Mcp-Method`/`Mcp-Name` routing headers are accepted (and logged). See
-[the migration notes](https://github.com/starkyru/mcpmake/blob/main/docs/mcp-2026-07-28-migration.md).
-
-### Distributed tracing (W3C Trace Context)
-
-An inbound [`traceparent`](https://www.w3.org/TR/trace-context/) is continued
-(or a fresh trace started) per request and stamped onto every upstream API call,
-so one trace spans client → MCP server → API. `tracestate` is propagated
-verbatim. Standardized in MCP 2026-07-28.
-
-### Docker Deployment
-
-```bash
-docker build -t {{serverName}} .
-docker run --rm -p 3000:3000 --read-only --cap-drop=ALL --security-opt=no-new-privileges --env-file .env {{serverName}}
-```
-
-The container runs as a non-root user and is compatible with `--read-only` filesystems.
-
-{{/if}}
-## Configuration
-
-Copy `.env.example` to `.env` and fill in:
-
-| Variable | Description | Required |
-|----------|-------------|----------|
-| `BASE_URL` | API base URL | Yes |
-{{#each authEnvVars}}
-| `{{name}}` | {{description}} | {{#if required}}Yes{{else}}No{{/if}} |
-{{/each}}
-| `MAX_RETRIES` | Max retry attempts (default: 3) | No |
-| `REQUEST_INTERVAL_MS` | Min ms between requests (default: 100) | No |
-
-## Tools
-
-This server exposes {{tools.length}} tools:
-{{#if dynamicDiscovery}}
-
-> **Dynamic discovery is enabled.** Instead of registering all {{tools.length}} tools
-> upfront (high token cost), this server exposes meta-tools — `list_tools`,
-> `search_tools`, `get_tool_schema`, and `execute_tool` — so the agent loads only
-> the schemas it needs.
-{{/if}}
-{{#if recommendDiscovery}}
-
-> **Tip — large API ({{tools.length}} tools).** Registering this many tools upfront
-> costs the agent a lot of context tokens, the most common reason big MCP servers
-> underperform. Re-run your generate command with `--dynamic-discovery` to expose
-> meta-tools (`list_tools` / `search_tools` / `get_tool_schema` / `execute_tool`)
-> and load tool schemas on demand.
-{{/if}}
-
-{{#each tools}}
-### `{{name}}`
-
-{{description}}
-
-{{/each}}
-
-## Claude Desktop Integration
-
-Add to your Claude Desktop config (`~/.claude/claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "{{serverName}}": {
-      "command": "node",
-      "args": ["{{serverName}}/dist/index.js"],
-      "env": {
-        "BASE_URL": "YOUR_BASE_URL"
-      }
-    }
-  }
-}
-```

package/dist/emitter/templates/resources.ts.hbs

@@ -1,63 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { executeRequest } from './http.js';
-import type { AppConfig } from './config.js';
-
-export function registerAllResources(server: McpServer, config: AppConfig): void {
-{{#each resources}}
-{{#if isTemplate}}
-  server.resource(
-    '{{name}}',
-    '{{uri}}',
-    {
-      description: `{{{description}}}`,
-      mimeType: 'application/json',
-    },
-    async (uri) => {
-{{{urlBody}}}
-      const response = await executeRequest({
-        method: 'get',
-        url,
-        headers: {},
-        config,
-      });
-      return {
-        contents: [
-          {
-            uri: uri.href,
-            mimeType: 'application/json',
-            text: JSON.stringify(response.data, null, 2),
-          },
-        ],
-      };
-    },
-  );
-{{else}}
-  server.resource(
-    '{{name}}',
-    '{{uri}}',
-    {
-      description: `{{{description}}}`,
-      mimeType: 'application/json',
-    },
-    async () => {
-      const response = await executeRequest({
-        method: 'get',
-        url: `${config.baseUrl}{{path}}`,
-        headers: {},
-        config,
-      });
-      return {
-        contents: [
-          {
-            uri: '{{uri}}',
-            mimeType: 'application/json',
-            text: JSON.stringify(response.data, null, 2),
-          },
-        ],
-      };
-    },
-  );
-{{/if}}
-
-{{/each}}
-}

package/dist/emitter/templates/server-main-http.ts.hbs

@@ -1,407 +0,0 @@
-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 { registerAllTools } from './tools/index.js';
-{{#if hasResources}}
-import { registerAllResources } from './resources.js';
-{{/if}}
-{{#if hasPrompts}}
-import { registerAllPrompts } from './prompts.js';
-{{/if}}
-import { loadConfig } from './config.js';
-{{#if hasAsyncTools}}
-import { handleTaskRoutes, handleTaskRpc } from './task-handlers.js';
-import { handleTaskSse } from './task-sse.js';
-{{/if}}
-{{#if hasOAuth}}
-import { getAuthServerMetadata } from './oauth.js';
-{{/if}}
-import http from 'node:http';
-import crypto from 'node:crypto';
-import { deriveContext, runWithTrace } from './trace.js';
-
-/* ── Structured JSON logger ─────────────────────────────────────────── */
-
-function log(level: 'info' | 'error', msg: string, extra?: Record<string, unknown>): void {
-  const entry = { ts: new Date().toISOString(), level, msg, ...extra };
-  process.stderr.write(JSON.stringify(entry) + '\n');
-}
-
-/* ── MCP 2026-07-28 ─────────────────────────────────────────────────────
- * This server is being migrated toward the 2026-07-28 spec revision (RC).
- * Implemented here (additive, works against the current SDK):
- *   - stateless transport by default (set MCP_STATEFUL=true to keep sessions)
- *   - server/discover preflight (SEP-2575)
- *   - Mcp-Method / Mcp-Name routing headers logged (SEP-2243)
- *   - Tasks extension methods tasks/get|update|cancel (tasks/list removed)
- * SDK-gated (lands when @modelcontextprotocol/sdk ships RC support, then the
- * package.json pin is bumped): removal of the initialize/initialized handshake
- * and moving protocolVersion/clientInfo/capabilities into per-request _meta.
- * The 2026-07-28 RC is NOT final — wire shapes marked VERIFY may change. */
-const PROTOCOL_REVISION = '2026-07-28'; // VERIFY against the final spec
-
-/* ── Bearer authentication ──────────────────────────────────────────────
- * Constant-time check that the request presents the expected bearer token via
- * the `Authorization: Bearer <token>` header. Returns true when no token is
- * configured (auth disabled). The token is never accepted from the query
- * string — URLs leak through logs, history, and referrers. */
-function isAuthorized(req: http.IncomingMessage, expected: string | undefined): boolean {
-  if (!expected) return true; // auth disabled when MCP_AUTH_TOKEN is unset
-
-  const header = req.headers.authorization;
-  if (typeof header !== 'string' || !header.startsWith('Bearer ')) return false;
-  const presented = header.slice(7).trim();
-  if (!presented) return false;
-
-  const a = Buffer.from(presented);
-  const b = Buffer.from(expected);
-  if (a.length !== b.length) return false;
-  return crypto.timingSafeEqual(a, b);
-}
-
-/* ── Bounded request-body reader ─────────────────────────────────────────
- * Buffers the body so we can peek JSON-RPC for server/discover + tasks/* and
- * then hand the parsed value to the SDK transport's `parsedBody` argument
- * (so the drained stream is never re-read). Resolves null past the size cap. */
-const MAX_BODY = 4 * 1024 * 1024; // 4 MB
-function readBody(req: http.IncomingMessage): Promise<Buffer | null> {
-  return new Promise((resolve) => {
-    const chunks: Buffer[] = [];
-    let total = 0;
-    let settled = false;
-    const done = (v: Buffer | null) => {
-      if (!settled) {
-        settled = true;
-        resolve(v);
-      }
-    };
-    req.on('data', (c: Buffer) => {
-      total += c.length;
-      if (total > MAX_BODY) {
-        done(null);
-        req.destroy();
-        return;
-      }
-      chunks.push(c);
-    });
-    req.on('end', () => done(Buffer.concat(chunks)));
-    req.on('error', () => done(null));
-    req.on('aborted', () => done(null));
-  });
-}
-
-function sendJson(res: http.ServerResponse, status: number, body: unknown): void {
-  res.writeHead(status, { 'Content-Type': 'application/json' });
-  res.end(JSON.stringify(body));
-}
-
-/** Narrow a possibly-repeated request header to a single string value. */
-function headerValue(v: string | string[] | undefined): string | undefined {
-  return Array.isArray(v) ? v[0] : v;
-}
-
-function rpcError(res: http.ServerResponse, id: unknown, code: number, message: string): void {
-  sendJson(res, 200, { jsonrpc: '2.0', id: id ?? null, error: { code, message } });
-}
-
-/* ── server/discover (SEP-2575) — VERIFY result shape against final spec ── */
-function buildDiscoverResult(id: unknown): Record<string, unknown> {
-  return {
-    jsonrpc: '2.0',
-    id: id ?? null,
-    result: {
-      server: { name: '{{serverName}}', version: '{{serverVersion}}' },
-      protocolRevision: PROTOCOL_REVISION,
-      capabilities: {
-        tools: { count: {{tools.length}} },
-{{#if hasResources}}
-        resources: {},
-{{/if}}
-{{#if hasPrompts}}
-        prompts: {},
-{{/if}}
-      },
-      extensions: [
-{{#if hasAsyncTools}}
-        'tasks',
-{{/if}}
-{{#if hasOAuth}}
-        'oauth',
-{{/if}}
-      ],
-      cacheTtlSeconds: 300,
-    },
-  };
-}
-
-/* ── MCP server factory ──────────────────────────────────────────────────
- * Builds a fully-registered McpServer. In stateless mode a fresh instance is
- * created per request (a single McpServer connected to multiple transports
- * concurrently races on its internal transport reference). */
-function createMcpServer(config: ReturnType<typeof loadConfig>): McpServer {
-  const server = new McpServer({
-    name: '{{serverName}}',
-    version: '{{serverVersion}}',
-  });
-  registerAllTools(server, config);
-{{#if hasResources}}
-  registerAllResources(server, config);
-{{/if}}
-{{#if hasPrompts}}
-  registerAllPrompts(server);
-{{/if}}
-  return server;
-}
-
-/* ── Bootstrap ───────────────────────────────────────────────────────── */
-
-const config = loadConfig();
-const transportMode = process.env.TRANSPORT ?? 'stdio';
-
-if (transportMode === 'http') {
-  const port = parseInt(process.env.PORT ?? '3000', 10);
-  if (!Number.isInteger(port) || port < 1 || port > 65535) {
-    log('error', 'Invalid PORT value, must be 1-65535', { PORT: process.env.PORT });
-    process.exit(1);
-  }
-  const allowedOrigin = process.env.ALLOWED_ORIGIN;
-  const authToken = process.env.MCP_AUTH_TOKEN;
-  /* Stateless by default (2026-07-28). MCP_STATEFUL=true keeps Mcp-Session-Id
-   * sessions during the migration / for clients that need resumable streams. */
-  const stateful = process.env.MCP_STATEFUL === 'true';
-  let isReady = false;
-
-  // Stateful mode uses one shared server + transport; stateless builds them
-  // per request (see createMcpServer + dispatchToTransport).
-  const sharedServer = stateful ? createMcpServer(config) : null;
-  const sharedTransport = stateful
-    ? new StreamableHTTPServerTransport({ sessionIdGenerator: () => crypto.randomUUID() })
-    : null;
-
-  async function dispatchToTransport(
-    req: http.IncomingMessage,
-    res: http.ServerResponse,
-    parsedBody?: unknown,
-  ): Promise<void> {
-    /* Bind W3C Trace Context for this request (continuing an inbound trace or
-     * starting one) so upstream API calls made inside the tool handlers carry
-     * the traceparent and the distributed trace spans the API hop. */
-    const trace = deriveContext(
-      headerValue(req.headers['traceparent']),
-      headerValue(req.headers['tracestate']),
-    );
-    await runWithTrace(trace, async () => {
-      if (stateful && sharedTransport) {
-        await sharedTransport.handleRequest(req, res, parsedBody);
-        return;
-      }
-      const reqServer = createMcpServer(config);
-      const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-      res.on('close', () => {
-        void transport.close();
-        void reqServer.close();
-      });
-      await reqServer.connect(transport);
-      await transport.handleRequest(req, res, parsedBody);
-    });
-  }
-
-  const httpServer = http.createServer(async (req, res) => {
-    const url = new URL(req.url ?? '/', `http://localhost:${port}`);
-    const method = req.method ?? 'GET';
-
-    /* ── Authentication ─────────────────────────────────────────────
-     * Every endpoint except /health, /ready{{#if hasOAuth}}, and the public
-     * OAuth metadata{{/if}} requires a valid bearer token when MCP_AUTH_TOKEN
-     * is set. This is the in-container line of defense; the hosting backend
-     * also validates before proxying. */
-    const isPublicPath =
-      url.pathname === '/health' ||
-      url.pathname === '/ready'{{#if hasOAuth}} ||
-      url.pathname === '/.well-known/oauth-authorization-server'{{/if}};
-    if (!isPublicPath && !isAuthorized(req, authToken)) {
-      log('error', 'Unauthorized request rejected', { path: url.pathname });
-      res.writeHead(401, {
-        'Content-Type': 'application/json',
-        'WWW-Authenticate': 'Bearer',
-      });
-      res.end(JSON.stringify({ error: 'Unauthorized: missing or invalid bearer token' }));
-      return;
-    }
-
-    /* ── Routing-header observability (SEP-2243, additive) ─────────── */
-    const mcpMethod = req.headers['mcp-method'];
-    const mcpName = req.headers['mcp-name'];
-    if (mcpMethod || mcpName) {
-      log('info', 'mcp-meta-headers', { mcpMethod, mcpName, path: url.pathname });
-    }
-
-{{#if hasOAuth}}
-    /* ── OAuth Authorization Server Metadata (RFC 8414) ─────────────
-     * Public discovery endpoint (the 2026-07-28 auth changes clarify
-     * .well-known discovery; DCR is retained, not replaced). */
-    if (url.pathname === '/.well-known/oauth-authorization-server') {
-      if (method !== 'GET') {
-        res.writeHead(405, { Allow: 'GET' });
-        res.end();
-        return;
-      }
-      const authorizationUrl = config.oauth2AuthorizationUrl;
-      const tokenUrl = config.oauth2TokenUrl;
-      if (!authorizationUrl || !tokenUrl) {
-        sendJson(res, 503, { error: 'OAuth is not configured' });
-        return;
-      }
-      const proto = req.headers['x-forwarded-proto'] === 'https' ? 'https' : 'http';
-      const issuer = allowedOrigin ?? `${proto}://${req.headers.host ?? 'localhost'}`;
-      sendJson(
-        res,
-        200,
-        getAuthServerMetadata(
-          {
-            clientId: config.oauth2ClientId ?? '',
-            clientSecret: config.oauth2ClientSecret,
-            authorizationUrl,
-            tokenUrl,
-            scopes: [],
-            redirectUri: config.oauth2RedirectUri ?? '',
-          },
-          issuer,
-        ),
-      );
-      return;
-    }
-
-{{/if}}
-{{#if hasAsyncTools}}
-    /* ── Task management REST routes (retained during the grace period) ── */
-    if (handleTaskSse(req, res, url)) return;
-    if (handleTaskRoutes(req, res, url)) return;
-
-{{/if}}
-    if (url.pathname === '/mcp') {
-      /* Origin validation (DNS-rebinding protection per MCP spec) */
-      const origin = req.headers.origin;
-      if (allowedOrigin) {
-        if (origin && origin !== allowedOrigin) {
-          log('error', 'Origin rejected', { origin, allowedOrigin });
-          res.writeHead(403, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({ error: 'Forbidden: invalid origin' }));
-          return;
-        }
-      } else if (origin) {
-        /* No allowlist configured but Origin header present — reject cross-origin requests */
-        log('error', 'Cross-origin request rejected (ALLOWED_ORIGIN not set)', { origin });
-        res.writeHead(403, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: 'Forbidden: ALLOWED_ORIGIN not configured' }));
-        return;
-      }
-
-      /* POST carries a JSON-RPC body: peek for server/discover + tasks/* and
-       * forward the parsed body to the transport. GET/DELETE (SSE stream /
-       * session teardown) pass straight through. */
-      if (method === 'POST') {
-        const raw = await readBody(req);
-        if (raw === null) {
-          rpcError(res, null, -32600, 'Request body too large');
-          return;
-        }
-        if (raw.length === 0) {
-          rpcError(res, null, -32600, 'Empty request body');
-          return;
-        }
-        let parsed: unknown;
-        try {
-          parsed = JSON.parse(raw.toString('utf-8'));
-        } catch {
-          rpcError(res, null, -32700, 'Parse error');
-          return;
-        }
-
-        /* Intercept single-object JSON-RPC extension methods the SDK doesn't
-         * dispatch yet. Batches are forwarded untouched. */
-        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-          const rpcMethod = (parsed as { method?: unknown }).method;
-          const rpcId = (parsed as { id?: unknown }).id;
-          if (rpcMethod === 'server/discover') {
-            sendJson(res, 200, buildDiscoverResult(rpcId));
-            return;
-          }
-{{#if hasAsyncTools}}
-          if (typeof rpcMethod === 'string' && rpcMethod.startsWith('tasks/')) {
-            const handled = handleTaskRpc(rpcMethod, (parsed as { params?: unknown }).params, rpcId);
-            if (handled) {
-              sendJson(res, 200, handled);
-              return;
-            }
-          }
-{{/if}}
-        }
-
-        await dispatchToTransport(req, res, parsed);
-        return;
-      }
-
-      await dispatchToTransport(req, res);
-    } else if (url.pathname === '/health') {
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ status: 'ok' }));
-    } else if (url.pathname === '/ready') {
-      if (isReady) {
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ status: 'ready' }));
-      } else {
-        res.writeHead(503, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ status: 'not ready' }));
-      }
-    } else {
-      res.writeHead(404);
-      res.end('Not found');
-    }
-  });
-
-  // Stateful: connect the shared server once before serving (readiness gates on
-  // it). Stateless: readiness gates on listen (no persistent connection).
-  if (stateful && sharedServer && sharedTransport) {
-    await sharedServer.connect(sharedTransport);
-    isReady = true;
-  }
-
-  httpServer.listen(port, () => {
-    if (!stateful) isReady = true;
-    log('info', 'MCP server running', {
-      name: '{{serverName}}',
-      port,
-      endpoint: '/mcp',
-      mode: stateful ? 'stateful' : 'stateless',
-    });
-  });
-
-  /* ── Graceful shutdown ─────────────────────────────────────────────── */
-
-  process.on('SIGTERM', () => {
-    log('info', 'SIGTERM received, shutting down');
-    isReady = false;
-
-    httpServer.close(async () => {
-      try {
-        if (sharedServer) await sharedServer.close();
-      } catch (err) {
-        log('error', 'Error closing MCP server', { err: String(err) });
-      }
-      log('info', 'Server closed');
-      process.exit(0);
-    });
-
-    /* Force exit after 5 seconds if in-flight requests don't complete */
-    setTimeout(() => {
-      log('error', 'Shutdown timed out after 5 s, forcing exit');
-      process.exit(1);
-    }, 5000).unref();
-  });
-} else {
-  const server = createMcpServer(config);
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  log('info', 'MCP server running on stdio', { name: '{{serverName}}' });
-}

package/dist/emitter/templates/server-main.ts.hbs

@@ -1,40 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-{{#if hasStaticTools}}
-import { registerAllTools } from './tools/index.js';
-{{/if}}
-{{#if hasDynamicDiscovery}}
-import { registerDiscoveryTools } from './discovery.js';
-{{/if}}
-{{#if hasResources}}
-import { registerAllResources } from './resources.js';
-{{/if}}
-{{#if hasPrompts}}
-import { registerAllPrompts } from './prompts.js';
-{{/if}}
-import { loadConfig } from './config.js';
-
-const config = loadConfig();
-
-const server = new McpServer({
-  name: '{{serverName}}',
-  version: '{{serverVersion}}',
-});
-
-{{#if hasStaticTools}}
-registerAllTools(server, config);
-{{/if}}
-{{#if hasDynamicDiscovery}}
-registerDiscoveryTools(server, config);
-{{/if}}
-{{#if hasResources}}
-registerAllResources(server, config);
-{{/if}}
-{{#if hasPrompts}}
-registerAllPrompts(server);
-{{/if}}
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-
-console.error('{{serverName}} MCP server running on stdio');