AI导哈

服务集成平台

一个针对ServiceTitan API的全面模型上下文协议(MCP)集成平台，通过多个专注于特定领域的服务器提供客户管理、库存管理、财务管理等功能。

  • by BuildWithBeacon
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 buildwithbeacon/servicetitan-mcp

使用说明

ServiceTitan MCP集成

ServiceTitan API的全面模型上下文协议（MCP）集成，组织成专注于特定领域的服务器。

建筑

这种集成被拆分为多个专门的MCP服务器，以提高性能，减少上下文窗口的使用，并实现专注的功能：

🔧 核心服务器(servicetitan-core)

文件: servicetitan_core.py

基本服务Titan功能：

  • 客户管理
  • 呼叫跟踪和总结
  • 预约
  • 核心CRM运营

用例：客户服务、基本日程安排、呼叫中心运营

📦 价目表服务器(servicetitan-pricebook)

文件: servicetitan_pricebook.py

完整的价目表管理：

  • 材料（CRUD操作）
  • 服务（CRUD操作）
  • 设备（原油操作）
  • 类别和层次结构
  • 折扣和费用
  • 图像和资产
  • 材料标记
  • 客户特定定价
  • 导出功能

用例：库存管理、定价更新、目录维护

🏭 库存服务器(servicetitan-inventory)

文件: servicetitan_inventory.py

库存和供应链管理：

  • 库存调整
  • 采购订单和请求
  • 收据和接收
  • 退货处理
  • 地点之间的转移
  • 供应商管理
  • 仓库操作
  • 卡车库存

用例：供应链、采购、仓库管理

📊 作业项目管理服务器(servicetitan-jpm)

文件: servicetitan_jpm.py

工作和项目运营：

  • 作业生命周期管理（创建、更新、完成、取消、保留）
  • 项目管理（CRUD、工作附着/分离）
  • 预约安排和管理（重新安排、暂停、确认）
  • 作业类型和配置管理
  • 笔记、历史记录和消息
  • 所有JPM数据的导出功能

用例：项目协调、作业调度、工作流管理、技术人员派遣

👥 CRM服务器(servicetitan-crm)

文件: servicetitan_crm.py

客户关系管理：

  • 客户管理（通过过滤从核心增强）
  • 联系人管理（CRUD操作）
  • 线索管理和跟踪
  • 位置管理
  • 预订和预订提供商标签
  • 标签管理和组织
  • 所有CRM数据的导出功能

用例：客户关系管理、潜在客户跟踪、联系组织、预订管理

🚚 调度服务器(servicetitan-dispatch)

文件: servicetitan_dispatch.py

日程安排、路线安排和技术人员管理：

  • 任命任务（指派/取消指派技术人员）
  • 到货窗口管理
  • 营业时间配置
  • 容量规划和调度
  • 团队管理
  • 技术人员轮班和调度
  • 区域管理和路由
  • 非工作任命
  • 技术人员跟踪
  • GPS提供商集成
  • 调度数据的导出功能

用例：技术人员调度、路线优化、容量规划、调度操作

💰 会计服务器(servicetitan-accounting)

文件: servicetitan_accounting.py

财务管理和会计业务：

  • 应付账款贷项和付款
  • 总账账户和账户类型
  • 带有自定义字段和导出的库存账单
  • 支持调整和项目管理的发票
  • 具有完整CRUD操作的日记账条目
  • 带有存款跟踪和自定义字段的付款
  • 导出所有财务数据的提要

用例：财务管理、会计操作、发票处理、付款跟踪

⭐ 客户交互服务器(servicetitan-customer-interactions)

文件: servicetitan_customer_interactions.py

客户反馈和技术人员评级管理：

  • 技术人员评级系统（添加、更新、设置评级）
  • 针对特定工作的技术人员绩效跟踪
  • 标准评级级别（优秀、良好、一般、差、极差）
  • 为多名技术人员提供批量评级操作
  • 客户满意度跟踪

用例：绩效管理、客户满意度跟踪、技术人员评估、质量保证

🔧 设备系统服务器(servicetitan-equipment-systems)

文件: servicetitan_equipment_systems.py

安装设备生命周期管理：

  • 设备CRUD操作（创建、读取、更新、删除）
  • 保修跟踪（制造商和服务提供商）
  • 基于位置的设备管理
  • 序列号和条形码跟踪
  • 设备文件附件管理
  • 高级搜索功能（按位置、制造商、序列号）
  • 保修状态分析和到期跟踪
  • 设备更换预测和计划
  • 外部系统集成的导出功能

用例：资产管理、保修跟踪、维护计划、设备审计、更换预测

📋 表单服务器(servicetitan-forms)

文件: servicetitan_forms.py

具有工作附件功能的表单和提交管理：

  • 使用高级过滤（条件逻辑、触发器、状态）进行表单检索
  • 具有全面搜索功能的表单提交管理
  • 作业附件操作（创建、检索、下载）
  • 所有者类型筛选（作业、呼叫、客户、位置、设备等）
  • 状态跟踪（已开始、已完成、已发布、未发布）
  • 日期范围过滤和分页支持

用例：表单管理、数据收集、工作文档、合规性跟踪、提交分析

📞 JBCE 服务器servicetitan-jbce)

文件: servicetitan_jbce.py

工作预约和电话录入管理：

  • 呼叫原因管理和配置
  • 活动/非活动原因过滤
  • 线索识别跟踪
  • 创建和修改日期过滤
  • 按不同字段排序的结果

用例：呼叫中心运营、预订工作流程、潜在客户管理、原因代码维护

📢 营销服务器(servicetitan-marketing)

文件: servicetitan_marketing.py

全面的营销活动管理：

  • 活动类别管理（CRUD操作）
  • 活动成本跟踪和财务管理
  • 完整的营销活动生命周期管理
  • 电子邮件抑制列表管理以实现合规性
  • DNIS（电话号码）跟踪和归因
  • 活动分析的来源/媒介跟踪
  • 业务部门整合

用例：营销活动管理、成本跟踪、电子邮件合规性、归因跟踪、活动分析

📊 营销广告服务器(servicetitan-marketing-ads)

文件: servicetitan_marketing_ads.py

高级广告性能和归因跟踪：

  • 通过线索类型过滤进行归因线索跟踪
  • 广告宣传容量警告
  • 外部呼叫归因管理
  • 分段性能数据分析
  • 用于ROI分析的工作归因跟踪
  • 网络预订归因监控
  • 网络潜在客户表单归因跟踪

用例：广告活动绩效分析、潜在客户归因、投资回报率跟踪、容量管理、数字营销优化

🎯 营销信誉服务器(servicetitan-marketing-reputation)

文件: servicetitan_marketing_reputation.py

声誉管理和审查分析：

  • 审查平台管理和配置
  • 声誉分析和评分
  • 评审响应管理
  • 品牌监控能力
  • 情绪分析和跟踪

用例：在线声誉管理、评论监控、品牌分析、客户情绪跟踪

👤 会员服务器(servicetitan-memberships)

文件: servicetitan_memberships.py

客户会员计划管理：

  • 会员类型配置和管理
  • 会员注册和生命周期跟踪
  • 优势和定价层管理
  • 续订和计费自动化
  • 会员分析和报告

用例：会员计划管理、客户保留、经常性收入管理

💼 工资服务器(servicetitan-payroll)

文件: servicetitan_payroll.py

综合工资管理系统：

  • 工资单操作：完成工资单生命周期（获取工资单、活动代码、时间表代码）
  • 总付款项目：员工薪酬项目的CRUD操作
  • 工资调整：创建、检索和更新工资单调整
  • 工作时间表：管理技术人员的时间跟踪和基于工作的时间表
  • 员工设置：为员工和技术人员配置工资单设置
  • 出口业务：批量导出工作拆分、工资单调整、时间表、活动代码、非工作时间表、总工资项目和时间表代码
  • 时间跟踪：详细的时间管理，包括工作关联和劳动力跟踪

用例：工资处理、时间跟踪、薪酬管理、人工成本分析、时间表管理

📈 报表服务器(servicetitan-reporting)

文件: servicetitan_reporting.py

商业智能和分析平台：

  • 动态值集：检索报告的可配置值集
  • 报告类别：浏览和管理报表组织结构
  • 报表管理：通过筛选访问类别内的报告
  • 报告说明：获取详细的元数据和参数信息
  • 报告数据：执行报告并检索带分页的格式化数据
  • 自定义参数：支持动态报告参数和过滤器

用例：业务分析、绩效报告、数据可视化、高管仪表板、KPI跟踪

💰 销售与估算服务器(servicetitan-sales)

文件: servicetitan_sales.py

完整的销售和估算工作流程：

  • 估算管理：用于估算的完整CRUD操作，具有全面的过滤功能
  • 估算项目：在估算中添加、检索和删除行项目
  • 状态操作：向客户发送估算，转换为工作，标记为已售出
  • 出口业务：具有延续令牌的批量导出功能
  • 业务集成：将估算与业务部门联系起来，并跟踪转化率
  • 工作流管理：处理从创建到完成的估算生命周期

用例：销售流程管理、估算创建、报价到工作转换、销售分析、定价管理

📋 服务协议服务器(servicetitan-service-agreements)

文件: servicetitan_service_agreements.py

服务合同与协议管理：

  • 服务协议操作：检索具有完整详细信息的单个协议
  • 查询操作：按客户、位置、状态、日期进行高级筛选
  • 出口业务：批量导出，支持大型数据集的延续令牌
  • 合同管理：跟踪协议条款、定价和服务时间表

用例：服务合同管理、维护协议、定期服务跟踪、合同分析

📅 安排Pro服务器(servicetitan-scheduling-pro)

文件: servicetitan_scheduling_pro.py

高级调度优化和路由：

  • 路由器操作：管理路由会话和性能分析
  • 调度程序操作：列出调度程序、管理会话、跟踪性能指标
  • 性能分析：监控调度效率和优化结果
  • 会话管理：跟踪路由和调度会话数据
  • 日期筛选：具有全面日期范围支持的查询操作

用例：路线优化、调度分析、调度员绩效、效率跟踪

⚙️ 设置服务器(servicetitan-settings)

文件: servicetitan_settings.py

系统配置和用户管理：

  • 员工管理：完整的CRUD操作、帐户操作（激活/停用）、批量导出
  • 技术人员管理：全面的技术人员生命周期和客户管理
  • 用户角色管理：配置和分配用户权限和角色
  • 业务部门管理：利用外部数据支持管理组织结构
  • 标签类型管理：配置和组织标签系统进行分类
  • 安全操作：用户帐户控制和访问管理

用例：用户管理、组织设置、安全管理、系统配置

📋 任务管理服务器(servicetitan-task-management)

文件: servicetitan_task_management.py

全面的任务和工作流管理：

  • 参考数据：访问员工、业务部门、优先级、类型、状态和类别
  • 任务操作：创建、检索、更新具有广泛过滤功能的任务（25+个参数）
  • 子任务管理：处理分层任务结构和依赖关系
  • 丰富的任务数据：包括评论、附件、作业和进度跟踪
  • 高级过滤：按受让人、创建者、优先级、状态、日期、业务部门等搜索

用例：项目管理、工作流自动化、任务跟踪、团队协调、流程管理

📞 电信服务器(servicetitan-telecom)

文件: servicetitan_telecom.py

通信和呼叫管理系统：

  • 呼叫管理：使用v3和v2 API支持访问调用日志
  • 选择加入/选择退出管理：使用E.164格式处理客户沟通偏好
  • 媒体访问：以二进制数据检索通话记录和语音邮件
  • 大宗出口业务：使用延续令牌导出大型数据集
  • 呼叫分析：全面的呼叫过滤、代理跟踪和性能指标
  • 通信合规性：管理客户沟通偏好和规定

用例：呼叫中心运营、通信合规性、呼叫分析、代理绩效、客户偏好

⏰ 时间表服务器(servicetitan-timesheets)

文件: servicetitan_timesheets.py

时间跟踪和劳动力管理：

  • 活动管理：通过详细的工作关联跟踪时间活动
  • 活动类别：组织和管理时间跟踪类别
  • 活动类型：配置不同类型的可跟踪活动
  • 大宗出口业务：导出时间表数据以进行工资和分析
  • 丰富的活动数据：包括工作关联、劳动力管理和标签支持
  • 时间分析：具有过滤和报告功能的全面时间跟踪

用例：时间跟踪、劳动力管理、工资单整合、生产率分析、项目时间分配

设置

1.先决条件

  • Python 3.8或更高版本
  • ServiceTitan API访问凭据
  • Git（用于克隆存储库）

2.安装

  1. 克隆存储库:

    git clone https://github.com/buildwithbeacon/servicetitan-mcp.git
cd servicetitan-mcp

  2. 再进行:

    选项A：使用pip（传统）:

    pip install -r requirements.txt

    选项B：使用紫外线（推荐-更快、更可靠）:

    uv sync
# or if you don't have a pyproject.toml yet:
uv pip install -r requirements.txt

  3. 环境配置: 复制示例环境文件并配置凭据：

    cp .env.example .env

    编辑 .env 使用您的ServiceTitan凭据：

    SERVICE_TITAN_CLIENT_ID=your_client_id_here
SERVICE_TITAN_CLIENT_SECRET=your_client_secret_here
SERVICE_TITAN_APP_KEY=your_app_key_here
SERVICE_TITAN_TENANT_ID=your_tenant_id_here

3.克劳德桌面配置

  1. 复制MCP配置: 使用提供的配置模板或与现有配置合并：

    • claude_desktop_config.json -用于标准Python执行
    • claude_desktop_config_uv.json -用于紫外线执行（推荐）

  2. 配置单个服务器: 编辑您的Claude Desktop配置文件（通常在 ~/.claude/claude_desktop_config.json)包括您需要的服务器：

    选项A：直接使用python:

    {
  "mcpServers": {
    "servicetitan-core": {
      "command": "python",
      "args": ["/path/to/servicetitan-mcp/servicetitan_core.py"],
      "env": {}
    },
    "servicetitan-accounting": {
      "command": "python", 
      "args": ["/path/to/servicetitan-mcp/servicetitan_accounting.py"],
      "env": {}
    }
  }
}

    选项B：使用uv run（推荐）:

    {
  "mcpServers": {
    "servicetitan-core": {
      "command": "uv",
      "args": ["run", "python", "/path/to/servicetitan-mcp/servicetitan_core.py"],
      "env": {}
    },
    "servicetitan-accounting": {
      "command": "uv",
      "args": ["run", "python", "/path/to/servicetitan-mcp/servicetitan_accounting.py"], 
      "env": {}
    }
  }
}

4.运行单个服务器

对于测试或开发，您可以单独运行服务器：

直接使用python:

# Core functionality
python servicetitan_core.py

# Accounting operations
python servicetitan_accounting.py

# Customer interactions
python servicetitan_customer_interactions.py

# Equipment systems
python servicetitan_equipment_systems.py

# And so on for other servers...

使用紫外线运行（推荐）:

# Core functionality
uv run python servicetitan_core.py

# Accounting operations
uv run python servicetitan_accounting.py

# Customer interactions
uv run python servicetitan_customer_interactions.py

# Equipment systems
uv run python servicetitan_equipment_systems.py

# And so on for other servers...

使用模式

单一领域焦点

处理特定域任务时使用一台服务器：

  • 客户服务工作流程 → servicetitan-core
  • 目录更新 → servicetitan-pricebook
  • 采购订单处理 → servicetitan-inventory
  • 工资处理 → servicetitan-payroll
  • 时间跟踪 → servicetitan-timesheets

多域操作

对于跨越多个域的复杂工作流，请在MCP客户端中同时配置多个服务器：

  • 完成工作流程：核心+JPM+调度+时间表
  • 财务经营：会计+工资+销售
  • 客户管理：核心+客户关系管理+客户互动+营销

上下文窗口优化

每台服务器都包含专注的工具，而不是100多个工具，从而改进了：

  • AI上下文理解
  • 响应精度
  • 演出
  • 减少代币使用

综合工具参考

核心服务器工具（7个工具）

  • get_customer_by_id -检索特定客户详细信息
  • get_customers -列出具有筛选功能的客户
  • summarize_calls -基于人工智能的呼叫分析
  • get_appointments -检索预约数据
  • create_appointment -安排新的约会
  • update_appointment -修改现有约会
  • cancel_appointment -取消预约

Pricebook服务器工具（25+工具）

材料管理：

  • get_materials, create_material, update_material, delete_material
  • get_material_by_id, get_material_images, upload_material_image

服务管理：

  • get_services, create_service, update_service, delete_service
  • get_service_by_id

设备管理：

  • get_equipment, create_equipment, update_equipment, delete_equipment
  • get_equipment_by_id

类别和组织：

  • get_categories, create_category, update_category, delete_category
  • get_discounts_and_fees, create_discount_fee, update_discount_fee

库存服务器工具（20+工具）

库存管理：

  • get_inventory_adjustments, create_inventory_adjustment, update_inventory_adjustment
  • get_purchase_orders, create_purchase_order, update_purchase_order
  • get_inventory_receipts, create_inventory_receipt, update_inventory_receipt
  • get_inventory_returns, create_inventory_return, update_inventory_return
  • get_inventory_transfers, create_inventory_transfer

供应商和仓库：

  • get_vendors, create_vendor, update_vendor
  • get_warehouses, get_trucks

工资服务器工具（34个工具）

核心工资运营：

  • get_payrolls -通过过滤检索工资单信息
  • get_activity_codes -获取工资单活动代码
  • get_timesheet_codes -检索时间表代码

薪酬总额管理：

  • get_gross_pay_items, create_gross_pay_item, update_gross_pay_item, delete_gross_pay_item

工资调整：

  • get_payroll_adjustments, create_payroll_adjustment, update_payroll_adjustment

工作时间表：

  • get_job_timesheets, create_job_timesheet, update_job_timesheet, delete_job_timesheet

员工设置：

  • get_employee_payroll_settings, update_employee_payroll_settings
  • get_technician_payroll_settings, update_technician_payroll_settings

出口操作（7个工具）：

  • export_job_splits, export_payroll_adjustments, export_timesheets
  • export_activity_codes, export_non_job_timesheets, export_gross_pay_items, export_timesheet_codes

报表服务器工具（5个工具）

  • get_dynamic_value_sets -检索可配置的报告值集
  • get_report_categories -浏览报表组织结构
  • get_reports_in_category -访问特定类别中的报告
  • get_report_description -获取详细的报告元数据和参数
  • get_report_data -执行报告并检索格式化数据

销售和估算服务器工具（12个工具）

估算管理：

  • get_estimates -列出具有全面过滤功能的估计值
  • get_estimate_by_id -检索具体的估算详细信息
  • create_estimate -创建新的估计值
  • update_estimate -修改现有估算

估算项目：

  • get_estimate_items -检索估算行项目
  • add_estimate_item -在估算中添加项目
  • delete_estimate_item -从估算中删除项目

状态操作：

  • send_estimate -向客户发送估价
  • convert_estimate_to_job -将估算转换为作业
  • mark_estimate_as_sold -将估价标记为已售出

出口：

  • export_estimates -大宗出口估算
  • export_estimate_items -大宗出口估算项目

服务协议服务器工具（3个工具）

  • get_service_agreements -查询带有过滤功能的服务协议
  • get_service_agreement_by_id -检索特定协议详细信息
  • export_service_agreements -使用延续代币进行批量出口

计划Pro服务器工具（5个工具）

路由器操作：

  • get_routers -列出可用路由器
  • get_router_sessions -检索路由器会话数据
  • get_router_performance -路由器性能分析

计划程序操作：

  • get_schedulers -列出具有过滤功能的调度程序
  • get_scheduler_performance -调度器性能指标

设置服务器工具（21个工具）

员工管理：

  • get_employees, create_employee, get_employee_by_id, update_employee, delete_employee
  • activate_employee, deactivate_employee, export_employees

技术人员管理：

  • get_technicians, create_technician, get_technician_by_id, update_technician, delete_technician
  • activate_technician, deactivate_technician, export_technicians

系统配置：

  • get_user_roles, get_business_units, create_business_unit, update_business_unit
  • get_tag_types, create_tag_type

任务管理服务器工具（5个工具）

  • get_reference_data -访问员工、业务部门、优先级、类型、状态、类别
  • get_tasks -通过广泛的过滤（25+个参数）检索任务
  • get_task_by_id -获取特定任务的详细信息
  • create_task -创建新任务
  • get_subtasks -检索父任务的子任务

电信服务器工具（11个工具）

呼叫管理：

  • get_calls_v3 -使用v3 API检索调用
  • get_calls_v2 -使用v2 API检索调用（旧版）

选择加入/选择退出管理：

  • opt_in_phone_number -将电话添加到通讯列表
  • opt_out_phone_number -从通讯列表中删除电话
  • get_opt_ins -检索选择加入记录
  • get_opt_outs -检索退出记录

媒体运营：

  • get_call_recording -将通话记录下载为二进制数据
  • get_voicemail -将语音邮件下载为二进制数据

出口业务：

  • export_calls -批量导出呼叫数据
  • export_opt_ins -批量导出选择加入数据
  • export_opt_outs -批量导出选择退出数据

时间表服务器工具（10个工具）

活动管理：

  • get_activities -使用工作关联检索时间活动
  • create_activity -创建新的时间跟踪活动
  • get_activity_by_id -获取具体活动详细信息
  • update_activity -修改现有活动
  • delete_activity -删除活动

类别和类型：

  • get_activity_categories -检索活动组织
  • get_activity_types -获取可跟踪活动的类型

出口业务：

  • export_activities -批量出口活动数据
  • export_activity_categories -出口类别结构
  • export_activity_types -出口活动类型

JPM服务器工具（25+工具）

作业管理：

  • get_job_by_id, create_job, update_job, cancel_job, complete_job, hold_job

项目管理：

  • get_project_by_id, create_project, update_project, attach_job_to_project, detach_job_from_project

预约管理：

  • get_appointment_by_id, create_appointment, reschedule_appointment, hold_appointment

CRM服务器工具（20+工具）

增强的客户管理：

  • get_customers, create_customer, update_customer （具有高级过滤功能）

联系人管理：

  • get_contact_by_id, get_contacts, create_contact, update_contact, delete_contact

潜在客户管理：

  • get_lead_by_id, get_leads, create_lead, update_lead

调度服务器工具（20+工具）

预约管理：

  • get_appointment_assignments, assign_technicians_to_appointment, unassign_technicians_from_appointment

行程安排：

  • get_arrival_windows, create_arrival_window, update_arrival_window
  • get_business_hours, create_business_hours
  • get_capacity -调度优化

团队和资源管理：

  • get_teams, create_team, get_team_by_id, delete_team
  • get_technician_shifts, create_technician_shift, update_technician_shift

会计服务器工具（25+工具）

应付账款

  • get_ap_credits, mark_ap_credits_as_exported
  • get_ap_payments, mark_ap_payments_as_exported

总账：

  • get_gl_accounts, create_gl_account, update_gl_account
  • get_gl_account_types

发票：

  • get_invoices, create_adjustment_invoice, update_invoice
  • update_invoice_items, delete_invoice_item

客户交互服务器工具（10个工具）

评级系统：

  • add_or_update_technician_rating, set_technician_rating, update_technician_rating

标准评级：

  • rate_technician_excellent, rate_technician_good, rate_technician_average, rate_technician_poor, rate_technician_very_poor

设备系统服务器工具（10+工具）

设备管理：

  • get_installed_equipment, get_installed_equipment_by_id, create_installed_equipment, update_installed_equipment

高级操作：

  • search_equipment_by_location, search_equipment_by_manufacturer, get_equipment_warranty_status

表单服务器工具（5个工具）

  • get_forms -使用高级筛选检索表单
  • get_form_submissions -全面的提交搜索
  • create_job_attachment, get_job_attachments, download_job_attachment

JBCE服务器工具（1个工具）

  • get_call_reasons -呼叫原因管理和配置

营销服务器工具（15+工具）

活动管理：

  • get_campaigns, create_campaign, update_campaign
  • get_campaign_costs, create_cost, update_cost

类别和组织：

  • get_categories, create_category, update_category

顺从：

  • get_suppressions, suppress_emails, unsuppress_emails

营销广告服务器工具（7个工具）

归因追踪：

  • get_attributed_leads -线索跟踪与过滤
  • create_external_call_attribution -外部呼叫跟踪
  • create_job_attribution -工作ROI跟踪
  • create_web_booking_attribution -网络预订跟踪
  • create_web_lead_form_attribution -表格归属

性能分析：

  • get_performance -具有细分功能的性能分析
  • get_capacity_warnings -广告容量意识

API身份验证

所有服务器都使用OAuth 2.0客户端凭据流进行身份验证。使用配置的环境变量自动处理身份验证：

  • SERVICE_TITAN_CLIENT_ID -您的ServiceTitan应用程序客户端ID
  • SERVICE_TITAN_CLIENT_SECRET -您的ServiceTitan应用程序客户端机密
  • SERVICE_TITAN_APP_KEY -您的ServiceTitan应用程序密钥
  • SERVICE_TITAN_TENANT_ID -您的ServiceTitan租户ID

错误处理

所有服务器都包括全面的错误处理：

  • 身份验证错误：自动刷新令牌并重试
  • 速率限制：智能退避和重试机制
  • 网络错误：连接超时和重试逻辑
  • API错误：带有上下文的详细错误消息

性能注意事项

服务器选择策略

  • 轻型作业：使用Core服务器进行基本的客户查找
  • 复杂的工作流程：使用多个专用服务器
  • 批量操作：使用具有导出功能的服务器（会计、工资单等）

分页支持

大多数列表操作都支持分页：

  • 页面大小：可配置（通常50-500个项目）
  • 延续令牌：适用于大型数据集（尤其是导出）
  • 总数：大多数回复中都有

缓存

  • 身份验证令牌：自动缓存和刷新
  • 参考数据：考虑缓存经常访问的数据，如业务部门、员工

益处

🎯 专注功能

每台服务器都在其领域内提供深度功能，而不会分散对无关工具的注意力。

🚀 改进的性能

更小的工具集意味着更快的处理速度和更准确的AI响应。

🔄 可扩展体系结构

易于添加新域，而不会使现有服务器膨胀。

🛠️ 可维护代码

明确的关注点分离使更新和调试更简单。

💾 减少上下文使用

较小的工具集使用较少的上下文窗口，允许更复杂的对话。

故障排除

常见问题

“缺少必需的ServiceTitan环境变量”

  • 确保您的 .env 文件存在并包含所有必需的变量
  • 检查变量名是否完全匹配（区分大小写）

“运输意外关闭”

  • 验证服务器脚本运行时没有语法错误
  • 检查是否安装了所有依赖项(pip install -r requirements.txt)
  • 确保Claude Desktop配置中的路径正确

“身份验证失败”

  • 验证您的ServiceTitan API凭证是否正确
  • 检查您的ServiceTitan应用程序是否具有必要的权限
  • 确保您的租户ID正确

“找不到工具”

  • 验证您使用的服务器是否符合所需功能
  • 检查服务器是否在Claude Desktop中正确配置
  • 确保服务器已成功启动（检查日志）

调试模式

设置环境变量 DEBUG=true 要启用详细日志记录，请执行以下操作：

export DEBUG=true
python servicetitan_accounting.py
# or with uv:
uv run python servicetitan_accounting.py

支持

对于问题和疑问：

  1. 检查上面的故障排除部分
  2. 查看ServiceTitan API文档
  3. 在GitHub上打开一个问题，其中包含详细的错误消息和重现步骤

致谢

构建使用：

  • FastMCP -模型上下文协议Python SDK
  • httpx -Python的HTTP客户端
  • python dotenv -环境变量管理
  • ServiceTitan API v2-现场服务管理平台

相关 MCP