@mcpmake/core 0.2.0

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

@@ -0,0 +1,110 @@
+export interface AppConfig {
+  baseUrl: string;
+{{#each authSchemes}}
+{{#if (eq type "apiKey")}}
+  apiKey?: string;
+{{/if}}
+{{#if (eq type "http-bearer")}}
+  bearerToken?: string;
+{{/if}}
+{{#if (eq type "http-basic")}}
+  basicUsername?: string;
+  basicPassword?: string;
+{{/if}}
+{{#if (eq type "oauth2")}}
+  oauth2Token?: string;
+  oauth2ClientId?: string;
+  oauth2ClientSecret?: string;
+  oauth2AuthorizationUrl?: string;
+  oauth2TokenUrl?: string;
+  oauth2RedirectUri?: string;
+{{/if}}
+{{/each}}
+  maxRetries: number;
+  requestIntervalMs: number;
+  /** Extra headers added to every upstream request (non-breaking; empty by default). */
+  defaultHeaders: Record<string, string>;
+}
+
+/**
+ * Resolve the upstream base URL with optional named environments.
+ *
+ * `MCP_ENVIRONMENTS` is a JSON object mapping an environment name to a base URL,
+ * e.g. `{"production":"https://api.example.com","sandbox":"https://sandbox.example.com"}`.
+ * `API_ENVIRONMENT` selects one of those names. When either is unset (or the
+ * name is unknown) the resolver falls back to `BASE_URL`, so existing
+ * deployments are unaffected.
+ */
+function resolveBaseUrl(): string {
+  const raw = process.env.MCP_ENVIRONMENTS;
+  const selected = process.env.API_ENVIRONMENT;
+  if (raw && selected) {
+    try {
+      const envs = JSON.parse(raw) as Record<string, unknown>;
+      const url = envs[selected];
+      if (typeof url === 'string' && url) {
+        return url.replace(/\/$/, '');
+      }
+    } catch {
+      // Malformed MCP_ENVIRONMENTS — fall through to BASE_URL.
+    }
+  }
+  return requireEnv('BASE_URL').replace(/\/$/, '');
+}
+
+/**
+ * Parse `MCP_DEFAULT_HEADERS` (a JSON object of header name → value) into a map
+ * applied to every upstream request. Invalid JSON or non-string values are
+ * ignored so a bad value never breaks the server.
+ */
+function loadDefaultHeaders(): Record<string, string> {
+  const raw = process.env.MCP_DEFAULT_HEADERS;
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const headers: Record<string, string> = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === 'string') headers[key] = value;
+    }
+    return headers;
+  } catch {
+    return {};
+  }
+}
+
+export function loadConfig(): AppConfig {
+  return {
+    baseUrl: resolveBaseUrl(),
+{{#each authSchemes}}
+{{#if (eq type "apiKey")}}
+    apiKey: process.env.{{envVarName}},
+{{/if}}
+{{#if (eq type "http-bearer")}}
+    bearerToken: process.env.{{envVarName}},
+{{/if}}
+{{#if (eq type "http-basic")}}
+    basicUsername: process.env.BASIC_USERNAME,
+    basicPassword: process.env.BASIC_PASSWORD,
+{{/if}}
+{{#if (eq type "oauth2")}}
+    oauth2Token: process.env.OAUTH2_TOKEN,
+    oauth2ClientId: process.env.OAUTH2_CLIENT_ID,
+    oauth2ClientSecret: process.env.OAUTH2_CLIENT_SECRET,
+    oauth2AuthorizationUrl: process.env.OAUTH2_AUTHORIZATION_URL,
+    oauth2TokenUrl: process.env.OAUTH2_TOKEN_URL,
+    oauth2RedirectUri: process.env.OAUTH2_REDIRECT_URI,
+{{/if}}
+{{/each}}
+    maxRetries: parseInt(process.env.MAX_RETRIES ?? '3', 10),
+    requestIntervalMs: parseInt(process.env.REQUEST_INTERVAL_MS ?? '100', 10),
+    defaultHeaders: loadDefaultHeaders(),
+  };
+}
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}

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

@@ -0,0 +1,320 @@
+/**
+ * Dynamic tool discovery — 4 meta-tools that let LLMs discover and call tools
+ * without all tool schemas loaded into context upfront.
+ *
+ * Reduces initial context from ~25-40K tokens (for large APIs) to ~1,300 tokens.
+ */
+
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { executeRequest } from './http.js';
+import { applyJqFilter } from './response-filter.js';
+import type { AppConfig } from './config.js';
+import catalogData from './tool-catalog.json' with { type: 'json' };
+
+interface CatalogEntry {
+  name: string;
+  title: string;
+  description: string;
+  method: string;
+  path: string;
+  inputSchema: Record<string, unknown>;
+  pathParams: string[];
+  queryParams: string[];
+  hasRequestBody: boolean;
+  requestBodyContentType: string;
+}
+
+const catalog: CatalogEntry[] = catalogData as CatalogEntry[];
+
+// Simple TF-IDF search index built at startup
+const searchIndex = buildSearchIndex(catalog);
+
+export function registerDiscoveryTools(server: McpServer, config: AppConfig): void {
+  // 1. list_tools — list available tools with optional query filter
+  server.registerTool(
+    'list_tools',
+    {
+      title: 'List Available Tools',
+      description: `List all ${catalog.length} available API tools. Use "query" to filter by name or description.`,
+      inputSchema: z.object({
+        query: z.string().optional().describe('Filter tools by name or description'),
+        offset: z.number().int().optional().describe('Pagination offset (default: 0)'),
+        limit: z.number().int().optional().describe('Max results (default: 20)'),
+      }),
+      annotations: { readOnlyHint: true },
+    },
+    async (input) => {
+      const query = (input as Record<string, unknown>).query as string | undefined;
+      const offset = ((input as Record<string, unknown>).offset as number) ?? 0;
+      const limit = ((input as Record<string, unknown>).limit as number) ?? 20;
+
+      let results = catalog;
+      if (query) {
+        results = searchTools(query);
+      }
+
+      const page = results.slice(offset, offset + limit);
+      const hasMore = offset + limit < results.length;
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify(
+              {
+                tools: page.map((t) => ({ name: t.name, description: t.description })),
+                total: results.length,
+                hasMore,
+                nextOffset: hasMore ? offset + limit : undefined,
+              },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+  );
+
+  // 2. get_tool_schema — get the full input schema for a specific tool
+  server.registerTool(
+    'get_tool_schema',
+    {
+      title: 'Get Tool Schema',
+      description: 'Get the full input schema and details for a specific tool by name.',
+      inputSchema: z.object({
+        name: z.string().describe('Tool name (from list_tools)'),
+      }),
+      annotations: { readOnlyHint: true },
+    },
+    async (input) => {
+      const name = (input as Record<string, unknown>).name as string;
+      const tool = catalog.find((t) => t.name === name);
+
+      if (!tool) {
+        return {
+          content: [{ type: 'text' as const, text: `Tool "${name}" not found.` }],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify(
+              {
+                name: tool.name,
+                title: tool.title,
+                description: tool.description,
+                method: tool.method,
+                path: tool.path,
+                inputSchema: tool.inputSchema,
+              },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+  );
+
+  // 3. execute_tool — execute a tool by name with arguments
+  server.registerTool(
+    'execute_tool',
+    {
+      title: 'Execute Tool',
+      description: 'Execute any API tool by name. Get the schema first with get_tool_schema.',
+      inputSchema: z.object({
+        name: z.string().describe('Tool name'),
+        args: z.record(z.unknown()).optional().describe('Tool arguments (match the input schema)'),
+        jq_filter: z
+          .string()
+          .optional()
+          .describe('Optional jq-style filter applied to the response (e.g. ".data", ".items[]").'),
+        idempotency_key: z
+          .string()
+          .optional()
+          .describe('Optional Idempotency-Key header for safe retries of mutating requests.'),
+      }),
+    },
+    async (input) => {
+      const name = (input as Record<string, unknown>).name as string;
+      const args = ((input as Record<string, unknown>).args as Record<string, unknown>) ?? {};
+      const jqFilter = (input as Record<string, unknown>).jq_filter as string | undefined;
+      const idempotencyKey = (input as Record<string, unknown>).idempotency_key as
+        | string
+        | undefined;
+      const tool = catalog.find((t) => t.name === name);
+
+      if (!tool) {
+        return {
+          content: [{ type: 'text' as const, text: `Tool "${name}" not found.` }],
+          isError: true,
+        };
+      }
+
+      try {
+        // Build URL from path template
+        let url = config.baseUrl + tool.path;
+        for (const param of tool.pathParams) {
+          if (args[param] !== undefined) {
+            url = url.replace(`{${param}}`, encodeURIComponent(String(args[param])));
+          }
+        }
+
+        // Add query params
+        const queryParams = new URLSearchParams();
+        for (const param of tool.queryParams) {
+          if (args[param] !== undefined) {
+            queryParams.set(param, String(args[param]));
+          }
+        }
+        const qs = queryParams.toString();
+        if (qs) url += `?${qs}`;
+
+        const response = await executeRequest({
+          method: tool.method,
+          url,
+          ...(tool.hasRequestBody && args.body
+            ? { body: args.body, contentType: tool.requestBodyContentType }
+            : {}),
+          headers: {},
+          config,
+          idempotencyKey,
+        });
+
+        const result =
+          typeof jqFilter === 'string' && jqFilter
+            ? applyJqFilter(response.data, jqFilter)
+            : response.data;
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: 'text' as const, text: `Error: ${message}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // 4. search_tools — semantic search over tool descriptions
+  server.registerTool(
+    'search_tools',
+    {
+      title: 'Search Tools',
+      description: 'Search for tools by description. Uses fuzzy matching.',
+      inputSchema: z.object({
+        description: z.string().describe('What you want to do (natural language)'),
+        limit: z.number().int().optional().describe('Max results (default: 5)'),
+      }),
+      annotations: { readOnlyHint: true },
+    },
+    async (input) => {
+      const description = (input as Record<string, unknown>).description as string;
+      const limit = ((input as Record<string, unknown>).limit as number) ?? 5;
+
+      const results = searchTools(description).slice(0, limit);
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify(
+              results.map((t) => ({ name: t.name, description: t.description, method: t.method, path: t.path })),
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TF-IDF Search
+// ---------------------------------------------------------------------------
+
+interface SearchEntry {
+  tool: CatalogEntry;
+  terms: Map<string, number>; // term -> TF-IDF weight
+}
+
+function buildSearchIndex(tools: CatalogEntry[]): SearchEntry[] {
+  const docFreq = new Map<string, number>();
+  const docs: Array<{ tool: CatalogEntry; terms: string[] }> = [];
+
+  for (const tool of tools) {
+    const text = `${tool.name} ${tool.title} ${tool.description} ${tool.method} ${tool.path}`;
+    const terms = tokenize(text);
+    docs.push({ tool, terms });
+
+    const unique = new Set(terms);
+    for (const term of unique) {
+      docFreq.set(term, (docFreq.get(term) ?? 0) + 1);
+    }
+  }
+
+  const N = tools.length;
+  return docs.map(({ tool, terms }) => {
+    const termFreq = new Map<string, number>();
+    for (const t of terms) {
+      termFreq.set(t, (termFreq.get(t) ?? 0) + 1);
+    }
+
+    const weighted = new Map<string, number>();
+    for (const [term, tf] of termFreq) {
+      const df = docFreq.get(term) ?? 1;
+      const idf = Math.log(N / df);
+      weighted.set(term, tf * idf);
+    }
+
+    return { tool, terms: weighted };
+  });
+}
+
+function searchTools(query: string): CatalogEntry[] {
+  const queryTerms = tokenize(query);
+  if (queryTerms.length === 0) return catalog;
+
+  const scores: Array<{ tool: CatalogEntry; score: number }> = [];
+
+  for (const entry of searchIndex) {
+    let score = 0;
+    for (const qt of queryTerms) {
+      // Exact match
+      score += entry.terms.get(qt) ?? 0;
+      // Prefix match (fuzzy)
+      for (const [term, weight] of entry.terms) {
+        if (term.startsWith(qt) || qt.startsWith(term)) {
+          score += weight * 0.5;
+        }
+      }
+    }
+    if (score > 0) {
+      scores.push({ tool: entry.tool, score });
+    }
+  }
+
+  return scores.sort((a, b) => b.score - a.score).map((s) => s.tool);
+}
+
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, ' ')
+    .split(/\s+/)
+    .filter((t) => t.length > 1);
+}

package/dist/emitter/templates/dockerfile.hbs

@@ -0,0 +1,34 @@
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY tsconfig.json ./
+COPY src/ src/
+RUN npm run build
+
+FROM node:20-alpine
+
+LABEL org.opencontainers.image.title="{{serverName}}"
+
+ENV NODE_ENV=production
+ENV TRANSPORT=http
+ENV PORT=3000
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+COPY --from=builder /app/dist dist/
+
+USER node
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD node -e "fetch('http://localhost:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+CMD ["node", "dist/index.js"]

package/dist/emitter/templates/env.example.hbs

@@ -0,0 +1,52 @@
+# {{serverName}} configuration
+
+# Base URL for the API
+BASE_URL={{baseUrl}}
+
+# Named environments (optional). MCP_ENVIRONMENTS is a JSON object mapping a
+# name to a base URL; API_ENVIRONMENT selects one. Falls back to BASE_URL when
+# unset or the name is unknown.
+{{#if environmentsJson}}
+MCP_ENVIRONMENTS={{environmentsJson}}
+API_ENVIRONMENT={{defaultEnvironment}}
+{{else}}
+# MCP_ENVIRONMENTS={"production":"{{baseUrl}}","sandbox":"https://sandbox.example.com"}
+# API_ENVIRONMENT=production
+{{/if}}
+
+{{#each authEnvVars}}
+# {{description}}
+{{name}}=
+{{/each}}
+
+# HTTP tuning
+MAX_RETRIES=3
+REQUEST_INTERVAL_MS=100
+
+# Runtime tool filtering (optional). Comma-separated tool names.
+# MCP_TOOLS — allowlist: only these tools are registered.
+# MCP_EXCLUDE_TOOLS — denylist: these tools are never registered (applied after the allowlist).
+# MCP_TOOLS=
+# MCP_EXCLUDE_TOOLS=
+
+# Custom default headers added to every upstream request (optional, JSON object).
+# MCP_DEFAULT_HEADERS={"X-Tenant-Id":"acme","X-Trace":"1"}
+
+# Auto-generate an Idempotency-Key header for mutating (POST/PUT/PATCH/DELETE)
+# requests when no per-call idempotency_key is supplied (optional).
+# MCP_IDEMPOTENCY_AUTO=true
+{{#if (eq transport "http")}}
+
+# Transport: "stdio" or "http"
+TRANSPORT=http
+PORT=3000
+# Allowed origin for CORS/DNS-rebinding protection (leave empty to allow all in dev)
+ALLOWED_ORIGIN=
+# Bearer token required on every /mcp request. When set, clients must send
+# `Authorization: Bearer <token>`. Leave empty to disable auth (local/dev only).
+MCP_AUTH_TOKEN=
+# Session mode (MCP 2026-07-28): leave empty for stateless (default, recommended
+# — any request can hit any instance). Set to "true" for stateful per-session
+# (Mcp-Session-Id) mode if a client needs resumable streams.
+MCP_STATEFUL=
+{{/if}}

package/dist/emitter/templates/gitignore.hbs

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

package/dist/emitter/templates/http-executor.ts.hbs

@@ -0,0 +1,159 @@
+import { getAuthHeaders } from './auth.js';
+import { traceHeaders } from './trace.js';
+import type { AppConfig } from './config.js';
+
+export interface RequestOptions {
+  method: string;
+  url: string;
+  body?: unknown;
+  contentType?: string;
+  headers: Record<string, string>;
+  config: AppConfig;
+  /**
+   * Optional Idempotency-Key for mutating (POST/PUT/PATCH/DELETE) requests. When
+   * absent and `MCP_IDEMPOTENCY_AUTO=true`, a UUID is generated automatically.
+   */
+  idempotencyKey?: string;
+}
+
+export interface ApiResponse {
+  status: number;
+  data: unknown;
+  headers: Record<string, string>;
+}
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly data: unknown,
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+const RETRYABLE_STATUS_CODES = [429, 500, 502, 503, 504];
+
+/** Methods that mutate server state and therefore benefit from an idempotency key. */
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+let lastRequestTime = 0;
+
+/**
+ * Resolve the Idempotency-Key for a mutating request. Precedence:
+ *   1. an explicit per-call key passed in `options.idempotencyKey`
+ *   2. when `MCP_IDEMPOTENCY_AUTO=true`, a generated UUID (so retries of the
+ *      same upstream call carry a stable key for the duration of the attempt loop)
+ * Returns undefined for non-mutating methods or when neither is configured, so
+ * the default behavior is unchanged.
+ */
+function resolveIdempotencyKey(method: string, explicit: string | undefined): string | undefined {
+  if (!MUTATING_METHODS.has(method)) return undefined;
+  if (explicit) return explicit;
+  // `process` is absent on Workers (nodejs_compat leaves it undefined here), so
+  // guard it; auto-keying is then simply off on that target unless a per-call
+  // key is supplied. The Web Crypto `crypto` global exists on both runtimes.
+  const auto =
+    typeof process !== 'undefined' && process.env?.MCP_IDEMPOTENCY_AUTO === 'true';
+  if (auto) {
+    return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+      ? crypto.randomUUID()
+      : `idem-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  }
+  return undefined;
+}
+
+export async function executeRequest(options: RequestOptions): Promise<ApiResponse> {
+  const { config } = options;
+
+  // Rate limiting
+  const now = Date.now();
+  const elapsed = now - lastRequestTime;
+  if (elapsed < config.requestIntervalMs) {
+    await sleep(config.requestIntervalMs - elapsed);
+  }
+  lastRequestTime = Date.now();
+
+  const authHeaders = await getAuthHeaders(config);
+  // Header precedence (lowest → highest): auth, runtime default headers
+  // (MCP_DEFAULT_HEADERS), W3C Trace Context, then per-call headers.
+  // Propagate W3C Trace Context to the upstream API (no-op outside an HTTP
+  // request, e.g. stdio transport, where there is no active trace).
+  const method = options.method.toUpperCase();
+  const headers: Record<string, string> = {
+    ...authHeaders,
+    ...config.defaultHeaders,
+    ...traceHeaders(),
+    ...options.headers,
+  };
+
+  if (options.body && options.contentType) {
+    headers['Content-Type'] = options.contentType;
+  }
+
+  // Idempotency-Key for mutating requests (explicit per-call, or auto when enabled).
+  const idempotencyKey = resolveIdempotencyKey(method, options.idempotencyKey);
+  if (idempotencyKey && !headers['Idempotency-Key']) {
+    headers['Idempotency-Key'] = idempotencyKey;
+  }
+
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    try {
+      const response = await fetch(options.url, {
+        method,
+        headers,
+        body: options.body ? JSON.stringify(options.body) : undefined,
+      });
+
+      if (RETRYABLE_STATUS_CODES.includes(response.status) && attempt < config.maxRetries) {
+        const retryAfter = response.headers.get('Retry-After');
+        const delay = retryAfter
+          ? parseInt(retryAfter, 10) * 1000
+          : 1000 * Math.pow(2, attempt);
+        await sleep(delay);
+        continue;
+      }
+
+      const data = await parseResponseBody(response);
+
+      if (!response.ok) {
+        throw new ApiError(
+          `${response.status} ${response.statusText}`,
+          response.status,
+          data,
+        );
+      }
+
+      return {
+        status: response.status,
+        data,
+        headers: Object.fromEntries(response.headers.entries()),
+      };
+    } catch (error) {
+      lastError = error as Error;
+      if (error instanceof ApiError && !RETRYABLE_STATUS_CODES.includes(error.status)) {
+        throw error;
+      }
+      if (attempt < config.maxRetries) {
+        await sleep(1000 * Math.pow(2, attempt));
+      }
+    }
+  }
+
+  throw lastError ?? new Error('Request failed after retries');
+}
+
+async function parseResponseBody(response: Response): Promise<unknown> {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (contentType.includes('application/json')) {
+    return response.json();
+  }
+  return response.text();
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}