@jsondb-cloud/mcp 1.0.14 → 1.0.25

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SIA Billy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -82,11 +82,14 @@ Add to `.cursor/mcp.json`:
 
 ### Environment Variables
 
-| Variable          | Required | Default                    | Description                                      |
-| ----------------- | -------- | -------------------------- | ------------------------------------------------ |
-| `JSONDB_API_KEY`  | Yes      | —                          | API key (`jdb_sk_live_...` or `jdb_sk_test_...`) |
-| `JSONDB_PROJECT`  | No       | `v1`                       | Project namespace                                |
-| `JSONDB_BASE_URL` | No       | `https://api.jsondb.cloud` | API base URL                                     |
+| Variable               | Required | Default                    | Description                                         |
+| ---------------------- | -------- | -------------------------- | --------------------------------------------------- |
+| `JSONDB_API_KEY`       | Yes      | —                          | API key (`jdb_sk_live_...` or `jdb_sk_test_...`)    |
+| `JSONDB_PROJECT`       | No       | `v1`                       | Project namespace                                   |
+| `JSONDB_BASE_URL`      | No       | `https://api.jsondb.cloud` | API base URL                                        |
+| `JSONDB_MCP_TRANSPORT` | No       | `stdio`                    | Transport type: `stdio` or `http`                   |
+| `JSONDB_MCP_PORT`      | No       | `3100`                     | HTTP server port (only used with `http` transport)  |
+| `JSONDB_MCP_HOST`      | No       | `127.0.0.1`                | HTTP bind address (only used with `http` transport) |
 
 ## Tools
 
@@ -141,6 +144,34 @@ Add to `.cursor/mcp.json`:
 | `delete_webhook` | Delete a webhook                                |
 | `test_webhook`   | Send a test event to verify delivery            |
 
+### Vectors
+
+| Tool                   | Description                                                                       |
+| ---------------------- | --------------------------------------------------------------------------------- |
+| `semantic_search`      | Search documents using natural language semantic similarity with relevance scores |
+| `store_with_embedding` | Store a document and auto-generate a vector embedding for semantic search         |
+
+Embeddings are generated **asynchronously by the jsondb.cloud backend** using **Ollama** (`nomic-embed-text`, 768 dimensions). The MCP server delegates to the REST API — no local embedding model or API key is needed.
+
+## HTTP Transport
+
+By default the server uses **stdio** transport (for Claude Desktop, Cursor, etc.). To run as an HTTP server instead, set:
+
+```bash
+JSONDB_MCP_TRANSPORT=http JSONDB_API_KEY=jdb_sk_live_... npx @jsondb-cloud/mcp
+```
+
+This starts a stateless Streamable HTTP server that creates a fresh `McpServer` + transport per request (no session affinity required). Endpoints:
+
+| Method   | Path      | Description                              |
+| -------- | --------- | ---------------------------------------- |
+| `POST`   | `/mcp`    | MCP JSON-RPC requests                    |
+| `GET`    | `/mcp`    | SSE stream for server notifications      |
+| `DELETE` | `/mcp`    | Session termination                      |
+| `GET`    | `/health` | Health check (returns `{"status":"ok"}`) |
+
+Configure the host and port with `JSONDB_MCP_HOST` and `JSONDB_MCP_PORT` (defaults: `127.0.0.1:3100`).
+
 ## Documentation
 
 Full documentation at [jsondb.cloud/docs](https://jsondb.cloud/docs).

package/dist/index.js

@@ -1,9 +1,33 @@
 "use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 
 // src/index.ts
 var import_mcp2 = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 var import_client = require("@jsondb-cloud/client");
+var import_node_http = __toESM(require("http"));
 
 // src/tools/documents.ts
 var import_zod = require("zod");
@@ -1177,6 +1201,171 @@ function registerWebhookTools(server, _db) {
   );
 }
 
+// src/tools/vectors.ts
+var import_zod6 = require("zod");
+
+// src/tools/_helpers.ts
+function success6(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+function error6(code, message, suggestion) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ error: { code, message, suggestion } }, null, 2)
+      }
+    ],
+    isError: true
+  };
+}
+function resolveEnv3() {
+  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 apiFetch(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();
+}
+
+// src/tools/vectors.ts
+function registerVectorTools(server, _db) {
+  server.tool(
+    "semantic_search",
+    "Search documents using natural language semantic similarity. Returns ranked results with relevance scores. Requires documents to have been stored with embeddings.",
+    {
+      collection: import_zod6.z.string().describe("Collection to search in"),
+      query: import_zod6.z.string().describe("Natural language search query"),
+      limit: import_zod6.z.number().min(1).max(100).default(10).optional().describe("Max results to return"),
+      threshold: import_zod6.z.number().min(0).max(1).default(0.7).optional().describe("Minimum similarity score (0-1)"),
+      filter: import_zod6.z.record(import_zod6.z.unknown()).optional().describe("Additional filter criteria")
+    },
+    async ({ collection, query, limit, threshold, filter }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv3();
+        const body = { query };
+        if (limit !== void 0) body.limit = limit;
+        if (threshold !== void 0) body.threshold = threshold;
+        if (filter !== void 0) body.filter = filter;
+        const data = await apiFetch(
+          `${baseUrl}/${project}/${collection}/_search`,
+          apiKey,
+          "POST",
+          body
+        );
+        return success6(data);
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error6(
+            "COLLECTION_NOT_FOUND",
+            `Collection '${collection}' not found or has no embeddings.`,
+            `Ensure the collection exists and documents were stored with store_with_embedding. Use list_collections to see available collections.`
+          );
+        }
+        if (e.status === 400) {
+          return error6(
+            "INVALID_SEARCH",
+            e.message || `Invalid search request for collection '${collection}'.`,
+            `Check that the query is a non-empty string and threshold is between 0 and 1.`
+          );
+        }
+        if (e.status === 403) {
+          return error6(
+            "SEARCH_NOT_AVAILABLE",
+            e.message || "Semantic search is not available on your current plan.",
+            `Upgrade your plan at https://jsondb.cloud/dashboard/billing to enable vector search.`
+          );
+        }
+        return error6(
+          "SEARCH_FAILED",
+          e.message || `Failed to search collection '${collection}'.`,
+          `Verify the collection name and that documents have been stored with embeddings.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "store_with_embedding",
+    "Store a document and automatically generate a vector embedding for semantic search. The embed_field specifies which field's text content should be embedded.",
+    {
+      collection: import_zod6.z.string().describe("Collection to store in"),
+      data: import_zod6.z.record(import_zod6.z.unknown()).describe("Document data to store"),
+      embed_field: import_zod6.z.string().describe("Field name whose content will be embedded for search"),
+      id: import_zod6.z.string().optional().describe("Optional custom document ID")
+    },
+    async ({ collection, data, embed_field, id }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv3();
+        const payload = { ...data, $embed: embed_field };
+        let result;
+        if (id) {
+          result = await apiFetch(
+            `${baseUrl}/${project}/${collection}/${id}`,
+            apiKey,
+            "PUT",
+            payload
+          );
+        } else {
+          result = await apiFetch(`${baseUrl}/${project}/${collection}`, apiKey, "POST", payload);
+        }
+        return success6(result);
+      } catch (err) {
+        const e = err;
+        if (e.status === 400) {
+          return error6(
+            "VALIDATION_ERROR",
+            e.message || `The document failed validation for collection '${collection}'.`,
+            `Ensure the embed_field '${embed_field}' exists in your data and contains text content suitable for embedding.`
+          );
+        }
+        if (e.status === 413) {
+          return error6(
+            "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 === 403) {
+          return error6(
+            "EMBEDDING_NOT_AVAILABLE",
+            e.message || "Embedding generation is not available on your current plan.",
+            `Upgrade your plan at https://jsondb.cloud/dashboard/billing to enable automatic embeddings.`
+          );
+        }
+        return error6(
+          "STORE_EMBEDDING_FAILED",
+          e.message || `Failed to store document with embedding in collection '${collection}'.`,
+          `Check that the collection name is valid, the data is a valid JSON object, and the embed_field references an existing text field.`
+        );
+      }
+    }
+  );
+}
+
 // src/resources/collections.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 function registerCollectionResources(server, db) {
@@ -1304,18 +1493,53 @@ async function main() {
     project,
     baseUrl
   });
-  const server = new import_mcp2.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 import_stdio.StdioServerTransport();
-  await server.connect(transport);
+  function createServer() {
+    const s = new import_mcp2.McpServer({ name: "jsondb-cloud", version: "1.0.0" });
+    registerDocumentTools(s, db);
+    registerCollectionTools(s, db);
+    registerSchemaTools(s, db);
+    registerVersionTools(s, db);
+    registerWebhookTools(s, db);
+    registerVectorTools(s, db);
+    registerCollectionResources(s, db);
+    return s;
+  }
+  const transportType = process.env.JSONDB_MCP_TRANSPORT || "stdio";
+  if (transportType === "http") {
+    const port = parseInt(process.env.JSONDB_MCP_PORT || "3100", 10);
+    const host = process.env.JSONDB_MCP_HOST || "127.0.0.1";
+    const httpServer = import_node_http.default.createServer(async (req, res) => {
+      if (req.method === "GET" && req.url === "/health") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ status: "ok" }));
+        return;
+      }
+      if (req.url === "/mcp") {
+        const server = createServer();
+        const transport = new import_streamableHttp.StreamableHTTPServerTransport({
+          sessionIdGenerator: void 0
+        });
+        res.on("close", () => {
+          transport.close().catch(() => {
+          });
+          server.close().catch(() => {
+          });
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+        return;
+      }
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Not found" }));
+    });
+    httpServer.listen(port, host, () => {
+      console.error(`MCP HTTP server listening on ${host}:${port}`);
+    });
+  } else {
+    const server = createServer();
+    const transport = new import_stdio.StdioServerTransport();
+    await server.connect(transport);
+  }
 }
 main().catch((err) => {
   console.error("Fatal error starting MCP server:", err);

package/dist/index.mjs

@@ -1,7 +1,9 @@
 // src/index.ts
 import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { JsonDB } from "@jsondb-cloud/client";
+import http from "http";
 
 // src/tools/documents.ts
 import { z } from "zod";
@@ -1175,6 +1177,171 @@ function registerWebhookTools(server, _db) {
   );
 }
 
+// src/tools/vectors.ts
+import { z as z6 } from "zod";
+
+// src/tools/_helpers.ts
+function success6(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+function error6(code, message, suggestion) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ error: { code, message, suggestion } }, null, 2)
+      }
+    ],
+    isError: true
+  };
+}
+function resolveEnv3() {
+  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 apiFetch(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();
+}
+
+// src/tools/vectors.ts
+function registerVectorTools(server, _db) {
+  server.tool(
+    "semantic_search",
+    "Search documents using natural language semantic similarity. Returns ranked results with relevance scores. Requires documents to have been stored with embeddings.",
+    {
+      collection: z6.string().describe("Collection to search in"),
+      query: z6.string().describe("Natural language search query"),
+      limit: z6.number().min(1).max(100).default(10).optional().describe("Max results to return"),
+      threshold: z6.number().min(0).max(1).default(0.7).optional().describe("Minimum similarity score (0-1)"),
+      filter: z6.record(z6.unknown()).optional().describe("Additional filter criteria")
+    },
+    async ({ collection, query, limit, threshold, filter }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv3();
+        const body = { query };
+        if (limit !== void 0) body.limit = limit;
+        if (threshold !== void 0) body.threshold = threshold;
+        if (filter !== void 0) body.filter = filter;
+        const data = await apiFetch(
+          `${baseUrl}/${project}/${collection}/_search`,
+          apiKey,
+          "POST",
+          body
+        );
+        return success6(data);
+      } catch (err) {
+        const e = err;
+        if (e.status === 404) {
+          return error6(
+            "COLLECTION_NOT_FOUND",
+            `Collection '${collection}' not found or has no embeddings.`,
+            `Ensure the collection exists and documents were stored with store_with_embedding. Use list_collections to see available collections.`
+          );
+        }
+        if (e.status === 400) {
+          return error6(
+            "INVALID_SEARCH",
+            e.message || `Invalid search request for collection '${collection}'.`,
+            `Check that the query is a non-empty string and threshold is between 0 and 1.`
+          );
+        }
+        if (e.status === 403) {
+          return error6(
+            "SEARCH_NOT_AVAILABLE",
+            e.message || "Semantic search is not available on your current plan.",
+            `Upgrade your plan at https://jsondb.cloud/dashboard/billing to enable vector search.`
+          );
+        }
+        return error6(
+          "SEARCH_FAILED",
+          e.message || `Failed to search collection '${collection}'.`,
+          `Verify the collection name and that documents have been stored with embeddings.`
+        );
+      }
+    }
+  );
+  server.tool(
+    "store_with_embedding",
+    "Store a document and automatically generate a vector embedding for semantic search. The embed_field specifies which field's text content should be embedded.",
+    {
+      collection: z6.string().describe("Collection to store in"),
+      data: z6.record(z6.unknown()).describe("Document data to store"),
+      embed_field: z6.string().describe("Field name whose content will be embedded for search"),
+      id: z6.string().optional().describe("Optional custom document ID")
+    },
+    async ({ collection, data, embed_field, id }) => {
+      try {
+        const { apiKey, project, baseUrl } = resolveEnv3();
+        const payload = { ...data, $embed: embed_field };
+        let result;
+        if (id) {
+          result = await apiFetch(
+            `${baseUrl}/${project}/${collection}/${id}`,
+            apiKey,
+            "PUT",
+            payload
+          );
+        } else {
+          result = await apiFetch(`${baseUrl}/${project}/${collection}`, apiKey, "POST", payload);
+        }
+        return success6(result);
+      } catch (err) {
+        const e = err;
+        if (e.status === 400) {
+          return error6(
+            "VALIDATION_ERROR",
+            e.message || `The document failed validation for collection '${collection}'.`,
+            `Ensure the embed_field '${embed_field}' exists in your data and contains text content suitable for embedding.`
+          );
+        }
+        if (e.status === 413) {
+          return error6(
+            "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 === 403) {
+          return error6(
+            "EMBEDDING_NOT_AVAILABLE",
+            e.message || "Embedding generation is not available on your current plan.",
+            `Upgrade your plan at https://jsondb.cloud/dashboard/billing to enable automatic embeddings.`
+          );
+        }
+        return error6(
+          "STORE_EMBEDDING_FAILED",
+          e.message || `Failed to store document with embedding in collection '${collection}'.`,
+          `Check that the collection name is valid, the data is a valid JSON object, and the embed_field references an existing text field.`
+        );
+      }
+    }
+  );
+}
+
 // src/resources/collections.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 function registerCollectionResources(server, db) {
@@ -1302,18 +1469,53 @@ async function main() {
     project,
     baseUrl
   });
-  const server = new McpServer2({
-    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);
+  function createServer() {
+    const s = new McpServer2({ name: "jsondb-cloud", version: "1.0.0" });
+    registerDocumentTools(s, db);
+    registerCollectionTools(s, db);
+    registerSchemaTools(s, db);
+    registerVersionTools(s, db);
+    registerWebhookTools(s, db);
+    registerVectorTools(s, db);
+    registerCollectionResources(s, db);
+    return s;
+  }
+  const transportType = process.env.JSONDB_MCP_TRANSPORT || "stdio";
+  if (transportType === "http") {
+    const port = parseInt(process.env.JSONDB_MCP_PORT || "3100", 10);
+    const host = process.env.JSONDB_MCP_HOST || "127.0.0.1";
+    const httpServer = http.createServer(async (req, res) => {
+      if (req.method === "GET" && req.url === "/health") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ status: "ok" }));
+        return;
+      }
+      if (req.url === "/mcp") {
+        const server = createServer();
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: void 0
+        });
+        res.on("close", () => {
+          transport.close().catch(() => {
+          });
+          server.close().catch(() => {
+          });
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+        return;
+      }
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Not found" }));
+    });
+    httpServer.listen(port, host, () => {
+      console.error(`MCP HTTP server listening on ${host}:${port}`);
+    });
+  } else {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+  }
 }
 main().catch((err) => {
   console.error("Fatal error starting MCP server:", err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsondb-cloud/mcp",
-  "version": "1.0.14",
+  "version": "1.0.25",
   "description": "MCP (Model Context Protocol) server for jsondb.cloud — lets AI agents interact with your JSON database",
   "license": "MIT",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@jsondb-cloud/client": "*",
+    "@jsondb-cloud/client": "^1.0.18",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.23.0"
   },