MCP Server Everhour

EverHour MCP服务器

用于EverHour时间跟踪和项目管理集成的模型上下文协议（MCP）服务器。该服务器使人工智能助手能够与EverHour的API交互，以实现全面的时间跟踪、项目管理、任务管理、费用跟踪和报告功能。

特性

🕐 时间跟踪

• 定时器管理：启动、停止和监视活动计时器
• 时间记录：创建、更新、删除和列出时间条目
• 时间报告：按项目、用户或日期范围生成详细的时间报告

📋 项目管理

• CRUD项目：创建、读取、更新和删除项目
• 项目结构：管理节、标签和项目组织
• 预算跟踪：制定和监控项目预算（时间和资金）
• 计费配置：配置小时费率和计费类型

✅ 任务管理

• 任务操作：任务的完整CRUD操作
• 任务组织：将任务分配给项目、部门和用户
• 任务估算：设置和跟踪时间估计
• 任务状态：管理打开/关闭状态和进度

👥 用户和团队管理

• 用户配置文件：访问用户信息和权限
• 团队组织：创建和管理团队
• 角色管理：处理管理员、主管和成员角色

💰 客户与费用管理

• 客户管理：创建和管理客户信息
• 费用跟踪：记录和分类业务费用
• 发票集成：为发票工作流程准备数据

📊 报告和分析

• 时间总结：生成全面的时间跟踪报告
• 项目报告：详细的项目绩效分析
• 用户报告：个人生产力和时间分配报告
• 自定义筛选：按日期、项目、用户或任务筛选报告

安装

1. 克隆并导航到目录:

   git clone 
   cd mcp-everhour

1. 安装依赖项:

   npm install

1. 获取EverHour API密钥:

- 首选 每小时设置 - 导航到“设置”→ API - 生成新的API密钥 - 复制API密钥进行配置

1. 验证API密钥 （可选但推荐）：

   npm run auth "your_api_key_here"

配置

环境变量

创建一个 .env 项目根目录中的文件：

# EverHour Configuration
EVERHOUR_API_KEY=your_everhour_api_key_here

# Server Configuration (optional)
PORT=6791

替代配置

您还可以在MCP初始化期间提供API密钥，而不是使用环境变量。

用法

开发模式

在开发模式下启动EverHour MCP服务器：

npm run dev

服务器将在上运行 http://localhost:6791/mcp/everhour/

生产模式

1. 构建项目:

   npm run build

1. 启动服务器:

   npm run start

测试服务器

测试服务器并验证可用工具：

# Start the server in one terminal
npm run dev

# Test the server in another terminal
npm run test:server

MCP客户端配置

将EverHour MCP服务器添加到MCP客户端配置中：

{
  "mcpServers": {
    "everhour": {
      "command": "npx",
      "args": ["ts-node", "src/index.ts"],
      "cwd": "/path/to/mcp-everhour",
      "env": {
        "EVERHOUR_API_KEY": "your_api_key_here"
      }
    }
  }
}

可用工具（共38个）

认证

• set_api_key -设置EverHour API密钥进行身份验证

用户管理

• get_me -获取当前用户配置文件信息
• list_users -列出工作区中的所有用户
• get_user -按ID获取特定用户详细信息

项目管理

• list_projects -列出所有具有筛选选项的项目
• get_project -获取具体项目详细信息
• create_project -创建新项目
• update_project -更新现有项目
• delete_project -删除项目

任务管理

• list_tasks -列出具有全面过滤功能的任务
• get_task -获取特定任务的详细信息
• create_task -创建新任务
• update_task -更新现有任务
• delete_task -删除任务

时间跟踪

• list_time_records -列出带有日期和项目筛选器的时间记录
• get_time_record -获取特定时间记录详细信息
• create_time_record -创建新的时间条目
• update_time_record -更新现有时间记录
• delete_time_record -删除时间记录

定时器管理

• get_running_timer -获取当前正在运行的计时器
• start_timer -为特定任务启动计时器
• stop_timer -停止当前正在运行的计时器

客户管理

• list_clients -列出所有客户
• get_client -获取特定客户详细信息
• create_client -创建新客户端
• update_client -更新现有客户端
• delete_client -删除客户端

费用管理

• list_expenses -列出带有过滤功能的费用
• create_expense -创建新的支出记录

报告和分析

• get_project_report -获取详细的项目时间报告
• get_user_report -获取详细的用户时间报告
• get_time_summary -通过分组获取时间跟踪摘要

项目结构

• list_sections -列出项目的各个部分
• create_section -在项目中创建新部分
• list_labels -列出项目标签
• create_label -创建新标签

团队管理

• list_teams -列出工作区中的所有团队
• create_team -创建新团队

示例用法

测试服务器

使用测试脚本验证服务器是否正常工作：

npm run test:server

这将：

• 进行健康检查
• 使用API密钥初始化
• 列出所有可用工具
• 测试一些基本的API调用

启动计时器

{
  "tool": "start_timer",
  "arguments": {
    "task": "task_id_here",
    "comment": "Working on feature implementation"
  }
}

创建时间记录

{
  "tool": "create_time_record",
  "arguments": {
    "task": "task_id_here",
    "time": 7200,
    "date": "2024-01-15",
    "comment": "Code review and testing"
  }
}

列出项目

{
  "tool": "list_projects",
  "arguments": {
    "status": "active",
    "limit": 50
  }
}

创建项目

{
  "tool": "create_project",
  "arguments": {
    "name": "Website Redesign",
    "client": "client_id_here",
    "type": "board",
    "billing": {
      "type": "project_hourly",
      "rate": 75
    },
    "budget": {
      "type": "time",
      "budget": 144000
    }
  }
}

api参考

认证

EverHour MCP服务器使用API密钥验证。API密钥可以通过两种方式提供：

1. 环境变量：设置 EVERHOUR_API_KEY 在您的环境中
2. MCP初始化：提供 api_key MCP初始化期间的参数

错误处理

服务器提供详细的错误消息和代码：

• AUTH_ERROR -身份验证失败或未提供API密钥
• INVALID_PARAMS -所需参数缺失或无效
• HTTP_XXX -EverHour API的HTTP状态代码错误
• NETWORK_ERROR -网络连接问题

速率限制

服务器遵守EverHour的API速率限制。如果遇到速率限制，服务器将返回相应的错误消息。

故障排除

常见问题

1. 身份验证错误

- 验证您的API密钥是否正确 - 检查API密钥是否具有足够的权限 - 确保您正在使用有效的活动API密钥

1. 网络错误

- 检查您的互联网连接 - 验证EverHour的服务状态 - 检查防火墙或代理问题

1. 权限错误

- 确保您的API密钥具有必要的权限 - 请联系您的EverHour管理员以获取访问权限

调试

通过设置启用调试日志记录 DEBUG 环境变量：

DEBUG=everhour:* npm run dev

测试API密钥

使用auth-helper验证您的API密钥：

npm run auth "your_api_key_here"

这将测试您的API密钥并显示可用权限和可访问数据。

可用的NPM脚本

• npm run dev -以开发模式启动服务器
• npm run build -构建TypeScript项目
• npm run start -启动内置服务器
• npm run auth "api_key" -测试并验证API密钥
• npm run test:server -测试正在运行的服务器并列出工具

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

MIT许可证。有关详细信息，请参阅LICENSE文件。

支持

对于问题和疑问：

1. 检查 EverHour API文档
2. 查看上面的故障排除部分
3. 在此存储库中打开问题

更新日志

v1.0.0

• 首次发布，全面覆盖EverHour API
• 项目、任务、时间记录的完整CRUD操作
• 定时器管理和时间跟踪
• 费用跟踪和客户管理
• 报告和分析工具
• 团队和用户管理功能