@jsondb-cloud/mcp 1.0.0

package/dist/index.mjs

@@ -0,0 +1,1339 @@
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { JsonDB } from "@jsondb-cloud/client";
+
+// src/tools/documents.ts
+import { z } from "zod";
+function success(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+function error(code, message, suggestion) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ error: { code, message, suggestion } }, null, 2)
+      }
+    ],
+    isError: true
+  };
+}
+function registerDocumentTools(server, db) {
+  server.tool(
+    "create_document",
+    "Create a new JSON document in a jsondb.cloud collection. Returns the created document with auto-generated _id, $createdAt, $updatedAt, and $version metadata.",
+    {
+      collection: z.string().describe("The collection name (e.g., 'users', 'posts', 'settings')"),
+      data: z.record(z.string(), z.any()).describe("The JSON document to store. Can contain any valid JSON."),
+      id: z.string().optional().describe(
+        "Optional custom document ID. If not provided, an ID is auto-generated."
+      )
+    },
+    async ({ collection, data, id }) => {
+      try {
+        const coll = db.collection(collection);
+        const doc = await coll.create(data, id ? { id } : void 0);
+        return success(doc);
+      } catch (err) {
+        const e = err;
+        if (e.status === 409) {
+          return error(
+            "DOCUMENT_CONFLICT",
+            `A document with this ID already exists in collection '${collection}'.`,
+            `Use update_document to replace an existing document, or omit the 'id' parameter to auto-generate a unique ID.`
+          );
+        }
+        if (e.status === 413) {
+          return error(
+            "DOCUMENT_TOO_LARGE",
+            `The document exceeds the maximum allowed size.`,
+            `Reduce the document size. Free plans allow up to 16 KB per document, Pro plans allow up to 1 MB.`
+          );
+        }
+        if (e.status === 400) {
+          return error(
+            "VALIDATION_ERROR",
+            e.message || `The document failed schema validation for collection '${collection}'.`,
+            `Use get_schema({ collection: '${collection}' }) to see the required schema, then adjust your document to match.`
+          );
+        }
+        return error(
+          "CREATE_FAILED",
+          e.message || "Failed to create document",
+          `Check that the collection name '${collection}' is valid and the data is a valid JSON object.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "get_document",
+    "Read a single document by ID from a jsondb.cloud collection. Returns the full document including metadata fields (_id, $createdAt, $updatedAt, $version).",
+    {
+      collection: z.string().describe("The collection name"),
+      id: z.string().describe("The document ID to retrieve")
+    },
+    async ({ collection, id }) => {
+      try {
+        const coll = db.collection(collection);
+        const doc = await coll.get(id);
+        return success(doc);
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error(
+            "DOCUMENT_NOT_FOUND",
+            `Document '${id}' not found in collection '${collection}'.`,
+            `Use list_documents({ collection: '${collection}' }) to see available documents, or check that the ID is correct.`
+          );
+        }
+        return error(
+          "GET_FAILED",
+          e.message || "Failed to get document",
+          `Verify that the collection '${collection}' exists and the document ID '${id}' is correct.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "list_documents",
+    "List documents in a jsondb.cloud collection with optional filtering, sorting, and pagination. Returns a paginated response with data array and metadata (total count, hasMore).",
+    {
+      collection: z.string().describe("The collection name"),
+      filter: z.record(z.string(), z.any()).optional().describe(
+        "Filter criteria. Keys are field names, values are match values. Use {field: {$gt: N}} for comparisons."
+      ),
+      sort: z.string().optional().describe(
+        "Field to sort by. Prefix with '-' for descending (e.g., '-$createdAt')"
+      ),
+      limit: z.number().optional().describe("Max documents to return (default: 20, max: 100)"),
+      offset: z.number().optional().describe("Number of documents to skip for pagination"),
+      select: z.array(z.string()).optional().describe(
+        "Field names to return. Omit to return all fields. Example: ['name', 'email', '$createdAt']"
+      )
+    },
+    async ({ collection, filter, sort, limit, offset, select }) => {
+      try {
+        const coll = db.collection(collection);
+        const result = await coll.list({
+          filter,
+          sort,
+          limit,
+          offset,
+          select
+        });
+        return success(result);
+      } catch (err) {
+        const e = err;
+        return error(
+          "LIST_FAILED",
+          e.message || `Failed to list documents in collection '${collection}'.`,
+          `Verify the collection name is correct. Use list_collections to see available collections.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "update_document",
+    "Replace a document entirely in a jsondb.cloud collection. The new data replaces all existing fields (except metadata). Use patch_document for partial updates.",
+    {
+      collection: z.string().describe("The collection name"),
+      id: z.string().describe("The document ID to replace"),
+      data: z.record(z.string(), z.any()).describe(
+        "The complete new document data. This replaces all existing fields."
+      )
+    },
+    async ({ collection, id, data }) => {
+      try {
+        const coll = db.collection(collection);
+        const doc = await coll.update(id, data);
+        return success(doc);
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error(
+            "DOCUMENT_NOT_FOUND",
+            `Document '${id}' not found in collection '${collection}'.`,
+            `Use list_documents({ collection: '${collection}' }) to see available documents. To create a new document, use create_document instead.`
+          );
+        }
+        if (e.status === 400) {
+          return error(
+            "VALIDATION_ERROR",
+            e.message || `The document failed schema validation.`,
+            `Use get_schema({ collection: '${collection}' }) to see the required schema, then adjust your document to match.`
+          );
+        }
+        return error(
+          "UPDATE_FAILED",
+          e.message || "Failed to update document",
+          `Verify that collection '${collection}' and document ID '${id}' are correct.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "patch_document",
+    "Partially update a document in a jsondb.cloud collection using merge patch. Only the provided fields are updated; other fields remain unchanged. This is preferred over update_document when you only need to change a few fields.",
+    {
+      collection: z.string().describe("The collection name"),
+      id: z.string().describe("The document ID to patch"),
+      data: z.record(z.string(), z.any()).describe(
+        "The fields to update. Only these fields are modified; other existing fields are preserved."
+      )
+    },
+    async ({ collection, id, data }) => {
+      try {
+        const coll = db.collection(collection);
+        const doc = await coll.patch(id, data);
+        return success(doc);
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error(
+            "DOCUMENT_NOT_FOUND",
+            `Document '${id}' not found in collection '${collection}'.`,
+            `Use list_documents({ collection: '${collection}' }) to see available documents. To create a new document, use create_document instead.`
+          );
+        }
+        if (e.status === 400) {
+          return error(
+            "VALIDATION_ERROR",
+            e.message || `The patched document failed schema validation.`,
+            `Use get_schema({ collection: '${collection}' }) to see the required schema. Ensure the patched result conforms to it.`
+          );
+        }
+        return error(
+          "PATCH_FAILED",
+          e.message || "Failed to patch document",
+          `Verify that collection '${collection}' and document ID '${id}' are correct.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "delete_document",
+    "Delete a document by ID from a jsondb.cloud collection. This action is permanent and cannot be undone.",
+    {
+      collection: z.string().describe("The collection name"),
+      id: z.string().describe("The document ID to delete")
+    },
+    async ({ collection, id }) => {
+      try {
+        const coll = db.collection(collection);
+        await coll.delete(id);
+        return success({
+          deleted: true,
+          _id: id,
+          collection
+        });
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error(
+            "DOCUMENT_NOT_FOUND",
+            `Document '${id}' not found in collection '${collection}'.`,
+            `The document may have already been deleted. Use list_documents({ collection: '${collection}' }) to see current documents.`
+          );
+        }
+        return error(
+          "DELETE_FAILED",
+          e.message || "Failed to delete document",
+          `Verify that collection '${collection}' and document ID '${id}' are correct.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "count_documents",
+    "Count documents in a jsondb.cloud collection, optionally filtered. Returns a single number. Use this instead of list_documents when you only need a count.",
+    {
+      collection: z.string().describe("The collection name"),
+      filter: z.record(z.string(), z.any()).optional().describe(
+        "Filter criteria. Same format as list_documents. Only matching documents are counted."
+      )
+    },
+    async ({ collection, filter }) => {
+      try {
+        const coll = db.collection(collection);
+        const count = await coll.count(filter);
+        return success({ collection, count });
+      } catch (err) {
+        const e = err;
+        return error(
+          "COUNT_FAILED",
+          e.message || `Failed to count documents in collection '${collection}'.`,
+          `Verify the collection name is correct. Use list_collections to see available collections.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "json_patch_document",
+    "Apply RFC 6902 JSON Patch operations to a document. Supports op types: add, remove, replace, move, copy, test. Use patch_document for simple field merges; use this for precise structural mutations like array element updates.",
+    {
+      collection: z.string().describe("The collection name"),
+      id: z.string().describe("The document ID to patch"),
+      operations: z.array(
+        z.object({
+          op: z.enum(["add", "remove", "replace", "move", "copy", "test"]).describe("Patch operation type"),
+          path: z.string().describe("JSON Pointer path (e.g., '/name', '/tags/0')"),
+          value: z.any().optional().describe("Value for add/replace/test operations"),
+          from: z.string().optional().describe("Source path for move/copy operations")
+        })
+      ).describe("Array of JSON Patch operations to apply in order")
+    },
+    async ({ collection, id, operations }) => {
+      try {
+        const coll = db.collection(collection);
+        const doc = await coll.jsonPatch(id, operations);
+        return success(doc);
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error(
+            "DOCUMENT_NOT_FOUND",
+            `Document '${id}' not found in collection '${collection}'.`,
+            `Use list_documents({ collection: '${collection}' }) to see available documents.`
+          );
+        }
+        if (e.status === 409) {
+          return error(
+            "PATCH_CONFLICT",
+            e.message || "A 'test' operation failed or a path conflict occurred.",
+            `Review the patch operations. A 'test' op asserts a value must match before applying changes.`
+          );
+        }
+        if (e.status === 400) {
+          return error(
+            "VALIDATION_ERROR",
+            e.message || "The patched document failed schema validation.",
+            `Use get_schema({ collection: '${collection}' }) to review the required schema.`
+          );
+        }
+        return error(
+          "JSON_PATCH_FAILED",
+          e.message || "Failed to apply JSON Patch",
+          `Verify the patch operations are valid RFC 6902. Paths must use JSON Pointer format (e.g., '/field', '/nested/key').`
+        );
+      }
+    }
+  );
+}
+
+// src/tools/collections.ts
+import { z as z2 } from "zod";
+function success2(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+function error2(code, message, suggestion) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ error: { code, message, suggestion } }, null, 2)
+      }
+    ],
+    isError: true
+  };
+}
+function buildFilterObject(filters) {
+  const filterObj = {};
+  const opMap = {
+    eq: "$eq",
+    neq: "$neq",
+    gt: "$gt",
+    gte: "$gte",
+    lt: "$lt",
+    lte: "$lte",
+    contains: "$contains",
+    in: "$in",
+    exists: "$exists"
+  };
+  for (const f of filters) {
+    if (f.operator === "eq") {
+      filterObj[f.field] = f.value;
+    } else {
+      const sdkOp = opMap[f.operator];
+      if (sdkOp) {
+        filterObj[f.field] = { [sdkOp]: f.value };
+      } else {
+        filterObj[f.field] = f.value;
+      }
+    }
+  }
+  return filterObj;
+}
+function registerCollectionTools(server, db) {
+  server.tool(
+    "list_collections",
+    "List all collections in the current jsondb.cloud project. Returns collection names that contain documents. Use this to discover what data is available before querying.",
+    {},
+    async () => {
+      try {
+        const apiKey = process.env.JSONDB_API_KEY || "";
+        const project = process.env.JSONDB_PROJECT || process.env.JSONDB_NAMESPACE || "v1";
+        const baseUrl = (process.env.JSONDB_BASE_URL || "https://api.jsondb.cloud").replace(/\/$/, "");
+        const res = await fetch(`${baseUrl}/${project}`, {
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json"
+          }
+        });
+        if (!res.ok) {
+          const body = await res.json().catch(() => ({}));
+          throw { status: res.status, message: body.error || res.statusText };
+        }
+        const data = await res.json();
+        return success2(data);
+      } catch (err) {
+        const e = err;
+        return error2(
+          "LIST_COLLECTIONS_FAILED",
+          e.message || "Failed to list collections.",
+          `Verify that the JSONDB_API_KEY and JSONDB_PROJECT environment variables are set correctly.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "search_documents",
+    "Search for documents matching specific criteria. Supports equality, comparison operators (gt, gte, lt, lte), contains (case-insensitive substring), and in (value in list). Filters are combined with AND logic.",
+    {
+      collection: z2.string().describe("The collection name"),
+      filters: z2.array(
+        z2.object({
+          field: z2.string().describe(
+            "Field path (supports dot notation for nested fields)"
+          ),
+          operator: z2.enum([
+            "eq",
+            "neq",
+            "gt",
+            "gte",
+            "lt",
+            "lte",
+            "contains",
+            "in",
+            "exists"
+          ]).describe("Comparison operator"),
+          value: z2.any().describe("Value to compare against")
+        })
+      ).describe("Array of filter conditions (combined with AND logic)"),
+      sort: z2.string().optional().describe(
+        "Field to sort by. Prefix with '-' for descending (e.g., '-$createdAt')"
+      ),
+      limit: z2.number().optional().describe("Max documents to return (default: 20, max: 100)"),
+      offset: z2.number().optional().describe("Number of documents to skip for pagination")
+    },
+    async ({ collection, filters, sort, limit, offset }) => {
+      try {
+        const coll = db.collection(collection);
+        const filterObj = buildFilterObject(filters);
+        const result = await coll.list({
+          filter: filterObj,
+          sort,
+          limit,
+          offset
+        });
+        return success2(result);
+      } catch (err) {
+        const e = err;
+        return error2(
+          "SEARCH_FAILED",
+          e.message || `Failed to search documents in collection '${collection}'.`,
+          `Verify the collection name and filter syntax. Available operators: eq, neq, gt, gte, lt, lte, contains, in. Use list_collections to see available collections.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "import_documents",
+    "Bulk import multiple documents into a jsondb.cloud collection at once. More efficient than creating documents one by one. Supports conflict resolution and custom ID field mapping.",
+    {
+      collection: z2.string().describe("The collection name to import into"),
+      documents: z2.array(z2.record(z2.string(), z2.any())).describe("Array of JSON documents to import"),
+      onConflict: z2.enum(["fail", "skip", "overwrite"]).optional().describe(
+        "How to handle ID conflicts: 'fail' (default) rejects the batch, 'skip' ignores duplicates, 'overwrite' replaces existing documents"
+      ),
+      idField: z2.string().optional().describe(
+        "Field in each document to use as _id. If omitted, IDs are auto-generated."
+      )
+    },
+    async ({ collection, documents, onConflict, idField }) => {
+      try {
+        const apiKey = process.env.JSONDB_API_KEY || "";
+        const project = process.env.JSONDB_PROJECT || process.env.JSONDB_NAMESPACE || "v1";
+        const baseUrl = (process.env.JSONDB_BASE_URL || "https://api.jsondb.cloud").replace(/\/$/, "");
+        const params = new URLSearchParams();
+        if (onConflict) params.set("onConflict", onConflict);
+        if (idField) params.set("idField", idField);
+        const qs = params.toString();
+        const res = await fetch(
+          `${baseUrl}/${project}/${collection}/_import${qs ? `?${qs}` : ""}`,
+          {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${apiKey}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify(documents)
+          }
+        );
+        if (!res.ok) {
+          const body = await res.json().catch(() => ({}));
+          throw {
+            status: res.status,
+            message: body.error || res.statusText
+          };
+        }
+        const data = await res.json();
+        return success2(data);
+      } catch (err) {
+        const e = err;
+        if (e.status === 413) {
+          return error2(
+            "IMPORT_TOO_LARGE",
+            "The import payload exceeds the maximum allowed size.",
+            `Free plans support up to 1,000 documents (5 MB). Pro plans support up to 10,000 documents (50 MB). Try importing in smaller batches.`
+          );
+        }
+        if (e.status === 409) {
+          return error2(
+            "IMPORT_CONFLICT",
+            e.message || "One or more documents conflict with existing IDs.",
+            `Use onConflict: 'skip' to ignore duplicates or 'overwrite' to replace existing documents.`
+          );
+        }
+        return error2(
+          "IMPORT_FAILED",
+          e.message || `Failed to import documents into collection '${collection}'.`,
+          `Verify each document is a valid JSON object. Check the import limits for your plan.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "export_collection",
+    "Export all documents from a jsondb.cloud collection as a JSON array. Supports optional filtering to export a subset. Free plans support up to 1,000 documents, Pro plans up to 100,000.",
+    {
+      collection: z2.string().describe("The collection name to export"),
+      filter: z2.record(z2.string(), z2.any()).optional().describe(
+        "Optional filter to export only matching documents. Same format as list_documents filter."
+      )
+    },
+    async ({ collection, filter }) => {
+      try {
+        const apiKey = process.env.JSONDB_API_KEY || "";
+        const project = process.env.JSONDB_PROJECT || process.env.JSONDB_NAMESPACE || "v1";
+        const baseUrl = (process.env.JSONDB_BASE_URL || "https://api.jsondb.cloud").replace(/\/$/, "");
+        const params = new URLSearchParams();
+        if (filter) {
+          for (const [field, value] of Object.entries(filter)) {
+            if (typeof value === "object" && value !== null) {
+              const ops = value;
+              for (const [op, v] of Object.entries(ops)) {
+                const cleanOp = op.replace(/^\$/, "");
+                params.set(`filter[${field}][${cleanOp}]`, String(v));
+              }
+            } else {
+              params.set(`filter[${field}]`, String(value));
+            }
+          }
+        }
+        const qs = params.toString();
+        const res = await fetch(
+          `${baseUrl}/${project}/${collection}/_export${qs ? `?${qs}` : ""}`,
+          {
+            headers: {
+              Authorization: `Bearer ${apiKey}`,
+              Accept: "application/json"
+            }
+          }
+        );
+        if (!res.ok) {
+          const body = await res.json().catch(() => ({}));
+          throw {
+            status: res.status,
+            message: body.error || res.statusText
+          };
+        }
+        const data = await res.json();
+        const documents = Array.isArray(data) ? data : data.data ?? [];
+        return success2({ collection, count: documents.length, documents });
+      } catch (err) {
+        const e = err;
+        if (e.status === 403) {
+          return error2(
+            "EXPORT_LIMIT_EXCEEDED",
+            "Export limit exceeded for your plan.",
+            `Free plans support up to 1,000 documents per export. Upgrade to Pro for up to 100,000.`
+          );
+        }
+        return error2(
+          "EXPORT_FAILED",
+          e.message || `Failed to export collection '${collection}'.`,
+          `Verify the collection name is correct. Use list_collections to see available collections.`
+        );
+      }
+    }
+  );
+}
+
+// src/tools/schemas.ts
+import { z as z3 } from "zod";
+function success3(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+function error3(code, message, suggestion) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ error: { code, message, suggestion } }, null, 2)
+      }
+    ],
+    isError: true
+  };
+}
+function registerSchemaTools(server, db) {
+  server.tool(
+    "get_schema",
+    "Get the JSON Schema for a jsondb.cloud collection. Returns the schema if one is set, or null if no schema is configured. Knowing the schema helps you create valid documents.",
+    {
+      collection: z3.string().describe("The collection name to get the schema for")
+    },
+    async ({ collection }) => {
+      try {
+        const coll = db.collection(collection);
+        const schema = await coll.getSchema();
+        if (schema === null) {
+          return success3({
+            collection,
+            schema: null,
+            message: `No schema is set for collection '${collection}'. Any valid JSON document can be stored.`
+          });
+        }
+        return success3({ collection, schema });
+      } catch (err) {
+        const e = err;
+        return error3(
+          "GET_SCHEMA_FAILED",
+          e.message || `Failed to get schema for collection '${collection}'.`,
+          `Verify the collection name is correct. Use list_collections to see available collections.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "set_schema",
+    "Set a JSON Schema for a jsondb.cloud collection. Documents created or updated in this collection will be validated against the schema. Supports standard JSON Schema keywords: type, required, properties, enum, minimum, maximum, minLength, maxLength, pattern, and additionalProperties.",
+    {
+      collection: z3.string().describe("The collection name to set the schema for"),
+      schema: z3.record(z3.string(), z3.any()).describe(
+        "The JSON Schema object. Example: { type: 'object', required: ['name'], properties: { name: { type: 'string' }, age: { type: 'number', minimum: 0 } } }"
+      )
+    },
+    async ({ collection, schema }) => {
+      try {
+        const coll = db.collection(collection);
+        await coll.setSchema(schema);
+        return success3({
+          collection,
+          schema,
+          message: `Schema set successfully for collection '${collection}'. All new and updated documents will be validated against this schema.`
+        });
+      } catch (err) {
+        const e = err;
+        if (e.status === 400) {
+          return error3(
+            "INVALID_SCHEMA",
+            e.message || "The provided schema is not a valid JSON Schema.",
+            `Ensure the schema follows JSON Schema format. The top-level 'type' should typically be 'object'. Example: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }`
+          );
+        }
+        return error3(
+          "SET_SCHEMA_FAILED",
+          e.message || `Failed to set schema for collection '${collection}'.`,
+          `Verify the collection name and ensure the schema is valid JSON Schema format.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "remove_schema",
+    "Remove the JSON Schema from a jsondb.cloud collection. After removal, any valid JSON document can be stored without validation. Existing documents are not affected.",
+    {
+      collection: z3.string().describe("The collection name to remove the schema from")
+    },
+    async ({ collection }) => {
+      try {
+        const coll = db.collection(collection);
+        await coll.removeSchema();
+        return success3({
+          collection,
+          schema: null,
+          message: `Schema removed from collection '${collection}'. Documents are no longer validated.`
+        });
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error3(
+            "SCHEMA_NOT_FOUND",
+            `No schema is set for collection '${collection}'.`,
+            `Use get_schema({ collection: '${collection}' }) to check whether a schema exists.`
+          );
+        }
+        return error3(
+          "REMOVE_SCHEMA_FAILED",
+          e.message || `Failed to remove schema from collection '${collection}'.`,
+          `Verify the collection name is correct. Use list_collections to see available collections.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "validate_document",
+    "Dry-run validate a document against a collection's schema without storing it. Returns { valid: true } or { valid: false, errors: [...] } with field-level error details. Use this before create_document when unsure if a document conforms to the schema.",
+    {
+      collection: z3.string().describe("The collection name whose schema to validate against"),
+      data: z3.record(z3.string(), z3.any()).describe("The document to validate")
+    },
+    async ({ collection, data }) => {
+      try {
+        const coll = db.collection(collection);
+        const result = await coll.validate(data);
+        return success3({ collection, ...result });
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error3(
+            "SCHEMA_NOT_FOUND",
+            `No schema is set for collection '${collection}'.`,
+            `Use set_schema to add a schema first, or use create_document directly if no validation is needed.`
+          );
+        }
+        return error3(
+          "VALIDATE_FAILED",
+          e.message || `Failed to validate document against collection '${collection}' schema.`,
+          `Verify the collection name is correct and the data is a valid JSON object.`
+        );
+      }
+    }
+  );
+}
+
+// src/tools/versions.ts
+import { z as z4 } from "zod";
+function success4(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+function error4(code, message, suggestion) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ error: { code, message, suggestion } }, null, 2)
+      }
+    ],
+    isError: true
+  };
+}
+function resolveEnv() {
+  return {
+    apiKey: process.env.JSONDB_API_KEY || "",
+    project: process.env.JSONDB_PROJECT || process.env.JSONDB_NAMESPACE || "v1",
+    baseUrl: (process.env.JSONDB_BASE_URL || "https://api.jsondb.cloud").replace(
+      /\/$/,
+      ""
+    )
+  };
+}
+async function versionFetch(url, apiKey, opts = {}) {
+  const res = await fetch(url, {
+    ...opts,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+      ...opts.headers
+    }
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw {
+      status: res.status,
+      message: body.error || res.statusText
+    };
+  }
+  if (res.status === 204) return { ok: true };
+  return res.json();
+}
+function registerVersionTools(server, _db) {
+  server.tool(
+    "list_versions",
+    "List all stored versions of a document. Returns version numbers, timestamps, and size. Version history depth depends on plan (Free: 5, Pro: 50).",
+    {
+      collection: z4.string().describe("The collection name"),
+      id: z4.string().describe("The document ID")
+    },
+    async ({ collection, id }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv();
+        const data = await versionFetch(
+          `${baseUrl}/${project}/${collection}/${id}/versions`,
+          apiKey
+        );
+        return success4(data);
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error4(
+            "DOCUMENT_NOT_FOUND",
+            `Document '${id}' not found in collection '${collection}'.`,
+            `Use list_documents({ collection: '${collection}' }) to see available documents.`
+          );
+        }
+        return error4(
+          "LIST_VERSIONS_FAILED",
+          e.message || `Failed to list versions for document '${id}'.`,
+          `Verify the collection and document ID are correct.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "get_version",
+    "Retrieve the document as it existed at a specific version number. Returns the full document snapshot at that version.",
+    {
+      collection: z4.string().describe("The collection name"),
+      id: z4.string().describe("The document ID"),
+      version: z4.number().int().positive().describe("The version number to retrieve (from list_versions)")
+    },
+    async ({ collection, id, version }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv();
+        const data = await versionFetch(
+          `${baseUrl}/${project}/${collection}/${id}/versions/${version}`,
+          apiKey
+        );
+        return success4(data);
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error4(
+            "VERSION_NOT_FOUND",
+            `Version ${version} of document '${id}' not found in collection '${collection}'.`,
+            `Use list_versions({ collection: '${collection}', id: '${id}' }) to see available versions.`
+          );
+        }
+        return error4(
+          "GET_VERSION_FAILED",
+          e.message || `Failed to get version ${version} of document '${id}'.`,
+          `Verify the collection, document ID, and version number are correct.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "restore_version",
+    "Restore a document to a previous version. The current document is overwritten with the historical snapshot. Creates a new version entry. This action cannot be undone.",
+    {
+      collection: z4.string().describe("The collection name"),
+      id: z4.string().describe("The document ID"),
+      version: z4.number().int().positive().describe("The version number to restore to (from list_versions)")
+    },
+    async ({ collection, id, version }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv();
+        const data = await versionFetch(
+          `${baseUrl}/${project}/${collection}/${id}/versions/${version}/restore`,
+          apiKey,
+          { method: "POST" }
+        );
+        return success4(data);
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error4(
+            "VERSION_NOT_FOUND",
+            `Version ${version} of document '${id}' not found in collection '${collection}'.`,
+            `Use list_versions({ collection: '${collection}', id: '${id}' }) to see available versions.`
+          );
+        }
+        if (e.status === 400) {
+          return error4(
+            "VALIDATION_ERROR",
+            e.message || "The restored document failed schema validation.",
+            `The historical version may not match the current schema. Use get_schema({ collection: '${collection}' }) to review.`
+          );
+        }
+        return error4(
+          "RESTORE_VERSION_FAILED",
+          e.message || `Failed to restore document '${id}' to version ${version}.`,
+          `Verify the collection, document ID, and version number are correct.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "diff_versions",
+    "Compare two versions of a document and return a structured diff showing added, removed, and changed fields. Pro plan feature only.",
+    {
+      collection: z4.string().describe("The collection name"),
+      id: z4.string().describe("The document ID"),
+      from: z4.number().int().positive().describe("The base version number (older version)"),
+      to: z4.number().int().positive().describe("The target version number (newer version)")
+    },
+    async ({ collection, id, from, to }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv();
+        const params = new URLSearchParams({
+          from: String(from),
+          to: String(to)
+        });
+        const data = await versionFetch(
+          `${baseUrl}/${project}/${collection}/${id}/versions/diff?${params.toString()}`,
+          apiKey
+        );
+        return success4(data);
+      } catch (err) {
+        const e = err;
+        if (e.status === 403) {
+          return error4(
+            "PRO_FEATURE",
+            "Version diff is a Pro plan feature.",
+            `Upgrade to Pro at https://jsondb.cloud/dashboard/billing to enable version diffs.`
+          );
+        }
+        if (e.status === 404) {
+          return error4(
+            "VERSION_NOT_FOUND",
+            `One or both versions (${from}, ${to}) not found for document '${id}'.`,
+            `Use list_versions({ collection: '${collection}', id: '${id}' }) to see available version numbers.`
+          );
+        }
+        return error4(
+          "DIFF_VERSIONS_FAILED",
+          e.message || `Failed to diff versions ${from} and ${to} of document '${id}'.`,
+          `Verify the collection, document ID, and both version numbers are correct.`
+        );
+      }
+    }
+  );
+}
+
+// src/tools/webhooks.ts
+import { z as z5 } from "zod";
+function success5(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+function error5(code, message, suggestion) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ error: { code, message, suggestion } }, null, 2)
+      }
+    ],
+    isError: true
+  };
+}
+function resolveEnv2() {
+  return {
+    apiKey: process.env.JSONDB_API_KEY || "",
+    project: process.env.JSONDB_PROJECT || process.env.JSONDB_NAMESPACE || "v1",
+    baseUrl: (process.env.JSONDB_BASE_URL || "https://api.jsondb.cloud").replace(
+      /\/$/,
+      ""
+    )
+  };
+}
+async function webhookFetch(url, apiKey, method = "GET", body) {
+  const opts = {
+    method,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json"
+    }
+  };
+  if (body !== void 0 && ["POST", "PUT", "PATCH"].includes(method)) {
+    opts.body = JSON.stringify(body);
+  }
+  const res = await fetch(url, opts);
+  if (!res.ok) {
+    const b = await res.json().catch(() => ({}));
+    throw {
+      status: res.status,
+      message: b.error || res.statusText
+    };
+  }
+  if (res.status === 204) return { ok: true };
+  return res.json();
+}
+var webhookEventEnum = z5.enum([
+  "document.created",
+  "document.updated",
+  "document.deleted"
+]);
+function registerWebhookTools(server, _db) {
+  server.tool(
+    "create_webhook",
+    "Register a webhook on a jsondb.cloud collection. The webhook URL receives POST requests signed with HMAC-SHA256 when the specified events occur.",
+    {
+      collection: z5.string().describe("The collection name to watch"),
+      url: z5.string().url().describe("The HTTPS URL to deliver webhook events to"),
+      events: z5.array(webhookEventEnum).describe(
+        "Events to subscribe to: 'document.created', 'document.updated', 'document.deleted'"
+      ),
+      description: z5.string().optional().describe("Optional human-readable label for this webhook")
+    },
+    async ({ collection, url: webhookUrl, events, description }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv2();
+        const data = await webhookFetch(
+          `${baseUrl}/${project}/${collection}/_webhooks`,
+          apiKey,
+          "POST",
+          { url: webhookUrl, events, description }
+        );
+        return success5(data);
+      } catch (err) {
+        const e = err;
+        if (e.status === 403) {
+          return error5(
+            "WEBHOOK_LIMIT",
+            e.message || "Webhook limit reached for this collection or plan.",
+            `Free plans allow 3 total webhooks (1 per collection). Pro plans allow 50 total (10 per collection). Delete unused webhooks or upgrade.`
+          );
+        }
+        return error5(
+          "CREATE_WEBHOOK_FAILED",
+          e.message || `Failed to create webhook for collection '${collection}'.`,
+          `Verify the URL is reachable HTTPS and the event names are valid.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "list_webhooks",
+    "List all webhooks registered on a jsondb.cloud collection. Returns webhook IDs, URLs, subscribed events, and status.",
+    {
+      collection: z5.string().describe("The collection name")
+    },
+    async ({ collection }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv2();
+        const data = await webhookFetch(
+          `${baseUrl}/${project}/${collection}/_webhooks`,
+          apiKey
+        );
+        return success5(data);
+      } catch (err) {
+        const e = err;
+        return error5(
+          "LIST_WEBHOOKS_FAILED",
+          e.message || `Failed to list webhooks for collection '${collection}'.`,
+          `Verify the collection name is correct. Use list_collections to see available collections.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "get_webhook",
+    "Get details for a specific webhook including its recent delivery history and failure counts.",
+    {
+      collection: z5.string().describe("The collection name"),
+      webhookId: z5.string().describe("The webhook ID (from list_webhooks or create_webhook)")
+    },
+    async ({ collection, webhookId }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv2();
+        const data = await webhookFetch(
+          `${baseUrl}/${project}/${collection}/_webhooks/${webhookId}`,
+          apiKey
+        );
+        return success5(data);
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error5(
+            "WEBHOOK_NOT_FOUND",
+            `Webhook '${webhookId}' not found in collection '${collection}'.`,
+            `Use list_webhooks({ collection: '${collection}' }) to see available webhooks.`
+          );
+        }
+        return error5(
+          "GET_WEBHOOK_FAILED",
+          e.message || `Failed to get webhook '${webhookId}'.`,
+          `Verify the collection name and webhook ID are correct.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "update_webhook",
+    "Update a webhook's URL, subscribed events, description, or enabled status. Only provided fields are changed.",
+    {
+      collection: z5.string().describe("The collection name"),
+      webhookId: z5.string().describe("The webhook ID to update"),
+      url: z5.string().url().optional().describe("New delivery URL"),
+      events: z5.array(webhookEventEnum).optional().describe("New event subscriptions (replaces existing list)"),
+      description: z5.string().optional().describe("New description"),
+      status: z5.enum(["active", "disabled"]).optional().describe("Set to 'disabled' to pause delivery, 'active' to resume")
+    },
+    async ({ collection, webhookId, url: webhookUrl, events, description, status: webhookStatus }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv2();
+        const body = {};
+        if (webhookUrl !== void 0) body.url = webhookUrl;
+        if (events !== void 0) body.events = events;
+        if (description !== void 0) body.description = description;
+        if (webhookStatus !== void 0) body.status = webhookStatus;
+        const data = await webhookFetch(
+          `${baseUrl}/${project}/${collection}/_webhooks/${webhookId}`,
+          apiKey,
+          "PUT",
+          body
+        );
+        return success5(data);
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error5(
+            "WEBHOOK_NOT_FOUND",
+            `Webhook '${webhookId}' not found in collection '${collection}'.`,
+            `Use list_webhooks({ collection: '${collection}' }) to see available webhooks.`
+          );
+        }
+        return error5(
+          "UPDATE_WEBHOOK_FAILED",
+          e.message || `Failed to update webhook '${webhookId}'.`,
+          `Verify the collection name and webhook ID are correct.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "delete_webhook",
+    "Delete a webhook permanently. Delivery of pending events is stopped immediately. This action cannot be undone.",
+    {
+      collection: z5.string().describe("The collection name"),
+      webhookId: z5.string().describe("The webhook ID to delete")
+    },
+    async ({ collection, webhookId }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv2();
+        await webhookFetch(
+          `${baseUrl}/${project}/${collection}/_webhooks/${webhookId}`,
+          apiKey,
+          "DELETE"
+        );
+        return success5({ deleted: true, webhookId, collection });
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error5(
+            "WEBHOOK_NOT_FOUND",
+            `Webhook '${webhookId}' not found in collection '${collection}'.`,
+            `Use list_webhooks({ collection: '${collection}' }) to see available webhooks.`
+          );
+        }
+        return error5(
+          "DELETE_WEBHOOK_FAILED",
+          e.message || `Failed to delete webhook '${webhookId}'.`,
+          `Verify the collection name and webhook ID are correct.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "test_webhook",
+    "Send a test event to a webhook to verify the endpoint is reachable and signature verification is working. Returns the delivery result.",
+    {
+      collection: z5.string().describe("The collection name"),
+      webhookId: z5.string().describe("The webhook ID to test")
+    },
+    async ({ collection, webhookId }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv2();
+        const data = await webhookFetch(
+          `${baseUrl}/${project}/${collection}/_webhooks/${webhookId}/test`,
+          apiKey,
+          "POST"
+        );
+        return success5(data);
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error5(
+            "WEBHOOK_NOT_FOUND",
+            `Webhook '${webhookId}' not found in collection '${collection}'.`,
+            `Use list_webhooks({ collection: '${collection}' }) to see available webhooks.`
+          );
+        }
+        return error5(
+          "TEST_WEBHOOK_FAILED",
+          e.message || `Failed to send test event to webhook '${webhookId}'.`,
+          `Verify the webhook URL is reachable and responding with a 2xx status.`
+        );
+      }
+    }
+  );
+}
+
+// src/resources/collections.ts
+function registerCollectionResources(server, db) {
+  server.resource(
+    "collections-list",
+    "jsondb://collections",
+    {
+      name: "jsondb.cloud Collections",
+      description: "List of all collections in the current project. Use this to discover what data is available.",
+      mimeType: "application/json"
+    },
+    async () => {
+      try {
+        const apiKey = process.env.JSONDB_API_KEY || "";
+        const project = process.env.JSONDB_PROJECT || process.env.JSONDB_NAMESPACE || "v1";
+        const baseUrl = (process.env.JSONDB_BASE_URL || "https://api.jsondb.cloud").replace(/\/$/, "");
+        const res = await fetch(`${baseUrl}/${project}`, {
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json"
+          }
+        });
+        if (!res.ok) {
+          return {
+            contents: [
+              {
+                uri: "jsondb://collections",
+                mimeType: "application/json",
+                text: JSON.stringify(
+                  { error: `Failed to fetch collections: ${res.statusText}` },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        const data = await res.json();
+        return {
+          contents: [
+            {
+              uri: "jsondb://collections",
+              mimeType: "application/json",
+              text: JSON.stringify(data, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        const e = err;
+        return {
+          contents: [
+            {
+              uri: "jsondb://collections",
+              mimeType: "application/json",
+              text: JSON.stringify(
+                { error: e.message || "Failed to fetch collections" },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.resource(
+    "collection-schema",
+    "jsondb://collections/{collection}/schema",
+    {
+      name: "Collection Schema",
+      description: "JSON Schema for a specific collection (if set). Helps AI agents understand the expected document structure.",
+      mimeType: "application/json"
+    },
+    async (uri, params) => {
+      const collection = typeof params.collection === "string" ? params.collection : String(params.collection);
+      try {
+        const coll = db.collection(collection);
+        const schema = await coll.getSchema();
+        const result = schema !== null ? { collection, schema } : {
+          collection,
+          schema: null,
+          message: `No schema is set for collection '${collection}'. Any valid JSON document can be stored.`
+        };
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: "application/json",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        const e = err;
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: "application/json",
+              text: JSON.stringify(
+                {
+                  error: e.message || `Failed to fetch schema for collection '${collection}'`
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/index.ts
+async function main() {
+  const apiKey = process.env.JSONDB_API_KEY;
+  if (!apiKey) {
+    console.error(
+      'Error: JSONDB_API_KEY environment variable is required.\n\nSet it in your MCP server configuration:\n  "env": { "JSONDB_API_KEY": "jdb_sk_live_..." }\n\nGet an API key from your jsondb.cloud dashboard.'
+    );
+    process.exit(1);
+  }
+  const project = process.env.JSONDB_PROJECT || process.env.JSONDB_NAMESPACE || "v1";
+  const baseUrl = process.env.JSONDB_BASE_URL || "https://api.jsondb.cloud";
+  const db = new JsonDB({
+    apiKey,
+    project,
+    baseUrl
+  });
+  const server = new McpServer({
+    name: "jsondb-cloud",
+    version: "1.0.0"
+  });
+  registerDocumentTools(server, db);
+  registerCollectionTools(server, db);
+  registerSchemaTools(server, db);
+  registerVersionTools(server, db);
+  registerWebhookTools(server, db);
+  registerCollectionResources(server, db);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("Fatal error starting MCP server:", err);
+  process.exit(1);
+});