stackby-mcp-server 0.2.0

package/README.md

@@ -0,0 +1,104 @@
+# Stackby MCP Server
+
+Model Context Protocol (MCP) server for Stackby. Exposes tools so AI clients (Cursor, Claude Desktop, Cline, ChatGPT with MCP) can work with Stackby data.
+
+**Auth:** Stackby Developer API via `STACKBY_API_KEY` (API key or Personal Access Token). See [CONFIG](https://github.com/stackby/Stackby_API/blob/production/MCP_SERVER/docs/CONFIG.md) in the planning repo (or sibling `Stackby_API/MCP_SERVER/docs/CONFIG.md`).
+
+---
+
+## Install (one-click)
+
+**1. Add to Cursor** — Edit `~/.cursor/mcp.json` (Mac/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "stackby": {
+      "command": "npx",
+      "args": ["-y", "stackby-mcp-server"],
+      "env": {
+        "STACKBY_API_KEY": "your-api-key-or-pat",
+        "STACKBY_API_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+Replace `your-api-key-or-pat` with your Stackby API key or PAT. Set `STACKBY_API_URL` to your Stackby API base URL (omit for default). Restart Cursor.
+
+**2. Or install globally:** `npm install -g stackby-mcp-server` then use `"command": "stackby-mcp-server"` in `mcp.json`.
+
+---
+
+## Tools (11)
+
+| Tool | Description |
+|------|-------------|
+| `list_stacks` | List stacks (bases) the user can access. |
+| `list_tables` | List tables in a stack. |
+| `describe_table` | Table schema: fields (columns), views. |
+| `list_records` | List rows in a table (with optional maxRecords). |
+| `search_records` | Search rows by text. |
+| `get_record` | Get one row by ID. |
+| `create_record` | Create a row (fields keyed by column name). |
+| `update_records` | Update rows (array of `{ id, fields }`, max 10). |
+| `delete_records` | Soft-delete rows by ID (max 10). |
+| `create_table` | Create a new table in a stack. |
+| `create_field` | Create a new column (field) in a table. |
+
+---
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+**How to verify the build:** After `npm run build` you should see `Build OK. Output in dist/`. Run `npm start` — the server runs over stdio (no visible output; it waits for Cursor/Claude to connect).
+
+## Verify in Cursor (Step 1.2)
+
+1. Open Cursor **Settings** → **MCP** (or edit the config file directly).
+2. Add the Stackby MCP server. Use **project** or **user** config.
+
+   **Option A — User config** (`~/.cursor/mcp.json` on Mac/Linux, or `%USERPROFILE%\\.cursor\\mcp.json` on Windows):
+
+   ```json
+   {
+     "mcpServers": {
+       "stackby": {
+         "command": "node",
+         "args": ["C:\\Users\\Admin\\Desktop\\Stackby\\stackby-mcp-server\\dist\\index.js"],
+         "env": {}
+       }
+     }
+   }
+   ```
+
+   **Option B — If you use `npx` from the project folder:** (from a terminal in `stackby-mcp-server` run `node dist/index.js`; Cursor can use that path in `args`.)
+
+   Use the **full path** to `dist/index.js` in `args` so Cursor can spawn the server.
+3. Restart Cursor (or reload the window).
+4. Set `STACKBY_API_KEY` (and optionally `STACKBY_API_URL`) in the `env` object. In a chat, check the **tools** list — you should see all 11 tools: **list_stacks**, **list_tables**, **describe_table**, **list_records**, **search_records**, **get_record**, **create_record**, **update_records**, **delete_records**, **create_table**, **create_field**.
+
+## Run (stdio — for Cursor / Claude)
+
+```bash
+STACKBY_API_KEY=your_api_key STACKBY_API_URL=https://api.stackby.com npm start
+```
+
+Or one-click: `npx stackby-mcp-server` (after npm publish)
+
+## Config
+
+| Env | Required | Description |
+|-----|----------|-------------|
+| `STACKBY_API_KEY` | Yes | Stackby API key (or PAT when implemented). |
+
+**Full config** (Cursor, Claude Desktop, Cline, HTTP transport): see `Stackby_API/MCP_SERVER/docs/CONFIG.md` in the sibling repo.
+
+---
+
+Planning and design: `Stackby_API/MCP_SERVER/` (sibling repo).

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,558 @@
+/**
+ * Stackby MCP Server — entry point.
+ * list_stacks, list_tables call real Stackby API.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { hasApiKey, getApiBaseUrl, getWorkspaces, getAllStacks, getTables, getTableViewList, describeTable, getRowList, searchRecords, getRecord, createRow, updateRows, deleteRows, createTable, createColumn, } from "./stackby-api.js";
+const mcpServer = new McpServer({
+    name: "stackby-mcp-server",
+    version: "0.1.0",
+});
+mcpServer.registerTool("list_workspaces", {
+    description: "List Stackby workspaces the user can access. Requires STACKBY_API_KEY (or PAT) in MCP config.",
+    inputSchema: {},
+}, async () => {
+    if (!hasApiKey()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "STACKBY_API_KEY is not set. Add it to your MCP config (e.g. in Cursor: .cursor/mcp.json → env.STACKBY_API_KEY) with your Stackby API key or Personal Access Token (PAT).",
+                },
+            ],
+        };
+    }
+    try {
+        const workspaces = await getWorkspaces();
+        const lines = workspaces.length === 0
+            ? ["No workspaces found."]
+            : workspaces.map((w) => `- ${w.name} (id: ${w.id})`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Workspaces (${workspaces.length}):\n${lines.join("\n")}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to list workspaces: ${message}. STACKBY_API_KEY and STACKBY_API_URL in use: ${getApiBaseUrl()}.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+mcpServer.registerTool("list_stacks", {
+    description: "List Stackby stacks (bases) the user can access. Requires STACKBY_API_KEY (or PAT) in MCP config.",
+    inputSchema: {},
+}, async () => {
+    if (!hasApiKey()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "STACKBY_API_KEY is not set. Add it to your MCP config (e.g. in Cursor: .cursor/mcp.json → env.STACKBY_API_KEY) with your Stackby API key or Personal Access Token (PAT).",
+                },
+            ],
+        };
+    }
+    try {
+        const stacks = await getAllStacks();
+        const lines = stacks.length === 0
+            ? ["No stacks found."]
+            : stacks.map((s) => `- ${s.stackName} (id: ${s.stackId}, workspace: ${s.workspaceName ?? s.workspaceId})`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Stacks (${stacks.length}):\n${lines.join("\n")}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to list stacks: ${message}. STACKBY_API_KEY and STACKBY_API_URL in use: ${getApiBaseUrl()}.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+mcpServer.registerTool("list_tables", {
+    description: "List tables in a Stackby stack. Use list_stacks first to get stack IDs.",
+    inputSchema: {
+        stackId: z.string().describe("Stack ID (from list_stacks)"),
+    },
+}, async ({ stackId }) => {
+    const id = stackId?.trim();
+    if (!id) {
+        return {
+            content: [{ type: "text", text: "stackId is required. Use list_stacks to get stack IDs." }],
+            isError: true,
+        };
+    }
+    if (!hasApiKey()) {
+        return {
+            content: [{ type: "text", text: "STACKBY_API_KEY is not set. Add it to your MCP config." }],
+        };
+    }
+    try {
+        const tables = await getTables(id);
+        const lines = tables.length === 0
+            ? ["No tables found in this stack."]
+            : tables.map((t) => `- ${t.name} (id: ${t.id})`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Tables in stack ${id} (${tables.length}):\n${lines.join("\n")}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to list tables: ${message}. Check stackId and API access.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+mcpServer.registerTool("describe_table", {
+    description: "Get table schema: name, fields (columns with id, name, type), and views. Use list_tables to get stackId and tableId.",
+    inputSchema: {
+        stackId: z.string().describe("Stack ID (from list_stacks)"),
+        tableId: z.string().describe("Table ID (from list_tables)"),
+    },
+}, async ({ stackId, tableId }) => {
+    const sId = stackId?.trim();
+    const tId = tableId?.trim();
+    if (!sId || !tId) {
+        return {
+            content: [{ type: "text", text: "stackId and tableId are required. Use list_stacks and list_tables to get IDs." }],
+            isError: true,
+        };
+    }
+    if (!hasApiKey()) {
+        return {
+            content: [{ type: "text", text: "STACKBY_API_KEY is not set. Add it to your MCP config." }],
+        };
+    }
+    try {
+        const schema = await describeTable(sId, tId);
+        const fieldLines = schema.fields.length === 0
+            ? ["(no fields)"]
+            : schema.fields.map((f) => `  - ${f.name} (id: ${f.id}, type: ${f.type})`);
+        const viewLines = schema.views.length === 0
+            ? ["(no views)"]
+            : schema.views.map((v) => `  - ${v.name} (id: ${v.id})`);
+        const text = [
+            `Table: ${schema.name} (id: ${schema.id})`,
+            "",
+            "Fields:",
+            ...fieldLines,
+            "",
+            "Views:",
+            ...viewLines,
+        ].join("\n");
+        return {
+            content: [{ type: "text", text }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                { type: "text", text: `Failed to describe table: ${message}. Check stackId, tableId, and API access.` },
+            ],
+            isError: true,
+        };
+    }
+});
+mcpServer.registerTool("list_records", {
+    description: "List rows (records) in a table. Use list_stacks and list_tables to get stackId and tableId.",
+    inputSchema: {
+        stackId: z.string().describe("Stack ID (from list_stacks)"),
+        tableId: z.string().describe("Table ID (from list_tables)"),
+        maxRecords: z.number().optional().describe("Max records to return (1–100, default 100)"),
+    },
+}, async ({ stackId, tableId, maxRecords }) => {
+    const sId = stackId?.trim();
+    const tId = tableId?.trim();
+    if (!sId || !tId) {
+        return {
+            content: [{ type: "text", text: "stackId and tableId are required. Use list_stacks and list_tables to get IDs." }],
+            isError: true,
+        };
+    }
+    if (!hasApiKey()) {
+        return {
+            content: [{ type: "text", text: "STACKBY_API_KEY is not set. Add it to your MCP config." }],
+        };
+    }
+    try {
+        const records = await getRowList(sId, tId, { maxRecords: maxRecords ?? 100 });
+        const lines = records.length === 0
+            ? ["No records found."]
+            : records.map((r) => `- id: ${r.id} | ${JSON.stringify(r.field)}`);
+        const text = [`Records in table ${tId} (${records.length}):`, "", ...lines].join("\n");
+        return {
+            content: [{ type: "text", text }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                { type: "text", text: `Failed to list records: ${message}. Check stackId, tableId, and API access.` },
+            ],
+            isError: true,
+        };
+    }
+});
+mcpServer.registerTool("search_records", {
+    description: "Search for rows containing text in a table. Uses first column if fieldIds not provided. Use list_stacks and list_tables to get IDs.",
+    inputSchema: {
+        stackId: z.string().describe("Stack ID (from list_stacks)"),
+        tableId: z.string().describe("Table ID (from list_tables)"),
+        searchTerm: z.string().describe("Text to search for"),
+        fieldIds: z.array(z.string()).optional().describe("Optional column IDs to search in (uses first column if omitted)"),
+        maxRecords: z.number().optional().describe("Max records to return (default 100)"),
+    },
+}, async ({ stackId, tableId, searchTerm, fieldIds, maxRecords }) => {
+    const sId = stackId?.trim();
+    const tId = tableId?.trim();
+    const term = searchTerm?.trim();
+    if (!sId || !tId || term === undefined || term === "") {
+        return {
+            content: [{ type: "text", text: "stackId, tableId, and searchTerm are required." }],
+            isError: true,
+        };
+    }
+    if (!hasApiKey()) {
+        return {
+            content: [{ type: "text", text: "STACKBY_API_KEY is not set. Add it to your MCP config." }],
+        };
+    }
+    try {
+        const columnId = fieldIds && fieldIds.length > 0 ? fieldIds[0] : undefined;
+        const result = await searchRecords(sId, tId, term, { columnId, maxRecords });
+        const count = result.rowIds.length;
+        const lines = count === 0
+            ? ["No matching records."]
+            : result.rowIds.map((id, i) => `- id: ${id} | ${(result.rowname && result.rowname[i]) || ""}`);
+        const text = [`Search "${term}" in table ${tId} (${count} match${count !== 1 ? "es" : ""}):`, "", ...lines].join("\n");
+        return {
+            content: [{ type: "text", text }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                { type: "text", text: `Failed to search records: ${message}. Check stackId, tableId, and API access.` },
+            ],
+            isError: true,
+        };
+    }
+});
+mcpServer.registerTool("get_record", {
+    description: "Get a single row (record) by id. Use list_records or search_records to get record IDs.",
+    inputSchema: {
+        stackId: z.string().describe("Stack ID (from list_stacks)"),
+        tableId: z.string().describe("Table ID (from list_tables)"),
+        recordId: z.string().describe("Record (row) ID"),
+    },
+}, async ({ stackId, tableId, recordId }) => {
+    const sId = stackId?.trim();
+    const tId = tableId?.trim();
+    const rId = recordId?.trim();
+    if (!sId || !tId || !rId) {
+        return {
+            content: [{ type: "text", text: "stackId, tableId, and recordId are required." }],
+            isError: true,
+        };
+    }
+    if (!hasApiKey()) {
+        return {
+            content: [{ type: "text", text: "STACKBY_API_KEY is not set. Add it to your MCP config." }],
+        };
+    }
+    try {
+        const record = await getRecord(sId, tId, rId);
+        if (!record) {
+            return {
+                content: [{ type: "text", text: `No record found with id ${rId} in table ${tId}.` }],
+            };
+        }
+        const text = [`Record ${record.id}:`, "", JSON.stringify(record.field, null, 2)].join("\n");
+        return {
+            content: [{ type: "text", text }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                { type: "text", text: `Failed to get record: ${message}. Check stackId, tableId, recordId, and API access.` },
+            ],
+            isError: true,
+        };
+    }
+});
+// --- Phase 3: Write tools ---
+mcpServer.registerTool("create_record", {
+    description: "Create a new row (record) in a table. Use describe_table to get column names. Fields are keyed by column name.",
+    inputSchema: {
+        stackId: z.string().describe("Stack ID (from list_stacks)"),
+        tableId: z.string().describe("Table ID (from list_tables)"),
+        fields: z.record(z.string(), z.unknown()).describe("Field values keyed by column name (e.g. { \"Name\": \"Task 1\", \"Status\": \"Done\" })"),
+    },
+}, async ({ stackId, tableId, fields }) => {
+    const sId = stackId?.trim();
+    const tId = tableId?.trim();
+    if (!sId || !tId) {
+        return {
+            content: [{ type: "text", text: "stackId and tableId are required." }],
+            isError: true,
+        };
+    }
+    if (!hasApiKey()) {
+        return {
+            content: [{ type: "text", text: "STACKBY_API_KEY is not set. Add it to your MCP config." }],
+        };
+    }
+    if (!fields || typeof fields !== "object" || Array.isArray(fields)) {
+        return {
+            content: [{ type: "text", text: "fields must be an object of column names to values." }],
+            isError: true,
+        };
+    }
+    try {
+        const records = await createRow(sId, tId, fields);
+        const created = records[0];
+        if (!created) {
+            return {
+                content: [{ type: "text", text: "No record was created. Check table schema and field names." }],
+                isError: true,
+            };
+        }
+        const text = [`Created record: ${created.id}`, "", JSON.stringify(created.field, null, 2)].join("\n");
+        return {
+            content: [{ type: "text", text }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                { type: "text", text: `Failed to create record: ${message}. Check stackId, tableId, and field names (use describe_table).` },
+            ],
+            isError: true,
+        };
+    }
+});
+mcpServer.registerTool("update_records", {
+    description: "Update existing rows. Provide an array of { id, fields }. At most 10 records per request. Use describe_table for column names.",
+    inputSchema: {
+        stackId: z.string().describe("Stack ID (from list_stacks)"),
+        tableId: z.string().describe("Table ID (from list_tables)"),
+        records: z
+            .array(z.object({
+            id: z.string().describe("Record (row) ID"),
+            fields: z.record(z.string(), z.unknown()).describe("Field values to set (column name -> value)"),
+        }))
+            .min(1)
+            .max(10)
+            .describe("Records to update"),
+    },
+}, async ({ stackId, tableId, records }) => {
+    const sId = stackId?.trim();
+    const tId = tableId?.trim();
+    if (!sId || !tId) {
+        return {
+            content: [{ type: "text", text: "stackId and tableId are required." }],
+            isError: true,
+        };
+    }
+    if (!hasApiKey()) {
+        return {
+            content: [{ type: "text", text: "STACKBY_API_KEY is not set. Add it to your MCP config." }],
+        };
+    }
+    try {
+        const updated = await updateRows(sId, tId, records.map((r) => ({ id: r.id, fields: r.fields })));
+        const lines = updated.map((r) => `- ${r.id}: ${JSON.stringify(r.field)}`);
+        const text = [`Updated ${updated.length} record(s):`, "", ...lines].join("\n");
+        return {
+            content: [{ type: "text", text }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                { type: "text", text: `Failed to update records: ${message}. Check stackId, tableId, record IDs, and field names.` },
+            ],
+            isError: true,
+        };
+    }
+});
+mcpServer.registerTool("delete_records", {
+    description: "Soft-delete rows (records) by ID. At most 10 per request. Use list_records or search_records to get IDs.",
+    inputSchema: {
+        stackId: z.string().describe("Stack ID (from list_stacks)"),
+        tableId: z.string().describe("Table ID (from list_tables)"),
+        recordIds: z.array(z.string()).min(1).max(10).describe("Record (row) IDs to delete"),
+    },
+}, async ({ stackId, tableId, recordIds }) => {
+    const sId = stackId?.trim();
+    const tId = tableId?.trim();
+    if (!sId || !tId) {
+        return {
+            content: [{ type: "text", text: "stackId and tableId are required." }],
+            isError: true,
+        };
+    }
+    if (!hasApiKey()) {
+        return {
+            content: [{ type: "text", text: "STACKBY_API_KEY is not set. Add it to your MCP config." }],
+        };
+    }
+    try {
+        const result = await deleteRows(sId, tId, recordIds);
+        const list = result?.records ?? [];
+        const lines = list.map((r) => `- ${r.id}: deleted=${r.deleted}`);
+        const text = [`Deleted ${list.length} record(s):`, "", ...lines].join("\n");
+        return {
+            content: [{ type: "text", text }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                { type: "text", text: `Failed to delete records: ${message}. Check stackId, tableId, and record IDs.` },
+            ],
+            isError: true,
+        };
+    }
+});
+// --- Phase 4: Schema tools (create only; update later) ---
+mcpServer.registerTool("create_table", {
+    description: "Create a new table in a stack. Use list_stacks to get stackId.",
+    inputSchema: {
+        stackId: z.string().describe("Stack ID (from list_stacks)"),
+        name: z.string().describe("Table name"),
+    },
+}, async ({ stackId, name }) => {
+    const sId = stackId?.trim();
+    const tableName = name?.trim();
+    if (!sId || !tableName) {
+        return {
+            content: [{ type: "text", text: "stackId and name are required." }],
+            isError: true,
+        };
+    }
+    if (!hasApiKey()) {
+        return {
+            content: [{ type: "text", text: "STACKBY_API_KEY is not set. Add it to your MCP config." }],
+        };
+    }
+    try {
+        const result = await createTable(sId, tableName);
+        const id = result?.tableId ?? result?.id ?? "unknown";
+        const text = [`Created table: ${tableName}`, `Table ID: ${id}`].join("\n");
+        return {
+            content: [{ type: "text", text }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                { type: "text", text: `Failed to create table: ${message}. Check stackId and plan limits.` },
+            ],
+            isError: true,
+        };
+    }
+});
+mcpServer.registerTool("create_field", {
+    description: "Create a new column (field) in a table. Use describe_table to see existing columns. For singleOption/multipleOptions pass options array.",
+    inputSchema: {
+        stackId: z.string().describe("Stack ID (from list_stacks)"),
+        tableId: z.string().describe("Table ID (from list_tables)"),
+        name: z.string().describe("Column name"),
+        columnType: z.string().describe("Column type: shortText, longText, number, checkbox, dateAndTime, singleOption, multipleOptions, email, url, etc."),
+        viewId: z.string().optional().describe("View ID (optional; first view used if omitted)"),
+        options: z.array(z.string()).optional().describe("For singleOption/multipleOptions: choice labels"),
+    },
+}, async ({ stackId, tableId, name, columnType, viewId, options }) => {
+    const sId = stackId?.trim();
+    const tId = tableId?.trim();
+    const colName = name?.trim();
+    const type = columnType?.trim();
+    if (!sId || !tId || !colName || !type) {
+        return {
+            content: [{ type: "text", text: "stackId, tableId, name, and columnType are required." }],
+            isError: true,
+        };
+    }
+    if (!hasApiKey()) {
+        return {
+            content: [{ type: "text", text: "STACKBY_API_KEY is not set. Add it to your MCP config." }],
+        };
+    }
+    try {
+        let viewIdToUse = viewId?.trim();
+        if (!viewIdToUse) {
+            const views = await getTableViewList(sId, tId);
+            viewIdToUse = views.length > 0 ? views[0].id : "";
+        }
+        const result = await createColumn(sId, tId, colName, type, {
+            viewId: viewIdToUse,
+            options: options && options.length > 0 ? options : undefined,
+        });
+        const id = result?.columnId ?? result?.id ?? "unknown";
+        const text = [`Created column: ${colName}`, `Column ID: ${id}`, `Type: ${type}`].join("\n");
+        return {
+            content: [{ type: "text", text }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                { type: "text", text: `Failed to create field: ${message}. Check stackId, tableId, name, columnType (use describe_table for types).` },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await mcpServer.connect(transport);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/stackby-api.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Stackby API client for MCP server.
+ * Uses dedicated MCP API only: /api/v1/mcp/* (existing developer API is unchanged).
+ */
+export declare function hasApiKey(): boolean;
+/** Returns the base URL actually in use (for error messages). */
+export declare function getApiBaseUrl(): string;
+export interface Workspace {
+    id: string;
+    name: string;
+}
+export interface Stack {
+    stackId: string;
+    workspaceId: string;
+    stackName: string;
+    info?: string;
+    color?: string;
+    icon?: string;
+    createdAt?: string;
+}
+/** GET /api/v1/mcp/workspaces — list workspaces (MCP API only). */
+export declare function getWorkspaces(): Promise<Workspace[]>;
+/** POST /api/v1/mcp/stacks — list stacks in a workspace. Body: { workspaceId }. */
+export declare function getStacks(workspaceId: string, workspaceName?: string): Promise<{
+    list: Stack[];
+    workspaceName: string;
+}>;
+/** Fetch all stacks across all workspaces (for list_stacks tool). */
+export declare function getAllStacks(): Promise<Array<Stack & {
+    workspaceName?: string;
+}>>;
+export interface Table {
+    id: string;
+    name: string;
+}
+/** GET /api/v1/mcp/stacks/:stackId/tables — list tables in a stack (MCP API only). */
+export declare function getTables(stackId: string): Promise<Table[]>;
+export interface TableField {
+    id: string;
+    name: string;
+    type: string;
+    key?: string;
+    label?: string;
+}
+export interface TableView {
+    id: string;
+    name: string;
+    tableId: string;
+}
+/** GET /api/v1/mcp/stacks/:stackId/tables/:tableId/columns — list columns (MCP API only). */
+export declare function getTableColumns(stackId: string, tableId: string): Promise<TableField[]>;
+/** GET /api/v1/mcp/stacks/:stackId/tables/:tableId/views — list all visible views (MCP API only). */
+export declare function getTableViewList(stackId: string, tableId: string): Promise<TableView[]>;
+export interface DescribeTableResult {
+    id: string;
+    name: string;
+    fields: TableField[];
+    views: TableView[];
+}
+/** Describe one table: name (from tablelist), fields (columnlist), views (viewlist). */
+export declare function describeTable(stackId: string, tableId: string): Promise<DescribeTableResult>;
+export interface TableRecord {
+    id: string;
+    field: Record<string, unknown>;
+}
+/** GET /api/v1/mcp/stacks/:stackId/tables/:tableId/rows — list rows (MCP API). */
+export declare function getRowList(stackId: string, tableId: string, opts?: {
+    maxRecords?: number;
+    offset?: number;
+    rowIds?: string[];
+}): Promise<TableRecord[]>;
+/** GET /api/v1/mcp/stacks/:stackId/tables/:tableId/rows/:recordId — get one record (MCP API). */
+export declare function getRecord(stackId: string, tableId: string, recordId: string): Promise<TableRecord | null>;
+export interface SearchRecordsResult {
+    rowIds: string[];
+    rowname: string[];
+    fields: Array<Record<string, unknown>>;
+}
+/** POST /api/v1/mcp/stacks/:stackId/tables/:tableId/search — search rows (MCP API). */
+export declare function searchRecords(stackId: string, tableId: string, searchTerm: string, opts?: {
+    columnId?: string;
+    maxRecords?: number;
+}): Promise<SearchRecordsResult>;
+/** POST /api/v1/mcp/stacks/:stackId/tables/:tableId/rows — create row(s) (MCP API). */
+export declare function createRow(stackId: string, tableId: string, fields: Record<string, unknown>): Promise<TableRecord[]>;
+/** POST /api/v1/mcp/stacks/:stackId/tables/:tableId/rows/update — update rows (MCP API). */
+export declare function updateRows(stackId: string, tableId: string, records: Array<{
+    id: string;
+    fields: Record<string, unknown>;
+}>): Promise<TableRecord[]>;
+/** DELETE /api/v1/mcp/stacks/:stackId/tables/:tableId/rows — soft-delete rows (MCP API). */
+export declare function deleteRows(stackId: string, tableId: string, recordIds: string[]): Promise<{
+    records: Array<{
+        id: string;
+        deleted: boolean;
+    }>;
+}>;
+export interface CreateTableResult {
+    tableId?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/** POST /api/v1/mcp/stacks/:stackId/tables — create a table in a stack (MCP API). */
+export declare function createTable(stackId: string, name: string, _description?: string): Promise<CreateTableResult>;
+/** Column types supported by POST /api/v1/columnCreate/:columnType (devapi). */
+export declare const COLUMN_TYPES: readonly ["shortText", "longText", "number", "checkbox", "dateAndTime", "time", "singleOption", "multipleOptions", "email", "url", "phoneNumber", "rating", "duration", "autoNumber", "createdTime", "updatedTime", "createdBy", "updatedBy", "attachment", "link", "lookup", "lookupCount", "aggregation", "formula", "checkList", "location", "barcode", "signature"];
+export type ColumnType = (typeof COLUMN_TYPES)[number];
+export interface CreateColumnResult {
+    columnId?: string;
+    tableId?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/** POST /api/v1/mcp/columns — create a column (MCP API). Body: stackId, tableId, name, columnType, viewId?, options? */
+export declare function createColumn(stackId: string, tableId: string, name: string, columnType: string, opts?: {
+    viewId?: string;
+    options?: string[];
+}): Promise<CreateColumnResult>;

package/dist/stackby-api.js

@@ -0,0 +1,250 @@
+/**
+ * Stackby API client for MCP server.
+ * Uses dedicated MCP API only: /api/v1/mcp/* (existing developer API is unchanged).
+ */
+const BASE_URL = process.env.STACKBY_API_URL || "https://stackby.com";
+const API_KEY = process.env.STACKBY_API_KEY || "";
+const MCP_API = "/api/v1/mcp";
+export function hasApiKey() {
+    return Boolean(API_KEY && API_KEY.trim().length > 0);
+}
+/** Returns the base URL actually in use (for error messages). */
+export function getApiBaseUrl() {
+    return BASE_URL.replace(/\/$/, "");
+}
+function authHeaders() {
+    const key = API_KEY.trim();
+    if (!key) {
+        throw new Error("STACKBY_API_KEY is not set. Set it in your MCP config (e.g. Cursor mcp.json env).");
+    }
+    return {
+        "Content-Type": "application/json",
+        "x-api-key": key,
+        ...(key.startsWith("pat_") ? { Authorization: `Bearer ${key}` } : {}),
+    };
+}
+async function request(path, options = {}) {
+    const url = path.startsWith("http") ? path : `${BASE_URL.replace(/\/$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
+    const res = await fetch(url, {
+        ...options,
+        headers: { ...authHeaders(), ...options.headers },
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+        const msg = body?.error ?? body?.message ?? res.statusText;
+        throw new Error(`Stackby API ${res.status}: ${msg}`);
+    }
+    return body;
+}
+/** GET /api/v1/mcp/workspaces — list workspaces (MCP API only). */
+export async function getWorkspaces() {
+    const out = await request(`${MCP_API}/workspaces`, { method: "GET" });
+    return Array.isArray(out.data) ? out.data : [];
+}
+/** POST /api/v1/mcp/stacks — list stacks in a workspace. Body: { workspaceId }. */
+export async function getStacks(workspaceId, workspaceName) {
+    const out = await request(`${MCP_API}/stacks`, {
+        method: "POST",
+        body: JSON.stringify({ workspaceId }),
+    });
+    const raw = Array.isArray(out.data) ? out.data : [];
+    const list = raw.map((s) => ({
+        stackId: s.stackId ?? "",
+        stackName: s.stackName,
+        workspaceId: s.workspaceId,
+        color: s.color,
+        icon: s.icon,
+    }));
+    return { list, workspaceName: workspaceName ?? "" };
+}
+/** Fetch all stacks across all workspaces (for list_stacks tool). */
+export async function getAllStacks() {
+    const workspaces = await getWorkspaces();
+    const all = [];
+    for (const ws of workspaces) {
+        try {
+            const { list, workspaceName } = await getStacks(ws.id, ws.name);
+            for (const s of list) {
+                all.push({ ...s, workspaceName });
+            }
+        }
+        catch (e) {
+            // skip workspace on error (e.g. no access)
+        }
+    }
+    return all;
+}
+/** GET /api/v1/mcp/stacks/:stackId/tables — list tables in a stack (MCP API only). */
+export async function getTables(stackId) {
+    const out = await request(`${MCP_API}/stacks/${encodeURIComponent(stackId)}/tables`, { method: "GET" });
+    return Array.isArray(out.data) ? out.data : [];
+}
+/** GET /api/v1/mcp/stacks/:stackId/tables/:tableId/columns — list columns (MCP API only). */
+export async function getTableColumns(stackId, tableId) {
+    const path = `${MCP_API}/stacks/${encodeURIComponent(stackId)}/tables/${encodeURIComponent(tableId)}/columns`;
+    const out = await request(path, { method: "GET" });
+    return Array.isArray(out.data) ? out.data : [];
+}
+/** GET /api/v1/mcp/stacks/:stackId/tables/:tableId/views — list all visible views (MCP API only). */
+export async function getTableViewList(stackId, tableId) {
+    const path = `${MCP_API}/stacks/${encodeURIComponent(stackId)}/tables/${encodeURIComponent(tableId)}/views`;
+    const out = await request(path, { method: "GET" });
+    return Array.isArray(out.data) ? out.data : [];
+}
+/** Describe one table: name (from tablelist), fields (columnlist), views (viewlist). */
+export async function describeTable(stackId, tableId) {
+    const [tables, fields, views] = await Promise.all([
+        getTables(stackId),
+        getTableColumns(stackId, tableId),
+        getTableViewList(stackId, tableId),
+    ]);
+    const tableMeta = tables.find((t) => t.id === tableId);
+    return {
+        id: tableId,
+        name: tableMeta?.name ?? tableId,
+        fields,
+        views,
+    };
+}
+/** GET /api/v1/mcp/stacks/:stackId/tables/:tableId/rows — list rows (MCP API). */
+export async function getRowList(stackId, tableId, opts = {}) {
+    const maxRecords = Math.min(Math.max(1, opts.maxRecords ?? 100), 100);
+    const offset = Math.max(0, opts.offset ?? 0);
+    let path = `${MCP_API}/stacks/${encodeURIComponent(stackId)}/tables/${encodeURIComponent(tableId)}/rows?maxrecord=${maxRecords}&offset=${offset}`;
+    if (opts.rowIds && opts.rowIds.length > 0) {
+        path += `&rowIds=${encodeURIComponent(opts.rowIds.join(","))}`;
+    }
+    const out = await request(path, { method: "GET" });
+    return Array.isArray(out.data) ? out.data : [];
+}
+/** GET /api/v1/mcp/stacks/:stackId/tables/:tableId/rows/:recordId — get one record (MCP API). */
+export async function getRecord(stackId, tableId, recordId) {
+    const path = `${MCP_API}/stacks/${encodeURIComponent(stackId)}/tables/${encodeURIComponent(tableId)}/rows/${encodeURIComponent(recordId)}`;
+    const out = await request(path, { method: "GET" });
+    const data = out.data;
+    if (Array.isArray(data))
+        return data.length > 0 ? data[0] : null;
+    return data && typeof data === "object" ? data : null;
+}
+/** POST /api/v1/mcp/stacks/:stackId/tables/:tableId/search — search rows (MCP API). */
+export async function searchRecords(stackId, tableId, searchTerm, opts = {}) {
+    let columnId = opts.columnId?.trim();
+    if (!columnId) {
+        const columns = await getTableColumns(stackId, tableId);
+        columnId = columns.length > 0 ? columns[0].id : "";
+    }
+    const maxRecord = Math.min(Math.max(1, opts.maxRecords ?? 100), 99999);
+    const path = `${MCP_API}/stacks/${encodeURIComponent(stackId)}/tables/${encodeURIComponent(tableId)}/search`;
+    const body = { search: searchTerm, columnId: columnId || undefined, maxRecords: maxRecord };
+    const out = await request(path, {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    const data = out.data;
+    const first = Array.isArray(data) ? data[0] : data;
+    if (!first || !first.rowIds) {
+        return { rowIds: [], rowname: [], fields: [] };
+    }
+    const f = first;
+    return { rowIds: f.rowIds ?? [], rowname: f.rowname ?? [], fields: f.fields ?? [] };
+}
+// --- Write APIs (Phase 3) ---
+/** POST /api/v1/mcp/stacks/:stackId/tables/:tableId/rows — create row(s) (MCP API). */
+export async function createRow(stackId, tableId, fields) {
+    const path = `${MCP_API}/stacks/${encodeURIComponent(stackId)}/tables/${encodeURIComponent(tableId)}/rows`;
+    const body = { records: [{ field: fields }] };
+    const out = await request(path, {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    return Array.isArray(out.data) ? out.data : [];
+}
+/** POST /api/v1/mcp/stacks/:stackId/tables/:tableId/rows/update — update rows (MCP API). */
+export async function updateRows(stackId, tableId, records) {
+    if (records.length === 0)
+        return [];
+    if (records.length > 10)
+        throw new Error("update_records supports at most 10 records per request.");
+    const path = `${MCP_API}/stacks/${encodeURIComponent(stackId)}/tables/${encodeURIComponent(tableId)}/rows/update`;
+    const body = {
+        records: records.map((r) => ({ id: r.id, field: r.fields })),
+    };
+    const out = await request(path, {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    return Array.isArray(out.data) ? out.data : [];
+}
+/** DELETE /api/v1/mcp/stacks/:stackId/tables/:tableId/rows — soft-delete rows (MCP API). */
+export async function deleteRows(stackId, tableId, recordIds) {
+    if (recordIds.length === 0)
+        return { records: [] };
+    if (recordIds.length > 10)
+        throw new Error("delete_records supports at most 10 records per request.");
+    const query = recordIds.map((id) => `rowIds=${encodeURIComponent(id)}`).join("&");
+    const path = `${MCP_API}/stacks/${encodeURIComponent(stackId)}/tables/${encodeURIComponent(tableId)}/rows?${query}`;
+    const out = await request(path, {
+        method: "DELETE",
+    });
+    return out.data ?? { records: [] };
+}
+/** POST /api/v1/mcp/stacks/:stackId/tables — create a table in a stack (MCP API). */
+export async function createTable(stackId, name, _description) {
+    const path = `${MCP_API}/stacks/${encodeURIComponent(stackId)}/tables`;
+    const body = { name: name.trim() };
+    const out = await request(path, {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    return out.data ?? {};
+}
+/** Column types supported by POST /api/v1/columnCreate/:columnType (devapi). */
+export const COLUMN_TYPES = [
+    "shortText",
+    "longText",
+    "number",
+    "checkbox",
+    "dateAndTime",
+    "time",
+    "singleOption",
+    "multipleOptions",
+    "email",
+    "url",
+    "phoneNumber",
+    "rating",
+    "duration",
+    "autoNumber",
+    "createdTime",
+    "updatedTime",
+    "createdBy",
+    "updatedBy",
+    "attachment",
+    "link",
+    "lookup",
+    "lookupCount",
+    "aggregation",
+    "formula",
+    "checkList",
+    "location",
+    "barcode",
+    "signature",
+];
+/** POST /api/v1/mcp/columns — create a column (MCP API). Body: stackId, tableId, name, columnType, viewId?, options? */
+export async function createColumn(stackId, tableId, name, columnType, opts = {}) {
+    const path = `${MCP_API}/columns`;
+    const body = {
+        stackId,
+        tableId,
+        name: name.trim(),
+        columnType,
+        viewId: opts.viewId ?? "",
+    };
+    if (opts.options && opts.options.length > 0) {
+        body.options = opts.options;
+    }
+    const out = await request(path, {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    return out.data ?? {};
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "stackby-mcp-server",
+  "version": "0.2.0",
+  "description": "MCP server for Stackby — list stacks, tables, records; create/update/delete rows and schema via AI clients (Cursor, Claude, Cline).",
+  "main": "dist/index.js",
+  "bin": { "stackby-mcp-server": "dist/index.js" },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc && node -e \"console.log('\\nBuild OK. Output in dist/'); console.log('Run npm start to run the server.');\"",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js",
+    "prepare": "npm run build"
+  },
+  "engines": { "node": ">=18" },
+  "keywords": ["mcp", "stackby", "model-context-protocol", "cursor", "claude", "ai"],
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  }
+}