servicefusion-mcp

🚀 ServiceFusion MCP 服务器

ServiceFusion MCP 服务器是一个基于模型上下文协议（MCP）的服务器，它为 AI 代理提供了标准化的方式来访问 ServiceFusion API 操作。

✨ 主要特性

• OAuth 2.0 认证：自动进行令牌管理和刷新。
• 完整的 CRUD 操作：可对客户和工作任务进行创建、读取、更新和删除操作。
• 类型安全的接口：全面支持 TypeScript 并进行验证。
• 资源访问：提供用于浏览客户和工作任务的 MCP 资源。
• 错误处理：具备全面的错误处理和验证机制。

📦 安装指南

1. 克隆项目并安装依赖：

npm install

2. 设置环境变量：

cp .env.example .env
# 使用你的 ServiceFusion 凭证编辑 .env 文件

3. 构建项目：

npm run build

💻 使用示例

运行 MCP 服务器

npm start

开发模式

npm run dev

测试

npm test

📚 详细文档

可用工具

连接管理

• sf_test_connection - 测试 ServiceFusion API 连接性。
• sf_get_api_status - 获取当前认证状态。

客户操作

• sf_create_customer - 创建带有联系人与地址的新客户。
• sf_get_customers - 分页搜索和检索客户信息。

工作任务操作

• sf_create_job - 创建新的工作订单/任务。
• sf_get_jobs - 过滤搜索和检索工作任务信息。
• sf_update_job - 更新工作任务状态和详细信息。
• sf_delete_job - 删除/取消工作任务。

可用资源

• servicefusion://customers - 客户的分页列表。
• servicefusion://jobs - 工作任务的分页列表。
• servicefusion://customer/{id} - 单个客户的详细信息。
• servicefusion://job/{id} - 单个工作任务的详细信息。
• servicefusion://api-status - API 连接状态。

配置

设置以下环境变量：

• SERVICEFUSION_CLIENT_ID - 你的 ServiceFusion API 客户端 ID。
• SERVICEFUSION_CLIENT_SECRET - 你的 ServiceFusion API 客户端密钥。
• SERVICEFUSION_BASE_URL - （可选）API 基础 URL（默认为 https://api.servicefusion.com）。

与 Claude Desktop 集成

将以下内容添加到你的 Claude Desktop MCP 配置中：

{
  "mcpServers": {
    "servicefusion": {
      "command": "node",
      "args": ["/path/to/servicefusion-mcp/build/index.js"],
      "env": {
        "SERVICEFUSION_CLIENT_ID": "your_client_id",
        "SERVICEFUSION_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

API 示例

创建客户

await sf_create_customer({
  customer_name: "ABC Property Management",
  contacts: [{
    fname: "John",
    lname: "Doe", 
    contact_type: "Primary",
    phone: "555-1234",
    email: "john@abc.com"
  }],
  locations: [{
    street_1: "123 Main St",
    city: "Dallas",
    state_prov: "TX",
    postal_code: "75201"
  }]
});

创建工作任务

await sf_create_job({
  check_number: "WO-12345",
  customer_id: 123456,
  description: "HVAC repair needed",
  category: "Maintenance",
  priority: "High",
  street_1: "123 Main St",
  city: "Dallas",
  state_prov: "TX"
});

搜索工作任务

await sf_get_jobs({
  page: 1,
  customer_name: "ABC Property",
  status: "Scheduled",
  updated_since: "2025-01-01T00:00:00Z"
});

数据模型

客户

• customer_name（必需）
• parent_customer（可选） - 用于分层客户。
• contacts[] - 联系人信息数组。
• locations[] - 地址信息数组。

工作任务

• check_number（必需） - 唯一标识符。
• customer_id（必需） - 关联的客户。
• description（必需） - 工作任务描述。
• status - 工作任务状态（已安排、进行中、已完成等）。
• priority - 工作任务优先级（正常、高、低）。
• custom_fields[] - 自定义字段值。

错误处理

服务器包含全面的错误处理，可处理以下情况：

• 认证失败（自动刷新令牌）。
• API 速率限制和超时。
• 无效输入验证。
• 网络连接问题。

贡献代码

1. 在 src/ 目录下的 TypeScript 文件中进行更改。
2. 使用 npm run build 进行构建。
3. 使用 npm test 进行测试。
4. 提交带有测试的拉取请求。

📄 许可证

本项目采用 MIT 许可证。