Autotask MCP 服务器

Kaseya 的 Autotask PSA 的一个模型上下文协议 (MCP) 服务器，它通过像 Claude 这样的 AI 助手实现对您的 Autotask 数据的自然语言查询。

功能

• 查询客户信息（合同、收入）
  • 活跃合同分析
  • 按合同类型划分的收入
  • 合同状态分布
• 分析支持代理活动和预约
  • 最近的预约安排
  • 时间条目分析
  • 资源利用率指标
  • 工作类型分布
• 跟踪项目状态和进度
  • 项目状态概览
  • 任务完成指标
  • 优先级分布
• 支持工单分析
  • 工单状态分布
  • 解决时间指标
  • 队列性能
• 具有高级功能的自然语言查询界面：
  • 日期范围解析（例如，“本周”，“上个月”）
  • 状态过滤（例如，“未解决工单”，“已解决工单”）
  • 队列和类别过滤
  • 优先级过滤
  • 结果排序和限制

前提条件

• Node.js（v16 或更高版本）
• Autotask API 凭证（用户名、密钥、集成代码）
• 访问 Autotask REST API 端点

设置

1. 克隆仓库

   git clone https://github.com/yourusername/autotask-mcp.git
   cd autotask-mcp
   

2. 安装依赖项：

   npm install
   

3. 将 .env.example 复制为 .env 并填写您的 Autotask API 凭证：

   cp .env.example .env
   

   使用您的凭证编辑 .env 文件：

   AUTOTASK_USER=your_autotask_username
   AUTOTASK_SECRET=your_autotask_secret
   AUTOTASK_INTEGRATION_CODE=your_integration_code
   

4. 如果您的 Autotask 实例使用不同的端点，请在 src/mcp-server.js 中配置 API 端点：

   autotask = new AutotaskRestApi(
     process.env.AUTOTASK_USER,
     process.env.AUTOTASK_SECRET,
     process.env.AUTOTASK_INTEGRATION_CODE,
     'https://webservices14.autotask.net/atservicesrest' // 如需更改，请修改此处
   );
   

5. 启动服务器：

   node src/mcp-server.js
   

连接到 AI 助手

此 MCP 服务器设计用于与支持模型上下文协议的 AI 助手配合使用。要连接：

1. 如上所述启动服务器
2. 在您的 AI 助手界面中，配置连接以指向正在运行的 MCP 服务器
3. 连接后，您可以开始使用自然语言查询您的 Autotask 数据

示例查询

合同和收入分析

• “我们的总合同收入是多少？”
• “按类型显示活跃合同”
• “合同状态的分布情况如何？”

支持代理分析

• “显示本周所有支持代理的预约”
• “每个资源花费的时间是多少？”
• “显示时间条目的工作类型分布”

项目分析

• “我们活跃项目的状况如何？”
• “显示任务完成指标”
• “项目的优先级分布情况如何？”

工单分析

• "显示工单状态分布"
• "我们的平均工单解决时间是多少？"
• "按队列显示工单"
• "显示本周创建的高优先级工单"
• "显示支持队列中最旧的10个工单"

时间条目分析

• "显示上周的时间条目"
• "获取过去7天内按客户/合同记录的小时数"
• "显示工单12345的可计费时间条目"
• "显示John昨天的时间条目"

故障排除

常见问题

1. 连接错误

   • 验证.env文件中的Autotask API凭据
   • 检查您的API端点是否正确
   • 确保您的IP地址在Autotask API设置中被列入白名单

2. 权限问题

   • API用户必须在Autotask中有适当的权限
   • 检查集成代码是否有访问被查询实体的权限

3. 响应格式问题

   • 服务器包含详细的日志以帮助诊断API响应格式问题
   • 查看控制台输出以获取调试信息

调试

服务器会将详细日志输出到控制台。要将这些日志捕获到文件中：

node src/mcp-server.js 2> server.log

部署选项

作为服务运行

要将MCP服务器作为后台服务运行，您可以使用以下工具：

• PM2（推荐用于Linux/macOS/Windows）:

  npm install -g pm2
  pm2 start src/mcp-server.js --name "autotask-mcp"
  pm2 save
  

• systemd（Linux）:
  在/etc/systemd/system/autotask-mcp.service创建一个服务文件

  [Unit]
  Description=Autotask MCP Server
  After=network.target
  
  [Service]
  Type=simple
  User=yourusername
  WorkingDirectory=/path/to/autotask-mcp
  ExecStart=/usr/bin/node /path/to/autotask-mcp/src/mcp-server.js
  Restart=on-failure
  
  [Install]
  WantedBy=multi-user.target
  

  然后启用并启动该服务：

  sudo systemctl enable autotask-mcp
  sudo systemctl start autotask-mcp
  

Docker部署

提供了一个Dockerfile用于容器化部署：

docker build -t autotask-mcp .
docker run -d -p 3000:3000 --env-file .env --name autotask-mcp autotask-mcp

安全考虑

• 安全存储API凭据，切勿将其提交到版本控制系统
• 在生产环境中考虑使用环境变量或秘密管理器
• 如果将服务器暴露于本地网络之外，请实施适当的访问控制
• 审查并限制Autotask API用户的权限，仅授予必要的权限

贡献

我们欢迎对Autotask MCP服务器做出贡献！以下是您如何贡献的方法：

1. Fork 仓库

   • 点击仓库页面右上角的“Fork”按钮

2. 克隆你的 Fork

   git clone https://github.com/your-username/autotask-mcp.git
   cd autotask-mcp
   

3. 为你的更改创建一个分支

   git checkout -b feature/your-feature-name
   

4. 进行你的更改

   • 实现你的功能或修复 bug
   • 根据需要添加或更新测试
   • 运行测试和代码检查以确保你的更改通过

     npm test
     npm run lint
     

5. 提交你的更改

   git commit -m "Add your descriptive commit message"
   

6. 推送到你的 Fork

   git push origin feature/your-feature-name
   

7. 创建 Pull Request

   • 前往原始仓库
   • 点击“New Pull Request”
   • 选择“compare across forks”
   • 选择你的 Fork 和分支
   • 填写 PR 模板，提供关于你更改的详细信息

所有 pull requests 将由维护者审核。CI 流水线将自动运行测试和代码检查。

有关贡献的更多详细信息，请参阅 CONTRIBUTING.md。

许可证

此项目根据 MIT 许可证发布 - 请参阅 LICENSE 文件获取详情。