@objectstack/mcp 8.0.0

package/dist/index.cjs

@@ -0,0 +1,817 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MCPServerPlugin: () => MCPServerPlugin,
+  MCPServerRuntime: () => MCPServerRuntime,
+  OBJECTSTACK_SKILL_DESCRIPTION: () => OBJECTSTACK_SKILL_DESCRIPTION,
+  OBJECTSTACK_SKILL_NAME: () => OBJECTSTACK_SKILL_NAME,
+  registerObjectTools: () => registerObjectTools,
+  renderSkillMarkdown: () => renderSkillMarkdown
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/plugin.ts
+var import_types = require("@objectstack/types");
+
+// src/mcp-server-runtime.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_webStandardStreamableHttp = require("@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js");
+
+// src/mcp-http-tools.ts
+var import_zod = require("zod");
+var DEFAULT_MAX_LIMIT = 50;
+function isSystemObject(name) {
+  return /^sys_/i.test(name);
+}
+function textResult(value) {
+  return { content: [{ type: "text", text: jsonText(value) }] };
+}
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+function jsonText(value) {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+function registerObjectTools(server, bridge, options = {}) {
+  const allowSystem = options.allowSystemObjects === true;
+  const maxLimit = options.maxQueryLimit ?? DEFAULT_MAX_LIMIT;
+  const guard = (objectName) => {
+    if (!objectName || typeof objectName !== "string") return "objectName is required";
+    if (!allowSystem && isSystemObject(objectName)) {
+      return `Object "${objectName}" is a system object and is not exposed via MCP`;
+    }
+    return void 0;
+  };
+  server.registerTool(
+    "list_objects",
+    {
+      description: "List the data objects (tables) available in this app. Returns each object's name, label and field count.",
+      inputSchema: {},
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    },
+    async () => {
+      try {
+        const objects = await bridge.listObjects();
+        const visible = allowSystem ? objects : objects.filter((o) => !isSystemObject(o.name));
+        return textResult({ objects: visible, totalCount: visible.length });
+      } catch (err) {
+        return errorResult(messageOf(err));
+      }
+    }
+  );
+  server.registerTool(
+    "describe_object",
+    {
+      description: "Get the schema of a data object: its fields (name, type, label, required) and enabled features.",
+      inputSchema: { objectName: import_zod.z.string().describe('The object/table name, e.g. "task"') },
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    },
+    async ({ objectName }) => {
+      const bad = guard(objectName);
+      if (bad) return errorResult(bad);
+      try {
+        const def = await bridge.describeObject(objectName);
+        if (!def) return errorResult(`Object "${objectName}" not found`);
+        return textResult(def);
+      } catch (err) {
+        return errorResult(messageOf(err));
+      }
+    }
+  );
+  server.registerTool(
+    "query_records",
+    {
+      description: "Query records from an object with optional filter, field selection, sorting and pagination. Runs under the caller's permissions and row-level security.",
+      inputSchema: {
+        objectName: import_zod.z.string().describe("The object/table name"),
+        where: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional().describe('Filter conditions, e.g. {"status":"open"}'),
+        fields: import_zod.z.array(import_zod.z.string()).optional().describe("Field names to return (defaults to all)"),
+        limit: import_zod.z.number().int().positive().max(maxLimit).optional().describe(`Max rows (\u2264 ${maxLimit})`),
+        offset: import_zod.z.number().int().nonnegative().optional().describe("Rows to skip"),
+        orderBy: import_zod.z.array(import_zod.z.object({ field: import_zod.z.string(), order: import_zod.z.enum(["asc", "desc"]) })).optional().describe("Sort order")
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    },
+    async ({ objectName, where, fields, limit, offset, orderBy }) => {
+      const bad = guard(objectName);
+      if (bad) return errorResult(bad);
+      try {
+        const result = await bridge.query(objectName, {
+          where,
+          fields,
+          limit: Math.min(limit ?? maxLimit, maxLimit),
+          offset,
+          orderBy
+        });
+        return textResult(result);
+      } catch (err) {
+        return errorResult(messageOf(err));
+      }
+    }
+  );
+  server.registerTool(
+    "get_record",
+    {
+      description: "Fetch a single record by id.",
+      inputSchema: {
+        objectName: import_zod.z.string().describe("The object/table name"),
+        recordId: import_zod.z.string().describe("The record id")
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    },
+    async ({ objectName, recordId }) => {
+      const bad = guard(objectName);
+      if (bad) return errorResult(bad);
+      try {
+        const record = await bridge.get(objectName, recordId);
+        if (record == null) return errorResult(`Record "${recordId}" not found in "${objectName}"`);
+        return textResult(record);
+      } catch (err) {
+        return errorResult(messageOf(err));
+      }
+    }
+  );
+  server.registerTool(
+    "create_record",
+    {
+      description: "Create a new record. Runs under the caller's permissions and validations.",
+      inputSchema: {
+        objectName: import_zod.z.string().describe("The object/table name"),
+        data: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).describe("Field values for the new record")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
+    },
+    async ({ objectName, data }) => {
+      const bad = guard(objectName);
+      if (bad) return errorResult(bad);
+      try {
+        return textResult(await bridge.create(objectName, data));
+      } catch (err) {
+        return errorResult(messageOf(err));
+      }
+    }
+  );
+  server.registerTool(
+    "update_record",
+    {
+      description: "Update fields on an existing record by id.",
+      inputSchema: {
+        objectName: import_zod.z.string().describe("The object/table name"),
+        recordId: import_zod.z.string().describe("The record id"),
+        data: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).describe("Field values to change")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
+    },
+    async ({ objectName, recordId, data }) => {
+      const bad = guard(objectName);
+      if (bad) return errorResult(bad);
+      try {
+        return textResult(await bridge.update(objectName, recordId, data));
+      } catch (err) {
+        return errorResult(messageOf(err));
+      }
+    }
+  );
+  server.registerTool(
+    "delete_record",
+    {
+      description: "Delete a record by id. This is destructive.",
+      inputSchema: {
+        objectName: import_zod.z.string().describe("The object/table name"),
+        recordId: import_zod.z.string().describe("The record id")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
+    },
+    async ({ objectName, recordId }) => {
+      const bad = guard(objectName);
+      if (bad) return errorResult(bad);
+      try {
+        return textResult(await bridge.remove(objectName, recordId));
+      } catch (err) {
+        return errorResult(messageOf(err));
+      }
+    }
+  );
+}
+function messageOf(err) {
+  if (err instanceof Error) return err.message;
+  if (err && typeof err === "object" && "message" in err) return String(err.message);
+  return String(err);
+}
+
+// src/mcp-server-runtime.ts
+var import_zod2 = require("zod");
+var READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
+  "list_objects",
+  "describe_object",
+  "query_records",
+  "get_record",
+  "aggregate_data"
+]);
+var DESTRUCTIVE_TOOLS = /* @__PURE__ */ new Set([
+  "delete_field"
+]);
+var MCPServerRuntime = class _MCPServerRuntime {
+  constructor(config = {}) {
+    this.started = false;
+    this.config = {
+      name: "objectstack",
+      version: "1.0.0",
+      transport: "stdio",
+      ...config
+    };
+    this.mcpServer = new import_mcp.McpServer(
+      {
+        name: this.config.name,
+        version: this.config.version
+      },
+      {
+        capabilities: {
+          resources: {},
+          tools: {},
+          prompts: {},
+          logging: {}
+        },
+        instructions: this.config.instructions ?? "ObjectStack MCP Server \u2014 access data objects, AI tools, and agent prompts."
+      }
+    );
+  }
+  /** The underlying McpServer instance (for advanced use cases). */
+  get server() {
+    return this.mcpServer;
+  }
+  /** Whether the server is currently connected and running. */
+  get isStarted() {
+    return this.started;
+  }
+  // ── Helpers ─────────────────────────────────────────────────────
+  /**
+   * Extract the text value from a ToolExecutionResult's output.
+   *
+   * The output may be a `{ type: 'text', value: string }` object (from the
+   * Vercel AI SDK ToolResultPart) or any serialisable value.
+   */
+  static formatToolOutput(result) {
+    const output = result.output;
+    if (output && typeof output === "object" && "value" in output) {
+      return String(output.value);
+    }
+    return JSON.stringify(output ?? "");
+  }
+  // ── Tool Bridge ────────────────────────────────────────────────
+  /**
+   * Bridge all tools from the ToolRegistry to MCP tools.
+   *
+   * Each registered tool becomes an MCP tool with the same name, description,
+   * and JSON Schema parameters. The handler delegates to the ToolRegistry's
+   * execute path.
+   */
+  bridgeTools(toolRegistry) {
+    const tools = toolRegistry.getAll();
+    const logger = this.config.logger;
+    for (const tool of tools) {
+      this.registerToolFromDefinition(tool, toolRegistry);
+    }
+    logger?.info(`[MCP] Bridged ${tools.length} tools from ToolRegistry`);
+  }
+  /**
+   * Register a single tool on the MCP server from an AIToolDefinition.
+   */
+  registerToolFromDefinition(tool, toolRegistry) {
+    const logger = this.config.logger;
+    this.mcpServer.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        annotations: {
+          // Mark tools with write side-effects for destructive operations
+          destructiveHint: this.isDestructiveTool(tool.name),
+          readOnlyHint: this.isReadOnlyTool(tool.name),
+          openWorldHint: false
+        }
+      },
+      async (extra) => {
+        const rawExtra = extra;
+        const args = rawExtra.arguments ?? {};
+        try {
+          const result = await toolRegistry.execute({
+            type: "tool-call",
+            toolCallId: `mcp-${tool.name}-${Date.now()}`,
+            toolName: tool.name,
+            input: args
+          });
+          const outputText = _MCPServerRuntime.formatToolOutput(result);
+          if (result.isError) {
+            return {
+              content: [{ type: "text", text: outputText }],
+              isError: true
+            };
+          }
+          return {
+            content: [{ type: "text", text: outputText }]
+          };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          logger?.warn(`[MCP] Tool "${tool.name}" execution failed:`, { error: message });
+          return {
+            content: [{ type: "text", text: message }],
+            isError: true
+          };
+        }
+      }
+    );
+  }
+  /**
+   * Check if a tool is read-only (data query tools).
+   */
+  isReadOnlyTool(name) {
+    return READ_ONLY_TOOLS.has(name);
+  }
+  /**
+   * Check if a tool performs destructive operations.
+   */
+  isDestructiveTool(name) {
+    return DESTRUCTIVE_TOOLS.has(name);
+  }
+  // ── Resource Bridge ────────────────────────────────────────────
+  /**
+   * Bridge metadata service and data engine to MCP resources.
+   *
+   * Exposes:
+   * - `objectstack://objects` — List all data objects
+   * - `objectstack://objects/{objectName}` — Get object schema
+   * - `objectstack://objects/{objectName}/records/{recordId}` — Get a specific record
+   * - `objectstack://metadata/types` — List all metadata types
+   */
+  bridgeResources(metadataService, dataEngine) {
+    const logger = this.config.logger;
+    let resourceCount = 0;
+    this.mcpServer.registerResource(
+      "object_list",
+      "objectstack://objects",
+      {
+        description: "List all data objects (tables) in the ObjectStack instance",
+        mimeType: "application/json"
+      },
+      async () => {
+        const objects = await metadataService.listObjects();
+        const summary = objects.map((o) => ({
+          name: o.name,
+          label: o.label ?? o.name,
+          fieldCount: o.fields ? Object.keys(o.fields).length : 0
+        }));
+        return {
+          contents: [{
+            uri: "objectstack://objects",
+            mimeType: "application/json",
+            text: JSON.stringify({ objects: summary, totalCount: summary.length }, null, 2)
+          }]
+        };
+      }
+    );
+    resourceCount++;
+    this.mcpServer.registerResource(
+      "object_schema",
+      new import_mcp.ResourceTemplate("objectstack://objects/{objectName}", { list: void 0 }),
+      {
+        description: "Get the full schema of a specific data object including fields and features",
+        mimeType: "application/json"
+      },
+      async (_uri, variables) => {
+        const objectName = String(variables.objectName);
+        const objectDef = await metadataService.getObject(objectName);
+        if (!objectDef) {
+          return {
+            contents: [{
+              uri: `objectstack://objects/${objectName}`,
+              mimeType: "application/json",
+              text: JSON.stringify({ error: `Object "${objectName}" not found` })
+            }]
+          };
+        }
+        const def = objectDef;
+        const fields = def.fields ?? {};
+        const fieldSummary = Object.entries(fields).map(([key, f]) => ({
+          name: key,
+          type: f.type,
+          label: f.label ?? key,
+          required: f.required ?? false
+        }));
+        return {
+          contents: [{
+            uri: `objectstack://objects/${objectName}`,
+            mimeType: "application/json",
+            text: JSON.stringify({
+              name: def.name,
+              label: def.label ?? def.name,
+              fields: fieldSummary,
+              enableFeatures: def.enable ?? {}
+            }, null, 2)
+          }]
+        };
+      }
+    );
+    resourceCount++;
+    if (dataEngine) {
+      this.mcpServer.registerResource(
+        "record_by_id",
+        new import_mcp.ResourceTemplate("objectstack://objects/{objectName}/records/{recordId}", { list: void 0 }),
+        {
+          description: "Get a specific record by ID from a data object",
+          mimeType: "application/json"
+        },
+        async (_uri, variables) => {
+          const objectName = String(variables.objectName);
+          const recordId = String(variables.recordId);
+          try {
+            const record = await dataEngine.findOne(objectName, {
+              where: { id: recordId }
+            });
+            if (!record) {
+              return {
+                contents: [{
+                  uri: `objectstack://objects/${objectName}/records/${recordId}`,
+                  mimeType: "application/json",
+                  text: JSON.stringify({ error: `Record "${recordId}" not found in "${objectName}"` })
+                }]
+              };
+            }
+            return {
+              contents: [{
+                uri: `objectstack://objects/${objectName}/records/${recordId}`,
+                mimeType: "application/json",
+                text: JSON.stringify(record, null, 2)
+              }]
+            };
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+              contents: [{
+                uri: `objectstack://objects/${objectName}/records/${recordId}`,
+                mimeType: "application/json",
+                text: JSON.stringify({ error: message })
+              }]
+            };
+          }
+        }
+      );
+      resourceCount++;
+    }
+    if (metadataService.getRegisteredTypes) {
+      this.mcpServer.registerResource(
+        "metadata_types",
+        "objectstack://metadata/types",
+        {
+          description: "List all registered metadata types (object, app, view, agent, tool, etc.)",
+          mimeType: "application/json"
+        },
+        async () => {
+          const types = await metadataService.getRegisteredTypes();
+          return {
+            contents: [{
+              uri: "objectstack://metadata/types",
+              mimeType: "application/json",
+              text: JSON.stringify({ types, totalCount: types.length }, null, 2)
+            }]
+          };
+        }
+      );
+      resourceCount++;
+    }
+    logger?.info(`[MCP] Bridged ${resourceCount} resource endpoints`);
+  }
+  // ── Prompt Bridge ──────────────────────────────────────────────
+  /**
+   * Bridge registered agents to MCP prompts.
+   *
+   * Each active agent becomes an MCP prompt with:
+   * - Name matching the agent name
+   * - System message from agent instructions
+   * - Optional context arguments (objectName, recordId, viewName)
+   */
+  bridgePrompts(metadataService) {
+    const logger = this.config.logger;
+    this.mcpServer.registerPrompt(
+      "agent_prompt",
+      {
+        description: "Load an agent's system prompt with optional UI context. Use the agentName argument to select which agent's instructions to use.",
+        argsSchema: {
+          agentName: import_zod2.z.string().describe('Name of the agent to load (e.g. "data_chat", "metadata_assistant")'),
+          objectName: import_zod2.z.string().optional().describe("Current object the user is viewing"),
+          recordId: import_zod2.z.string().optional().describe("Currently selected record ID"),
+          viewName: import_zod2.z.string().optional().describe("Current view name")
+        }
+      },
+      async (args) => {
+        const agentName = String(args.agentName ?? "");
+        if (!agentName) {
+          return {
+            messages: [{
+              role: "user",
+              content: { type: "text", text: "Error: agentName argument is required" }
+            }]
+          };
+        }
+        const raw = await metadataService.get("agent", agentName);
+        if (!raw) {
+          return {
+            messages: [{
+              role: "user",
+              content: { type: "text", text: `Error: Agent "${agentName}" not found` }
+            }]
+          };
+        }
+        const agent = raw;
+        const parts = [];
+        parts.push(agent.instructions ?? "");
+        const contextHints = [];
+        if (args.objectName) contextHints.push(`Current object: ${args.objectName}`);
+        if (args.recordId) contextHints.push(`Selected record ID: ${args.recordId}`);
+        if (args.viewName) contextHints.push(`Current view: ${args.viewName}`);
+        if (contextHints.length > 0) {
+          parts.push("\n--- Current Context ---\n" + contextHints.join("\n"));
+        }
+        return {
+          messages: [{
+            role: "assistant",
+            content: { type: "text", text: parts.join("\n") }
+          }]
+        };
+      }
+    );
+    logger?.info("[MCP] Agent prompts bridged");
+  }
+  // ── Lifecycle ──────────────────────────────────────────────────
+  /**
+   * Start the MCP server with the configured transport.
+   *
+   * For stdio transport, this connects to process stdin/stdout.
+   */
+  async start() {
+    if (this.started) return;
+    const logger = this.config.logger;
+    if (this.config.transport === "stdio") {
+      this.transport = new import_stdio.StdioServerTransport();
+      await this.mcpServer.connect(this.transport);
+      this.started = true;
+      logger?.info(`[MCP] Server started (transport: stdio, name: ${this.config.name})`);
+    } else {
+      logger?.info("[MCP] HTTP transport ready (served per-request at /api/v1/mcp).");
+    }
+  }
+  /**
+   * Stop the MCP server and disconnect the transport.
+   */
+  async stop() {
+    if (!this.started) return;
+    await this.mcpServer.close();
+    this.transport = void 0;
+    this.started = false;
+    this.config.logger?.info("[MCP] Server stopped");
+  }
+  // ── HTTP (Streamable HTTP) transport ───────────────────────────
+  /**
+   * Handle one MCP request over the **Streamable HTTP** transport (Web Standard
+   * `Request`/`Response`), the network-reachable surface for external agents.
+   *
+   * Stateless by design: a fresh {@link McpServer} + transport is built per
+   * request (the SDK-recommended pattern for stateless HTTP — it avoids any
+   * cross-request session/request-id collision and keeps each call isolated).
+   * The tool set is the object-CRUD bridge, bound to the **caller's principal**
+   * via `bridge`; the runtime wires that bridge to the existing permission +
+   * RLS path, so an external agent can never exceed the key's authority.
+   *
+   * Only the object-CRUD tools are exposed here — the internal AI/authoring
+   * toolRegistry (which can mutate metadata) is deliberately NOT bridged onto
+   * the external surface.
+   *
+   * @param request    The inbound Web `Request` (headers/method/url).
+   * @param opts.bridge       Principal-bound data accessor (required to expose tools).
+   * @param opts.parsedBody   Pre-parsed JSON-RPC body (the dispatcher already read it).
+   * @param opts.authInfo     Optional auth info forwarded to message handlers.
+   * @param opts.toolOptions  Object-tool exposure options (system objects, limits).
+   */
+  async handleHttpRequest(request, opts = {}) {
+    const server = new import_mcp.McpServer(
+      { name: this.config.name, version: this.config.version },
+      {
+        capabilities: { tools: {} },
+        instructions: this.config.instructions ?? "ObjectStack MCP Server \u2014 query and modify your app's data objects as tools."
+      }
+    );
+    if (opts.bridge) {
+      registerObjectTools(server, opts.bridge, opts.toolOptions);
+    }
+    const transport = new import_webStandardStreamableHttp.WebStandardStreamableHTTPServerTransport({
+      // Stateless: no session id, single request/response.
+      sessionIdGenerator: void 0,
+      // Return a buffered JSON response (no long-lived SSE) — fits the
+      // Worker→container hop without streaming pass-through concerns.
+      enableJsonResponse: true
+    });
+    await server.connect(transport);
+    try {
+      return await transport.handleRequest(request, {
+        parsedBody: opts.parsedBody,
+        authInfo: opts.authInfo
+      });
+    } finally {
+      await server.close().catch(() => {
+      });
+    }
+  }
+};
+
+// src/plugin.ts
+var MCPServerPlugin = class {
+  constructor(options = {}) {
+    this.name = "com.objectstack.mcp";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.dependencies = [];
+    this.options = options;
+  }
+  async init(ctx) {
+    const config = {
+      name: (0, import_types.readEnvWithDeprecation)("OS_MCP_SERVER_NAME", "MCP_SERVER_NAME") ?? this.options.name ?? "objectstack",
+      version: this.options.version ?? "1.0.0",
+      transport: (0, import_types.readEnvWithDeprecation)("OS_MCP_SERVER_TRANSPORT", "MCP_SERVER_TRANSPORT") ?? this.options.transport ?? "stdio",
+      instructions: this.options.instructions,
+      logger: ctx.logger
+    };
+    this.runtime = new MCPServerRuntime(config);
+    ctx.registerService("mcp", this.runtime);
+    ctx.logger.info("[MCP] Plugin initialized");
+  }
+  async start(ctx) {
+    if (!this.runtime) return;
+    try {
+      const aiService = ctx.getService("ai");
+      if (aiService?.toolRegistry) {
+        this.runtime.bridgeTools(aiService.toolRegistry);
+      } else {
+        ctx.logger.debug("[MCP] AI service does not expose a toolRegistry, skipping tool bridging");
+      }
+    } catch {
+      ctx.logger.debug("[MCP] AI service not available, skipping tool bridging");
+    }
+    let metadataService;
+    let dataEngine;
+    try {
+      metadataService = ctx.getService("metadata");
+    } catch {
+      ctx.logger.debug("[MCP] Metadata service not available, skipping resource bridging");
+    }
+    try {
+      dataEngine = ctx.getService("data");
+    } catch {
+      ctx.logger.debug("[MCP] Data engine not available, skipping record resources");
+    }
+    if (metadataService) {
+      this.runtime.bridgeResources(metadataService, dataEngine);
+      this.runtime.bridgePrompts(metadataService);
+    }
+    const shouldStart = this.options.autoStart || (0, import_types.readEnvWithDeprecation)("OS_MCP_SERVER_ENABLED", "MCP_SERVER_ENABLED") === "true";
+    if (shouldStart) {
+      await this.runtime.start();
+      ctx.logger.info("[MCP] Server started automatically");
+    } else {
+      ctx.logger.info(
+        "[MCP] Server ready but not started. Set OS_MCP_SERVER_ENABLED=true or use autoStart option."
+      );
+    }
+    await ctx.trigger("mcp:ready", this.runtime);
+  }
+  async destroy() {
+    if (this.runtime?.isStarted) {
+      await this.runtime.stop();
+    }
+    this.runtime = void 0;
+  }
+};
+
+// src/skill.ts
+var OBJECTSTACK_SKILL_NAME = "objectstack";
+var OBJECTSTACK_SKILL_DESCRIPTION = "Query and modify data in an ObjectStack app over MCP \u2014 discover objects, read and filter records, and create/update/delete under your own permissions and row-level security. Use when the user wants to inspect or change data in their ObjectStack environment.";
+var URL_PLACEHOLDER = "<YOUR_ENV_MCP_URL>";
+function renderSkillMarkdown(options = {}) {
+  const url = options.mcpUrl?.trim() || URL_PLACEHOLDER;
+  const envLabel = options.envName?.trim();
+  const intro = envLabel ? `This skill connects you to the **${envLabel}** ObjectStack environment.` : "This skill connects you to an ObjectStack environment.";
+  return `---
+name: ${OBJECTSTACK_SKILL_NAME}
+description: ${OBJECTSTACK_SKILL_DESCRIPTION}
+---
+
+# ObjectStack
+
+${intro} An ObjectStack environment exposes its data **objects** (tables) as
+tools over the Model Context Protocol (MCP). Every operation runs **as you** \u2014
+under your account's permissions and row-level security \u2014 so you may see a
+subset of rows, or get a permission error on a write. That is expected
+governance, not a failure.
+
+## When to use
+
+Use these tools whenever the user wants to **inspect or change data** in their
+ObjectStack app: look up records, filter/report, create or update entries, or
+clean up data. Prefer these tools over guessing \u2014 the environment is the source
+of truth.
+
+## Connect
+
+This skill drives the MCP server at:
+
+\`\`\`
+${url}
+\`\`\`
+
+Authenticate with an ObjectStack API key sent as a request header (the key is
+shown to you once when created; treat it like a password):
+
+\`\`\`
+x-api-key: <YOUR_API_KEY>
+\`\`\`
+
+(The header \`Authorization: ApiKey <YOUR_API_KEY>\` is also accepted.) If your
+MCP client supports custom headers on a remote server, set the header there.
+
+## Discover before you act
+
+The schema is **not** baked into this skill \u2014 it is discovered live, so it is
+always current even as the app evolves:
+
+1. \`list_objects\` \u2014 see what objects exist.
+2. \`describe_object({ objectName })\` \u2014 get an object's fields (name, type,
+   required) before querying or writing it.
+
+Always discover the relevant object's shape before constructing a filter or a
+create/update payload.
+
+## Tools
+
+- **list_objects()** \u2014 list available objects (system \`sys_*\` objects are hidden).
+- **describe_object({ objectName })** \u2014 an object's fields and features.
+- **query_records({ objectName, where?, fields?, limit?, offset?, orderBy? })** \u2014
+  read records. \`where\` is a field\u2192value match, e.g. \`{ "status": "open" }\`.
+  Results are page-capped; use \`limit\`/\`offset\` to page.
+- **get_record({ objectName, recordId })** \u2014 fetch one record by id.
+- **create_record({ objectName, data })** \u2014 create a record.
+- **update_record({ objectName, recordId, data })** \u2014 change fields on a record.
+- **delete_record({ objectName, recordId })** \u2014 delete a record (destructive \u2014
+  confirm with the user first).
+
+## Conventions & gotchas
+
+- **Permissions/RLS apply to every call.** Fewer rows than expected, or a
+  write that's rejected, usually means your key isn't authorized \u2014 don't retry
+  blindly; tell the user.
+- **Discover, don't assume.** Object and field names vary per app; always
+  \`list_objects\` / \`describe_object\` first.
+- **Writes are real and immediate.** There is no implicit dry-run. Confirm
+  destructive actions (\`delete_record\`, bulk updates) with the user.
+- **Page large reads.** Use \`limit\`/\`offset\` rather than asking for everything.
+
+## Recommended workflow
+
+1. \`list_objects\` to orient.
+2. \`describe_object\` on the target object.
+3. \`query_records\` to read / verify current state.
+4. \`create_record\` / \`update_record\` / \`delete_record\` to make changes,
+   confirming destructive steps with the user.
+`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MCPServerPlugin,
+  MCPServerRuntime,
+  OBJECTSTACK_SKILL_DESCRIPTION,
+  OBJECTSTACK_SKILL_NAME,
+  registerObjectTools,
+  renderSkillMarkdown
+});
+//# sourceMappingURL=index.cjs.map