@squadbase/vite-server 0.1.10-dev.5aa0720 → 0.1.10-dev.5b0c0a8

package/dist/connectors/mongodb.js

@@ -0,0 +1,879 @@
+// ../connectors/src/parameter-definition.ts
+var ParameterDefinition = class {
+  slug;
+  name;
+  description;
+  envVarBaseKey;
+  type;
+  secret;
+  required;
+  constructor(config) {
+    this.slug = config.slug;
+    this.name = config.name;
+    this.description = config.description;
+    this.envVarBaseKey = config.envVarBaseKey;
+    this.type = config.type;
+    this.secret = config.secret;
+    this.required = config.required;
+  }
+  /**
+   * Get the parameter value from a ConnectorConnectionObject.
+   */
+  getValue(connection2) {
+    const param = connection2.parameters.find(
+      (p) => p.parameterSlug === this.slug
+    );
+    if (!param || param.value == null) {
+      throw new Error(
+        `Parameter "${this.slug}" not found or has no value in connection "${connection2.id}"`
+      );
+    }
+    return param.value;
+  }
+  /**
+   * Try to get the parameter value. Returns undefined if not found (for optional params).
+   */
+  tryGetValue(connection2) {
+    const param = connection2.parameters.find(
+      (p) => p.parameterSlug === this.slug
+    );
+    if (!param || param.value == null) return void 0;
+    return param.value;
+  }
+};
+
+// ../connectors/src/connectors/mongodb/parameters.ts
+var parameters = {
+  connectionUrl: new ParameterDefinition({
+    slug: "connection-url",
+    name: "MongoDB Connection URL",
+    description: "The MongoDB connection string (e.g., mongodb+srv://user:password@cluster.mongodb.net or mongodb://user:password@host:27017).",
+    envVarBaseKey: "MONGODB_URL",
+    type: "text",
+    secret: true,
+    required: true
+  }),
+  database: new ParameterDefinition({
+    slug: "database",
+    name: "MongoDB Database",
+    description: "The database name to connect to.",
+    envVarBaseKey: "MONGODB_DATABASE",
+    type: "text",
+    secret: false,
+    required: true
+  })
+};
+
+// ../connectors/src/connectors/mongodb/sdk/index.ts
+var CONNECT_TIMEOUT_MS = 1e4;
+var QUERY_TIMEOUT_MS = 6e4;
+function createClient(params) {
+  const connectionUrl = params[parameters.connectionUrl.slug];
+  if (!connectionUrl) {
+    throw new Error(
+      `mongodb: missing required parameter: ${parameters.connectionUrl.slug}`
+    );
+  }
+  const database = params[parameters.database.slug];
+  if (!database) {
+    throw new Error(
+      `mongodb: missing required parameter: ${parameters.database.slug}`
+    );
+  }
+  function redact(message) {
+    return message.replaceAll(connectionUrl, "***");
+  }
+  function serializeDocument(doc) {
+    const out = {};
+    for (const [key, value] of Object.entries(doc)) {
+      out[key] = value !== null && typeof value === "object" && "toHexString" in value && typeof value.toHexString === "function" ? String(value) : value;
+    }
+    return out;
+  }
+  async function withDb(fn) {
+    const { MongoClient } = await import("mongodb");
+    const client = new MongoClient(connectionUrl, {
+      connectTimeoutMS: CONNECT_TIMEOUT_MS,
+      serverSelectionTimeoutMS: CONNECT_TIMEOUT_MS,
+      socketTimeoutMS: QUERY_TIMEOUT_MS
+    });
+    try {
+      await client.connect();
+      return await fn(client.db(database));
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(redact(msg));
+    } finally {
+      await client.close();
+    }
+  }
+  async function aggregate(collection, pipeline, options) {
+    return withDb(async (db) => {
+      const cursor = db.collection(collection).aggregate(pipeline, options);
+      const documents = await cursor.toArray();
+      return documents.map(serializeDocument);
+    });
+  }
+  async function find(collection, filter = {}, options = {}) {
+    return withDb(async (db) => {
+      let cursor = db.collection(collection).find(filter);
+      if (options.projection) cursor = cursor.project(options.projection);
+      if (options.sort) cursor = cursor.sort(options.sort);
+      if (options.skip != null) cursor = cursor.skip(options.skip);
+      if (options.limit != null) cursor = cursor.limit(options.limit);
+      const documents = await cursor.toArray();
+      return documents.map(serializeDocument);
+    });
+  }
+  async function findOne(collection, filter = {}, options = {}) {
+    const docs = await find(collection, filter, { ...options, limit: 1 });
+    return docs.length > 0 ? docs[0] : null;
+  }
+  async function countDocuments(collection, filter = {}) {
+    return withDb(async (db) => {
+      return db.collection(collection).countDocuments(filter);
+    });
+  }
+  async function listCollections() {
+    return withDb(async (db) => {
+      const list = await db.listCollections().toArray();
+      return list.map((c) => ({ name: c.name, type: c.type ?? "collection" }));
+    });
+  }
+  return {
+    aggregate,
+    find,
+    findOne,
+    countDocuments,
+    listCollections
+  };
+}
+
+// ../connectors/src/connector-onboarding.ts
+var ConnectorOnboarding = class {
+  /** Phase 1: Connection setup instructions (optional — some connectors don't need this) */
+  connectionSetupInstructions;
+  /** Phase 2: Data overview instructions */
+  dataOverviewInstructions;
+  constructor(config) {
+    this.connectionSetupInstructions = config.connectionSetupInstructions;
+    this.dataOverviewInstructions = config.dataOverviewInstructions;
+  }
+  getConnectionSetupPrompt(language) {
+    return this.connectionSetupInstructions?.[language] ?? null;
+  }
+  getDataOverviewInstructions(language) {
+    return this.dataOverviewInstructions[language];
+  }
+};
+
+// ../connectors/src/connector-tool.ts
+var ConnectorTool = class {
+  name;
+  description;
+  inputSchema;
+  outputSchema;
+  _execute;
+  constructor(config) {
+    this.name = config.name;
+    this.description = config.description;
+    this.inputSchema = config.inputSchema;
+    this.outputSchema = config.outputSchema;
+    this._execute = config.execute;
+  }
+  createTool(connections, config) {
+    return {
+      description: this.description,
+      inputSchema: this.inputSchema,
+      outputSchema: this.outputSchema,
+      execute: (input) => this._execute(input, connections, config)
+    };
+  }
+};
+
+// ../connectors/src/connector-plugin.ts
+var ConnectorPlugin = class _ConnectorPlugin {
+  slug;
+  authType;
+  name;
+  description;
+  iconUrl;
+  parameters;
+  releaseFlag;
+  proxyPolicy;
+  experimentalAttributes;
+  categories;
+  onboarding;
+  systemPrompt;
+  tools;
+  query;
+  checkConnection;
+  constructor(config) {
+    this.slug = config.slug;
+    this.authType = config.authType;
+    this.name = config.name;
+    this.description = config.description;
+    this.iconUrl = config.iconUrl;
+    this.parameters = config.parameters;
+    this.releaseFlag = config.releaseFlag;
+    this.proxyPolicy = config.proxyPolicy;
+    this.experimentalAttributes = config.experimentalAttributes;
+    this.categories = config.categories ?? [];
+    this.onboarding = config.onboarding;
+    this.systemPrompt = config.systemPrompt;
+    this.tools = config.tools;
+    this.query = config.query;
+    this.checkConnection = config.checkConnection;
+  }
+  get connectorKey() {
+    return _ConnectorPlugin.deriveKey(this.slug, this.authType);
+  }
+  /**
+   * Create tools for connections that belong to this connector.
+   * Filters connections by connectorKey internally.
+   * Returns tools keyed as `${connectorKey}_${toolName}`.
+   */
+  createTools(connections, config, opts) {
+    const myConnections = connections.filter(
+      (c) => _ConnectorPlugin.deriveKey(c.connector.slug, c.connector.authType) === this.connectorKey
+    );
+    const result = {};
+    for (const t of Object.values(this.tools)) {
+      const tool = t.createTool(myConnections, config);
+      const originalToModelOutput = tool.toModelOutput;
+      result[`${this.connectorKey}_${t.name}`] = {
+        ...tool,
+        toModelOutput: async (options) => {
+          if (!originalToModelOutput) {
+            return opts.truncateOutput(options.output);
+          }
+          const modelOutput = await originalToModelOutput(options);
+          if (modelOutput.type === "text" || modelOutput.type === "json") {
+            return opts.truncateOutput(modelOutput.value);
+          }
+          return modelOutput;
+        }
+      };
+    }
+    return result;
+  }
+  static deriveKey(slug, authType) {
+    if (authType) return `${slug}-${authType}`;
+    const LEGACY_NULL_AUTH_TYPE_MAP = {
+      // user-password
+      "postgresql": "user-password",
+      "mysql": "user-password",
+      "clickhouse": "user-password",
+      "kintone": "user-password",
+      "squadbase-db": "user-password",
+      // service-account
+      "snowflake": "service-account",
+      "bigquery": "service-account",
+      "google-analytics": "service-account",
+      "google-calendar": "service-account",
+      "aws-athena": "service-account",
+      "redshift": "service-account",
+      // api-key
+      "databricks": "api-key",
+      "dbt": "api-key",
+      "airtable": "api-key",
+      "openai": "api-key",
+      "gemini": "api-key",
+      "anthropic": "api-key",
+      "wix-store": "api-key"
+    };
+    const fallbackAuthType = LEGACY_NULL_AUTH_TYPE_MAP[slug];
+    if (fallbackAuthType) return `${slug}-${fallbackAuthType}`;
+    return slug;
+  }
+};
+
+// ../connectors/src/auth-types.ts
+var AUTH_TYPES = {
+  OAUTH: "oauth",
+  API_KEY: "api-key",
+  JWT: "jwt",
+  SERVICE_ACCOUNT: "service-account",
+  PAT: "pat",
+  USER_PASSWORD: "user-password"
+};
+
+// ../connectors/src/connectors/mongodb/setup.ts
+var mongodbOnboarding = new ConnectorOnboarding({
+  dataOverviewInstructions: {
+    en: `1. Use listCollections to list all collections in the database
+2. For key collections, use find with limit to sample documents: collection="users", filter="{}", limit=5
+3. Examine the document structure to understand the schema (MongoDB is schema-flexible, so documents in the same collection may have different fields)
+4. Use aggregate with $group to understand data distribution if needed: pipeline='[{"$group": {"_id": "$fieldName", "count": {"$sum": 1}}}, {"$limit": 20}]'`,
+    ja: `1. listCollections \u3067\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u5185\u306E\u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u4E00\u89A7\u3092\u53D6\u5F97
+2. \u4E3B\u8981\u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u306B\u3064\u3044\u3066 find \u3067\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u3092\u30B5\u30F3\u30D7\u30EA\u30F3\u30B0: collection="users", filter="{}", limit=5
+3. \u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u69CB\u9020\u3092\u78BA\u8A8D\u3057\u3066\u30B9\u30AD\u30FC\u30DE\u3092\u628A\u63E1\uFF08MongoDB\u306F\u30B9\u30AD\u30FC\u30DE\u304C\u67D4\u8EDF\u306A\u305F\u3081\u3001\u540C\u3058\u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u5185\u3067\u3082\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u306E\u30D5\u30A3\u30FC\u30EB\u30C9\u304C\u7570\u306A\u308B\u5834\u5408\u304C\u3042\u308A\u307E\u3059\uFF09
+4. \u5FC5\u8981\u306B\u5FDC\u3058\u3066 aggregate \u306E $group \u3067\u30C7\u30FC\u30BF\u5206\u5E03\u3092\u78BA\u8A8D: pipeline='[{"$group": {"_id": "$fieldName", "count": {"$sum": 1}}}, {"$limit": 20}]'`
+  }
+});
+
+// ../connectors/src/connectors/mongodb/tools/find-documents.ts
+import { z } from "zod";
+var MAX_DOCUMENTS = 500;
+var CONNECT_TIMEOUT_MS2 = 1e4;
+var QUERY_TIMEOUT_MS2 = 6e4;
+var inputSchema = z.object({
+  toolUseIntent: z.string().optional().describe(
+    "Brief description of what you intend to accomplish with this tool call"
+  ),
+  connectionId: z.string().describe("ID of the MongoDB connection to use"),
+  collection: z.string().describe("The name of the collection to query"),
+  filter: z.string().optional().describe(
+    `MongoDB filter query as a JSON string (e.g., '{"status": "active"}', '{"age": {"$gt": 25}}'). Defaults to '{}' (all documents).`
+  ),
+  projection: z.string().optional().describe(
+    `MongoDB projection as a JSON string to include/exclude fields (e.g., '{"name": 1, "email": 1}' to include only name and email).`
+  ),
+  sort: z.string().optional().describe(
+    `MongoDB sort specification as a JSON string (e.g., '{"createdAt": -1}' for descending by createdAt).`
+  ),
+  limit: z.number().optional().describe(
+    `Maximum number of documents to return. Defaults to ${MAX_DOCUMENTS}. Cannot exceed ${MAX_DOCUMENTS}.`
+  )
+});
+var outputSchema = z.discriminatedUnion("success", [
+  z.object({
+    success: z.literal(true),
+    documentCount: z.number(),
+    truncated: z.boolean(),
+    documents: z.array(z.record(z.string(), z.unknown()))
+  }),
+  z.object({
+    success: z.literal(false),
+    error: z.string()
+  })
+]);
+var findDocumentsTool = new ConnectorTool({
+  name: "find",
+  description: `Find documents in a MongoDB collection. Returns up to ${MAX_DOCUMENTS} documents.
+Use for: querying documents with filters, projecting specific fields, sorting results, and data sampling.
+Pass filter, projection, and sort as JSON strings. Always use limit to avoid loading large amounts of data.
+For listing collections, use the aggregate tool with an empty pipeline on the special collection name "$cmd.listCollections".`,
+  inputSchema,
+  outputSchema,
+  async execute({ connectionId, collection, filter, projection, sort, limit }, connections) {
+    const connection2 = connections.find((c) => c.id === connectionId);
+    if (!connection2) {
+      return {
+        success: false,
+        error: `Connection ${connectionId} not found`
+      };
+    }
+    console.log(
+      `[connector-query] mongodb/${connection2.name}: find in ${collection}`
+    );
+    let connectionUrl;
+    try {
+      const { MongoClient } = await import("mongodb");
+      connectionUrl = parameters.connectionUrl.getValue(connection2);
+      const database = parameters.database.getValue(connection2);
+      const client = new MongoClient(connectionUrl, {
+        connectTimeoutMS: CONNECT_TIMEOUT_MS2,
+        serverSelectionTimeoutMS: CONNECT_TIMEOUT_MS2,
+        socketTimeoutMS: QUERY_TIMEOUT_MS2
+      });
+      try {
+        await client.connect();
+        const db = client.db(database);
+        const coll = db.collection(collection);
+        const parsedFilter = filter ? JSON.parse(filter) : {};
+        const parsedProjection = projection ? JSON.parse(projection) : void 0;
+        const parsedSort = sort ? JSON.parse(sort) : void 0;
+        const effectiveLimit = Math.min(limit ?? MAX_DOCUMENTS, MAX_DOCUMENTS);
+        let cursor = coll.find(parsedFilter);
+        if (parsedProjection) cursor = cursor.project(parsedProjection);
+        if (parsedSort) cursor = cursor.sort(parsedSort);
+        cursor = cursor.limit(effectiveLimit + 1);
+        const documents = await cursor.toArray();
+        const truncated = documents.length > effectiveLimit;
+        const resultDocs = documents.slice(0, effectiveLimit).map((doc) => {
+          const obj = {};
+          for (const [key, value] of Object.entries(doc)) {
+            obj[key] = value instanceof Object && "toHexString" in value ? String(value) : value;
+          }
+          return obj;
+        });
+        return {
+          success: true,
+          documentCount: resultDocs.length,
+          truncated,
+          documents: resultDocs
+        };
+      } finally {
+        await client.close();
+      }
+    } catch (err) {
+      let msg = err instanceof Error ? err.message : String(err);
+      if (connectionUrl) {
+        msg = msg.replaceAll(connectionUrl, "***");
+      }
+      return { success: false, error: msg };
+    }
+  }
+});
+
+// ../connectors/src/connectors/mongodb/tools/aggregate.ts
+import { z as z2 } from "zod";
+var MAX_DOCUMENTS2 = 500;
+var CONNECT_TIMEOUT_MS3 = 1e4;
+var QUERY_TIMEOUT_MS3 = 6e4;
+var inputSchema2 = z2.object({
+  toolUseIntent: z2.string().optional().describe(
+    "Brief description of what you intend to accomplish with this tool call"
+  ),
+  connectionId: z2.string().describe("ID of the MongoDB connection to use"),
+  collection: z2.string().describe("The name of the collection to run the aggregation pipeline on"),
+  pipeline: z2.string().describe(
+    `MongoDB aggregation pipeline as a JSON string. An array of stage objects (e.g., '[{"$match": {"status": "active"}}, {"$group": {"_id": "$category", "count": {"$sum": 1}}}]'). Always include a $limit stage to avoid returning too many documents.`
+  )
+});
+var outputSchema2 = z2.discriminatedUnion("success", [
+  z2.object({
+    success: z2.literal(true),
+    documentCount: z2.number(),
+    truncated: z2.boolean(),
+    documents: z2.array(z2.record(z2.string(), z2.unknown()))
+  }),
+  z2.object({
+    success: z2.literal(false),
+    error: z2.string()
+  })
+]);
+var aggregateTool = new ConnectorTool({
+  name: "aggregate",
+  description: `Run a MongoDB aggregation pipeline on a collection. Returns up to ${MAX_DOCUMENTS2} documents.
+Use for: complex data transformations, grouping, filtering, joining (via $lookup), statistical calculations, and data analysis.
+Pass the pipeline as a JSON string representing an array of aggregation stages.
+Always include a $limit stage in the pipeline to avoid loading large amounts of data.
+Common stages: $match (filter), $group (aggregate), $sort (order), $project (reshape), $lookup (join), $unwind (flatten arrays).`,
+  inputSchema: inputSchema2,
+  outputSchema: outputSchema2,
+  async execute({ connectionId, collection, pipeline }, connections) {
+    const connection2 = connections.find((c) => c.id === connectionId);
+    if (!connection2) {
+      return {
+        success: false,
+        error: `Connection ${connectionId} not found`
+      };
+    }
+    console.log(
+      `[connector-query] mongodb/${connection2.name}: aggregate on ${collection}`
+    );
+    let connectionUrl;
+    try {
+      const { MongoClient } = await import("mongodb");
+      connectionUrl = parameters.connectionUrl.getValue(connection2);
+      const database = parameters.database.getValue(connection2);
+      const client = new MongoClient(connectionUrl, {
+        connectTimeoutMS: CONNECT_TIMEOUT_MS3,
+        serverSelectionTimeoutMS: CONNECT_TIMEOUT_MS3,
+        socketTimeoutMS: QUERY_TIMEOUT_MS3
+      });
+      try {
+        await client.connect();
+        const db = client.db(database);
+        const coll = db.collection(collection);
+        const parsedPipeline = JSON.parse(pipeline);
+        const documents = await coll.aggregate(parsedPipeline).toArray();
+        const truncated = documents.length > MAX_DOCUMENTS2;
+        const resultDocs = documents.slice(0, MAX_DOCUMENTS2).map((doc) => {
+          const obj = {};
+          for (const [key, value] of Object.entries(doc)) {
+            obj[key] = value instanceof Object && "toHexString" in value ? String(value) : value;
+          }
+          return obj;
+        });
+        return {
+          success: true,
+          documentCount: resultDocs.length,
+          truncated,
+          documents: resultDocs
+        };
+      } finally {
+        await client.close();
+      }
+    } catch (err) {
+      let msg = err instanceof Error ? err.message : String(err);
+      if (connectionUrl) {
+        msg = msg.replaceAll(connectionUrl, "***");
+      }
+      return { success: false, error: msg };
+    }
+  }
+});
+
+// ../connectors/src/connectors/mongodb/tools/list-collections.ts
+import { z as z3 } from "zod";
+var CONNECT_TIMEOUT_MS4 = 1e4;
+var inputSchema3 = z3.object({
+  toolUseIntent: z3.string().optional().describe(
+    "Brief description of what you intend to accomplish with this tool call"
+  ),
+  connectionId: z3.string().describe("ID of the MongoDB connection to use")
+});
+var outputSchema3 = z3.discriminatedUnion("success", [
+  z3.object({
+    success: z3.literal(true),
+    collections: z3.array(z3.object({
+      name: z3.string(),
+      type: z3.string()
+    }))
+  }),
+  z3.object({
+    success: z3.literal(false),
+    error: z3.string()
+  })
+]);
+var listCollectionsTool = new ConnectorTool({
+  name: "listCollections",
+  description: `List all collections in the MongoDB database.
+Use this as the first step to explore the data structure. Returns collection names and types.
+After listing collections, use the find tool to sample documents and understand the schema of each collection.`,
+  inputSchema: inputSchema3,
+  outputSchema: outputSchema3,
+  async execute({ connectionId }, connections) {
+    const connection2 = connections.find((c) => c.id === connectionId);
+    if (!connection2) {
+      return {
+        success: false,
+        error: `Connection ${connectionId} not found`
+      };
+    }
+    console.log(
+      `[connector-query] mongodb/${connection2.name}: listCollections`
+    );
+    let connectionUrl;
+    try {
+      const { MongoClient } = await import("mongodb");
+      connectionUrl = parameters.connectionUrl.getValue(connection2);
+      const database = parameters.database.getValue(connection2);
+      const client = new MongoClient(connectionUrl, {
+        connectTimeoutMS: CONNECT_TIMEOUT_MS4,
+        serverSelectionTimeoutMS: CONNECT_TIMEOUT_MS4
+      });
+      try {
+        await client.connect();
+        const db = client.db(database);
+        const collections = await db.listCollections().toArray();
+        return {
+          success: true,
+          collections: collections.map((c) => ({
+            name: c.name,
+            type: c.type || "collection"
+          }))
+        };
+      } finally {
+        await client.close();
+      }
+    } catch (err) {
+      let msg = err instanceof Error ? err.message : String(err);
+      if (connectionUrl) {
+        msg = msg.replaceAll(connectionUrl, "***");
+      }
+      return { success: false, error: msg };
+    }
+  }
+});
+
+// ../connectors/src/connectors/mongodb/index.ts
+var tools = {
+  find: findDocumentsTool,
+  aggregate: aggregateTool,
+  listCollections: listCollectionsTool
+};
+var mongodbConnector = new ConnectorPlugin({
+  slug: "mongodb",
+  authType: AUTH_TYPES.USER_PASSWORD,
+  name: "MongoDB",
+  description: "Connect to MongoDB for document-oriented data storage and querying.",
+  iconUrl: "https://images.ctfassets.net/9ncizv60xc5y/48JSUx9HE6oSa9JrHGg2E1/12b4cac65924cac3641d4bafcef37dbe/mongodb-icon.webp",
+  parameters,
+  releaseFlag: { dev1: true, dev2: true, prod: true },
+  categories: ["database"],
+  onboarding: mongodbOnboarding,
+  systemPrompt: {
+    en: `### Tools
+
+- \`mongodb_listCollections\`: Lists all collections in the database. Use this first to explore available data.
+- \`mongodb_find\`: Finds documents in a collection with optional filter, projection, sort, and limit. Use for data sampling and querying specific documents. Pass filter, projection, and sort as JSON strings.
+- \`mongodb_aggregate\`: Runs a MongoDB aggregation pipeline on a collection. Use for complex data analysis, grouping, joining, and transformations. Pass pipeline as a JSON string.
+
+### Business Logic
+
+The business logic type for this connector is "typescript". Write handler code using the connector SDK shown below. Do NOT access credentials directly from environment variables, and do NOT \`import { MongoClient } from "mongodb"\` in handler code \u2014 the \`mongodb\` driver is not part of the user dashboard's runtime, only of the connector SDK.
+
+\u26A0\uFE0F **The client returned by \`connection(connectionId)\` is NOT a raw \`mongodb\` \`MongoClient\`.** It is a thin wrapper that opens a fresh connection per call, runs the requested operation against the database configured on the connection, and converts BSON \`ObjectId\` values to their hex string for JSON-safe responses. The methods are:
+
+- \`client.aggregate<T>(collection, pipeline, options?) => Promise<T[]>\` \u2014 runs an aggregation pipeline and returns the document array. Always include a \`$limit\` stage.
+- \`client.find<T>(collection, filter?, options?) => Promise<T[]>\` \u2014 \`options\` accepts \`{ projection?, sort?, limit?, skip? }\`. Always pass \`limit\`.
+- \`client.findOne<T>(collection, filter?, options?) => Promise<T | null>\` \u2014 convenience wrapper around \`find\` with \`limit: 1\`.
+- \`client.countDocuments(collection, filter?) => Promise<number>\` \u2014 accurate count (not \`estimatedDocumentCount\`).
+- \`client.listCollections() => Promise<{ name: string; type: string }[]>\` \u2014 collections in the configured database.
+
+There is **no** \`client.db(...)\`, \`client.connect()\`, or raw cursor / \`MongoClient\` API exposed through this client \u2014 those calls fail with \`X is not a function\`.
+
+\`\`\`ts
+import type { Context } from "hono";
+import { connection } from "@squadbase/vite-server/connectors/mongodb";
+
+const mongo = connection("<connectionId>");
+
+export default async function handler(_c: Context) {
+  const rows = await mongo.aggregate<{ country: string; count: number }>(
+    "<collectionName>",
+    [
+      { $match: { country: { $nin: [null, ""] } } },
+      { $group: { _id: "$country", count: { $sum: 1 } } },
+      { $sort: { count: -1 } },
+      { $limit: 20 },
+      { $project: { _id: 0, country: "$_id", count: 1 } },
+    ],
+  );
+
+  return new Response(JSON.stringify(rows), {
+    headers: { "Content-Type": "application/json" },
+  });
+}
+\`\`\`
+
+### MongoDB Reference
+- MongoDB stores data as flexible JSON-like documents (BSON)
+- Documents in the same collection can have different fields
+- Query filter operators: \`$eq\`, \`$gt\`, \`$gte\`, \`$lt\`, \`$lte\`, \`$ne\`, \`$in\`, \`$nin\`, \`$and\`, \`$or\`, \`$not\`, \`$regex\`
+- Aggregation stages: \`$match\` (filter), \`$group\` (aggregate), \`$sort\` (order), \`$project\` (reshape), \`$lookup\` (join), \`$unwind\` (flatten arrays), \`$limit\`, \`$skip\`, \`$count\`
+- Aggregation operators: \`$sum\`, \`$avg\`, \`$min\`, \`$max\`, \`$first\`, \`$last\`, \`$push\`, \`$addToSet\`
+- Data exploration pattern:
+  1. listCollections to see available data
+  2. find with limit to sample documents and understand schema
+  3. aggregate with $group to analyze data distribution
+- Always include limit in find queries and $limit in aggregation pipelines`,
+    ja: `### \u30C4\u30FC\u30EB
+
+- \`mongodb_listCollections\`: \u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u5185\u306E\u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u4E00\u89A7\u3092\u53D6\u5F97\u3057\u307E\u3059\u3002\u30C7\u30FC\u30BF\u63A2\u7D22\u306E\u6700\u521D\u306E\u30B9\u30C6\u30C3\u30D7\u3068\u3057\u3066\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002
+- \`mongodb_find\`: \u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u5185\u306E\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u3092\u691C\u7D22\u3057\u307E\u3059\u3002\u30D5\u30A3\u30EB\u30BF\u30FC\u3001\u30D7\u30ED\u30B8\u30A7\u30AF\u30B7\u30E7\u30F3\u3001\u30BD\u30FC\u30C8\u3001\u5236\u9650\u3092\u30AA\u30D7\u30B7\u30E7\u30F3\u3067\u6307\u5B9A\u53EF\u80FD\u3002\u30C7\u30FC\u30BF\u306E\u30B5\u30F3\u30D7\u30EA\u30F3\u30B0\u3084\u7279\u5B9A\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u306E\u30AF\u30A8\u30EA\u306B\u4F7F\u7528\u3057\u307E\u3059\u3002filter\u3001projection\u3001sort\u306FJSON\u6587\u5B57\u5217\u3067\u6E21\u3057\u3066\u304F\u3060\u3055\u3044\u3002
+- \`mongodb_aggregate\`: \u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u4E0A\u3067MongoDB\u96C6\u7D04\u30D1\u30A4\u30D7\u30E9\u30A4\u30F3\u3092\u5B9F\u884C\u3057\u307E\u3059\u3002\u8907\u96D1\u306A\u30C7\u30FC\u30BF\u5206\u6790\u3001\u30B0\u30EB\u30FC\u30D7\u5316\u3001\u7D50\u5408\u3001\u5909\u63DB\u306B\u4F7F\u7528\u3057\u307E\u3059\u3002pipeline\u306FJSON\u6587\u5B57\u5217\u3067\u6E21\u3057\u3066\u304F\u3060\u3055\u3044\u3002
+
+### Business Logic
+
+\u3053\u306E\u30B3\u30CD\u30AF\u30BF\u306E\u30D3\u30B8\u30CD\u30B9\u30ED\u30B8\u30C3\u30AF\u30BF\u30A4\u30D7\u306F "typescript" \u3067\u3059\u3002\u4EE5\u4E0B\u306B\u793A\u3059\u30B3\u30CD\u30AF\u30BFSDK\u3092\u4F7F\u7528\u3057\u3066\u30CF\u30F3\u30C9\u30E9\u30B3\u30FC\u30C9\u3092\u8A18\u8FF0\u3057\u3066\u304F\u3060\u3055\u3044\u3002\u74B0\u5883\u5909\u6570\u304B\u3089\u76F4\u63A5\u8A8D\u8A3C\u60C5\u5831\u306B\u30A2\u30AF\u30BB\u30B9\u3057\u305F\u308A\u3001\u30CF\u30F3\u30C9\u30E9\u30B3\u30FC\u30C9\u3067 \`import { MongoClient } from "mongodb"\` \u3092\u884C\u3063\u305F\u308A\u3057\u306A\u3044\u3067\u304F\u3060\u3055\u3044 \u2014 \`mongodb\` \u30C9\u30E9\u30A4\u30D0\u306F\u30E6\u30FC\u30B6\u30FC\u30C0\u30C3\u30B7\u30E5\u30DC\u30FC\u30C9\u306E\u30E9\u30F3\u30BF\u30A4\u30E0\u306B\u306F\u542B\u307E\u308C\u305A\u3001\u30B3\u30CD\u30AF\u30BFSDK\u5185\u90E8\u306B\u306E\u307F\u5B58\u5728\u3057\u307E\u3059\u3002
+
+\u26A0\uFE0F **\`connection(connectionId)\` \u304C\u8FD4\u3059\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u306F \`mongodb\` \u306E \`MongoClient\` \u305D\u306E\u3082\u306E\u3067\u306F\u3042\u308A\u307E\u305B\u3093\u3002** \u547C\u3073\u51FA\u3057\u3054\u3068\u306B\u65B0\u3057\u3044\u63A5\u7D9A\u3092\u958B\u304D\u3001\u30B3\u30CD\u30AF\u30B7\u30E7\u30F3\u306B\u8A2D\u5B9A\u3055\u308C\u305F\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u306B\u5BFE\u3057\u3066\u64CD\u4F5C\u3092\u5B9F\u884C\u3057\u3001BSON \u306E \`ObjectId\` \u3092 JSON \u5316\u306B\u5B89\u5168\u306A hex \u6587\u5B57\u5217\u306B\u5909\u63DB\u3059\u308B\u8584\u3044\u30E9\u30C3\u30D1\u30FC\u3067\u3059\u3002\u516C\u958B\u30E1\u30BD\u30C3\u30C9\u306F\u6B21\u306E\u3068\u304A\u308A\u3067\u3059\uFF1A
+
+- \`client.aggregate<T>(collection, pipeline, options?) => Promise<T[]>\` \u2014 \u96C6\u7D04\u30D1\u30A4\u30D7\u30E9\u30A4\u30F3\u3092\u5B9F\u884C\u3057\u3066\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u914D\u5217\u3092\u8FD4\u3059\u3002\`$limit\` \u30B9\u30C6\u30FC\u30B8\u3092\u5FC5\u305A\u542B\u3081\u308B\u3053\u3068\u3002
+- \`client.find<T>(collection, filter?, options?) => Promise<T[]>\` \u2014 \`options\` \u306F \`{ projection?, sort?, limit?, skip? }\`\u3002\`limit\` \u3092\u5FC5\u305A\u6307\u5B9A\u3059\u308B\u3053\u3068\u3002
+- \`client.findOne<T>(collection, filter?, options?) => Promise<T | null>\` \u2014 \`limit: 1\` \u3067\u306E \`find\` \u306E\u30E9\u30C3\u30D1\u30FC\u3002
+- \`client.countDocuments(collection, filter?) => Promise<number>\` \u2014 \u6B63\u78BA\u306A\u30AB\u30A6\u30F3\u30C8\uFF08\`estimatedDocumentCount\` \u3067\u306F\u306A\u3044\uFF09\u3002
+- \`client.listCollections() => Promise<{ name: string; type: string }[]>\` \u2014 \u8A2D\u5B9A\u3055\u308C\u305F\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u5185\u306E\u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u4E00\u89A7\u3002
+
+\`client.db(...)\`\u3001\`client.connect()\`\u3001\u751F\u306E\u30AB\u30FC\u30BD\u30EB\u3084 \`MongoClient\` API \u306F **\u5B58\u5728\u3057\u306A\u3044** \u2014 \`X is not a function\` \u3067\u5931\u6557\u3059\u308B\u3002
+
+\`\`\`ts
+import type { Context } from "hono";
+import { connection } from "@squadbase/vite-server/connectors/mongodb";
+
+const mongo = connection("<connectionId>");
+
+export default async function handler(_c: Context) {
+  const rows = await mongo.aggregate<{ country: string; count: number }>(
+    "<collectionName>",
+    [
+      { $match: { country: { $nin: [null, ""] } } },
+      { $group: { _id: "$country", count: { $sum: 1 } } },
+      { $sort: { count: -1 } },
+      { $limit: 20 },
+      { $project: { _id: 0, country: "$_id", count: 1 } },
+    ],
+  );
+
+  return new Response(JSON.stringify(rows), {
+    headers: { "Content-Type": "application/json" },
+  });
+}
+\`\`\`
+
+### MongoDB \u30EA\u30D5\u30A1\u30EC\u30F3\u30B9
+- MongoDB\u306F\u30D5\u30EC\u30AD\u30B7\u30D6\u30EB\u306AJSON\u5F62\u5F0F\u306E\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\uFF08BSON\uFF09\u3068\u3057\u3066\u30C7\u30FC\u30BF\u3092\u683C\u7D0D\u3057\u307E\u3059
+- \u540C\u3058\u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u5185\u306E\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u306F\u7570\u306A\u308B\u30D5\u30A3\u30FC\u30EB\u30C9\u3092\u6301\u3064\u3053\u3068\u304C\u3067\u304D\u307E\u3059
+- \u30AF\u30A8\u30EA\u30D5\u30A3\u30EB\u30BF\u30FC\u6F14\u7B97\u5B50: \`$eq\`, \`$gt\`, \`$gte\`, \`$lt\`, \`$lte\`, \`$ne\`, \`$in\`, \`$nin\`, \`$and\`, \`$or\`, \`$not\`, \`$regex\`
+- \u96C6\u7D04\u30B9\u30C6\u30FC\u30B8: \`$match\`\uFF08\u30D5\u30A3\u30EB\u30BF\u30FC\uFF09, \`$group\`\uFF08\u96C6\u7D04\uFF09, \`$sort\`\uFF08\u30BD\u30FC\u30C8\uFF09, \`$project\`\uFF08\u5909\u63DB\uFF09, \`$lookup\`\uFF08\u7D50\u5408\uFF09, \`$unwind\`\uFF08\u914D\u5217\u5C55\u958B\uFF09, \`$limit\`, \`$skip\`, \`$count\`
+- \u96C6\u7D04\u6F14\u7B97\u5B50: \`$sum\`, \`$avg\`, \`$min\`, \`$max\`, \`$first\`, \`$last\`, \`$push\`, \`$addToSet\`
+- \u30C7\u30FC\u30BF\u63A2\u7D22\u30D1\u30BF\u30FC\u30F3:
+  1. listCollections \u3067\u5229\u7528\u53EF\u80FD\u306A\u30C7\u30FC\u30BF\u3092\u78BA\u8A8D
+  2. find \u3068 limit \u3067\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u3092\u30B5\u30F3\u30D7\u30EA\u30F3\u30B0\u3057\u3066\u30B9\u30AD\u30FC\u30DE\u3092\u628A\u63E1
+  3. aggregate \u306E $group \u3067\u30C7\u30FC\u30BF\u5206\u5E03\u3092\u5206\u6790
+- find \u30AF\u30A8\u30EA\u306B\u306F\u5FC5\u305A limit \u3092\u3001\u96C6\u7D04\u30D1\u30A4\u30D7\u30E9\u30A4\u30F3\u306B\u306F $limit \u3092\u542B\u3081\u3066\u304F\u3060\u3055\u3044`
+  },
+  tools,
+  async checkConnection(params, _config) {
+    try {
+      const { MongoClient } = await import("mongodb");
+      const client = new MongoClient(params[parameters.connectionUrl.slug], {
+        connectTimeoutMS: 1e4,
+        serverSelectionTimeoutMS: 1e4
+      });
+      try {
+        await client.connect();
+        const db = client.db(params[parameters.database.slug]);
+        await db.command({ ping: 1 });
+        return { success: true };
+      } finally {
+        await client.close();
+      }
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+});
+
+// src/connectors/create-connector-sdk.ts
+import { readFileSync } from "fs";
+import path from "path";
+
+// src/connector-client/env.ts
+function resolveEnvVar(entry, key, connectionId) {
+  const envVarName = entry.envVars[key];
+  if (!envVarName) {
+    throw new Error(`Connection "${connectionId}" is missing envVars mapping for key "${key}"`);
+  }
+  const value = process.env[envVarName];
+  if (!value) {
+    throw new Error(`Environment variable "${envVarName}" (for connection "${connectionId}", key "${key}") is not set`);
+  }
+  return value;
+}
+function resolveEnvVarOptional(entry, key) {
+  const envVarName = entry.envVars[key];
+  if (!envVarName) return void 0;
+  return process.env[envVarName] || void 0;
+}
+
+// src/connector-client/proxy-fetch.ts
+import { getContext } from "hono/context-storage";
+import { getCookie } from "hono/cookie";
+var APP_SESSION_COOKIE_NAME = "__Host-squadbase-session";
+function normalizeHeaders(input) {
+  const out = {};
+  if (!input) return out;
+  new Headers(input).forEach((value, key) => {
+    out[key] = value;
+  });
+  return out;
+}
+function createSandboxProxyFetch(connectionId) {
+  return async (input, init) => {
+    const token = process.env.INTERNAL_SQUADBASE_OAUTH_MACHINE_CREDENTIAL;
+    const sandboxId = process.env.INTERNAL_SQUADBASE_SANDBOX_ID;
+    if (!token || !sandboxId) {
+      throw new Error(
+        "Connection proxy is not configured. Please check your deployment settings."
+      );
+    }
+    const originalUrl = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const originalMethod = init?.method ?? "GET";
+    const originalBody = init?.body ? JSON.parse(init.body) : void 0;
+    const baseDomain = process.env["SQUADBASE_PREVIEW_BASE_DOMAIN"] ?? "preview.app.squadbase.dev";
+    const proxyUrl = `https://${sandboxId}.${baseDomain}/_sqcore/connections/${connectionId}/request`;
+    return fetch(proxyUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`
+      },
+      body: JSON.stringify({
+        url: originalUrl,
+        method: originalMethod,
+        headers: normalizeHeaders(init?.headers),
+        body: originalBody
+      })
+    });
+  };
+}
+function createDeployedAppProxyFetch(connectionId) {
+  const projectId = process.env["SQUADBASE_PROJECT_ID"];
+  if (!projectId) {
+    throw new Error(
+      "Connection proxy is not configured. Please check your deployment settings."
+    );
+  }
+  const baseDomain = process.env["SQUADBASE_APP_BASE_DOMAIN"] ?? "squadbase.app";
+  const proxyUrl = `https://${projectId}.${baseDomain}/_sqcore/connections/${connectionId}/request`;
+  return async (input, init) => {
+    const originalUrl = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const originalMethod = init?.method ?? "GET";
+    const originalBody = init?.body ? JSON.parse(init.body) : void 0;
+    const c = getContext();
+    const appSession = getCookie(c, APP_SESSION_COOKIE_NAME);
+    if (!appSession) {
+      throw new Error(
+        "No authentication method available for connection proxy."
+      );
+    }
+    return fetch(proxyUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${appSession}`
+      },
+      body: JSON.stringify({
+        url: originalUrl,
+        method: originalMethod,
+        headers: normalizeHeaders(init?.headers),
+        body: originalBody
+      })
+    });
+  };
+}
+function createProxyFetch(connectionId) {
+  if (process.env.INTERNAL_SQUADBASE_SANDBOX_ID) {
+    return createSandboxProxyFetch(connectionId);
+  }
+  return createDeployedAppProxyFetch(connectionId);
+}
+
+// src/connectors/create-connector-sdk.ts
+function loadConnectionsSync() {
+  const filePath = process.env.CONNECTIONS_PATH ?? path.join(process.cwd(), ".squadbase/connections.json");
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function createConnectorSdk(plugin, createClient2) {
+  return (connectionId) => {
+    const connections = loadConnectionsSync();
+    const entry = connections[connectionId];
+    if (!entry) {
+      throw new Error(
+        `Connection "${connectionId}" not found in .squadbase/connections.json`
+      );
+    }
+    if (entry.connector.slug !== plugin.slug) {
+      throw new Error(
+        `Connection "${connectionId}" is not a ${plugin.slug} connection (got "${entry.connector.slug}")`
+      );
+    }
+    const params = {};
+    for (const param of Object.values(plugin.parameters)) {
+      if (param.required) {
+        params[param.slug] = resolveEnvVar(entry, param.slug, connectionId);
+      } else {
+        const val = resolveEnvVarOptional(entry, param.slug);
+        if (val !== void 0) params[param.slug] = val;
+      }
+    }
+    return createClient2(params, createProxyFetch(connectionId));
+  };
+}
+
+// src/connectors/entries/mongodb.ts
+var connection = createConnectorSdk(mongodbConnector, createClient);
+export {
+  connection
+};