@mcpmake/core 0.2.0

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

@@ -0,0 +1,188 @@
+/**
+ * OAuth 2.1 token management.
+ * Supports Authorization Code + PKCE and Client Credentials flows.
+ */
+
+import crypto from 'node:crypto';
+
+export interface OAuthConfig {
+  clientId: string;
+  clientSecret?: string;
+  authorizationUrl: string;
+  tokenUrl: string;
+  scopes: string[];
+  redirectUri: string;
+}
+
+interface TokenResponse {
+  access_token: string;
+  token_type: string;
+  expires_in?: number;
+  refresh_token?: string;
+  scope?: string;
+}
+
+let cachedToken: { accessToken: string; expiresAt: number; refreshToken?: string } | undefined;
+
+/**
+ * Get a valid access token, refreshing if needed.
+ */
+export async function getAccessToken(config: OAuthConfig): Promise<string> {
+  if (cachedToken && Date.now() < cachedToken.expiresAt - 60_000) {
+    return cachedToken.accessToken;
+  }
+
+  // Try refresh first
+  if (cachedToken?.refreshToken) {
+    try {
+      const token = await refreshToken(config, cachedToken.refreshToken);
+      cacheToken(token);
+      return token.access_token;
+    } catch {
+      // Refresh failed — fall through to re-authenticate
+    }
+  }
+
+  // Client Credentials flow (machine-to-machine)
+  if (config.clientSecret && !process.env.OAUTH2_TOKEN) {
+    const token = await clientCredentialsGrant(config);
+    cacheToken(token);
+    return token.access_token;
+  }
+
+  // Pre-obtained token from env
+  if (process.env.OAUTH2_TOKEN) {
+    return process.env.OAUTH2_TOKEN;
+  }
+
+  throw new Error(
+    'No OAuth token available. Set OAUTH2_TOKEN or configure OAUTH2_CLIENT_ID + OAUTH2_CLIENT_SECRET for client credentials flow.',
+  );
+}
+
+/**
+ * Client Credentials grant (RFC 6749 Section 4.4).
+ */
+async function clientCredentialsGrant(config: OAuthConfig): Promise<TokenResponse> {
+  const params = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: config.clientId,
+    ...(config.clientSecret ? { client_secret: config.clientSecret } : {}),
+    ...(config.scopes.length > 0 ? { scope: config.scopes.join(' ') } : {}),
+  });
+
+  const response = await fetch(config.tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: params.toString(),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`OAuth client credentials failed (${response.status}): ${body}`);
+  }
+
+  return response.json() as Promise<TokenResponse>;
+}
+
+/**
+ * Refresh an access token using a refresh token.
+ */
+async function refreshToken(config: OAuthConfig, refreshTokenValue: string): Promise<TokenResponse> {
+  const params = new URLSearchParams({
+    grant_type: 'refresh_token',
+    client_id: config.clientId,
+    refresh_token: refreshTokenValue,
+  });
+
+  const response = await fetch(config.tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: params.toString(),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Token refresh failed: ${response.status}`);
+  }
+
+  return response.json() as Promise<TokenResponse>;
+}
+
+/**
+ * Generate PKCE code verifier and challenge for Authorization Code flow.
+ */
+export function generatePkce(): { codeVerifier: string; codeChallenge: string } {
+  const codeVerifier = crypto.randomBytes(32).toString('base64url');
+  const codeChallenge = crypto
+    .createHash('sha256')
+    .update(codeVerifier)
+    .digest('base64url');
+  return { codeVerifier, codeChallenge };
+}
+
+/**
+ * Build the authorization URL for the Authorization Code + PKCE flow.
+ */
+export function buildAuthorizationUrl(config: OAuthConfig, state: string, codeChallenge: string): string {
+  const params = new URLSearchParams({
+    response_type: 'code',
+    client_id: config.clientId,
+    redirect_uri: config.redirectUri,
+    state,
+    code_challenge: codeChallenge,
+    code_challenge_method: 'S256',
+    ...(config.scopes.length > 0 ? { scope: config.scopes.join(' ') } : {}),
+  });
+  return `${config.authorizationUrl}?${params.toString()}`;
+}
+
+/**
+ * Exchange an authorization code for tokens (PKCE flow).
+ */
+export async function exchangeCode(config: OAuthConfig, code: string, codeVerifier: string): Promise<TokenResponse> {
+  const params = new URLSearchParams({
+    grant_type: 'authorization_code',
+    client_id: config.clientId,
+    code,
+    redirect_uri: config.redirectUri,
+    code_verifier: codeVerifier,
+  });
+
+  const response = await fetch(config.tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: params.toString(),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`OAuth code exchange failed (${response.status}): ${body}`);
+  }
+
+  const token = await response.json() as TokenResponse;
+  cacheToken(token);
+  return token;
+}
+
+function cacheToken(token: TokenResponse): void {
+  cachedToken = {
+    accessToken: token.access_token,
+    expiresAt: Date.now() + (token.expires_in ?? 3600) * 1000,
+    refreshToken: token.refresh_token,
+  };
+}
+
+/**
+ * OAuth Authorization Server Metadata (RFC 8414).
+ */
+export function getAuthServerMetadata(config: OAuthConfig, issuer: string): Record<string, unknown> {
+  return {
+    issuer,
+    authorization_endpoint: config.authorizationUrl,
+    token_endpoint: config.tokenUrl,
+    response_types_supported: ['code'],
+    grant_types_supported: ['authorization_code', 'client_credentials', 'refresh_token'],
+    code_challenge_methods_supported: ['S256'],
+    scopes_supported: config.scopes,
+  };
+}

package/dist/emitter/templates/package.json.hbs

@@ -0,0 +1,25 @@
+{
+  "name": "{{serverName}}",
+  "version": "{{serverVersion}}",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "tsx": "^4.19.0",
+    "vitest": "^3.1.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1,156 @@
+# {{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 |
+| `MCP_ENVIRONMENTS` | JSON map of environment name → base URL (e.g. `{"production":"…","sandbox":"…"}`) | No |
+| `API_ENVIRONMENT` | Selects a named environment from `MCP_ENVIRONMENTS` (falls back to `BASE_URL`) | No |
+| `MCP_TOOLS` | Comma-separated allowlist of tool names to register | No |
+| `MCP_EXCLUDE_TOOLS` | Comma-separated denylist of tool names to skip | No |
+| `MCP_DEFAULT_HEADERS` | JSON object of headers added to every upstream request | No |
+| `MCP_IDEMPOTENCY_AUTO` | `true` to auto-generate an `Idempotency-Key` for mutating requests | No |
+
+### Named environments
+
+Select an upstream environment by name at runtime instead of hard-coding a URL:
+
+```bash
+MCP_ENVIRONMENTS='{"production":"https://api.example.com","sandbox":"https://sandbox.example.com"}' \
+  API_ENVIRONMENT=sandbox npm start
+```
+
+When `API_ENVIRONMENT` is unset or names an unknown environment, the server uses `BASE_URL`.
+
+### Runtime tool filtering
+
+Narrow which tools are exposed without regenerating the server:
+
+```bash
+MCP_TOOLS=list_pets,show_pet_by_id npm start   # allowlist
+MCP_EXCLUDE_TOOLS=delete_pet npm start          # denylist
+```
+
+### Per-call arguments
+
+Every tool accepts two optional arguments (omit them for the original behavior):
+
+- `jq_filter` — a jq-style selector (e.g. `.data`, `.items[0].id`, `.items[]`) applied to the JSON response before it is returned, to trim large payloads.
+- `idempotency_key` — sent as the `Idempotency-Key` header on mutating requests for safe retries.
+
+## 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

@@ -0,0 +1,63 @@
+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/response-filter.ts.hbs

@@ -0,0 +1,128 @@
+/**
+ * Minimal, dependency-free jq-style response filter.
+ *
+ * Stainless exposes a per-call `jq_filter` argument that trims the JSON response
+ * before it is returned to the agent (saving context tokens). A full jq engine is
+ * a heavy dependency, so this implements a safe, commonly-used subset:
+ *
+ *   .                identity (whole document)
+ *   .a.b.c           nested object access
+ *   .a.b?            optional access (never throws on a missing key)
+ *   .items[0]        array index (negative indexes count from the end)
+ *   .items[]         iterate an array, applying the rest of the path to each item
+ *   .a | .b          pipe (each stage receives the previous stage's output)
+ *
+ * Anything outside this subset (or any error while evaluating) makes the filter
+ * fall back to returning the unfiltered value, so a bad filter never breaks a
+ * tool call. This is intentionally conservative: it only ever *selects* data,
+ * it never executes arbitrary expressions.
+ */
+export function applyJqFilter(data: unknown, filter: string): unknown {
+  const trimmed = filter.trim();
+  if (!trimmed || trimmed === '.') return data;
+
+  // A pipe runs each stage in sequence; later stages refine the earlier output.
+  const stages = trimmed.split('|').map((s) => s.trim());
+  let current: unknown = data;
+  for (const stage of stages) {
+    current = applyStage(current, stage);
+  }
+  return current;
+}
+
+function applyStage(data: unknown, stage: string): unknown {
+  if (!stage || stage === '.') return data;
+
+  // Tokenize a leading-dot path into object keys and array selectors.
+  // e.g. ".a.b[0].c[]" → [{key:"a"}, {key:"b"}, {index:0}, {key:"c"}, {iterate:true}]
+  const tokens = tokenizePath(stage);
+  if (!tokens) return data; // unsupported syntax → leave the value untouched
+
+  let current: unknown = data;
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (current == null) return undefined;
+
+    if (token.iterate) {
+      if (!Array.isArray(current)) return undefined;
+      const rest = tokens.slice(i + 1);
+      return current.map((item) => walk(item, rest));
+    }
+
+    if (token.index !== undefined) {
+      if (!Array.isArray(current)) return undefined;
+      const idx = token.index < 0 ? current.length + token.index : token.index;
+      current = current[idx];
+      continue;
+    }
+
+    if (typeof current !== 'object' || Array.isArray(current)) return undefined;
+    current = (current as Record<string, unknown>)[token.key as string];
+  }
+  return current;
+}
+
+interface PathToken {
+  key?: string;
+  index?: number;
+  iterate?: boolean;
+}
+
+function walk(data: unknown, tokens: PathToken[]): unknown {
+  let current: unknown = data;
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (current == null) return undefined;
+    if (token.iterate) {
+      if (!Array.isArray(current)) return undefined;
+      const rest = tokens.slice(i + 1);
+      return current.map((item) => walk(item, rest));
+    }
+    if (token.index !== undefined) {
+      if (!Array.isArray(current)) return undefined;
+      const idx = token.index < 0 ? current.length + token.index : token.index;
+      current = current[idx];
+      continue;
+    }
+    if (typeof current !== 'object' || Array.isArray(current)) return undefined;
+    current = (current as Record<string, unknown>)[token.key as string];
+  }
+  return current;
+}
+
+function tokenizePath(path: string): PathToken[] | null {
+  const tokens: PathToken[] = [];
+  let i = 0;
+  const n = path.length;
+  while (i < n) {
+    const ch = path[i];
+    if (ch === '.') {
+      i++;
+      // Read an object key (identifier-ish chars). A bare "." (e.g. before "[")
+      // is allowed and contributes no key token.
+      let key = '';
+      while (i < n && /[A-Za-z0-9_$-]/.test(path[i])) {
+        key += path[i];
+        i++;
+      }
+      // Tolerate the jq optional-access marker "?".
+      if (i < n && path[i] === '?') i++;
+      if (key) tokens.push({ key });
+    } else if (ch === '[') {
+      const close = path.indexOf(']', i);
+      if (close === -1) return null;
+      const inner = path.slice(i + 1, close).trim();
+      if (inner === '') {
+        tokens.push({ iterate: true });
+      } else if (/^-?\d+$/.test(inner)) {
+        tokens.push({ index: parseInt(inner, 10) });
+      } else {
+        return null; // unsupported selector (filters, slices, string keys)
+      }
+      i = close + 1;
+    } else {
+      return null; // unexpected character → unsupported
+    }
+  }
+  return tokens;
+}