使用说明

影响气垫MCP服务器

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

为什么效果？

此服务器利用Effect库提供：

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

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

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

要求：Node.js

从以下位置安装Node.js（版本18或更高）和npm nodejs.org
验证安装：
```
node --version
npm --version
```

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

获取Airtable API密钥

登录您的Airtable帐户 airtable.com
在以下位置创建个人访问令牌 Airtable的Builder Hub
在“个人访问令牌”部分，选择以下范围：
- data.records：读取
- data.records：写入
- schema.bases:读取
- schema.bases：写入
选择要授予访问个人访问令牌权限的工作区或基地
请确保此密钥的安全——您需要它进行配置

安装

方法1：使用npx（推荐）

导航到Claude配置目录：
- 窗户： C:\Users\NAME\AppData\Roaming\Claude
- macOS： ~/Library/Application Support/Claude/
您还可以在Claude Desktop应用程序中找到这些目录：Claude Desktop>设置>开发人员>编辑配置
创建或编辑 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"
      }
    }
  }
}

验证安装

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

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服务器做出贡献！

快速开始

分叉和克隆：

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

创建要素分支：

git checkout -b feature/your-feature-name

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

运行测试和梳理：

npm test
npm run lint
npm run format:check

承诺并推动：

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

打开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社区