stackby-mcp-server 0.2.2 → 0.2.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -103
- package/dist/stackby-api.d.ts +1 -1
- package/dist/stackby-api.js +19 -12
- package/package.json +43 -26
package/README.md
CHANGED
|
@@ -1,103 +1,103 @@
|
|
|
1
|
-
# Stackby MCP Server
|
|
2
|
-
|
|
3
|
-
Model Context Protocol (MCP) server for Stackby. Exposes tools so AI clients (Cursor, Claude Desktop, Cline, ChatGPT with MCP) can work with Stackby data.
|
|
4
|
-
|
|
5
|
-
**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`).
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## Install (one-click)
|
|
10
|
-
|
|
11
|
-
**1. Add to Cursor** — Edit `~/.cursor/mcp.json` (Mac/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows):
|
|
12
|
-
|
|
13
|
-
```json
|
|
14
|
-
{
|
|
15
|
-
"mcpServers": {
|
|
16
|
-
"stackby": {
|
|
17
|
-
"command": "npx",
|
|
18
|
-
"args": ["-y", "stackby-mcp-server"],
|
|
19
|
-
"env": {
|
|
20
|
-
"STACKBY_API_KEY": "your-api-key-or-pat",
|
|
21
|
-
}
|
|
22
|
-
}
|
|
23
|
-
}
|
|
24
|
-
}
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
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.
|
|
28
|
-
|
|
29
|
-
**2. Or install globally:** `npm install -g stackby-mcp-server` then use `"command": "stackby-mcp-server"` in `mcp.json`.
|
|
30
|
-
|
|
31
|
-
---
|
|
32
|
-
|
|
33
|
-
## Tools (11)
|
|
34
|
-
|
|
35
|
-
| Tool | Description |
|
|
36
|
-
|------|-------------|
|
|
37
|
-
| `list_stacks` | List stacks (bases) the user can access. |
|
|
38
|
-
| `list_tables` | List tables in a stack. |
|
|
39
|
-
| `describe_table` | Table schema: fields (columns), views. |
|
|
40
|
-
| `list_records` | List rows in a table (with optional maxRecords). |
|
|
41
|
-
| `search_records` | Search rows by text. |
|
|
42
|
-
| `get_record` | Get one row by ID. |
|
|
43
|
-
| `create_record` | Create a row (fields keyed by column name). |
|
|
44
|
-
| `update_records` | Update rows (array of `{ id, fields }`, max 10). |
|
|
45
|
-
| `delete_records` | Soft-delete rows by ID (max 10). |
|
|
46
|
-
| `create_table` | Create a new table in a stack. |
|
|
47
|
-
| `create_field` | Create a new column (field) in a table. |
|
|
48
|
-
|
|
49
|
-
---
|
|
50
|
-
|
|
51
|
-
## Setup
|
|
52
|
-
|
|
53
|
-
```bash
|
|
54
|
-
npm install
|
|
55
|
-
npm run build
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
**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).
|
|
59
|
-
|
|
60
|
-
## Verify in Cursor (Step 1.2)
|
|
61
|
-
|
|
62
|
-
1. Open Cursor **Settings** → **MCP** (or edit the config file directly).
|
|
63
|
-
2. Add the Stackby MCP server. Use **project** or **user** config.
|
|
64
|
-
|
|
65
|
-
**Option A — User config** (`~/.cursor/mcp.json` on Mac/Linux, or `%USERPROFILE%\\.cursor\\mcp.json` on Windows):
|
|
66
|
-
|
|
67
|
-
```json
|
|
68
|
-
{
|
|
69
|
-
"mcpServers": {
|
|
70
|
-
"stackby": {
|
|
71
|
-
"command": "node",
|
|
72
|
-
"args": ["C:\\Users\\Admin\\Desktop\\Stackby\\stackby-mcp-server\\dist\\index.js"],
|
|
73
|
-
"env": {}
|
|
74
|
-
}
|
|
75
|
-
}
|
|
76
|
-
}
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
**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`.)
|
|
80
|
-
|
|
81
|
-
Use the **full path** to `dist/index.js` in `args` so Cursor can spawn the server.
|
|
82
|
-
3. Restart Cursor (or reload the window).
|
|
83
|
-
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**.
|
|
84
|
-
|
|
85
|
-
## Run (stdio — for Cursor / Claude)
|
|
86
|
-
|
|
87
|
-
```bash
|
|
88
|
-
STACKBY_API_KEY=your_api_key STACKBY_API_URL=https://api.stackby.com npm start
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
Or one-click: `npx stackby-mcp-server` (after npm publish)
|
|
92
|
-
|
|
93
|
-
## Config
|
|
94
|
-
|
|
95
|
-
| Env | Required | Description |
|
|
96
|
-
|-----|----------|-------------|
|
|
97
|
-
| `STACKBY_API_KEY` | Yes | Stackby API key (or PAT when implemented). |
|
|
98
|
-
|
|
99
|
-
**Full config** (Cursor, Claude Desktop, Cline, HTTP transport): see `Stackby_API/MCP_SERVER/docs/CONFIG.md` in the sibling repo.
|
|
100
|
-
|
|
101
|
-
---
|
|
102
|
-
|
|
103
|
-
Planning and design: `Stackby_API/MCP_SERVER/` (sibling repo).
|
|
1
|
+
# Stackby MCP Server
|
|
2
|
+
|
|
3
|
+
Model Context Protocol (MCP) server for Stackby. Exposes tools so AI clients (Cursor, Claude Desktop, Cline, ChatGPT with MCP) can work with Stackby data.
|
|
4
|
+
|
|
5
|
+
**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`).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Install (one-click)
|
|
10
|
+
|
|
11
|
+
**1. Add to Cursor** — Edit `~/.cursor/mcp.json` (Mac/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows):
|
|
12
|
+
|
|
13
|
+
```json
|
|
14
|
+
{
|
|
15
|
+
"mcpServers": {
|
|
16
|
+
"stackby": {
|
|
17
|
+
"command": "npx",
|
|
18
|
+
"args": ["-y", "stackby-mcp-server"],
|
|
19
|
+
"env": {
|
|
20
|
+
"STACKBY_API_KEY": "your-api-key-or-pat",
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
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.
|
|
28
|
+
|
|
29
|
+
**2. Or install globally:** `npm install -g stackby-mcp-server` then use `"command": "stackby-mcp-server"` in `mcp.json`.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Tools (11)
|
|
34
|
+
|
|
35
|
+
| Tool | Description |
|
|
36
|
+
|------|-------------|
|
|
37
|
+
| `list_stacks` | List stacks (bases) the user can access. |
|
|
38
|
+
| `list_tables` | List tables in a stack. |
|
|
39
|
+
| `describe_table` | Table schema: fields (columns), views. |
|
|
40
|
+
| `list_records` | List rows in a table (with optional maxRecords). |
|
|
41
|
+
| `search_records` | Search rows by text. |
|
|
42
|
+
| `get_record` | Get one row by ID. |
|
|
43
|
+
| `create_record` | Create a row (fields keyed by column name). |
|
|
44
|
+
| `update_records` | Update rows (array of `{ id, fields }`, max 10). |
|
|
45
|
+
| `delete_records` | Soft-delete rows by ID (max 10). |
|
|
46
|
+
| `create_table` | Create a new table in a stack. |
|
|
47
|
+
| `create_field` | Create a new column (field) in a table. |
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Setup
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npm install
|
|
55
|
+
npm run build
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**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).
|
|
59
|
+
|
|
60
|
+
## Verify in Cursor (Step 1.2)
|
|
61
|
+
|
|
62
|
+
1. Open Cursor **Settings** → **MCP** (or edit the config file directly).
|
|
63
|
+
2. Add the Stackby MCP server. Use **project** or **user** config.
|
|
64
|
+
|
|
65
|
+
**Option A — User config** (`~/.cursor/mcp.json` on Mac/Linux, or `%USERPROFILE%\\.cursor\\mcp.json` on Windows):
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
{
|
|
69
|
+
"mcpServers": {
|
|
70
|
+
"stackby": {
|
|
71
|
+
"command": "node",
|
|
72
|
+
"args": ["C:\\Users\\Admin\\Desktop\\Stackby\\stackby-mcp-server\\dist\\index.js"],
|
|
73
|
+
"env": {}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
**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`.)
|
|
80
|
+
|
|
81
|
+
Use the **full path** to `dist/index.js` in `args` so Cursor can spawn the server.
|
|
82
|
+
3. Restart Cursor (or reload the window).
|
|
83
|
+
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**.
|
|
84
|
+
|
|
85
|
+
## Run (stdio — for Cursor / Claude)
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
STACKBY_API_KEY=your_api_key STACKBY_API_URL=https://api.stackby.com npm start
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Or one-click: `npx stackby-mcp-server` (after npm publish)
|
|
92
|
+
|
|
93
|
+
## Config
|
|
94
|
+
|
|
95
|
+
| Env | Required | Description |
|
|
96
|
+
|-----|----------|-------------|
|
|
97
|
+
| `STACKBY_API_KEY` | Yes | Stackby API key (or PAT when implemented). |
|
|
98
|
+
|
|
99
|
+
**Full config** (Cursor, Claude Desktop, Cline, HTTP transport): see `Stackby_API/MCP_SERVER/docs/CONFIG.md` in the sibling repo.
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
Planning and design: `Stackby_API/MCP_SERVER/` (sibling repo).
|
package/dist/stackby-api.d.ts
CHANGED
|
@@ -57,7 +57,7 @@ export interface DescribeTableResult {
|
|
|
57
57
|
fields: TableField[];
|
|
58
58
|
views: TableView[];
|
|
59
59
|
}
|
|
60
|
-
/**
|
|
60
|
+
/** GET /api/v1/mcp/stacks/:stackId/tables/:tableId — describe table (single API: id, name, fields, views). */
|
|
61
61
|
export declare function describeTable(stackId: string, tableId: string): Promise<DescribeTableResult>;
|
|
62
62
|
export interface TableRecord {
|
|
63
63
|
id: string;
|
package/dist/stackby-api.js
CHANGED
|
@@ -23,6 +23,16 @@ function authHeaders() {
|
|
|
23
23
|
...(key.startsWith("pat_") ? { Authorization: `Bearer ${key}` } : {}),
|
|
24
24
|
};
|
|
25
25
|
}
|
|
26
|
+
/**
|
|
27
|
+
* Backend sendResponseAuthentication.js sends MCP routes as "plain": the raw payload
|
|
28
|
+
* (body.data) is sent, not { data: body.data }. So we accept both shapes.
|
|
29
|
+
*/
|
|
30
|
+
function normalizeResponse(body) {
|
|
31
|
+
if (body != null && typeof body === "object" && "data" in body && body.data !== undefined) {
|
|
32
|
+
return { data: body.data };
|
|
33
|
+
}
|
|
34
|
+
return { data: body };
|
|
35
|
+
}
|
|
26
36
|
async function request(path, options = {}) {
|
|
27
37
|
const url = path.startsWith("http") ? path : `${BASE_URL.replace(/\/$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
|
|
28
38
|
const res = await fetch(url, {
|
|
@@ -34,7 +44,7 @@ async function request(path, options = {}) {
|
|
|
34
44
|
const msg = body?.error ?? body?.message ?? res.statusText;
|
|
35
45
|
throw new Error(`Stackby API ${res.status}: ${msg}`);
|
|
36
46
|
}
|
|
37
|
-
return body;
|
|
47
|
+
return normalizeResponse(body);
|
|
38
48
|
}
|
|
39
49
|
/** GET /api/v1/mcp/workspaces — list workspaces (MCP API only). */
|
|
40
50
|
export async function getWorkspaces() {
|
|
@@ -91,19 +101,16 @@ export async function getTableViewList(stackId, tableId) {
|
|
|
91
101
|
const out = await request(path, { method: "GET" });
|
|
92
102
|
return Array.isArray(out.data) ? out.data : [];
|
|
93
103
|
}
|
|
94
|
-
/**
|
|
104
|
+
/** GET /api/v1/mcp/stacks/:stackId/tables/:tableId — describe table (single API: id, name, fields, views). */
|
|
95
105
|
export async function describeTable(stackId, tableId) {
|
|
96
|
-
const
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
getTableViewList(stackId, tableId),
|
|
100
|
-
]);
|
|
101
|
-
const tableMeta = tables.find((t) => t.id === tableId);
|
|
106
|
+
const path = `${MCP_API}/stacks/${encodeURIComponent(stackId)}/tables/${encodeURIComponent(tableId)}`;
|
|
107
|
+
const out = await request(path, { method: "GET" });
|
|
108
|
+
const d = out.data;
|
|
102
109
|
return {
|
|
103
|
-
id: tableId,
|
|
104
|
-
name:
|
|
105
|
-
fields,
|
|
106
|
-
views,
|
|
110
|
+
id: d?.id ?? tableId,
|
|
111
|
+
name: d?.name ?? tableId,
|
|
112
|
+
fields: Array.isArray(d?.fields) ? d.fields : [],
|
|
113
|
+
views: Array.isArray(d?.views) ? d.views : [],
|
|
107
114
|
};
|
|
108
115
|
}
|
|
109
116
|
/** GET /api/v1/mcp/stacks/:stackId/tables/:tableId/rows — list rows (MCP API). */
|
package/package.json
CHANGED
|
@@ -1,26 +1,43 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "stackby-mcp-server",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "MCP server for Stackby — list stacks, tables, records; create/update/delete rows and schema via AI clients (Cursor, Claude, Cline).",
|
|
5
|
-
"main": "dist/index.js",
|
|
6
|
-
"bin": {
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
"
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
"
|
|
19
|
-
"
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
"
|
|
24
|
-
"
|
|
25
|
-
|
|
26
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "stackby-mcp-server",
|
|
3
|
+
"version": "0.2.8",
|
|
4
|
+
"description": "MCP server for Stackby — list stacks, tables, records; create/update/delete rows and schema via AI clients (Cursor, Claude, Cline).",
|
|
5
|
+
"main": "dist/index.js",
|
|
6
|
+
"bin": {
|
|
7
|
+
"stackby-mcp-server": "dist/index.js"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"dist"
|
|
11
|
+
],
|
|
12
|
+
"scripts": {
|
|
13
|
+
"build": "tsc && node -e \"console.log('\\nBuild OK. Output in dist/'); console.log('Run npm start to run the server.');\"",
|
|
14
|
+
"start": "node dist/index.js",
|
|
15
|
+
"dev": "tsc && node dist/index.js",
|
|
16
|
+
"prepare": "npm run build"
|
|
17
|
+
},
|
|
18
|
+
"engines": {
|
|
19
|
+
"node": ">=18"
|
|
20
|
+
},
|
|
21
|
+
"keywords": [
|
|
22
|
+
"mcp",
|
|
23
|
+
"stackby",
|
|
24
|
+
"model-context-protocol",
|
|
25
|
+
"cursor",
|
|
26
|
+
"claude",
|
|
27
|
+
"ai"
|
|
28
|
+
],
|
|
29
|
+
"license": "MIT",
|
|
30
|
+
"repository": {
|
|
31
|
+
"type": "git",
|
|
32
|
+
"url": "https://github.com/stackbyhq/stackby-mcp-server"
|
|
33
|
+
},
|
|
34
|
+
"type": "module",
|
|
35
|
+
"dependencies": {
|
|
36
|
+
"@modelcontextprotocol/sdk": "^1.0.0",
|
|
37
|
+
"zod": "^3.23.0"
|
|
38
|
+
},
|
|
39
|
+
"devDependencies": {
|
|
40
|
+
"@types/node": "^20.10.0",
|
|
41
|
+
"typescript": "^5.3.0"
|
|
42
|
+
}
|
|
43
|
+
}
|