Effect Airtable MCP

影响气垫MCP服务器

A. 生产准备就绪 Airtable的模型上下文协议服务器，使用 效果 用于类型安全、可组合和健壮的API交互。此服务器允许通过Claude Desktop或其他MCP客户端对Airtable库、表、字段和记录进行程序化管理。

为什么效果？

此服务器利用Effect库提供：

• 类型安全：从输入验证到输出序列化的完全端到端类型安全
• 错误处理：具有自动验证和重试功能的结构化错误类型
• 可组合性：具有可重用验证管道的模块化工具架构
• 可测试性：纯函数和基于效果的测试，无需模拟
• 可靠性：合同驱动设计在验证边界捕捉API变化

与传统实现不同，此服务器具有以下功能：

• 分阶段创建表：逐步构建复杂的表，以最大限度地减少API故障
• 架构验证：Zod模式确保运行时的正确性
• 自动检索：瞬态故障的基于效果的重试逻辑
• 开发者体验：全面的错误消息和类型推断

要求：Node.js

1. 从以下位置安装Node.js（版本18或更高）和npm
2. 验证安装：

   node --version
   npm --version

⚠️ 重要：在运行之前，请确保设置Airtable API密钥

获取Airtable API密钥

1. 登录您的Airtable帐户 airtable.com
2. 在以下位置创建个人访问令牌 Airtable的Builder Hub
3. 在“个人访问令牌”部分，选择以下范围：

- data.records：读取 - data.records：写入 - schema.bases:读取 - schema.bases：写入

1. 选择要授予访问个人访问令牌权限的工作区或基地
2. 请确保此密钥的安全——您需要它进行配置

安装

方法1：使用npx（推荐）

1. 导航到Claude配置目录：

- 窗户： C:\Users\NAME\AppData\Roaming\Claude - macOS： ~/Library/Application Support/Claude/

您还可以在Claude Desktop应用程序中找到这些目录：Claude Desktop>设置>开发人员>编辑配置

1. 创建或编辑 claude_desktop_config.json:

{
  "mcpServers": {
    "airtable-effect": {
      "command": "npx",
      "args": ["@kastalien-research/effect-airtable-mcp"],
      "env": {
        "AIRTABLE_API_KEY": "your_api_key_here"
      }
    }
  }
}

注意：对于Windows路径，请使用双反斜杠（\\）或正斜杠（/）。

方法2：本地开发安装

如果你想贡献或修改代码：

# Clone the repository
git clone https://github.com/glassBead-tc/effect-airtable-mcp.git
cd effect-airtable-mcp

# Install dependencies
npm install

# Build the server
npm run build

# Run tests
npm test

# Run locally
node build/index.js

然后修改Claude Desktop配置文件以使用本地安装：

{
  "mcpServers": {
    "airtable-effect": {
      "command": "node",
      "args": ["/absolute/path/to/effect-airtable-mcp/build/index.js"],
      "env": {
        "AIRTABLE_API_KEY": "your_api_key_here"
      }
    }
  }
}

验证安装

1. 启动克劳德桌面
2. Airtable MCP服务器应列在“连接的MCP服务器”部分
3. 使用一个简单的命令进行测试：

List all bases

建筑

基于效果的设计

此服务器使用 契约驱动架构 由Effect提供动力：

// Every tool follows this pattern:
ToolExecutor {
  1. Validate Input (Zod schema)
  2. Execute Operation (Effect workflow)
  3. Validate Output (Zod schema)
  4. Check Postconditions (business rules)
  → Return typed result or structured error
}

关键部件：

• ToolExecutor：具有验证管道的通用执行框架
• mcp-adapter：MCP协议的桥接效应工作流程
• 架构模块：所有输入/输出（基、表、字段、记录）的Zod模式
• 工具模块：纯粹基于效果的操作，在执行之前没有副作用

错误处理：

• InputValidationError：工具参数无效
• OutputValidationError：意外的API响应（捕获中断的更改）
• AirtableApiError：带有上下文和重试逻辑的HTTP错误
• PostconditionError：违反业务规则

看 src/docs/effect-architecture.md 详细文档。

特性

可用操作

数据库管理

• list_bases：列出所有可访问的Airtable基地
• list_tables：列出基中的所有表
• create_table：使用字段创建新表
• update_table：更新表的名称或描述

现场管理

• create_field：向表中添加新字段
• update_field：修改现有字段

记录操作

• list_records：从表中检索记录
• create_record：添加新记录
• update_record：修改现有记录
• delete_record：删除记录
• search_records：查找符合条件的记录
• get_record：按ID获取单个记录

字段类型

• singleLineText：单行文本字段
• multilineText：多行文本区域
• email：电子邮件地址字段
• phoneNumber：电话号码字段
• number：具有可选精度的数字字段
• currency：带货币符号的货币字段
• date：带格式选项的日期字段
• singleSelect：选项中的单选
• multiSelect：选项中的多项选择

字段颜色

选定字段的可用颜色：

• blueBright, redBright, greenBright
• yellowBright, purpleBright, pinkBright
• grayBright, cyanBright, orangeBright
• blueDark1, greenDark1

贡献

我们欢迎为改进Effect Airtable MCP服务器做出贡献！

快速开始

1. 分叉和克隆：

   git clone https://github.com/your-username/effect-airtable-mcp.git
   cd effect-airtable-mcp
   npm install

1. 创建要素分支：

   git checkout -b feature/your-feature-name

1. 按照效果模式进行更改（请参见 src/docs/effect-architecture.md)

1. 运行测试和梳理：

   npm test
   npm run lint
   npm run format:check

1. 承诺并推动：

   git add .
   git commit -m "feat: add your feature description"
   git push origin feature/your-feature-name

1. 打开Pull请求https://github.com/glassBead-tc/effect-airtable-mcp

开发指南

• 使用效果图案：所有工具使用 ToolExecutor 通过Zod验证
• 类型安全性：没有 any 类型，启用严格的TypeScript
• 测试：编写基于效果的测试（无需模拟）
• 错误处理：使用结构化 ToolError 类型
• 文档：更新模式和工具描述
• 承诺：遵循语义提交消息（feat/fix/docs/re重构）

获取帮助

• 为bug或功能请求打开问题
• 加入现有问题的讨论
• 在pull请求中提问

你的贡献有助于使这个工具对每个人都更好。无论是：

• 添加新功能
• 修复bug
• 改进文件
• 建议增强功能

我们感谢您的帮助，使Airtable MCP服务器更加强大和用户友好！

许可证

麻省理工学院

______________________________________________________________________

由以下材料制成❤️ Airtable MCP社区