Stackby MCP Server

Stackby MCP服务器

Stackby的模型上下文协议（MCP）服务器。公开工具，以便AI客户端（Cursor、Claude Desktop、Cline、带MCP的ChatGPT）可以使用Stackby数据。

认证： Stackby开发人员API通过 STACKBY_API_KEY （API密钥或个人访问令牌）。看 配置 在计划库（或兄弟库）中 Stackby_API/MCP_SERVER/docs/CONFIG.md).

______________________________________________________________________

安装（一键）

1.添加到光标 --编辑 ~/.cursor/mcp.json （Mac/Linux）或 %USERPROFILE%\.cursor\mcp.json （Windows）：

{
  "mcpServers": {
    "stackby": {
      "command": "npx",
      "args": ["-y", "stackby-mcp-server"],
      "env": {
        "STACKBY_API_KEY": "your-api-key-or-pat",
      }
    }
  }
}

替换 your-api-key-or-pat 使用Stackby API密钥或PAT。集 STACKBY_API_URL 到您的Stackby API基础URL（默认情况下省略）。重新启动游标。

1b。托管(https://mcp.stackby.com) --如果使用托管的MCP端点，请将其添加到Cursor中，如下所示 可流式传输HTTP 并在标头中发送您的API密钥：

{
  "mcpServers": {
    "stackby": {
      "type": "streamableHttp",
      "url": "https://mcp.stackby.com/mcp",
      "headers": {
        "X-Stackby-API-Key": "your-api-key-or-pat"
      }
    }
  }
}

或者使用 "Authorization": "Bearer your-api-key-or-pat" 而不是 X-Stackby-API-Key如果没有这些标头之一，服务器将返回401，Cursor可能会显示连接/500样式错误。更改配置后重新启动Cursor。

1c。本地测试托管端点 --要在您的计算机上运行HTTP MCP服务器并将Cursor连接到它（与托管的协议相同）：

1. 构建并启动HTTP服务器： npm run build && npm run start:http （在端口3001上侦听）。
2. 在 mcp.json 使用 可流式传输HTTP 使用您的本地URL和API密钥头：

{
  "mcpServers": {
    "stackby": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "headers": {
        "X-Stackby-API-Key": "your-api-key-or-pat"
      }
    }
  }
}

1. 重新启动光标（或重新加载窗口）。要稍后切换到真正的托管端点，请更改 url 到 https://mcp.stackby.com/mcp 并重新启动。

2.或全局安装： npm install -g stackby-mcp-server 然后使用 "command": "stackby-mcp-server" 在 mcp.json.

______________________________________________________________________

工具（27）

______________________________________________________________________

create_field参数指南

使用 create_field 使用这些按键输入：

• 所有人都需要： stackId, tableId, name, columnType
• 可选通用： viewId
• 对于 singleOption / multipleOptions: options
• 对于 link: linkToTableId （必填）， linkToTableViewId （可选）
• 对于 formula: formulaText

对于关系计算字段(lookup, count / lookupCount, rollup / aggregation):

• linkColumnId：当前表上的链接字段ID（创建新字段的表上的关系链接列）
• linkedColumnId：链接（外部）表上的字段ID

如何按类型映射：

• lookup：使用 linkColumnId，通常与 linkedColumnId
• lookupCount （或 count)：使用 linkColumnId （没有 linkedColumnId 需要）
• aggregation （或 rollup)：使用 linkColumnId 和 linkedColumnId

例子：

• 如果添加查找 表1 展示 Col2 从 表2:

- linkColumnId =表1上指向表2的链接列 - linkedColumnId = Col2 表2中的列ID

提示：跑步 describe_table 首先在两个表上获取正确的列ID。

______________________________________________________________________

设置

npm install
npm run build

如何验证构建： 之后 npm run build 你应该看看 Build OK. Output in dist/.快跑 npm start --服务器在stdio上运行（没有可见的输出；它等待Cursor/Claude连接）。

使用PM2运行HTTP服务器（生产）

在服务器上，使用PM2构建并启动HTTP MCP后端：

npm run build
npm run pm2:start

这运行 pm2 start dist/server-http.js --name mcp-backend.确保 PM2 已安装(npm install -g pm2).服务器监听端口 3001 默认情况下（设置 PORT 如果需要，在环境中）。

• 代码更改后重新启动： npm run build && npm run pm2:restart
• 停止： npm run pm2:stop

在游标中验证（步骤1.2）

1. 打开的游标 设置 → 主控程序 （或直接编辑配置文件）。

1. 添加Stackby MCP服务器。使用 项目 或 用户 配置。

选项A——用户配置 (~/.cursor/mcp.json 在Mac/Linux上，或 %USERPROFILE%\\.cursor\\mcp.json 在Windows上）：

   {
     "mcpServers": {
       "stackby": {
         "command": "node",
         "args": ["C:\\Users\\Admin\\Desktop\\Stackby\\stackby-mcp-server\\dist\\index.js"],
         "env": {
           "STACKBY_API_KEY": "your-api-key-or-pat"
         }
       }
     }
   }

使用 命令 + 参数 （stdio）。Thoout科普特语第二个月-LongName 不 将此服务器添加为URL（streamableHttp/SSE）——该模式用于托管HTTP，需要不同的设置。

选项B——如果你使用 npx 从项目文件夹中： （来自终端 stackby-mcp-server 跑 node dist/index.js；游标可以在中使用该路径 args.)

使用 完整路径 到 dist/index.js 在 args 因此Cursor可以生成服务器。

1. 重新启动光标（或重新加载窗口）。

1. 集 STACKBY_API_KEY （以及可选 STACKBY_API_URL)在 env 对象。在聊天中，查看 工具 列表-您应该看到所有11个工具： list_stacks, list_tables, describe_table, list_records, 搜索记录, 获取记录, create_record, update_records, 删除记录, create_table, create_field.

🔀 参数格式\ 输入键可以以以下方式提供 camelCase 或 snake_case。服务器将 自动转换 workspace_id → workspaceId （和类似的）所以GPT连接器 可以发送他们喜欢的任何样式。

运行（stdio--用于光标/Claude）

STACKBY_API_KEY=your_api_key STACKBY_API_URL=https://api.stackby.com npm start

或者单击一下： npx stackby-mcp-server （npm发布后）

配置

完整配置 （游标、克劳德桌面、Cline、HTTP传输）：请参阅 Stackby_API/MCP_SERVER/docs/CONFIG.md 在兄弟回购中。

______________________________________________________________________

故障排除

游标中stackby MCP服务器的“错误-显示输出”

1. 查看真正的错误 --在光标中转到 设置→ MCP，查找 斯塔克比，然后单击 “显示输出”日志将显示服务器失败的原因（例如缺少文件、缺少环境或节点错误）。
2. 在本地使用此仓库 --你必须 建造 将项目和光标指向已构建的文件：

- 在终端中： cd 转到此repo，然后运行 npm install 和 npm run build. - 在 %USERPROFILE%\.cursor\mcp.json （Windows）使用 标准 配置为 完整路径 到 dist\index.js:

   "stackby": {
     "command": "node",
     "args": ["C:\\Users\\Admin\\Desktop\\Stackby\\stackby-mcp-server\\dist\\index.js"],
     "env": { "STACKBY_API_KEY": "your-api-key-or-pat" }
   }

如果你的仓库在别处，请替换路径。不要使用 npx -y stackby-mcp-server 用于本地开发，除非您已经发布/安装了该软件包。

1. API密钥 --确保 STACKBY_API_KEY （或PAT）在服务器的 env 在 mcp.json.编辑配置后重新启动Cursor。

本地stdio正常工作，但托管URL返回500，没有错误正文

• 这 标准 配置（例如。 command / args 到 dist/index.js 随着 env.STACKBY_API_KEY)之所以有效，是因为密钥在进程env中。这 托管URL (https://mcp.stackby.com/mcp)必须在上接收API密钥 每一个请求 通过标题： X-Stackby-API-Key 或 Authorization: Bearer .
• 得到 正确的错误响应 从托管端点（因此您可以看到失败的内容，而不仅仅是状态500）：

1. 部署最新代码 来自此回购（包括 server-http.ts).服务器在500返回一个JSON正文 error, name, message，并且可选 stack 和 code，加上a X-MCP-Error 带有短消息的响应标头。 1. 部署后，500 响应体 将是JSON，例如。 { "error": "MCP handler error", "name": "Error", "message": "..." }.检查车身（或 X-MCP-Error header）查看Postman/dev工具中的真实错误。 1. 在服务器上，检查以下日志 [MCP /mcp] Error handling request: 以及要调试的堆栈跟踪。

流式HTTP“向端点发送错误”或SSE“非-200状态代码（500）”

• 检查API密钥 --服务器在没有密钥的情况下返回401，对于其他错误，可以返回500。在 mcp.json 在streamableHttp配置下，设置 标头 因此，每个请求都包含您的密钥，例如。 "X-Stackby-API-Key": "your-api-key-or-pat" 或 "Authorization": "Bearer your-api-key-or-pat"。编辑后重新启动游标。
• 如果你在本地测试 (url": "http://localhost:3001/mcp")：run npm run start:http 在终端中，并在Cursor连接时查看日志。你会看到 [MCP /mcp] Error handling request: 加上实际误差。修复该原因并重新启动服务器。
• 如果您使用的是托管URL (https://mcp.stackby.com/mcp)：500表示托管服务器抛出错误。确认标题设置如上。确保托管服务器运行 最新的 server-http 从这个仓库中，500个响应包括完整的错误JSON和 X-MCP-Error 头球

作为本地服务器添加时出现相同错误

• 如果要在本地运行服务器，请将其添加为 命令（stdio） 服务器，而不是URL： 命令 npx, 参数 ["-y", "stackby-mcp-server"], 环境 { "STACKBY_API_KEY": "your-api-key-or-pat" }.

Stackby:describe_table 说“尚未加载”/要求 tool_search 第一

• 这通常是客户端工具目录加载问题（不是 describe_table 参数错误）。
• 修复步骤：

1. 重新启动MCP客户端会话（或重新启动Cursor/ChatGPT连接器）。 1. 如果是本地服务器，请确保重建/重新启动服务器(npm run build，然后重新启动MCP服务器进程）。 1. 首先运行客户端工具发现(tool_search 与查询类似 stackby describe table)，然后致电 describe_table.

• describe_table 支持两种按键样式：

- 案例： stackId, tableId - 蛇病例： stack_id, table_id

______________________________________________________________________

规划与设计： Stackby_API/MCP_SERVER/ （兄弟回购）。