Fillout.io MCP 服务器

Fillout.io API 的 MCP 服务器，支持表单管理、响应处理和分析。

令牌设置

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

   • 登录到您的 Fillout.io 账户
   • 前往账户设置 → API 和 Webhooks
   • 点击“创建新的 API 密钥”
   • 复制您的新 API 密钥

2. API 密钥信息：

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

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

⚠️ 安全提示：

• 保持您的 API 密钥安全且私密
• 在开发时使用测试密钥
• 将密钥存储在环境变量中
• 定期更换密钥
• 永远不要将密钥提交到版本控制系统

令牌故障排除

常见错误消息

1. "提供的 API 密钥无效" 或 "身份验证失败"

   • 原因：API 密钥缺失、格式不正确或无效
   • 解决方案：
     • 验证密钥是否以 fo_live_ 或 fo_test_ 开头
     • 检查是否有额外的空格或字符
     • 确保环境变量设置正确
     • 如有必要，创建一个新的密钥

2. "使用测试模式密钥与生产表单"

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

3. "超出速率限制"

   • 原因：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 (可选)

本地开发

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

Docker 构建

# Build image
docker build -t mcp/fillout .

# Run container
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) {
    // Handle invalid API key
  } else if (error instanceof FilloutError) {
    // Handle API-specific errors
  } else {
    // Handle unexpected errors
  }
}

许可证

本项目根据 MIT 许可证许可。详情请参阅 LICENSE 文件。