Mg Connector

code manifest → registry.ts → sync.ts → DB connectors_catalog
                                          ↓
                              org creates connector instance (with config/secrets)
                                          ↓
                              AI agent calls tool via MCP → handler executes with resolved config

interface ToolExecutionContext {
  config: Record<string, string>;   // resolved config (secrets decrypted)
  input: Record<string, unknown>;   // validated tool input from MCP call
  organizationId: string;
  connectorId: string;
}

interface ToolExecutionResult {
  success: boolean;
  data?: Record<string, unknown>;
  error?: string;
}

interface ConnectorToolDefinition {
  catalog: CatalogTool;             // metadata stored in DB
  handler: (ctx: ToolExecutionContext) => Promise<ToolExecutionResult>;
}

interface ConfigFieldSchema {
  type: "string" | "secret" | "number" | "boolean";
  required: boolean;
  description: string;
  default?: string | number | boolean;
}

type ConnectorType = "api" | "webhook" | "database" | "messaging";

interface ConnectorManifest {
  name: string;                     // Human-readable, e.g. "Medusa"
  slug: string;                     // URL-safe unique ID, e.g. "medusa"
  description: string;
  connectorType: ConnectorType;
  configSchema: Record<string, ConfigFieldSchema>;
  authMethods: string[];            // e.g. ["api_key"], ["oauth2"], ["bearer_token"]
  iconUrl: string;
  tools: ConnectorToolDefinition[];
}

interface CatalogTool {
  name: string;                        // Human-readable, e.g. "List Products"
  description: string;
  inputSchema: Record<string, unknown>; // JSON Schema
  defaultRequiresConfirmation: boolean;
  defaultTimeoutSeconds: number;
}

// modelguide-api/src/features/connectors/catalog/{slug}/client.ts

interface {Name}FetchOptions {
  method?: string;
  body?: Record<string, unknown>;
  params?: Record<string, string | number | undefined>;
}

export class {Name}ApiError extends Error {
  constructor(
    public status: number,
    public body: string,
  ) {
    super(`{Name} API error ${status}: ${body}`);
    this.name = "{Name}ApiError";
  }
}

export type {Name}Fetcher = <T = unknown>(
  path: string,
  options?: {Name}FetchOptions,
) => Promise<T>;

export function create{Name}Fetcher(
  config: Record<string, string>,
): {Name}Fetcher {
  const baseUrl = config.baseUrl?.replace(/\/+$/, "");
  if (!baseUrl) {
    throw new Error("{Name} baseUrl is required");
  }

  const headers: Record<string, string> = {
    "Content-Type": "application/json",
    Accept: "application/json",
  };

  // Add auth headers based on the service's auth method
  if (config.apiKey) {
    headers["Authorization"] = `Bearer ${config.apiKey}`;
  }

  return async function fetch<T = unknown>(
    path: string,
    options?: {Name}FetchOptions,
  ): Promise<T> {
    const { method = "GET", body, params } = options ?? {};

    let url = `${baseUrl}${path}`;
    if (params) {
      const entries = Object.entries(params).filter(([, v]) => v !== undefined);
      if (entries.length > 0) {
        const qs = new URLSearchParams(entries.map(([k, v]) => [k, String(v)]));
        url += `?${qs}`;
      }
    }

    const response = await fetch(url, {
      method,
      headers,
      body: body ? JSON.stringify(body) : undefined,
    });

    if (!response.ok) {
      const text = await response.text();
      throw new {Name}ApiError(response.status, text);
    }

    return response.json() as Promise<T>;
  };
}

// modelguide-api/src/features/connectors/catalog/{slug}/handlers.ts

import type { ToolExecutionContext, ToolExecutionResult } from "../types";
import {
  {Name}ApiError,
  type {Name}Fetcher,
  create{Name}Fetcher,
} from "./client";

function errorResult(err: unknown): ToolExecutionResult {
  if (err instanceof {Name}ApiError) {
    return { success: false, error: `{Name} API ${err.status}: ${err.body}` };
  }
  const message = err instanceof Error ? err.message : String(err);
  return { success: false, error: message };
}

/**
 * Wraps a handler so every tool gets a fetcher and consistent error handling.
 */
function with{Name}(
  fn: (
    fetcher: {Name}Fetcher,
    ctx: ToolExecutionContext,
  ) => Promise<ToolExecutionResult>,
): (ctx: ToolExecutionContext) => Promise<ToolExecutionResult> {
  return async function handler(ctx) {
    try {
      const fetcher = create{Name}Fetcher(ctx.config);
      return await fn(fetcher, ctx);
    } catch (err) {
      return errorResult(err);
    }
  };
}

// Export one handler per tool:
export const listSomething = with{Name}(async (fetcher, ctx) => {
  const input = ctx.input as { /* typed input */ };
  const data = await fetcher<Record<string, unknown>>("/api/endpoint", {
    params: { /* query params */ },
  });
  return { success: true, data };
});