Relation MCP

🔗 relation-mcp

一個面向 Re:lation（由株式會社インゲージ提供）的 Model Context Protocol 服務器。讓 Claude / Claude Code / 任意 MCP 客戶端能夠直接從智能體中搜索與處理客服工單、創建內部記錄，並查看通訊錄。

💡 說明

本服務器基於官方 Re:lation REST API（https://<tenant>.relationapp.jp/api/v2/）運行。完整的 API 參考文檔請見 developer.ingage.jp。

✨ 主要特性

• search_tickets —— 按狀態、負責人、標籤、自由文本查詢進行篩選
• get_ticket / update_ticket —— 獲取工單詳情，修改狀態/負責人/標籤
• reply_mail —— 面向客戶的郵件回覆，受 confirm_send: true 聯鎖機制保護
• list_mail_accounts —— 獲取 reply_mail 所需的 mail_account_id
• create_record —— 發佈內部 応対メモ（客戶不可見）
• create_comment —— 在工單上發佈團隊評論
• search_customers / get_customer —— 通訊錄查詢
• list_labels / list_users —— 用於腳本自動化的參考數據
• 內置令牌桶限流器（確保不超過租戶每分鐘 60 次請求的限制）
• 類型化錯誤（RelationApiError、RelationAuthError、RelationRateLimitError）

⚠️ 關於 reply_mail 的安全須知

reply_mail 會向工單對應的客戶發送真實郵件。為防止智能體在工具鏈式調用中誤觸發，該工具要求傳入 confirm_send: true 參數——若缺失或為 false，調用會在觸達 Re:lation API 之前被拒絕。請謹慎使用。

📦 安裝指南

npm install -g relation-mcp
# or run ad-hoc with npx
npx relation-mcp

⚙️ 配置

在 Re:lation 中生成訪問令牌（管理界面 → API token），然後導出環境變量：

export RELATION_SUBDOMAIN=yourtenant          # the part before .relationapp.jp
export RELATION_MESSAGE_BOX_ID=1              # default 受信箱 ID
export RELATION_ACCESS_TOKEN=your_token_here

隨附了一份 .env.example 副本供參考。

🚀 在 Claude Code / Claude Desktop 中使用

將以下配置添加到你的 MCP 配置文件（例如 ~/.claude/config.json 或 Claude Desktop 配置文件）：

{
  "mcpServers": {
    "relation": {
      "command": "npx",
      "args": ["-y", "relation-mcp"],
      "env": {
        "RELATION_SUBDOMAIN": "yourtenant",
        "RELATION_MESSAGE_BOX_ID": "1",
        "RELATION_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

然後向智能體發出提示：

Find tickets where status is open and the subject contains "本人確認", then summarize the top 5.

📚 工具參考

所有工具都接受一個可選的 message_box_id 參數，用於在單次調用中覆蓋默認值。

🔧 開發

git clone https://github.com/sewon-supernova/relation-mcp.git
cd relation-mcp
npm install
npm run typecheck
npm test
npm run build

針對真實租戶進行本地運行：

cp .env.example .env   # fill in values
npm run build
node dist/index.js     # speaks MCP over stdio

🗺️ 路線圖

• [ ] list_message_boxes
• [ ] list_pending_reasons / list_case_categories
• [ ] 分頁輔助工具（自動遍歷 page）
• [ ] 提示詞模板（MCP prompts/*），用於常見的工單分診流程
• [ ] 針對預發佈租戶的端到端測試
• [ ] Docker 鏡像

📄 許可證

MIT —— 詳見完整文本。

🔖 與株式會社インゲージ無關聯

這是一個非官方的、由社區維護的客戶端。"Re:lation" 與 "relationapp.jp" 是各自所有者的商標。