Fillout MCP Server

🚀 Fillout.io MCP 服务器

Fillout.io MCP 服务器为 Fillout.io API 提供支持，可实现表单管理、响应处理和数据分析等功能，为用户提供便捷高效的表单服务体验。

🚀 快速开始

为了让您尽快使用 Fillout.io MCP 服务器，下面将详细介绍如何进行令牌设置以及后续的操作。

🔑 令牌设置

1. 获取 Fillout.io API 密钥：
   • 登录您的 Fillout.io 账户。
   • 进入账户设置，选择“API 和网络钩子”。
   • 点击“创建新 API 密钥”，然后复制新生成的 API 密钥。
2. API 密钥信息：
   • 生产密钥以 fo_live_ 开头。
   • 测试密钥以 fo_test_ 开头，且仅适用于测试表单。
   • API 密钥可提供对您账户中所有资源的访问权限。
3. 配置 API 密钥：在配置文件中，将 your-fillout-api-key 替换为您自己的 API 密钥。

⚠️ 重要提示

• 请务必保持您的 API 密钥安全且私密。
• 建议在开发阶段使用测试密钥。
• 可将密钥存储在环境变量中，避免在代码中硬编码密钥。
• 定期更新和轮换密钥，以保障账户安全。

❓ 故障排除

常见错误及解决方案：

1. 无效的 API 密钥
   • 仔细检查密钥是否正确，注意 API 可能对大小写敏感。
   • 确认密钥未过期。
2. 网络连接问题
   • 检查网络是否正常，确保 API 服务端点可达。
   • 可使用抓包工具检查请求和响应。
3. 权限不足
   • 确认密钥具有所需权限。
   • 若权限不足，可联系管理员检查密钥权限设置。
   • 查看 API 文档，确认操作是否需要额外权限。
4. 速率限制
   • 若遇到速率限制，可等待一段时间后重试。
   • 可以使用排队或限流机制。
   • 若仍无法解决，可联系支持人员增加配额。

✨ 主要特性

• 表单管理：支持创建、读取、更新和删除表单，满足多样化的表单管理需求。
• 响应处理：可提交、获取、修改和删除响应数据，方便对表单响应进行管理。
• 用户身份验证：集成多种身份验证方法，保障系统安全。
• 数据分析：能够统计表单填写情况，为决策提供数据支持。
• 事件触发：可配置表单完成后的自定义操作，实现个性化业务流程。

📦 安装指南

安装与运行

# 安装依赖项
npm install

# 开发模式启动
npm run dev

# 构建生产版本
npm run build

Docker 部署

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

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

构建要求

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

💻 使用示例

基础用法

创建表单

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: "是"
    }
  ]
});

高级用法

错误处理

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

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

📄 许可证

本项目在 MIT 许可证下发布。查看 LICENSE 文件以获取详细信息。