@procedures/mongo 0.0.0-stage → 0.2.0

package/src/procedures/indexes.drop.ts

@@ -0,0 +1,56 @@
+/**
+ * Procedure: mongo.indexes.drop
+ * Drop an index from a collection
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
+import { collectionFor, type ScopeInput } from "../scope.js";
+import { scopeFields } from "./input-schemas.js";
+import { z } from "zod";
+
+// Input/Output types
+interface DropIndexInput extends ScopeInput {
+  indexName: string;
+}
+
+interface DropIndexOutput {
+  acknowledged: boolean;
+}
+
+// Schemas
+const dropIndexInputSchema = zodAdapter<DropIndexInput>(
+  z.object({
+    ...scopeFields(),
+    indexName: z.string().min(1).describe("The name of the index to drop"),
+  })
+);
+const dropIndexOutputSchema = zodAdapter<DropIndexOutput>(
+  z.looseObject({
+    acknowledged: z.boolean().describe("True when the server confirmed the write"),
+  })
+);
+
+export const dropIndexProcedure: Procedure<
+  DropIndexInput,
+  DropIndexOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "indexes", "drop"])
+  .input(dropIndexInputSchema)
+  .output(dropIndexOutputSchema)
+  .meta({
+    description: "Drop an index from a collection",
+    effects: { reads: ["mongo", "network"], writes: ["mongo", "network"] },
+  })
+  .handler(async (input: DropIndexInput, ctx: ProcedureContext) => {
+    const { collection } = await collectionFor(input, ctx);
+
+    await collection.dropIndex(input.indexName);
+
+    return {
+      acknowledged: true,
+    };
+  })
+  .build();
+
+export type { DropIndexInput, DropIndexOutput };

package/src/procedures/indexes.list.ts

@@ -0,0 +1,67 @@
+/**
+ * Procedure: mongo.indexes.list
+ * List indexes on a collection
+ */
+
+import { createProcedure, zodAdapter, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
+import { collectionFor, type ScopeInput } from "../scope.js";
+import { scopeFields } from "./input-schemas.js";
+import { z } from "zod";
+import { type IndexInfo } from "../types.js";
+
+// Input/Output types
+/** The input: only the scope fields. */
+type ListIndexesInput = ScopeInput;
+
+interface ListIndexesOutput {
+  indexes: IndexInfo[];
+}
+
+// Schemas
+const listIndexesInputSchema = zodAdapter<ListIndexesInput>(
+  z.object({ ...scopeFields() })
+);
+const listIndexesOutputSchema = zodAdapter<ListIndexesOutput>(
+  z.looseObject({
+    indexes: z
+      .array(
+        z.looseObject({
+          name: z.string().describe("The index name"),
+          key: z.record(z.string(), z.union([z.number(), z.string()])).describe("The fields of the index and their kind (1, -1, \"text\", \"hashed\")"),
+          unique: z.boolean().optional().describe("True for a unique index"),
+          sparse: z.boolean().optional().describe("True for a sparse index"),
+        })
+      )
+      .describe("The indexes of the collection"),
+  })
+);
+
+export const listIndexesProcedure: Procedure<
+  ListIndexesInput,
+  ListIndexesOutput,
+  { description: string; effects?: Effects }
+> = createProcedure()
+  .path(["mongo", "indexes", "list"])
+  .input(listIndexesInputSchema)
+  .output(listIndexesOutputSchema)
+  .meta({
+    description: "List indexes on a collection",
+    effects: { reads: ["mongo", "network"], writes: [] },
+  })
+  .handler(async (input: ListIndexesInput, ctx: ProcedureContext) => {
+    const { collection } = await collectionFor(input, ctx);
+
+    const indexes = await collection.listIndexes().toArray();
+
+    return {
+      indexes: indexes.map((idx) => ({
+        name: idx.name,
+        key: idx.key,
+        unique: idx.unique,
+        sparse: idx.sparse,
+      })),
+    };
+  })
+  .build();
+
+export type { ListIndexesInput, ListIndexesOutput };

package/src/procedures/input-schemas.ts

@@ -0,0 +1,63 @@
+/**
+ * The shared fields of the mongo input schemas (roadmap 2.1).
+ *
+ * Each `mongo.*` tool describes its fields, so Claude and `mark --help` know them. Before, most
+ * tools had a pass-through schema: the tool list showed no fields, and a field name with a
+ * typing error reached the handler.
+ *
+ * A write (`update`, `delete`) and `find`/`get` keep their own parse functions: they check the
+ * target rules of deep dive DATA-4 (exactly one of `id` or `filter`, an unknown field is an
+ * error, an empty filter needs `confirm`). `described()` gives such a function the JSON Schema of
+ * a zod object that names the same fields.
+ */
+
+import { z } from "zod";
+import { jsonSchemaOf, zodAdapter, type ZodLikeSchema } from "@procedures/client";
+
+/** The fields that select the database and the collection. */
+export function scopeFields(): { collection: z.ZodOptional<z.ZodString>; database: z.ZodOptional<z.ZodString> } {
+  return {
+    collection: z.string().min(1).optional().describe("The collection name. It takes the place of metadata.collection."),
+    database: z.string().min(1).optional().describe("The database name (default: the database of the connection)"),
+  };
+}
+
+/** A MongoDB document or a filter: an object with any fields. */
+export function documentObject(): z.ZodRecord<z.ZodString, z.ZodUnknown> {
+  return z.record(z.string(), z.unknown());
+}
+
+/** The fields that select the documents of a write: one `id`, or a `filter`. */
+export function targetFields(): {
+  filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  id: z.ZodOptional<z.ZodString>;
+  idType: z.ZodOptional<z.ZodEnum<{ auto: "auto"; objectId: "objectId"; string: "string" }>>;
+  multi: z.ZodOptional<z.ZodBoolean>;
+  confirm: z.ZodOptional<z.ZodBoolean>;
+} {
+  return {
+    filter: documentObject()
+      .optional()
+      .describe("The filter of the documents (give exactly one of id or filter). An empty filter needs confirm: true."),
+    id: z.string().min(1).optional().describe("The id of one document (the alternative to filter)"),
+    idType: idTypeField(),
+    multi: z.boolean().optional().describe("Change every matching document, not only the first one"),
+    confirm: z.boolean().optional().describe("Set to true to use an empty filter, which matches every document"),
+  };
+}
+
+/** How to read a string id. */
+export function idTypeField(): z.ZodOptional<z.ZodEnum<{ auto: "auto"; objectId: "objectId"; string: "string" }>> {
+  return z
+    .enum(["auto", "objectId", "string"])
+    .optional()
+    .describe('How to read the id: "auto" (the default: an ObjectId or a string), "objectId" or "string"');
+}
+
+/**
+ * A schema whose validation is a parse function, and whose JSON Schema is the one of a zod object
+ * that names the same fields.
+ */
+export function described<T>(parse: (data: unknown) => T, fields: z.ZodObject): ZodLikeSchema<T> {
+  return Object.assign(zodAdapter<T>({ parse }), { "~jsonSchema": jsonSchemaOf(fields) });
+}

package/src/procedures/schema.ts

@@ -0,0 +1 @@
+export { outputSchema as schema } from "@procedures/client";

package/src/procedures/target.ts

@@ -0,0 +1,123 @@
+/**
+ * The target of a write: one document by `id`, or the documents that match a `filter`.
+ *
+ * Before, a call without `id` and `filter` used the filter `{}`, and the field name of
+ * `find`/`count` (`query`) was ignored: `delete { query, multi: true }` emptied the
+ * collection (deep dive DATA-4). Now a write needs exactly one target, an unknown field is an
+ * error, and an empty filter needs `confirm: true`.
+ */
+
+import { ObjectId, type Collection, type Document } from "mongodb";
+import { buildIdFilter, type DocumentQuery, type IdType } from "../types.js";
+import { SCOPE_FIELDS, copyScope, type ScopeInput } from "../scope.js";
+
+/** The fields of a write target. */
+export interface TargetInput extends ScopeInput {
+  /** The filter of the documents to change. An empty filter needs `confirm: true`. */
+  filter?: DocumentQuery;
+  /** The ID of one document (the alternative to `filter`). */
+  id?: string;
+  /** How to read the ID (default: "auto", which matches an ObjectId or a string). */
+  idType?: IdType;
+  /** Change all matching documents, not only the first one. */
+  multi?: boolean;
+  /** Set to true to use an empty filter (it matches every document). */
+  confirm?: boolean;
+}
+
+const TARGET_FIELDS = ["filter", "id", "idType", "multi", "confirm", ...SCOPE_FIELDS] as const;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function optionalBoolean(procedure: string, raw: Record<string, unknown>, field: string): boolean | undefined {
+  const value = raw[field];
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") throw new Error(`${procedure}: ${field} must be a boolean`);
+  return value;
+}
+
+/**
+ * This function reads and checks the target fields of a write input.
+ * `extraFields` are the other fields that the procedure accepts.
+ */
+export function parseTarget(
+  procedure: string,
+  data: unknown,
+  extraFields: readonly string[] = [],
+): { target: TargetInput; raw: Record<string, unknown> } {
+  if (!isPlainObject(data)) {
+    throw new Error(`${procedure}: input must be an object`);
+  }
+  const raw = data;
+  const allowed = new Set<string>([...TARGET_FIELDS, ...extraFields]);
+  for (const key of Object.keys(raw)) {
+    if (!allowed.has(key)) {
+      const hint = key === "query" ? ' Use "filter".' : "";
+      throw new Error(`${procedure}: unknown field "${key}".${hint} The fields are: ${[...allowed].join(", ")}`);
+    }
+  }
+
+  const hasId = raw["id"] !== undefined;
+  const hasFilter = raw["filter"] !== undefined;
+  if (hasId === hasFilter) {
+    throw new Error(`${procedure}: give exactly one of id or filter`);
+  }
+
+  const target: TargetInput = {};
+  copyScope(raw, target);
+
+  if (hasId) {
+    const id = raw["id"];
+    if (typeof id !== "string" || id.length === 0) {
+      throw new Error(`${procedure}: id must be a non-empty string`);
+    }
+    target.id = id;
+  } else {
+    const filter = raw["filter"];
+    if (!isPlainObject(filter)) {
+      throw new Error(`${procedure}: filter must be an object`);
+    }
+    target.filter = filter as DocumentQuery;
+  }
+
+  const idType = raw["idType"];
+  if (idType !== undefined) {
+    if (idType !== "auto" && idType !== "objectId" && idType !== "string") {
+      throw new Error(`${procedure}: idType must be "auto", "objectId" or "string"`);
+    }
+    target.idType = idType;
+  }
+
+  const multi = optionalBoolean(procedure, raw, "multi");
+  const confirm = optionalBoolean(procedure, raw, "confirm");
+  if (multi !== undefined) target.multi = multi;
+  if (confirm !== undefined) target.confirm = confirm;
+
+  if (target.filter && Object.keys(target.filter).length === 0 && confirm !== true) {
+    throw new Error(`${procedure}: an empty filter matches every document. Set confirm: true to use it.`);
+  }
+
+  return { target, raw };
+}
+
+/** The filter of a target. */
+export function targetFilter(target: TargetInput): Document {
+  return target.id !== undefined ? buildIdFilter(target.id, target.idType) : (target.filter as Document);
+}
+
+/**
+ * The filter of an upsert by ID. It names one exact `_id`.
+ *
+ * In the "auto" mode the ID filter is `$or` of the ObjectId and the string form. MongoDB cannot
+ * take an `_id` from `$or`, so each upsert inserted a new document with a new ID (deep dive
+ * DATA-15). This function uses the `_id` of the existing document, or the ObjectId form when no
+ * document matches.
+ */
+export async function upsertFilter(collection: Collection<Document>, target: TargetInput): Promise<Document> {
+  const filter = targetFilter(target);
+  if (target.id === undefined || !("$or" in filter)) return filter;
+  const existing = await collection.findOne(filter, { projection: { _id: 1 } });
+  return { _id: existing ? existing["_id"] : new ObjectId(target.id) };
+}

package/src/procedures.types.ts

@@ -0,0 +1,162 @@
+/**
+ * Typed Procedures Interface
+ *
+ * Provides compile-time autocomplete for client-mongo procedures.
+ * Import this type and use with a typed caller for full type safety.
+ *
+ * @example
+ * ```typescript
+ * import type { MongoProcedures } from "@procedures/mongo";
+ * import { createTypedCaller } from "@procedures/client";
+ *
+ * const call = createTypedCaller<MongoProcedures>(client.call);
+ *
+ * // Full autocomplete on path and input!
+ * const result = await call(
+ *   ["mongo", "documents", "find"],
+ *   { query: { status: "active" } },
+ *   { metadata: { collection: "users" } }
+ * );
+ * // result is typed as FindOutput
+ * ```
+ */
+
+import type { CollectionStats, DatabaseInfo } from "./types.js";
+
+// =============================================================================
+// Input and output types
+// =============================================================================
+// These are the types the handlers use: each procedure file exports them, so this
+// interface cannot drift from the handlers. (BUGS-2026-07 M17: the copies kept here before
+// had drifted from what the handlers accept and return.)
+
+import type { PingInput, PingOutput } from "./procedures/database.ping.js";
+import type { InfoInput } from "./procedures/database.info.js";
+import type { ListInput as ListCollectionsInput, ListOutput as ListCollectionsOutput } from "./procedures/collections.list.js";
+import type { CreateInput as CreateCollectionInput, CreateOutput as CreateCollectionOutput } from "./procedures/collections.create.js";
+import type { DropInput as DropCollectionInput, DropOutput as DropCollectionOutput } from "./procedures/collections.drop.js";
+import type { StatsInput } from "./procedures/collections.stats.js";
+import type { FindInput, FindOutput } from "./procedures/documents.find.js";
+import type { GetInput, GetOutput } from "./procedures/documents.get.js";
+import type { InsertInput, InsertOutput } from "./procedures/documents.insert.js";
+import type { UpdateInput, UpdateOutput } from "./procedures/documents.update.js";
+import type { DeleteInput, DeleteOutput } from "./procedures/documents.delete.js";
+import type { CountInput, CountOutput } from "./procedures/documents.count.js";
+import type { AggregateInput, AggregateOutput } from "./procedures/documents.aggregate.js";
+import type { ListIndexesInput, ListIndexesOutput } from "./procedures/indexes.list.js";
+import type { CreateIndexInput, CreateIndexOutput } from "./procedures/indexes.create.js";
+import type { DropIndexInput, DropIndexOutput } from "./procedures/indexes.drop.js";
+
+export type {
+  PingInput,
+  PingOutput,
+  InfoInput,
+  ListCollectionsInput,
+  ListCollectionsOutput,
+  CreateCollectionInput,
+  CreateCollectionOutput,
+  DropCollectionInput,
+  DropCollectionOutput,
+  StatsInput,
+  FindInput,
+  FindOutput,
+  GetInput,
+  GetOutput,
+  InsertInput,
+  InsertOutput,
+  UpdateInput,
+  UpdateOutput,
+  DeleteInput,
+  DeleteOutput,
+  CountInput,
+  CountOutput,
+  AggregateInput,
+  AggregateOutput,
+  ListIndexesInput,
+  ListIndexesOutput,
+  CreateIndexInput,
+  CreateIndexOutput,
+  DropIndexInput,
+  DropIndexOutput,
+};
+
+// =============================================================================
+// Combined Procedures Interface
+// =============================================================================
+
+/**
+ * Typed interface for all MongoDB procedures.
+ * Use with createTypedCaller for compile-time autocomplete.
+ */
+export interface MongoProcedures {
+  mongo: {
+    database: {
+      ping: { input: PingInput; output: PingOutput };
+      info: { input: InfoInput; output: DatabaseInfo };
+    };
+    collections: {
+      list: { input: ListCollectionsInput; output: ListCollectionsOutput };
+      create: { input: CreateCollectionInput; output: CreateCollectionOutput };
+      drop: { input: DropCollectionInput; output: DropCollectionOutput };
+      stats: { input: StatsInput; output: CollectionStats };
+    };
+    documents: {
+      find: { input: FindInput; output: FindOutput };
+      get: { input: GetInput; output: GetOutput };
+      insert: { input: InsertInput; output: InsertOutput };
+      update: { input: UpdateInput; output: UpdateOutput };
+      delete: { input: DeleteInput; output: DeleteOutput };
+      count: { input: CountInput; output: CountOutput };
+      aggregate: { input: AggregateInput; output: AggregateOutput };
+    };
+    indexes: {
+      list: { input: ListIndexesInput; output: ListIndexesOutput };
+      create: { input: CreateIndexInput; output: CreateIndexOutput };
+      drop: { input: DropIndexInput; output: DropIndexOutput };
+    };
+  };
+}
+
+/**
+ * Helper type to extract input type from a procedure path
+ */
+export type ProcedureInput<P extends readonly string[]> =
+  P extends ["mongo", "database", "ping"] ? PingInput :
+  P extends ["mongo", "database", "info"] ? InfoInput :
+  P extends ["mongo", "collections", "list"] ? ListCollectionsInput :
+  P extends ["mongo", "collections", "create"] ? CreateCollectionInput :
+  P extends ["mongo", "collections", "drop"] ? DropCollectionInput :
+  P extends ["mongo", "collections", "stats"] ? StatsInput :
+  P extends ["mongo", "documents", "find"] ? FindInput :
+  P extends ["mongo", "documents", "get"] ? GetInput :
+  P extends ["mongo", "documents", "insert"] ? InsertInput :
+  P extends ["mongo", "documents", "update"] ? UpdateInput :
+  P extends ["mongo", "documents", "delete"] ? DeleteInput :
+  P extends ["mongo", "documents", "count"] ? CountInput :
+  P extends ["mongo", "documents", "aggregate"] ? AggregateInput :
+  P extends ["mongo", "indexes", "list"] ? ListIndexesInput :
+  P extends ["mongo", "indexes", "create"] ? CreateIndexInput :
+  P extends ["mongo", "indexes", "drop"] ? DropIndexInput :
+  never;
+
+/**
+ * Helper type to extract output type from a procedure path
+ */
+export type ProcedureOutput<P extends readonly string[]> =
+  P extends ["mongo", "database", "ping"] ? PingOutput :
+  P extends ["mongo", "database", "info"] ? DatabaseInfo :
+  P extends ["mongo", "collections", "list"] ? ListCollectionsOutput :
+  P extends ["mongo", "collections", "create"] ? CreateCollectionOutput :
+  P extends ["mongo", "collections", "drop"] ? DropCollectionOutput :
+  P extends ["mongo", "collections", "stats"] ? CollectionStats :
+  P extends ["mongo", "documents", "find"] ? FindOutput :
+  P extends ["mongo", "documents", "get"] ? GetOutput :
+  P extends ["mongo", "documents", "insert"] ? InsertOutput :
+  P extends ["mongo", "documents", "update"] ? UpdateOutput :
+  P extends ["mongo", "documents", "delete"] ? DeleteOutput :
+  P extends ["mongo", "documents", "count"] ? CountOutput :
+  P extends ["mongo", "documents", "aggregate"] ? AggregateOutput :
+  P extends ["mongo", "indexes", "list"] ? ListIndexesOutput :
+  P extends ["mongo", "indexes", "create"] ? CreateIndexOutput :
+  P extends ["mongo", "indexes", "drop"] ? DropIndexOutput :
+  never;

package/src/register.ts

@@ -0,0 +1,11 @@
+/**
+ * Importing this file registers the procedures of @procedures/mongo, and of the modules that it
+ * requires, in the global registry: `import "@procedures/mongo/register"`. The package root and the
+ * `./module` entry register nothing (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+
+import { registerMongoProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerMongoProcedures();

package/src/scope.ts

@@ -0,0 +1,69 @@
+/**
+ * The database and the collection of a call.
+ *
+ * Each procedure reads `collection` and `database` from its input. The call metadata stays a
+ * fallback for the clients that set it. (Before, only the metadata gave them, and an MCP tool
+ * call cannot set metadata: deep dive DATA-5.)
+ */
+
+import type { Collection, Db, Document } from "mongodb";
+import type { ProcedureContext } from "@procedures/client";
+import { ensureConnection } from "./connection.js";
+
+/** The input fields that select the database and the collection. */
+export interface ScopeInput {
+  /** The collection name. It takes the place of `metadata.collection`. */
+  collection?: string | undefined;
+  /** The database name. It takes the place of `metadata.database` and the connection default. */
+  database?: string | undefined;
+}
+
+/** The names of the scope fields, for the input parsers. */
+export const SCOPE_FIELDS = ["collection", "database"] as const;
+
+function optionalName(value: unknown, field: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+/** The database name of a call: the input, then the metadata. Undefined means the connection default. */
+export function databaseName(input: ScopeInput, ctx: Pick<ProcedureContext, "metadata">): string | undefined {
+  return optionalName(input.database, "database") ?? optionalName(ctx.metadata["database"], "metadata.database");
+}
+
+/** The collection name of a call: the input, then the metadata. */
+export function collectionName(input: ScopeInput, ctx: Pick<ProcedureContext, "metadata">): string {
+  const name = optionalName(input.collection, "collection") ?? optionalName(ctx.metadata["collection"], "metadata.collection");
+  if (name === undefined) {
+    throw new Error("collection is required: give it in the input (or in the call metadata)");
+  }
+  return name;
+}
+
+/** The database of a call. This function connects first when there is no open connection. */
+export async function databaseFor(input: ScopeInput, ctx: Pick<ProcedureContext, "metadata">): Promise<Db> {
+  const name = databaseName(input, ctx);
+  const connection = await ensureConnection();
+  return name ? connection.getClient().db(name) : connection.getDb();
+}
+
+/** The collection of a call. This function connects first when there is no open connection. */
+export async function collectionFor(
+  input: ScopeInput,
+  ctx: Pick<ProcedureContext, "metadata">,
+): Promise<{ collection: Collection<Document>; name: string; db: Db }> {
+  const name = collectionName(input, ctx);
+  const db = await databaseFor(input, ctx);
+  return { collection: db.collection(name), name, db };
+}
+
+/** This function copies the scope fields of a raw input into a parsed input. */
+export function copyScope(raw: Record<string, unknown>, parsed: ScopeInput): void {
+  const collection = optionalName(raw["collection"], "collection");
+  const database = optionalName(raw["database"], "database");
+  if (collection !== undefined) parsed.collection = collection;
+  if (database !== undefined) parsed.database = database;
+}

package/src/storage/index.ts

@@ -0,0 +1,6 @@
+/**
+ * MongoDB Storage Exports
+ */
+
+export { MongoStorage } from "./mongo-storage.js";
+export type { MongoStorageOptions } from "./mongo-storage.js";