Fillout MCP Server

🚀 Fillout.io MCP 服務器

Fillout.io MCP 服務器為 Fillout.io API 提供支持，具備表單管理、響應處理和分析等功能，助力用戶高效處理表單相關事務。

🚀 快速開始

令牌設置

1. 獲取您的 Fillout.io API 密鑰：
   • 登錄到您的 Fillout.io 賬戶。
   • 進入賬戶設置 → API 和網絡鉤子。
   • 點擊“創建新 API 密鑰”。
   • 複製您的新 API 密鑰。
2. API 密鑰信息：
   • 生產密鑰以 fo_live_ 開頭。
   • 測試密鑰以 fo_test_ 開頭。
   • 測試密鑰僅適用於測試表單。
   • API 密鑰提供對您賬戶中所有資源的訪問權限。
3. 在配置文件中，將 your-fillout-api-key 替換為您自己的 API 密鑰。

⚠️ 重要提示

• 請保持您的 API 密鑰安全且私密。
• 建議使用測試密鑰進行開發。
• 請將密鑰存儲在環境變量中，避免在代碼中硬編碼密鑰。
• 定期更新和輪換密鑰。

安裝與運行

# 安裝依賴項
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 {
    // 處理意外錯誤
  }
}

📚 詳細文檔

故障排除

常見錯誤及解決方案

1. 無效的 API 密鑰
   • 確保密鑰正確無誤。
   • 檢查是否區分大小寫（API 可能對大小寫敏感）。
   • 確認密鑰未過期。
2. 網絡連接問題
   • 檢查網絡是否正常。
   • 確保 API 服務端點可達。
   • 使用抓包工具檢查請求和響應。
3. 權限不足
   • 確認密鑰具有所需權限。
   • 聯繫管理員檢查密鑰權限設置。
   • 查看 API 文檔確認操作是否需要額外權限。
4. 速率限制
   • 等待一段時間後重試。
   • 使用排隊或限流機制。
   • 聯繫支持增加配額。

📄 許可證

本項目在 MIT 許可證下發布。查看 LICENSE 文件以獲取詳細信息。