mcp-orbit 0.1.0

package/src/utils/http-client.ts

@@ -0,0 +1,86 @@
+/**
+ * Generic HTTP Client Utility
+ *
+ * Pure HTTP logic without MCP-specific types.
+ * Used by providers (kraken-api, etc.) for making HTTP requests.
+ */
+
+import {request} from "undici";
+
+// ============================================================================
+// HTTP CLIENT CONFIG
+// ============================================================================
+
+export interface HTTPClientConfig {
+  url: string;
+  method: "GET" | "POST" | "PUT" | "DELETE";
+  headers?: Record<string, string>;
+  body?: string;
+  timeout?: number;
+  maxResponseSize?: number;
+}
+
+export interface HTTPClientResponse {
+  statusCode: number;
+  headers: Record<string, string>;
+  body: string;
+}
+
+// ============================================================================
+// HTTP CLIENT
+// ============================================================================
+
+export class HTTPClient {
+  private defaultTimeout = 30000; // 30 seconds
+  private defaultMaxSize = 10 * 1024 * 1024; // 10 MB
+
+  /**
+   * Execute HTTP request with timeout and size limits
+   */
+  async request(config: HTTPClientConfig): Promise<HTTPClientResponse> {
+    const timeout = config.timeout || this.defaultTimeout;
+    const maxSize = config.maxResponseSize || this.defaultMaxSize;
+
+    try {
+      // Execute request with timeout
+      const response = await request(config.url, {
+        method: config.method,
+        headers: config.headers,
+        body: config.body,
+        signal: AbortSignal.timeout(timeout),
+      });
+
+      // Read body with size limit
+      const chunks: Buffer[] = [];
+      let totalSize = 0;
+
+      for await (const chunk of response.body) {
+        totalSize += chunk.length;
+        if (totalSize > maxSize) {
+          throw new Error(`Response size exceeded ${maxSize} bytes`);
+        }
+        chunks.push(chunk);
+      }
+
+      // Convert headers to Record<string, string>
+      const headers: Record<string, string> = {};
+      for (const [key, value] of Object.entries(response.headers)) {
+        headers[key] = Array.isArray(value) ? value[0] : value || "";
+      }
+
+      return {
+        statusCode: response.statusCode,
+        headers,
+        body: Buffer.concat(chunks).toString("utf-8"),
+      };
+    } catch (error) {
+      if (error instanceof Error) {
+        throw error;
+      }
+      throw new Error(`HTTP request failed: ${String(error)}`);
+    }
+  }
+}
+
+// Singleton instance
+export const httpClient = new HTTPClient();

package/src/utils/logger.ts

@@ -0,0 +1,138 @@
+import chalk from "chalk";
+import {inspect} from "node:util";
+
+export type LogLevel = "debug" | "info" | "success" | "warn" | "error";
+
+export interface Logger {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  success: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  child: (scope: string, levelOverride?: LogLevel) => Logger;
+  level: LogLevel;
+}
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  success: 25,
+  warn: 30,
+  error: 40,
+};
+
+const LEVEL_COLORS: Record<LogLevel, typeof chalk.gray> = {
+  debug: chalk.gray,
+  info: chalk.blue,
+  success: chalk.green,
+  warn: chalk.yellow,
+  error: chalk.red,
+};
+
+const LEVEL_WRITERS: Record<LogLevel, (...args: unknown[]) => void> = {
+  debug: (...args) => getWriter("debug")(...args),
+  info: (...args) => getWriter("info")(...args),
+  success: (...args) => getWriter("success")(...args),
+  warn: (...args) => getWriter("warn")(...args),
+  error: (...args) => getWriter("error")(...args),
+};
+
+const GLOBAL_LEVEL = resolveLogLevel(process.env.MCP_LOG_LEVEL ?? process.env.LOG_LEVEL ?? "info");
+
+export let forceStdErrMode = false;
+export function _setForceStdErrMode(value: boolean) {
+  forceStdErrMode = value;
+}
+
+function getWriter(level: LogLevel) {
+  if (forceStdErrMode) {
+    return console.error;
+  }
+  switch (level) {
+    case "debug":
+    case "info":
+    case "success":
+      return console.log;
+    case "warn":
+      return console.warn;
+    case "error":
+      return console.error;
+  }
+}
+
+/**
+ * Public log function for quick one-off logs without creating a scoped logger.
+ */
+export function log(level: LogLevel, ...args: unknown[]) {
+  writeLog(level, GLOBAL_LEVEL, undefined, args);
+}
+
+/**
+ * Creates a scoped logger instance. Child loggers inherit the current level unless overridden.
+ */
+export function createLogger(scope?: string, level: LogLevel = GLOBAL_LEVEL): Logger {
+  const write =
+    (targetLevel: LogLevel) =>
+    (...args: unknown[]) =>
+      writeLog(targetLevel, level, scope, args);
+
+  return {
+    level,
+    debug: write("debug"),
+    info: write("info"),
+    success: write("success"),
+    warn: write("warn"),
+    error: write("error"),
+    child(childScope: string, levelOverride?: LogLevel) {
+      const nextScope = scope ? `${scope}:${childScope}` : childScope;
+      return createLogger(nextScope, levelOverride ?? level);
+    },
+  };
+}
+
+const defaultLogger = createLogger();
+
+export default defaultLogger;
+export {LOG_LEVELS};
+
+function writeLog(level: LogLevel, threshold: LogLevel, scope: string | undefined, args: unknown[]) {
+  if (LOG_LEVELS[level] < LOG_LEVELS[threshold]) {
+    return;
+  }
+
+  const prefix = LEVEL_COLORS[level](`[${level.toUpperCase()}]`);
+  const scopeLabel = scope ? chalk.magenta(`[${scope}]`) : undefined;
+  const timestamp = chalk.dim(new Date().toISOString());
+  const writer = LEVEL_WRITERS[level];
+  const formatter = LEVEL_COLORS[level];
+  const formattedArgs = args.map((value) => formatter(formatValue(value)));
+
+  const header = [timestamp, prefix, scopeLabel].filter(Boolean);
+  writer(...header, ...formattedArgs);
+}
+
+function resolveLogLevel(raw: string): LogLevel {
+  const normalized = raw.toLowerCase() as LogLevel;
+  if (normalized in LOG_LEVELS) {
+    return normalized;
+  }
+
+  return "info";
+}
+
+function formatValue(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (value instanceof Error) {
+    return value.stack ?? `${value.name}: ${value.message}`;
+  }
+
+  return inspect(value, {
+    depth: 5,
+    breakLength: 80,
+    compact: false,
+    colors: chalk.level > 0,
+  });
+}

package/src/utils/zod-to-mcp-schema.ts

@@ -0,0 +1,127 @@
+import { zodToJsonSchema, type Options } from 'zod-to-json-schema';
+import { z, type ZodTypeAny } from 'zod';
+import type { JsonSchema } from '../core/types.js';
+
+// Options are optional; wrap in Partial to allow calling with {} or nothing.
+export type McpSchemaOptions = Partial<Options> & {
+  /**
+   * Fallback value used when normalizing non-boolean additionalProperties.
+   * MCP requires boolean; default is true for permissive maps.
+   */
+  additionalPropertiesFallback?: boolean;
+  /**
+   * Removes "$schema" fields from generated JSON Schema.
+   * Enabled by default to keep MCP payloads compact and uniform.
+   */
+  stripMetaSchema?: boolean;
+};
+
+/**
+ * Deeply normalizes a JSON Schema so every `additionalProperties` is boolean.
+ * Keep exported in this file to centralize MCP compatibility tweaks and make
+ * future converter upgrades (e.g., if upstream fixes this) easy.
+ */
+export function fixAdditionalProperties<T>(schema: T, fallback = true): T {
+  const clone = cloneSchema(schema);
+  return normalize(clone, fallback);
+}
+
+/**
+ * Recursively unwraps a Zod schema to check if its core type is a ZodArray.
+ * This is necessary because methods like .describe() wrap the schema in a
+ * ZodEffects object, which hides the underlying type.
+ */
+export function isZodArray(schema: ZodTypeAny): boolean {
+  if (schema instanceof z.ZodArray) {
+    return true;
+  }
+  if (schema instanceof z.ZodEffects) {
+    return isZodArray(schema.innerType());
+  }
+  return false;
+}
+
+/**
+ * Converts a Zod schema to JSON Schema and enforces MCP's requirement
+ * that every `additionalProperties` field is a boolean.
+ *
+ * If the schema is an array type (even if wrapped), it will be wrapped
+ * in an object with a 'result' property.
+ */
+export function zodToMcpJsonSchema(
+  schema: ZodTypeAny,
+  options?: McpSchemaOptions,
+) {
+  const {
+    additionalPropertiesFallback = true,
+    stripMetaSchema = true,
+    ...converterOptions
+  } = options ?? {};
+  const jsonSchema = zodToJsonSchema(schema, converterOptions as Options | undefined) as JsonSchema;
+
+  const normalized = isZodArray(schema)
+    ? fixAdditionalProperties(
+        {
+          type: 'object',
+          properties: {
+            result: jsonSchema,
+          },
+        },
+        additionalPropertiesFallback,
+      )
+    : fixAdditionalProperties(jsonSchema, additionalPropertiesFallback);
+
+  return stripMetaSchema ? removeMetaSchema(normalized) : normalized;
+}
+
+export default zodToMcpJsonSchema;
+
+function removeMetaSchema<T>(node: T): T {
+  if (Array.isArray(node)) {
+    return node.map((item) => removeMetaSchema(item)) as T;
+  }
+
+  if (node === null || typeof node !== 'object') {
+    return node;
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+    if (key === '$schema') {
+      continue;
+    }
+    result[key] = removeMetaSchema(value);
+  }
+
+  return result as T;
+}
+
+function normalize(node: unknown, fallback: boolean): any {
+  if (Array.isArray(node)) {
+    return node.map((child) => normalize(child, fallback));
+  }
+
+  if (node === null || typeof node !== 'object') {
+    return node;
+  }
+
+  const result: Record<string, unknown> = { ...(node as Record<string, unknown>) };
+
+  if ('additionalProperties' in result && typeof result.additionalProperties !== 'boolean') {
+    result.additionalProperties = fallback;
+  }
+
+  for (const key of Object.keys(result)) {
+    if (key === 'additionalProperties') continue;
+    result[key] = normalize(result[key], fallback);
+  }
+
+  return result;
+}
+
+function cloneSchema<T>(schema: T): T {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(schema);
+  }
+  return JSON.parse(JSON.stringify(schema));
+}