@topgunbuild/mcp-server 0.9.0

package/dist/index.mjs

@@ -0,0 +1,1495 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { TopGunClient } from '@topgunbuild/client';
+import { z } from 'zod';
+import pino from 'pino';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { createServer } from 'http';
+import { randomUUID } from 'crypto';
+
+// src/TopGunMCPServer.ts
+var QueryArgsSchema = z.object({
+  map: z.string().describe("Name of the map to query (e.g., 'tasks', 'users', 'products')"),
+  filter: z.record(z.string(), z.unknown()).optional().describe('Filter criteria as key-value pairs. Example: { "status": "active", "priority": "high" }'),
+  sort: z.object({
+    field: z.string().describe("Field name to sort by"),
+    order: z.enum(["asc", "desc"]).describe("Sort order: ascending or descending")
+  }).optional().describe("Sort configuration"),
+  limit: z.number().optional().default(10).describe("Maximum number of results to return"),
+  offset: z.number().optional().default(0).describe("Number of results to skip (for pagination)")
+});
+var MutateArgsSchema = z.object({
+  map: z.string().describe("Name of the map to modify (e.g., 'tasks', 'users')"),
+  operation: z.enum(["set", "remove"]).describe('"set" creates or updates a record, "remove" deletes it'),
+  key: z.string().describe("Unique key for the record"),
+  data: z.record(z.string(), z.unknown()).optional().describe('Data to write (required for "set" operation)')
+});
+var SearchArgsSchema = z.object({
+  map: z.string().describe("Name of the map to search (e.g., 'articles', 'documents', 'tasks')"),
+  query: z.string().describe("Search query (keywords or phrases to find)"),
+  methods: z.array(z.enum(["exact", "fulltext", "range"])).optional().default(["exact", "fulltext"]).describe('Search methods to use. Default: ["exact", "fulltext"]'),
+  limit: z.number().optional().default(10).describe("Maximum number of results to return"),
+  minScore: z.number().optional().default(0).describe("Minimum relevance score (0-1) for results")
+});
+var SubscribeArgsSchema = z.object({
+  map: z.string().describe("Name of the map to watch (e.g., 'tasks', 'notifications')"),
+  filter: z.record(z.string(), z.unknown()).optional().describe("Filter criteria - only report changes matching these conditions"),
+  timeout: z.number().optional().default(60).describe("How long to watch for changes (in seconds)")
+});
+var SchemaArgsSchema = z.object({
+  map: z.string().describe("Name of the map to get schema for")
+});
+var StatsArgsSchema = z.object({
+  map: z.string().optional().describe("Specific map to get stats for (optional, returns all maps if not specified)")
+});
+var ExplainArgsSchema = z.object({
+  map: z.string().describe("Name of the map to query"),
+  filter: z.record(z.string(), z.unknown()).optional().describe("Filter criteria to analyze")
+});
+var ListMapsArgsSchema = z.object({});
+var toolSchemas = {
+  query: {
+    type: "object",
+    properties: {
+      map: {
+        type: "string",
+        description: "Name of the map to query (e.g., 'tasks', 'users', 'products')"
+      },
+      filter: {
+        type: "object",
+        description: 'Filter criteria as key-value pairs. Example: { "status": "active", "priority": "high" }',
+        additionalProperties: true
+      },
+      sort: {
+        type: "object",
+        properties: {
+          field: { type: "string", description: "Field name to sort by" },
+          order: { type: "string", enum: ["asc", "desc"], description: "Sort order: ascending or descending" }
+        },
+        required: ["field", "order"],
+        description: "Sort configuration"
+      },
+      limit: { type: "number", description: "Maximum number of results to return", default: 10 },
+      offset: { type: "number", description: "Number of results to skip (for pagination)", default: 0 }
+    },
+    required: ["map"]
+  },
+  mutate: {
+    type: "object",
+    properties: {
+      map: { type: "string", description: "Name of the map to modify (e.g., 'tasks', 'users')" },
+      operation: {
+        type: "string",
+        enum: ["set", "remove"],
+        description: '"set" creates or updates a record, "remove" deletes it'
+      },
+      key: { type: "string", description: "Unique key for the record" },
+      data: {
+        type: "object",
+        description: 'Data to write (required for "set" operation)',
+        additionalProperties: true
+      }
+    },
+    required: ["map", "operation", "key"]
+  },
+  search: {
+    type: "object",
+    properties: {
+      map: { type: "string", description: "Name of the map to search (e.g., 'articles', 'documents', 'tasks')" },
+      query: { type: "string", description: "Search query (keywords or phrases to find)" },
+      methods: {
+        type: "array",
+        items: { type: "string", enum: ["exact", "fulltext", "range"] },
+        description: 'Search methods to use. Default: ["exact", "fulltext"]',
+        default: ["exact", "fulltext"]
+      },
+      limit: { type: "number", description: "Maximum number of results to return", default: 10 },
+      minScore: { type: "number", description: "Minimum relevance score (0-1) for results", default: 0 }
+    },
+    required: ["map", "query"]
+  },
+  subscribe: {
+    type: "object",
+    properties: {
+      map: { type: "string", description: "Name of the map to watch (e.g., 'tasks', 'notifications')" },
+      filter: {
+        type: "object",
+        description: "Filter criteria - only report changes matching these conditions",
+        additionalProperties: true
+      },
+      timeout: { type: "number", description: "How long to watch for changes (in seconds)", default: 60 }
+    },
+    required: ["map"]
+  },
+  schema: {
+    type: "object",
+    properties: {
+      map: { type: "string", description: "Name of the map to get schema for" }
+    },
+    required: ["map"]
+  },
+  stats: {
+    type: "object",
+    properties: {
+      map: {
+        type: "string",
+        description: "Specific map to get stats for (optional, returns all maps if not specified)"
+      }
+    },
+    required: []
+  },
+  explain: {
+    type: "object",
+    properties: {
+      map: { type: "string", description: "Name of the map to query" },
+      filter: {
+        type: "object",
+        description: "Filter criteria to analyze",
+        additionalProperties: true
+      }
+    },
+    required: ["map"]
+  },
+  listMaps: {
+    type: "object",
+    properties: {},
+    required: []
+  }
+};
+
+// src/tools/query.ts
+var queryTool = {
+  name: "topgun_query",
+  description: "Query data from a TopGun map with filters and sorting. Use this to read data from the database. Supports filtering by field values and sorting by any field.",
+  inputSchema: toolSchemas.query
+};
+async function handleQuery(rawArgs, ctx) {
+  const parseResult = QueryArgsSchema.safeParse(rawArgs);
+  if (!parseResult.success) {
+    const errors = parseResult.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+    return {
+      content: [{ type: "text", text: `Invalid arguments: ${errors}` }],
+      isError: true
+    };
+  }
+  const { map, filter, sort, limit, offset } = parseResult.data;
+  if (ctx.config.allowedMaps && !ctx.config.allowedMaps.includes(map)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: Access to map '${map}' is not allowed. Available maps: ${ctx.config.allowedMaps.join(", ")}`
+        }
+      ],
+      isError: true
+    };
+  }
+  const effectiveLimit = Math.min(limit ?? ctx.config.defaultLimit, ctx.config.maxLimit);
+  const effectiveOffset = offset ?? 0;
+  try {
+    const lwwMap = ctx.client.getMap(map);
+    const allEntries = [];
+    for (const [key, value] of lwwMap.entries()) {
+      if (value !== null && typeof value === "object") {
+        let matches = true;
+        if (filter) {
+          for (const [filterKey, filterValue] of Object.entries(filter)) {
+            if (value[filterKey] !== filterValue) {
+              matches = false;
+              break;
+            }
+          }
+        }
+        if (matches) {
+          allEntries.push({ key: String(key), value });
+        }
+      }
+    }
+    if (sort?.field) {
+      allEntries.sort((a, b) => {
+        const aVal = a.value[sort.field];
+        const bVal = b.value[sort.field];
+        if (aVal === bVal) return 0;
+        if (aVal === void 0 || aVal === null) return 1;
+        if (bVal === void 0 || bVal === null) return -1;
+        const comparison = aVal < bVal ? -1 : 1;
+        return sort.order === "desc" ? -comparison : comparison;
+      });
+    }
+    const paginatedEntries = allEntries.slice(effectiveOffset, effectiveOffset + effectiveLimit);
+    if (paginatedEntries.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No results found in map '${map}'${filter ? " matching the filter" : ""}.`
+          }
+        ]
+      };
+    }
+    const formatted = paginatedEntries.map((entry, idx) => `${idx + 1 + effectiveOffset}. [${entry.key}]: ${JSON.stringify(entry.value, null, 2)}`).join("\n\n");
+    const totalInfo = allEntries.length > effectiveLimit ? `
+
+(Showing ${effectiveOffset + 1}-${effectiveOffset + paginatedEntries.length} of ${allEntries.length} total)` : "";
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Found ${paginatedEntries.length} result(s) in map '${map}':
+
+${formatted}${totalInfo}`
+        }
+      ]
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error querying map '${map}': ${message}`
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/tools/mutate.ts
+var mutateTool = {
+  name: "topgun_mutate",
+  description: 'Create, update, or delete data in a TopGun map. Use "set" operation to create or update a record. Use "remove" operation to delete a record.',
+  inputSchema: toolSchemas.mutate
+};
+async function handleMutate(rawArgs, ctx) {
+  const parseResult = MutateArgsSchema.safeParse(rawArgs);
+  if (!parseResult.success) {
+    const errors = parseResult.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+    return {
+      content: [{ type: "text", text: `Invalid arguments: ${errors}` }],
+      isError: true
+    };
+  }
+  const { map, operation, key, data } = parseResult.data;
+  if (!ctx.config.enableMutations) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "Error: Mutation operations are disabled on this MCP server."
+        }
+      ],
+      isError: true
+    };
+  }
+  if (ctx.config.allowedMaps && !ctx.config.allowedMaps.includes(map)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: Access to map '${map}' is not allowed. Available maps: ${ctx.config.allowedMaps.join(", ")}`
+        }
+      ],
+      isError: true
+    };
+  }
+  try {
+    const lwwMap = ctx.client.getMap(map);
+    if (operation === "set") {
+      if (!data) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: 'Error: "data" is required for "set" operation.'
+            }
+          ],
+          isError: true
+        };
+      }
+      const recordData = {
+        ...data,
+        _updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      const existingValue = lwwMap.get(key);
+      const isCreate = existingValue === void 0;
+      lwwMap.set(key, recordData);
+      return {
+        content: [
+          {
+            type: "text",
+            text: isCreate ? `Successfully created record '${key}' in map '${map}':
+${JSON.stringify(recordData, null, 2)}` : `Successfully updated record '${key}' in map '${map}':
+${JSON.stringify(recordData, null, 2)}`
+          }
+        ]
+      };
+    } else if (operation === "remove") {
+      const existingValue = lwwMap.get(key);
+      if (existingValue === void 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Warning: Record '${key}' does not exist in map '${map}'. No action taken.`
+            }
+          ]
+        };
+      }
+      lwwMap.remove(key);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Successfully removed record '${key}' from map '${map}'.`
+          }
+        ]
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: Invalid operation '${operation}'. Use 'set' or 'remove'.`
+        }
+      ],
+      isError: true
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error performing ${operation} on map '${map}': ${message}`
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/tools/search.ts
+var searchTool = {
+  name: "topgun_search",
+  description: "Perform hybrid search across a TopGun map using BM25 full-text search. Returns results ranked by relevance score. Use this when searching for text content or when the exact field values are unknown.",
+  inputSchema: toolSchemas.search
+};
+async function handleSearch(rawArgs, ctx) {
+  const parseResult = SearchArgsSchema.safeParse(rawArgs);
+  if (!parseResult.success) {
+    const errors = parseResult.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+    return {
+      content: [{ type: "text", text: `Invalid arguments: ${errors}` }],
+      isError: true
+    };
+  }
+  const args = parseResult.data;
+  const { map, query, limit, minScore } = args;
+  if (ctx.config.allowedMaps && !ctx.config.allowedMaps.includes(map)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: Access to map '${map}' is not allowed. Available maps: ${ctx.config.allowedMaps.join(", ")}`
+        }
+      ],
+      isError: true
+    };
+  }
+  const effectiveLimit = Math.min(limit ?? ctx.config.defaultLimit, ctx.config.maxLimit);
+  const effectiveMinScore = minScore ?? 0;
+  try {
+    const results = await ctx.client.search(map, query, {
+      limit: effectiveLimit,
+      minScore: effectiveMinScore
+    });
+    if (results.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No results found in map '${map}' for query "${query}".`
+          }
+        ]
+      };
+    }
+    const formatted = results.map(
+      (result, idx) => `${idx + 1}. [Score: ${result.score.toFixed(3)}] [${result.key}]
+   Matched: ${result.matchedTerms.join(", ")}
+   Data: ${JSON.stringify(result.value, null, 2).split("\n").join("\n   ")}`
+    ).join("\n\n");
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Found ${results.length} result(s) in map '${map}' for query "${query}":
+
+${formatted}`
+        }
+      ]
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("not enabled") || message.includes("FTS")) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Full-text search is not enabled for map '${map}'. Use topgun_query instead for exact matching, or enable FTS on the server.`
+          }
+        ],
+        isError: true
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error searching map '${map}': ${message}`
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/tools/subscribe.ts
+var subscribeTool = {
+  name: "topgun_subscribe",
+  description: "Subscribe to real-time changes in a TopGun map. Returns changes that occur within the timeout period. Use this to watch for new or updated data.",
+  inputSchema: toolSchemas.subscribe
+};
+async function handleSubscribe(rawArgs, ctx) {
+  const parseResult = SubscribeArgsSchema.safeParse(rawArgs);
+  if (!parseResult.success) {
+    const errors = parseResult.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+    return {
+      content: [{ type: "text", text: `Invalid arguments: ${errors}` }],
+      isError: true
+    };
+  }
+  const args = parseResult.data;
+  const { map, filter, timeout } = args;
+  if (!ctx.config.enableSubscriptions) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "Error: Subscription operations are disabled on this MCP server."
+        }
+      ],
+      isError: true
+    };
+  }
+  if (ctx.config.allowedMaps && !ctx.config.allowedMaps.includes(map)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: Access to map '${map}' is not allowed. Available maps: ${ctx.config.allowedMaps.join(", ")}`
+        }
+      ],
+      isError: true
+    };
+  }
+  const effectiveTimeout = Math.min(
+    timeout ?? ctx.config.subscriptionTimeoutSeconds,
+    ctx.config.subscriptionTimeoutSeconds
+  );
+  try {
+    const queryHandle = ctx.client.query(map, filter ?? {});
+    const changes = [];
+    let isInitialLoad = true;
+    const unsubscribe = queryHandle.subscribe((results) => {
+      if (isInitialLoad) {
+        isInitialLoad = false;
+        return;
+      }
+      for (const result of results) {
+        changes.push({
+          type: "update",
+          key: result._key ?? "unknown",
+          value: result,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+    });
+    await new Promise((resolve) => setTimeout(resolve, effectiveTimeout * 1e3));
+    unsubscribe();
+    if (changes.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No changes detected in map '${map}' during the ${effectiveTimeout} second watch period.`
+          }
+        ]
+      };
+    }
+    const formatted = changes.map(
+      (change, idx) => `${idx + 1}. [${change.timestamp}] ${change.type.toUpperCase()} - ${change.key}
+` + (change.value ? `   ${JSON.stringify(change.value, null, 2).split("\n").join("\n   ")}` : "")
+    ).join("\n\n");
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Detected ${changes.length} change(s) in map '${map}' during ${effectiveTimeout} seconds:
+
+${formatted}`
+        }
+      ]
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error subscribing to map '${map}': ${message}`
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/tools/schema.ts
+var schemaTool = {
+  name: "topgun_schema",
+  description: "Get schema information about a TopGun map. Returns inferred field types and indexes. Use this to understand the structure of data in a map.",
+  inputSchema: toolSchemas.schema
+};
+function inferType(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "array";
+    const itemTypes = [...new Set(value.map((v) => inferType(v)))];
+    return `array<${itemTypes.join(" | ")}>`;
+  }
+  if (value instanceof Date) return "date";
+  if (typeof value === "object") return "object";
+  return typeof value;
+}
+function isTimestamp(value) {
+  if (typeof value === "string") {
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(value)) return true;
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) return true;
+  }
+  if (typeof value === "number") {
+    if (value > 9466848e5 && value < 41024448e5) return true;
+  }
+  return false;
+}
+function inferEnum(values) {
+  const uniqueValues = [...new Set(values.filter((v) => typeof v === "string"))];
+  if (uniqueValues.length >= 2 && uniqueValues.length <= 10) {
+    return uniqueValues;
+  }
+  return null;
+}
+async function handleSchema(rawArgs, ctx) {
+  const parseResult = SchemaArgsSchema.safeParse(rawArgs);
+  if (!parseResult.success) {
+    const errors = parseResult.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+    return {
+      content: [{ type: "text", text: `Invalid arguments: ${errors}` }],
+      isError: true
+    };
+  }
+  const args = parseResult.data;
+  const { map } = args;
+  if (ctx.config.allowedMaps && !ctx.config.allowedMaps.includes(map)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: Access to map '${map}' is not allowed. Available maps: ${ctx.config.allowedMaps.join(", ")}`
+        }
+      ],
+      isError: true
+    };
+  }
+  try {
+    const lwwMap = ctx.client.getMap(map);
+    const fieldTypes = /* @__PURE__ */ new Map();
+    const fieldValues = /* @__PURE__ */ new Map();
+    let recordCount = 0;
+    for (const [, value] of lwwMap.entries()) {
+      if (value !== null && typeof value === "object") {
+        recordCount++;
+        for (const [fieldName, fieldValue] of Object.entries(value)) {
+          if (!fieldTypes.has(fieldName)) {
+            fieldTypes.set(fieldName, /* @__PURE__ */ new Set());
+          }
+          let inferredType = inferType(fieldValue);
+          if (isTimestamp(fieldValue)) {
+            inferredType = "timestamp";
+          }
+          fieldTypes.get(fieldName).add(inferredType);
+          if (!fieldValues.has(fieldName)) {
+            fieldValues.set(fieldName, []);
+          }
+          fieldValues.get(fieldName).push(fieldValue);
+        }
+      }
+    }
+    if (recordCount === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Map '${map}' is empty. No schema information available.
+
+Tip: Add some data to the map to infer its schema.`
+          }
+        ]
+      };
+    }
+    const fields = {};
+    for (const [fieldName, types] of fieldTypes.entries()) {
+      const typeArray = [...types];
+      const values = fieldValues.get(fieldName) ?? [];
+      const enumValues = inferEnum(values);
+      if (enumValues && typeArray.length === 1 && typeArray[0] === "string") {
+        fields[fieldName] = `enum(${enumValues.join(", ")})`;
+      } else if (typeArray.length === 1) {
+        fields[fieldName] = typeArray[0];
+      } else {
+        fields[fieldName] = typeArray.join(" | ");
+      }
+    }
+    const schemaOutput = {
+      map,
+      recordCount,
+      fields,
+      // Note: Index information would come from server metadata in a full implementation
+      indexes: []
+    };
+    const fieldsFormatted = Object.entries(fields).map(([name, type]) => `  - ${name}: ${type}`).join("\n");
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Schema for map '${map}':
+
+Records: ${recordCount}
+
+Fields:
+${fieldsFormatted}
+
+Raw schema:
+${JSON.stringify(schemaOutput, null, 2)}`
+        }
+      ]
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error getting schema for map '${map}': ${message}`
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/tools/stats.ts
+var statsTool = {
+  name: "topgun_stats",
+  description: "Get statistics about TopGun maps. Returns record counts, connection status, and sync state. Use this to understand the health and size of your data.",
+  inputSchema: toolSchemas.stats
+};
+async function handleStats(rawArgs, ctx) {
+  const parseResult = StatsArgsSchema.safeParse(rawArgs);
+  if (!parseResult.success) {
+    const errors = parseResult.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+    return {
+      content: [{ type: "text", text: `Invalid arguments: ${errors}` }],
+      isError: true
+    };
+  }
+  const args = parseResult.data;
+  const { map } = args;
+  if (map && ctx.config.allowedMaps && !ctx.config.allowedMaps.includes(map)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: Access to map '${map}' is not allowed. Available maps: ${ctx.config.allowedMaps.join(", ")}`
+        }
+      ],
+      isError: true
+    };
+  }
+  try {
+    const stats = {
+      connection: {
+        state: ctx.client.getConnectionState(),
+        isCluster: ctx.client.isCluster(),
+        pendingOps: ctx.client.getPendingOpsCount(),
+        backpressurePaused: ctx.client.isBackpressurePaused()
+      },
+      maps: []
+    };
+    if (ctx.client.isCluster()) {
+      stats.cluster = {
+        nodes: ctx.client.getConnectedNodes(),
+        partitionMapVersion: ctx.client.getPartitionMapVersion(),
+        routingActive: ctx.client.isRoutingActive()
+      };
+    }
+    if (map) {
+      const lwwMap = ctx.client.getMap(map);
+      let recordCount = 0;
+      let tombstoneCount = 0;
+      for (const [, value] of lwwMap.entries()) {
+        if (value === null || value === void 0) {
+          tombstoneCount++;
+        } else {
+          recordCount++;
+        }
+      }
+      stats.maps.push({
+        name: map,
+        recordCount,
+        tombstoneCount
+      });
+    }
+    const connectionInfo = `Connection Status:
+  - State: ${stats.connection.state}
+  - Mode: ${stats.connection.isCluster ? "Cluster" : "Single Server"}
+  - Pending Operations: ${stats.connection.pendingOps}
+  - Backpressure Paused: ${stats.connection.backpressurePaused}`;
+    const clusterInfo = stats.cluster ? `
+
+Cluster Info:
+  - Connected Nodes: ${stats.cluster.nodes.length > 0 ? stats.cluster.nodes.join(", ") : "none"}
+  - Partition Map Version: ${stats.cluster.partitionMapVersion}
+  - Routing Active: ${stats.cluster.routingActive}` : "";
+    const mapInfo = stats.maps.length > 0 ? `
+
+Map Statistics:
+` + stats.maps.map(
+      (m) => `  ${m.name}:
+    - Records: ${m.recordCount}
+    - Tombstones: ${m.tombstoneCount}`
+    ).join("\n") : map ? `
+
+Map '${map}' has no data yet.` : "";
+    return {
+      content: [
+        {
+          type: "text",
+          text: `TopGun Statistics:
+
+${connectionInfo}${clusterInfo}${mapInfo}`
+        }
+      ]
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error getting stats: ${message}`
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/tools/explain.ts
+var explainTool = {
+  name: "topgun_explain",
+  description: "Explain how a query would be executed against a TopGun map. Returns the query plan, estimated result count, and execution strategy. Use this to understand and optimize queries.",
+  inputSchema: toolSchemas.explain
+};
+async function handleExplain(rawArgs, ctx) {
+  const parseResult = ExplainArgsSchema.safeParse(rawArgs);
+  if (!parseResult.success) {
+    const errors = parseResult.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+    return {
+      content: [{ type: "text", text: `Invalid arguments: ${errors}` }],
+      isError: true
+    };
+  }
+  const args = parseResult.data;
+  const { map, filter } = args;
+  if (ctx.config.allowedMaps && !ctx.config.allowedMaps.includes(map)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: Access to map '${map}' is not allowed. Available maps: ${ctx.config.allowedMaps.join(", ")}`
+        }
+      ],
+      isError: true
+    };
+  }
+  try {
+    const lwwMap = ctx.client.getMap(map);
+    let totalRecords = 0;
+    let matchingRecords = 0;
+    for (const [, value] of lwwMap.entries()) {
+      if (value !== null && typeof value === "object") {
+        totalRecords++;
+        if (filter) {
+          let matches = true;
+          for (const [filterKey, filterValue] of Object.entries(filter)) {
+            if (value[filterKey] !== filterValue) {
+              matches = false;
+              break;
+            }
+          }
+          if (matches) matchingRecords++;
+        } else {
+          matchingRecords++;
+        }
+      }
+    }
+    const plan = {
+      strategy: filter ? "FILTER_SCAN" : "FULL_SCAN",
+      steps: [],
+      estimatedResults: matchingRecords,
+      totalRecords,
+      selectivity: totalRecords > 0 ? matchingRecords / totalRecords : 0,
+      recommendations: []
+    };
+    plan.steps.push(`1. Scan map '${map}' (${totalRecords} records)`);
+    if (filter) {
+      const filterFields = Object.keys(filter);
+      plan.steps.push(`2. Apply filter on fields: ${filterFields.join(", ")}`);
+      plan.steps.push(`3. Return matching records (estimated: ${matchingRecords})`);
+      if (plan.selectivity < 0.1) {
+        plan.recommendations.push(
+          `Consider creating an index on ${filterFields.join(", ")} for better performance.`
+        );
+      }
+      if (totalRecords > 1e3 && plan.selectivity > 0.5) {
+        plan.recommendations.push(
+          `Query is not selective (${(plan.selectivity * 100).toFixed(1)}% of records match). Consider adding more filter criteria.`
+        );
+      }
+    } else {
+      plan.steps.push(`2. Return all records`);
+      if (totalRecords > 100) {
+        plan.recommendations.push(
+          `No filter applied. Consider adding filter criteria to reduce result size.`
+        );
+      }
+    }
+    if (filter) {
+      const stringFilters = Object.entries(filter).filter(
+        ([, v]) => typeof v === "string" && String(v).length > 3
+      );
+      if (stringFilters.length > 0) {
+        plan.recommendations.push(
+          `For text search on fields [${stringFilters.map(([k]) => k).join(", ")}], consider using topgun_search instead for better relevance ranking.`
+        );
+      }
+    }
+    const stepsFormatted = plan.steps.join("\n");
+    const recommendationsFormatted = plan.recommendations.length > 0 ? `
+
+Recommendations:
+${plan.recommendations.map((r) => `  - ${r}`).join("\n")}` : "";
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Query Plan for map '${map}':
+
+Strategy: ${plan.strategy}
+
+Execution Steps:
+${stepsFormatted}
+
+Statistics:
+  - Total Records: ${plan.totalRecords}
+  - Estimated Results: ${plan.estimatedResults}
+  - Selectivity: ${(plan.selectivity * 100).toFixed(1)}%` + recommendationsFormatted
+        }
+      ]
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error explaining query on map '${map}': ${message}`
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/tools/listMaps.ts
+var listMapsTool = {
+  name: "topgun_list_maps",
+  description: "List all available TopGun maps that can be queried. Returns the names of maps you have access to. Use this first to discover what data is available.",
+  inputSchema: toolSchemas.listMaps
+};
+async function handleListMaps(rawArgs, ctx) {
+  const parseResult = ListMapsArgsSchema.safeParse(rawArgs);
+  if (!parseResult.success) {
+    const errors = parseResult.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+    return {
+      content: [{ type: "text", text: `Invalid arguments: ${errors}` }],
+      isError: true
+    };
+  }
+  try {
+    if (ctx.config.allowedMaps && ctx.config.allowedMaps.length > 0) {
+      const mapList = ctx.config.allowedMaps.map((name) => `  - ${name}`).join("\n");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Available maps (${ctx.config.allowedMaps.length}):
+${mapList}
+
+Use topgun_schema to get field information for a specific map.
+Use topgun_query to read data from a map.`
+          }
+        ]
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `This MCP server allows access to all maps (no restrictions configured).
+
+To query a map, use topgun_query with the map name.
+To get schema information, use topgun_schema.
+To search, use topgun_search.
+
+Common map patterns:
+  - 'users' - User accounts
+  - 'tasks' - Task items
+  - 'posts' - Blog posts or messages
+  - 'products' - E-commerce products
+
+Tip: Ask the user what maps are available in their application.`
+        }
+      ]
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error listing maps: ${message}`
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/tools/index.ts
+var allTools = [
+  listMapsTool,
+  queryTool,
+  mutateTool,
+  searchTool,
+  subscribeTool,
+  schemaTool,
+  statsTool,
+  explainTool
+];
+var toolHandlers = {
+  topgun_list_maps: handleListMaps,
+  topgun_query: handleQuery,
+  topgun_mutate: handleMutate,
+  topgun_search: handleSearch,
+  topgun_subscribe: handleSubscribe,
+  topgun_schema: handleSchema,
+  topgun_stats: handleStats,
+  topgun_explain: handleExplain
+};
+function createLogger(options = {}) {
+  const { debug = false, name = "topgun-mcp" } = options;
+  return pino({
+    name,
+    level: debug ? "debug" : "info",
+    // Always use stderr to not interfere with MCP stdio protocol
+    transport: void 0
+  }, pino.destination(2));
+}
+createLogger();
+
+// src/TopGunMCPServer.ts
+var DEFAULT_CONFIG = {
+  name: "topgun-mcp-server",
+  version: "1.0.0",
+  topgunUrl: "ws://localhost:8080",
+  enableMutations: true,
+  enableSubscriptions: true,
+  defaultLimit: 10,
+  maxLimit: 100,
+  subscriptionTimeoutSeconds: 60,
+  debug: false
+};
+var TopGunMCPServer = class {
+  server;
+  client;
+  config;
+  toolContext;
+  logger;
+  isStarted = false;
+  externalClient = false;
+  constructor(config = {}) {
+    this.config = {
+      name: config.name ?? DEFAULT_CONFIG.name,
+      version: config.version ?? DEFAULT_CONFIG.version,
+      topgunUrl: config.topgunUrl ?? DEFAULT_CONFIG.topgunUrl,
+      authToken: config.authToken,
+      allowedMaps: config.allowedMaps,
+      enableMutations: config.enableMutations ?? DEFAULT_CONFIG.enableMutations,
+      enableSubscriptions: config.enableSubscriptions ?? DEFAULT_CONFIG.enableSubscriptions,
+      defaultLimit: config.defaultLimit ?? DEFAULT_CONFIG.defaultLimit,
+      maxLimit: config.maxLimit ?? DEFAULT_CONFIG.maxLimit,
+      subscriptionTimeoutSeconds: config.subscriptionTimeoutSeconds ?? DEFAULT_CONFIG.subscriptionTimeoutSeconds,
+      debug: config.debug ?? DEFAULT_CONFIG.debug
+    };
+    if (config.client) {
+      this.client = config.client;
+      this.externalClient = true;
+    } else {
+      this.client = new TopGunClient({
+        serverUrl: this.config.topgunUrl,
+        storage: new InMemoryStorageAdapter()
+      });
+      if (this.config.authToken) {
+        this.client.setAuthToken(this.config.authToken);
+      }
+    }
+    this.toolContext = {
+      client: this.client,
+      config: this.config
+    };
+    this.logger = createLogger({
+      debug: this.config.debug,
+      name: this.config.name
+    });
+    this.server = new Server(
+      {
+        name: this.config.name,
+        version: this.config.version
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+    this.registerHandlers();
+    this.logger.info({
+      topgunUrl: this.config.topgunUrl,
+      allowedMaps: this.config.allowedMaps,
+      enableMutations: this.config.enableMutations
+    }, "TopGunMCPServer initialized");
+  }
+  /**
+   * Register MCP protocol handlers
+   */
+  registerHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      let availableTools = [...allTools];
+      if (!this.config.enableMutations) {
+        availableTools = availableTools.filter((t) => t.name !== "topgun_mutate");
+      }
+      if (!this.config.enableSubscriptions) {
+        availableTools = availableTools.filter((t) => t.name !== "topgun_subscribe");
+      }
+      this.logger.debug({ count: availableTools.length }, "tools/list called");
+      return {
+        tools: availableTools.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema
+        }))
+      };
+    });
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      this.logger.debug({ name, args }, "tools/call");
+      const handler = toolHandlers[name];
+      if (!handler) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Unknown tool: ${name}. Use tools/list to see available tools.`
+            }
+          ],
+          isError: true
+        };
+      }
+      try {
+        const result = await handler(args ?? {}, this.toolContext);
+        this.logger.debug({ name, isError: result.isError }, "Tool result");
+        return {
+          content: result.content.map((c) => ({
+            type: "text",
+            text: c.text ?? ""
+          })),
+          isError: result.isError
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.logger.error({ name, error: message }, "Tool error");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error executing ${name}: ${message}`
+            }
+          ],
+          isError: true
+        };
+      }
+    });
+  }
+  /**
+   * Start the MCP server with stdio transport
+   */
+  async start() {
+    if (this.isStarted) {
+      throw new Error("Server is already started");
+    }
+    await this.client.start();
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    this.isStarted = true;
+    this.logger.info("TopGun MCP Server started on stdio");
+  }
+  /**
+   * Start the MCP server with a custom transport
+   */
+  async startWithTransport(transport) {
+    if (this.isStarted) {
+      throw new Error("Server is already started");
+    }
+    await this.client.start();
+    await this.server.connect(transport);
+    this.isStarted = true;
+    this.logger.info("TopGun MCP Server started with custom transport");
+  }
+  /**
+   * Stop the server and cleanup resources
+   */
+  async stop() {
+    if (!this.isStarted) return;
+    await this.server.close();
+    if (!this.externalClient) {
+      this.client.close();
+    }
+    this.isStarted = false;
+    this.logger.info("TopGun MCP Server stopped");
+  }
+  /**
+   * Execute a tool directly (for testing)
+   */
+  async callTool(name, args) {
+    const handler = toolHandlers[name];
+    if (!handler) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+    return handler(args, this.toolContext);
+  }
+  /**
+   * Get the underlying MCP server instance
+   */
+  getServer() {
+    return this.server;
+  }
+  /**
+   * Get the TopGun client instance
+   */
+  getClient() {
+    return this.client;
+  }
+  /**
+   * Get resolved configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+};
+var InMemoryStorageAdapter = class {
+  data = /* @__PURE__ */ new Map();
+  meta = /* @__PURE__ */ new Map();
+  opLog = [];
+  opLogIdCounter = 0;
+  async initialize(_name) {
+  }
+  async close() {
+    this.data.clear();
+    this.meta.clear();
+    this.opLog = [];
+  }
+  async get(key) {
+    return this.data.get(key);
+  }
+  async put(key, value) {
+    this.data.set(key, value);
+  }
+  async remove(key) {
+    this.data.delete(key);
+  }
+  async getAllKeys() {
+    return Array.from(this.data.keys());
+  }
+  async getMeta(key) {
+    return this.meta.get(key);
+  }
+  async setMeta(key, value) {
+    this.meta.set(key, value);
+  }
+  async batchPut(entries) {
+    for (const [key, value] of entries) {
+      this.data.set(key, value);
+    }
+  }
+  async appendOpLog(entry) {
+    const id = ++this.opLogIdCounter;
+    this.opLog.push({ ...entry, id });
+    return id;
+  }
+  async getPendingOps() {
+    return this.opLog.filter((e) => e.synced === 0);
+  }
+  async markOpsSynced(lastId) {
+    for (const op of this.opLog) {
+      if (op.id !== void 0 && op.id <= lastId) {
+        op.synced = 1;
+      }
+    }
+  }
+};
+var DEFAULT_HTTP_CONFIG = {
+  port: 3e3,
+  host: "0.0.0.0",
+  corsOrigins: ["*"],
+  mcpPath: "/mcp",
+  eventPath: "/mcp/events",
+  debug: false
+};
+var HTTPTransport = class {
+  config;
+  httpServer;
+  isRunning = false;
+  activeSessions = /* @__PURE__ */ new Map();
+  constructor(config = {}) {
+    this.config = {
+      port: config.port ?? DEFAULT_HTTP_CONFIG.port,
+      host: config.host ?? DEFAULT_HTTP_CONFIG.host,
+      corsOrigins: config.corsOrigins ?? DEFAULT_HTTP_CONFIG.corsOrigins,
+      mcpPath: config.mcpPath ?? DEFAULT_HTTP_CONFIG.mcpPath,
+      eventPath: config.eventPath ?? DEFAULT_HTTP_CONFIG.eventPath,
+      debug: config.debug ?? DEFAULT_HTTP_CONFIG.debug
+    };
+  }
+  /**
+   * Start HTTP server with MCP transport
+   */
+  async start(mcpServer) {
+    if (this.isRunning) {
+      throw new Error("HTTP transport is already running");
+    }
+    this.httpServer = createServer((req, res) => {
+      this.handleRequest(req, res, mcpServer);
+    });
+    return new Promise((resolve, reject) => {
+      this.httpServer.on("error", reject);
+      this.httpServer.listen(this.config.port, this.config.host, () => {
+        this.isRunning = true;
+        this.log(`HTTP transport listening on ${this.config.host}:${this.config.port}`);
+        resolve();
+      });
+    });
+  }
+  /**
+   * Stop HTTP server
+   */
+  async stop() {
+    if (!this.isRunning || !this.httpServer) return;
+    for (const [sessionId, transport] of this.activeSessions) {
+      try {
+        await transport.close();
+      } catch {
+      }
+      this.activeSessions.delete(sessionId);
+    }
+    return new Promise((resolve) => {
+      this.httpServer.close(() => {
+        this.isRunning = false;
+        this.log("HTTP transport stopped");
+        resolve();
+      });
+    });
+  }
+  /**
+   * Handle incoming HTTP request
+   */
+  async handleRequest(req, res, mcpServer) {
+    this.setCorsHeaders(req, res);
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+    const url = new URL(req.url || "/", `http://${req.headers.host}`);
+    const pathname = url.pathname;
+    this.log(`${req.method} ${pathname}`);
+    if (pathname === "/health") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok", timestamp: (/* @__PURE__ */ new Date()).toISOString() }));
+      return;
+    }
+    if (pathname === this.config.mcpPath && req.method === "GET") {
+      const config = mcpServer.getConfig();
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          name: config.name,
+          version: config.version,
+          transport: "http+sse",
+          mcpPath: this.config.mcpPath,
+          eventPath: this.config.eventPath
+        })
+      );
+      return;
+    }
+    if (pathname === this.config.eventPath && req.method === "GET") {
+      await this.handleSSEConnection(req, res, mcpServer);
+      return;
+    }
+    if (pathname === this.config.mcpPath && req.method === "POST") {
+      await this.handleMCPRequest(req, res, mcpServer);
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not found" }));
+  }
+  /**
+   * Handle SSE connection for real-time MCP
+   */
+  async handleSSEConnection(_req, res, mcpServer) {
+    const sessionId = randomUUID();
+    this.log(`New SSE session: ${sessionId}`);
+    const transport = new SSEServerTransport(this.config.mcpPath, res);
+    this.activeSessions.set(sessionId, transport);
+    try {
+      await mcpServer.getServer().connect(transport);
+      await new Promise((resolve) => {
+        res.on("close", () => {
+          this.log(`SSE session closed: ${sessionId}`);
+          this.activeSessions.delete(sessionId);
+          resolve();
+        });
+      });
+    } catch (error) {
+      this.log(`SSE session error: ${sessionId}`, error);
+      this.activeSessions.delete(sessionId);
+    }
+  }
+  /**
+   * Handle stateless MCP POST request
+   */
+  async handleMCPRequest(req, res, mcpServer) {
+    try {
+      const body = await this.readBody(req);
+      const request = JSON.parse(body);
+      this.log("MCP request", request);
+      if (request.method === "tools/call") {
+        const { name, arguments: args } = request.params || {};
+        if (!name) {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "Missing tool name" }));
+          return;
+        }
+        const result = await mcpServer.callTool(name, args);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ result }));
+      } else {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error: "Unsupported method. Use SSE transport for full MCP support."
+          })
+        );
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.log("MCP request error", error);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: message }));
+    }
+  }
+  /**
+   * Read request body
+   */
+  readBody(req) {
+    return new Promise((resolve, reject) => {
+      let body = "";
+      req.on("data", (chunk) => body += chunk);
+      req.on("end", () => resolve(body));
+      req.on("error", reject);
+    });
+  }
+  /**
+   * Set CORS headers
+   */
+  setCorsHeaders(req, res) {
+    const origin = req.headers.origin || "*";
+    const allowedOrigin = this.config.corsOrigins.includes("*") ? "*" : this.config.corsOrigins.includes(origin) ? origin : this.config.corsOrigins[0];
+    res.setHeader("Access-Control-Allow-Origin", allowedOrigin);
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+    res.setHeader("Access-Control-Max-Age", "86400");
+  }
+  /**
+   * Debug logging
+   */
+  log(message, data) {
+    if (this.config.debug) {
+      console.error(`[HTTPTransport] ${message}`, data ? JSON.stringify(data) : "");
+    }
+  }
+  /**
+   * Get current session count
+   */
+  getSessionCount() {
+    return this.activeSessions.size;
+  }
+  /**
+   * Check if running
+   */
+  isActive() {
+    return this.isRunning;
+  }
+};
+async function createHTTPServer(mcpServer, config) {
+  const transport = new HTTPTransport(config);
+  await transport.start(mcpServer);
+  return transport;
+}
+
+export { HTTPTransport, TopGunMCPServer, allTools, createHTTPServer, explainTool, listMapsTool, mutateTool, queryTool, schemaTool, searchTool, statsTool, subscribeTool, toolHandlers };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map