danielma-tic_fillout-mcp-server

🚀 Fillout.io MCP 服务器

Fillout.io MCP 服务器借助 Fillout.io API，实现表单管理、响应处理和分析等功能，为用户提供便捷的表单操作体验。

🚀 快速开始

令牌设置

1. 获取 Fillout.io API 密钥：
   • 登录你的 Fillout.io 账户。
   • 前往账户设置 → API 和 Webhook。
   • 点击“创建新 API 密钥”。
   • 复制新生成的 API 密钥。
2. API 密钥信息：
   • 生产密钥以 fo_live_ 开头。
   • 测试密钥以 fo_test_ 开头，且仅适用于测试表单。
3. 配置环境变量：

FILLOUT_API_KEY=你的 Fillout.io API 密钥

✨ 主要特性

表单管理

• 创建表单
• 更新表单
• 删除表单
• 列出所有表单

响应处理

• 提交响应
• 获取特定响应
• 删除响应
• 导出响应数据

分析

• 生成报告
• 查看统计信息
• 设置自定义分析

📦 安装指南

本地开发配置

# 安装依赖
npm install

# 运行开发模式
npm run dev

# 构建生产版本
npm run build

Docker 配置

# 构建镜像
docker build -t mcp/fillout .

# 运行容器
docker run -e FILLOUT_API_KEY=你的密钥 mcp/fillout

💻 使用示例

基础用法

创建表单

const form = await client.createForm({
  name: "客户反馈",
  description: "请分享您的体验",
  questions: [
    {
      type: "ShortAnswer",
      name: "您最喜欢的部分是什么？",
      required: true
    },
    {
      type: "MultipleChoice",
      name: "您会推荐我们吗？",
      required: true,
      choices: ["是", "否", "可能"]
    }
  ]
});

提交响应

const response = await client.submitFormResponse(formId, {
  responses: [
    {
      questionId: "q1",
      value: "出色的客户服务！"
    },
    {
      questionId: "q2",
      value: "是"
    }
  ]
});

📚 详细文档

故障排除

以下是常见问题及其解决方案：

1. 无效的 API 密钥

• 症状：API 请求返回“ unauthorized ”错误。
• 原因：使用的密钥不正确或已被禁用。
• 解决方法：
  • 确认密钥是否正确。
  • 检查密钥状态（启用/禁用）。

2. 超出速率限制

• 症状：API 请求返回“ too many requests ”错误。
• 原因：短时间内请求次数过多。
• 解决方法：
  • 等待一段时间再尝试。
  • 提升 API 使用计划。

错误处理

服务器提供详细的错误消息以帮助诊断问题：

try {
  const forms = await client.listForms();
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 处理无效 API 密钥
  } else if (error instanceof FilloutError) {
    // 处理 API 特定错误
  } else {
    // 处理意外错误
  }
}

📄 许可证

本项目采用 MIT 许可证。有关详细信息，请参阅 LICENSE 文件。