@utdk/mcp 0.1.0-dev.646adf4

package/src/auth.ts

@@ -0,0 +1,111 @@
+/**
+ * Auth chain for @utdk/mcp-server.
+ *
+ * Resolves credentials in priority order: environment variables → gateway proxy.
+ * Auth configuration is read from the provider package's `utdk.auth` field.
+ */
+
+import { ApiKey, BearerToken, OAuth2ClientCredentials } from "@utdk/common";
+import type { AuthProvider } from "@utdk/common";
+
+export type { AuthProvider };
+
+export interface UtdkAuthConfig {
+  auth_type: string;
+  api_key?: string;
+  var_name?: string;
+  location?: string;
+  token_url?: string;
+  client_id?: string;
+  client_secret?: string;
+  scope?: string;
+}
+
+/**
+ * Interpolate `${ENV_VAR}` placeholders in a string with actual environment values.
+ * Returns null if any placeholder resolved to an empty or missing env var.
+ */
+function interpolateEnv(value: string): string | null {
+  let hasEmpty = false;
+  const result = value.replace(/\$\{([^}]+)\}/g, (_match, varName: string) => {
+    const envValue = process.env[varName];
+    if (!envValue) {
+      hasEmpty = true;
+    }
+    return envValue ?? "";
+  });
+  return hasEmpty ? null : result;
+}
+
+/**
+ * Build an AuthProvider from a provider's `utdk.auth` config entry and env vars.
+ * Returns undefined if no credentials are found in the environment.
+ */
+function authFromConfig(config: UtdkAuthConfig): AuthProvider | undefined {
+  const authType = config.auth_type;
+
+  if (authType === "api_key" && config.api_key) {
+    const resolved = interpolateEnv(config.api_key);
+    if (resolved === null) return undefined;
+
+    const trimmed = resolved.trim();
+    if (!trimmed) return undefined;
+
+    const varName = config.var_name ?? "Authorization";
+    const location = config.location ?? "header";
+
+    if (location !== "header") {
+      // Query/cookie auth not yet supported in this chain
+      return undefined;
+    }
+
+    // If the value looks like "Bearer <token>", use BearerToken; otherwise ApiKey
+    const bearerMatch = /^Bearer\s+(\S.*)$/.exec(trimmed);
+    if (bearerMatch) {
+      return new BearerToken((bearerMatch[1] as string).trim());
+    }
+
+    return new ApiKey({ headerName: varName, value: trimmed });
+  }
+
+  if (authType === "oauth2") {
+    const clientId = config.client_id ? interpolateEnv(config.client_id) : null;
+    const clientSecret = config.client_secret ? interpolateEnv(config.client_secret) : null;
+
+    if (clientId && clientSecret && config.token_url) {
+      return new OAuth2ClientCredentials({
+        clientId,
+        clientSecret,
+        tokenUrl: config.token_url,
+        scopes: config.scope?.split(/\s+/) ?? [],
+      });
+    }
+
+    return undefined;
+  }
+
+  return undefined;
+}
+
+/**
+ * Build an AuthProvider for a provider from its utdk auth config array.
+ * Tries each config entry in order; returns the first that resolves from env.
+ * Returns undefined if no credentials are available (unauthenticated or gateway-delegated).
+ */
+export function buildAuthProvider(
+  providerName: string,
+  authConfigs: UtdkAuthConfig[],
+): AuthProvider | undefined {
+  // First try the explicit provider TOKEN env var (e.g. GITHUB_TOKEN, SLACK_TOKEN)
+  const providerToken = process.env[`${providerName.toUpperCase()}_TOKEN`];
+  if (providerToken) {
+    return new BearerToken(providerToken);
+  }
+
+  for (const config of authConfigs) {
+    const provider = authFromConfig(config);
+    if (provider) return provider;
+  }
+
+  return undefined;
+}

package/src/loader.ts

@@ -0,0 +1,309 @@
+/**
+ * Dynamic provider loader for @utdk/mcp-server.
+ *
+ * Loads OpenAPI documents and auth configuration from @utdk/* provider packages.
+ * Converts each OpenAPI spec to MCP-compatible tool definitions using OpenApiConverter.
+ */
+
+import { OpenApiConverter } from "@utcp/http";
+import type { Tool } from "@utcp/sdk";
+import type { AuthProvider } from "@utdk/common";
+import { withSpan, configureTelemetry } from "@utdk/common";
+
+import { buildAuthProvider } from "./auth.js";
+import type { UtdkAuthConfig } from "./auth.js";
+
+export interface ProviderTool {
+  /** MCP tool name (e.g. "github__repos_list") */
+  mcpName: string;
+  /** Original UTCP tool name (e.g. "github.repos/list") */
+  utcpName: string;
+  description: string;
+  /** JSON Schema for the tool's inputs */
+  inputSchema: Record<string, unknown>;
+  /** Provider name (e.g. "github") */
+  providerName: string;
+  /** OpenAPI operation tags (e.g. ["repos", "issues"]) */
+  tags: string[];
+  /** Transport method (e.g. "GET", "POST") */
+  method: string;
+  /** Route template with {param} placeholders */
+  routeTemplate: string;
+  /** Content-Type for requests */
+  contentType: string;
+  /** Parameter keys that appear in the URL path */
+  pathParamKeys: string[];
+  /** Parameter keys that should go in query string for GET/DELETE */
+  queryParamKeys: string[];
+  /** Auth provider for this provider */
+  auth: AuthProvider | undefined;
+}
+
+interface UtdkPackageJson {
+  name: string;
+  utdk?: {
+    provider: string;
+    auth?: UtdkAuthConfig[];
+    openapi?: {
+      title?: string;
+    };
+  };
+}
+
+interface TransportCallTemplate {
+  call_template_type: string;
+  http_method?: string;
+  url?: string;
+  content_type?: string;
+}
+
+/**
+ * Extract path parameter keys from a route template like "/repos/{owner}/{repo}".
+ */
+function extractPathParams(routeTemplate: string): string[] {
+  const matches = routeTemplate.match(/\{([^}]+)\}/g) ?? [];
+  return matches.map((m) => m.slice(1, -1));
+}
+
+/**
+ * Convert a UTCP tool name to a safe MCP tool name.
+ * MCP tool names must match [a-zA-Z0-9_-]+ .
+ * e.g. "github.repos/list" → "github__repos_list"
+ */
+function toMcpToolName(utcpName: string): string {
+  return utcpName.replace(/\./g, "__").replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+/**
+ * Load a provider package's OpenAPI document and package metadata.
+ * Returns null if the package cannot be found or loaded.
+ */
+async function loadProviderPackage(providerName: string): Promise<{
+  openApiDoc: Record<string, unknown>;
+  packageJson: UtdkPackageJson;
+} | null> {
+  const packageName = `@utdk/${providerName}`;
+
+  try {
+    // Dynamically import the provider's openapi.json via the package path
+    // Provider packages expose their openapi.json as a JSON import
+    const [openApiMod, pkgMod] = await Promise.all([
+      import(`${packageName}/openapi.json`, { with: { type: "json" } }).catch(() => null),
+      import(`${packageName}/package.json`, { with: { type: "json" } }).catch(() => null),
+    ]);
+
+    if (!openApiMod || !pkgMod) {
+      // Try loading the whole package and see if it exposes the doc
+      process.stderr.write(
+        `[mcp-server] Warning: could not import openapi.json or package.json for ${packageName}\n`,
+      );
+      return null;
+    }
+
+    return {
+      openApiDoc: (openApiMod as { default: Record<string, unknown> }).default as Record<string, unknown>,
+      packageJson: (pkgMod as { default: UtdkPackageJson }).default as UtdkPackageJson,
+    };
+  } catch (err) {
+    process.stderr.write(
+      `[mcp-server] Warning: failed to load provider ${providerName}: ${err}\n`,
+    );
+    return null;
+  }
+}
+
+/**
+ * Convert a loaded provider's OpenAPI doc into MCP-ready tool definitions.
+ */
+function buildProviderTools(
+  providerName: string,
+  openApiDoc: Record<string, unknown>,
+  auth: AuthProvider | undefined,
+): ProviderTool[] {
+  const converter = new OpenApiConverter(openApiDoc, {
+    callTemplateName: providerName,
+  });
+
+  const manual = converter.convert();
+  const tools: ProviderTool[] = [];
+
+  for (const tool of manual.tools) {
+    const template = tool.tool_call_template as TransportCallTemplate | undefined;
+    if (!template) continue;
+
+    const routeTemplate = template.url ?? "/";
+    const method = (template.http_method ?? "GET").toUpperCase();
+    const contentType = template.content_type ?? "application/json";
+    const pathParamKeys = extractPathParams(routeTemplate);
+
+    // Determine which input properties go in query params vs body
+    // For GET/HEAD/DELETE, non-path params → query string
+    // For POST/PUT/PATCH, non-path params → body
+    const inputProperties = (tool.inputs?.properties ?? {}) as Record<string, unknown>;
+    const allInputKeys = Object.keys(inputProperties);
+    const isBodyMethod = ["POST", "PUT", "PATCH"].includes(method);
+    const queryParamKeys = isBodyMethod ? [] : allInputKeys.filter((k) => !pathParamKeys.includes(k));
+
+    tools.push({
+      mcpName: toMcpToolName(tool.name),
+      utcpName: tool.name,
+      description: tool.description ?? `${method} ${routeTemplate}`,
+      inputSchema: tool.inputs as Record<string, unknown>,
+      providerName,
+      tags: (tool.tags as string[] | undefined) ?? [],
+      method,
+      routeTemplate,
+      contentType,
+      pathParamKeys,
+      queryParamKeys,
+      auth,
+    });
+  }
+
+  return tools;
+}
+
+/**
+ * Load all tools for a list of provider names.
+ * Providers that fail to load are skipped with a warning.
+ */
+export async function loadProviders(providerNames: string[]): Promise<ProviderTool[]> {
+  const allTools: ProviderTool[] = [];
+
+  await Promise.all(
+    providerNames.map(async (providerName) => {
+      const pkg = await loadProviderPackage(providerName);
+      if (!pkg) return;
+
+      const authConfigs = pkg.packageJson.utdk?.auth ?? [];
+      const auth = buildAuthProvider(providerName, authConfigs);
+
+      const tools = buildProviderTools(providerName, pkg.openApiDoc, auth);
+      process.stderr.write(
+        `[mcp-server] Loaded ${tools.length} tools from @utdk/${providerName}\n`,
+      );
+      allTools.push(...tools);
+    }),
+  );
+
+  return allTools;
+}
+
+/**
+ * Parse the UTDK_PROVIDERS environment variable.
+ * Returns an array of provider names (e.g. ["github", "slack", "stripe"]).
+ */
+export function parseProviderNames(envValue: string | undefined): string[] {
+  if (!envValue?.trim()) return [];
+  return envValue
+    .split(",")
+    .map((name) => name.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+/**
+ * Initialize telemetry if UTDK_OTEL_EXPORTER is set.
+ */
+export async function initTelemetry(): Promise<void> {
+  const exporter = process.env["UTDK_OTEL_EXPORTER"];
+  if (exporter === "otlp" || exporter === "console") {
+    await configureTelemetry({ enabled: true, exporter });
+  }
+}
+
+/**
+ * Execute a tool call with telemetry and auth.
+ */
+export async function executeTool(
+  tool: ProviderTool,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  return withSpan(
+    {
+      provider: tool.providerName,
+      operation: tool.utcpName,
+      spanName: `utdk.mcp.tool_call`,
+    },
+    async (span) => {
+      span.setAttribute("utdk.provider", tool.providerName);
+      span.setAttribute("utdk.tool", tool.utcpName);
+      span.setAttribute("mcp.tool_name", tool.mcpName);
+
+      // Build URL by substituting path parameters
+      let url = tool.routeTemplate;
+      const remainingArgs: Record<string, unknown> = { ...args };
+
+      for (const pathKey of tool.pathParamKeys) {
+        const value = remainingArgs[pathKey];
+        if (value !== undefined) {
+          url = url.replace(`{${pathKey}}`, encodeURIComponent(String(value)));
+          delete remainingArgs[pathKey];
+        } else {
+          url = url.replace(`{${pathKey}}`, "");
+        }
+      }
+
+      // Build query string for GET-style methods
+      const isBodyMethod = ["POST", "PUT", "PATCH"].includes(tool.method);
+      let body: string | undefined;
+      const requestHeaders: Record<string, string> = {
+        "Content-Type": tool.contentType,
+        "User-Agent": "@utdk/mcp-server/0.1.0",
+      };
+
+      if (isBodyMethod) {
+        const bodyObj: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(remainingArgs)) {
+          bodyObj[k] = v;
+        }
+        if (Object.keys(bodyObj).length > 0) {
+          body = JSON.stringify(bodyObj);
+        }
+      } else {
+        // Query params
+        const urlObj = new URL(url);
+        for (const [k, v] of Object.entries(remainingArgs)) {
+          if (v !== undefined && v !== null) {
+            urlObj.searchParams.append(k, String(v));
+          }
+        }
+        url = urlObj.toString();
+      }
+
+      // Apply auth
+      if (tool.auth) {
+        await tool.auth.authenticate(requestHeaders);
+      }
+
+      span.setAttribute("http.method", tool.method);
+      span.setAttribute("http.url", url);
+
+      const response = await fetch(url, {
+        method: tool.method,
+        headers: requestHeaders,
+        body,
+      });
+
+      span.setAttribute("http.status_code", response.status);
+
+      if (!response.ok) {
+        const errorBody = await response.text();
+        throw new Error(
+          `Tool call failed: ${response.status} ${response.statusText}${errorBody ? `\n${errorBody}` : ""}`,
+        );
+      }
+
+      // Parse response
+      if (response.status === 204 || response.status === 205) {
+        return null;
+      }
+
+      const contentType = response.headers.get("content-type") ?? "";
+      if (contentType.includes("json")) {
+        return response.json();
+      }
+
+      return response.text();
+    },
+  );
+}

package/src/search.ts

@@ -0,0 +1,175 @@
+/**
+ * Search and tokenization utilities for the MCP server wrapper tools.
+ *
+ * Extracted into a separate module so they can be unit-tested without
+ * importing the full server entry-point (which starts stdio transport).
+ */
+
+import type { ProviderTool } from "./loader.js";
+
+// ---------------------------------------------------------------------------
+// Tokenization
+// ---------------------------------------------------------------------------
+
+/**
+ * Tokenize text into lowercase words, splitting on non-alphanumeric characters.
+ * Also splits camelCase boundaries for better matching of MCP tool names.
+ *
+ * Examples:
+ *   "github__repos_list" → ["github", "repos", "list"]
+ *   "List public repositories" → ["list", "public", "repositories"]
+ *   "security-advisories" → ["security", "advisories"]
+ */
+export function tokenize(text: string): string[] {
+  return text
+    .replace(/([a-z])([A-Z])/g, "$1 $2") // split camelCase boundaries
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+}
+
+// ---------------------------------------------------------------------------
+// TF-IDF scoring
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a TF-IDF scoring function over a corpus of tools.
+ *
+ * Field weights applied during term-frequency calculation:
+ *   - name  × 3   (most signal)
+ *   - tags  × 2   (category signal)
+ *   - description × 1
+ *
+ * IDF formula: log((N + 1) / df)  — smoothed to avoid division-by-zero.
+ *
+ * Returns a function `score(tool, queryWords) → number` that can be called
+ * for each candidate. Build once per search call, reuse across candidates.
+ */
+export function buildTfIdf(
+  tools: ProviderTool[],
+): (tool: ProviderTool, words: string[]) => number {
+  const N = tools.length;
+  if (N === 0) return () => 0;
+
+  type TokenBag = Map<string, number>;
+
+  // Precompute weighted token bags for each tool
+  const bags: TokenBag[] = tools.map((tool) => {
+    const bag: TokenBag = new Map();
+    const add = (tokens: string[], weight: number) => {
+      for (const tok of tokens) {
+        bag.set(tok, (bag.get(tok) ?? 0) + weight);
+      }
+    };
+    add(tokenize(tool.mcpName), 3);
+    for (const tag of tool.tags) {
+      add(tokenize(tag), 2);
+    }
+    add(tokenize(tool.description), 1);
+    return bag;
+  });
+
+  // Document frequency: how many tools contain each token
+  const df = new Map<string, number>();
+  for (const bag of bags) {
+    for (const tok of bag.keys()) {
+      df.set(tok, (df.get(tok) ?? 0) + 1);
+    }
+  }
+
+  const bagIndex = new Map<ProviderTool, TokenBag>(tools.map((t, i) => [t, bags[i]!]));
+
+  return (tool: ProviderTool, words: string[]): number => {
+    const bag = bagIndex.get(tool);
+    if (!bag) return 0;
+    const totalWeight = [...bag.values()].reduce((s, v) => s + v, 0) || 1;
+    let score = 0;
+    for (const word of words) {
+      const tf = (bag.get(word) ?? 0) / totalWeight;
+      const docFreq = df.get(word) ?? 0;
+      if (docFreq === 0) continue;
+      const idf = Math.log((N + 1) / docFreq);
+      score += tf * idf;
+    }
+    return score;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// searchTools
+// ---------------------------------------------------------------------------
+
+/**
+ * Search tools by keyword using TF-IDF relevance ranking.
+ *
+ * Matching: ALL query words must appear in at least one of name, tags, or
+ * description (case-insensitive substring match used for filtering; TF-IDF
+ * token scoring used for ranking).
+ *
+ * Returns up to `limit` results in descending relevance order.
+ */
+export function searchTools(
+  tools: ProviderTool[],
+  query: string,
+  provider: string | undefined,
+  limit: number,
+): Array<{ name: string; description: string; tags: string[] }> {
+  const words = tokenize(query);
+  if (words.length === 0) return [];
+
+  const source = provider ? tools.filter((t) => t.providerName === provider) : tools;
+  const scoreFn = buildTfIdf(source);
+
+  const candidates: Array<{ tool: ProviderTool; score: number }> = [];
+
+  for (const tool of source) {
+    const nameLower = tool.mcpName.toLowerCase();
+    const tagsText = tool.tags.join(" ").toLowerCase();
+    const descLower = tool.description.toLowerCase();
+
+    const allMatch = words.every(
+      (word) =>
+        nameLower.includes(word) || tagsText.includes(word) || descLower.includes(word),
+    );
+
+    if (allMatch) {
+      candidates.push({ tool, score: scoreFn(tool, words) });
+    }
+  }
+
+  candidates.sort((a, b) => b.score - a.score);
+
+  return candidates.slice(0, limit).map(({ tool }) => ({
+    name: tool.mcpName,
+    description: tool.description,
+    tags: tool.tags,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// groupTools
+// ---------------------------------------------------------------------------
+
+/**
+ * Group tools by provider name or by OpenAPI tag.
+ * Tools with no tags fall back to grouping under their provider name.
+ */
+export function groupTools(
+  tools: ProviderTool[],
+  by: "provider" | "tag",
+): Record<string, string[]> {
+  const grouped: Record<string, string[]> = {};
+
+  for (const tool of tools) {
+    if (by === "provider") {
+      (grouped[tool.providerName] ??= []).push(tool.mcpName);
+    } else {
+      const keys = tool.tags.length > 0 ? tool.tags : [tool.providerName];
+      for (const key of keys) {
+        (grouped[key] ??= []).push(tool.mcpName);
+      }
+    }
+  }
+
+  return grouped;
+}