Fillout.io MCP 服务器

Fillout.io API 的 MCP 服务器，用于实现表单管理、响应处理和分析。

Token 设置

1. 获取您的 Fillout.io API 密钥：

   • 登录到您的 Fillout.io 帐户
   • 转到“帐户设置”→“API & Webhooks”
   • 点击“创建新的 API 密钥”
   • 复制您的新 API 密钥

2. API 密钥信息：

   • 生产密钥以 fo_live_ 开头
   • 测试密钥以 fo_test_ 开头
   • 测试密钥仅适用于测试表单
   • API 密钥提供对您帐户中所有资源的访问权限

3. 将配置中的 your-fillout-api-key 替换为您的 API 密钥。

⚠️ 安全注意事项：

• 确保您的 API 密钥安全和私密
• 使用测试密钥进行开发
• 将密钥存储在环境变量中
• 定期轮换密钥
• 永远不要将密钥提交到版本控制

Token 故障排除

常见错误消息

1. "Invalid API key provided" 或 "Authentication failed"

   • 原因：API 密钥缺失、格式错误或无效
   • 解决方案：
     • 验证密钥是否以 fo_live_ 或 fo_test_ 开头
     • 检查是否存在多余的空格或字符
     • 确保环境变量设置正确
     • 必要时创建新密钥

2. "Test mode key used with live form"

   • 原因：将测试密钥 (fo_test_) 用于生产表单
   • 解决方案：
     • 对生产表单使用生产密钥
     • 为开发创建测试表单
     • 切换到适当的密钥类型

3. "Rate limit exceeded"

   • 原因：API 请求过多
   • 解决方案：
     • 实施请求节流
     • 在仪表板中检查使用情况
     • 优化请求模式

验证步骤

1. 检查 API 密钥格式：

   # 密钥应：
   - 以 'fo_live_' 或 'fo_test_' 开头
   - 大约 50 个字符
   - 仅包含字母、数字和下划线
   

2. 测试 API 密钥：

   curl -H "Authorization: Bearer your-api-key" \
     https://api.fillout.com/v1/api/forms
   

功能

表单管理

• 列出所有表单
• 获取表单详细信息
• 创建新表单
• 删除表单
• 更新表单设置

响应处理

• 提交表单响应
• 获取表单提交
• 过滤响应
• 导出响应

分析

• 响应率
• 完成时间
• 提交趋势

工具

1. list_forms

   • 获取所有可访问的表单
   • 参数：
     • limit（可选）：要返回的表单数量
     • offset（可选）：分页偏移量
   • 返回：表单对象数组

2. get_form

   • 获取详细的表单信息
   • 参数：
     • formId（字符串）：表单标识符
   • 返回：表单详细信息，包括问题和设置

3. create_form

   • 创建新表单
   • 参数：
     • name（字符串）：表单名称
     • description（可选字符串）：表单描述
     • questions（数组）：问题对象数组
       • type：问题类型（例如，“ShortAnswer”、“MultipleChoice”）
       • name：问题文本
       • required：问题是否必填
       • choices：多项选择题的选项数组
   • 返回：已创建的表单对象

4. get_form_responses

   • 获取表单提交
   • 参数：
     • formId（字符串）：表单标识符
     • filters（可选）：响应过滤器
     • pageSize（可选）：每页结果数
     • afterDate（可选）：按提交日期过滤
     • beforeDate（可选）：按提交日期过滤
     • status（可选）：按完成状态过滤
   • 返回：表单响应数组

5. submit_form_response

   • 提交新响应
   • 参数：
     • formId（字符串）：表单标识符
     • responses（数组）：答案数组
       • questionId：问题标识符
       • value：响应值
     • calculations（可选）：自定义计算
   • 返回：提交确认

设置

与 Claude Desktop 一起使用

Docker 配置

{
  "mcpServers": {
    "fillout": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "FILLOUT_API_KEY",
        "mcp/fillout"
      ],
      "env": {
        "FILLOUT_API_KEY": "your-fillout-api-key"
      }
    }
  }
}

NPX 配置

{
  "mcpServers": {
    "fillout": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-fillout"
      ],
      "env": {
        "FILLOUT_API_KEY": "your-fillout-api-key"
      }
    }
  }
}

构建

前提条件

• Node.js 18 或更高版本
• npm 或 yarn
• Docker（可选）

本地开发

# 安装依赖
npm install

# 在开发模式下运行
npm run dev

# 构建用于生产
npm run build

Docker 构建

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

# 运行容器
docker run -e FILLOUT_API_KEY=your-key mcp/fillout

示例

创建表单

const form = await client.createForm({
  name: "Customer Feedback",
  description: "Please share your experience",
  questions: [
    {
      type: "ShortAnswer",
      name: "What did you like most?",
      required: true
    },
    {
      type: "MultipleChoice",
      name: "Would you recommend us?",
      required: true,
      choices: ["Yes", "No", "Maybe"]
    }
  ]
});

提交响应

const response = await client.submitFormResponse(formId, {
  responses: [
    {
      questionId: "q1",
      value: "Great customer service!"
    },
    {
      questionId: "q2",
      value: "Yes"
    }
  ]
});

错误处理

服务器为常见问题提供详细的错误消息：

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

许可证

该项目已获得 MIT 许可证的许可。 有关详细信息，请参见 LICENSE 文件。