Hajjefy MCP Server

哈吉菲MCP服务器

一个模型上下文协议（MCP）服务器，为Claude提供对Hajjefy时间跟踪分析和见解的访问。

特性

• 时间跟踪摘要：全面了解跨项目所花费的时间
• 用户分析：分析个人用户绩效和生产力
• 团队概述：查看整个团队的绩效指标和排名
• 计费分析：跟踪计费与非计费小时数和收入洞察
• 客户分析：通过Salesforce CRM集成、项目细分、团队分配和全面的客户洞察，深入了解客户特定的指标
• 产能分析：团队工作量分布和利用率
• 每日工作时间细分：具有趋势和模式的综合日常活动
• TAM见解 ⭐ 新：确定战略客户技术客户管理工作的最佳资源
• 同步状态：数据新鲜度和同步信息
• 数据导出：以JSON或CSV格式导出时间跟踪数据

快速安装（推荐）

自动设置脚本

安装Hajjefy MCP服务器的最简单方法：

# Clone the repository
git clone https://github.com/nhajje/hajjefy-mcp-server.git
cd hajjefy-mcp-server

# Run the installation script
./install.sh

脚本将：

1. ✅ 安装依赖项
2. ✅ 构建TypeScript项目
3. ✅ 创建 .env 模板文件
4. ✅ 使用正确的路径生成Claude Desktop配置
5. ✅ 测试服务器安装

手动安装

如果您更喜欢手动安装：

1.克隆和构建

git clone https://github.com/nhajje/hajjefy-mcp-server.git
cd hajjefy-mcp-server
npm install
npm run build

2.获取您的朝觐API代币

1. 登录您的 哈吉菲仪表板
2. 转到“设置”（需要管理员权限）
3. 导航到“API令牌”部分
4. 点击“创建新令牌”
5. 命名为“克劳德桌面MCP”
6. 复制生成的令牌（以开头 hjf_live_...)

3.配置环境变量

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

cp .env.example .env

编辑 .env 并添加您的令牌：

HAJJEFY_API_TOKEN=hjf_live_your_token_here
HAJJEFY_BASE_URL=https://hajjefy.com

4.配置克劳德桌面

编辑您的Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

⚠️ 重要：使用 完全绝对路径 到构建的文件：

{
  "mcpServers": {
    "hajjefy": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/hajjefy-mcp-server/dist/index.js"
      ],
      "env": {
        "HAJJEFY_API_TOKEN": "hjf_live_your_token_here",
        "HAJJEFY_BASE_URL": "https://hajjefy.com"
      }
    }
  }
}

macOS路径示例:

"/Users/yourname/hajjefy-mcp-server/dist/index.js"

Windows路径示例:

"C:\\Users\\yourname\\hajjefy-mcp-server\\dist\\index.js"

Linux路径示例:

"/home/yourname/hajjefy-mcp-server/dist/index.js"

5.测试安装

重新启动Claude Desktop之前，请测试服务器：

# From the hajjefy-mcp-server directory
node dist/index.js

如果启动时没有错误（等待输入），请按 Ctrl+C 然后继续。

6.重新启动克劳德桌面

完全退出并重新启动Claude Desktop以加载新的MCP服务器。

用法

配置后，您可以向Claude询问有关时间跟踪数据的问题：

• *“显示本周的时间跟踪摘要”*
• *“本月按小时计算，我们的首要项目是什么？”*
• *“将过去30天的数据导出为CSV”*
• *“与上个月相比，我们的团队表现如何？”*
• *“显示计费与非计费小时细分”*
• *“哪些资源最适合TAM在战略客户方面的工作？”*
• *“确定我的顶级TAM资源及其专业水平”*
• *“为Ahold Delhaize客户获取TAM见解”*

可用工具

get_time_summary

获取指定时间段的全面时间跟踪概述。

参数：

• days （可选）：要分析的天数（1-365，默认值：30）
• from_date （可选）：YYYY-MM-DD格式的开始日期
• to_date （可选）：YYYY-MM-DD格式的结束日期

get_user_analytics

获取特定用户的详细分析。

参数：

• username （必填）：要分析的用户名
• days （可选）：要分析的天数（1-365，默认值：30）

get_team_overview

获取团队绩效概览和排名。

参数：

• days （可选）：要分析的天数（1-365，默认值：30）

get_billable_analysis

获取计费小时数分析和收入见解。

参数：

• days （可选）：要分析的天数（1-365，默认值：30）
• from_date （可选）：YYYY-MM-DD格式的开始日期
• to_date （可选）：YYYY-MM-DD格式的结束日期

export_data

以各种格式导出时间跟踪数据。

参数：

• format （可选）：导出格式-“json”或“csv”（默认：“json”）
• days （可选）：导出天数（1-365，默认值：30）
• include_details （可选）：包括详细的工作日志条目（默认值：false）

get_tam_insights ⭐ 新

获取TAM（技术客户管理）见解，以确定哪些资源最适合TAM在战略客户方面的工作。分析交叉收费时间、用户绩效、专业知识水平，并为资源分配提供战略建议。

参数：

• days （可选）：要分析的天数（1-365，默认值：90）
• from_date （可选）：YYYY-MM-DD格式的开始日期
• to_date （可选）：YYYY-MM-DD格式的结束日期
• customer （可选）：按特定客户/帐户筛选
• min_hours （可选）：包括用户的最低TAM小时阈值（默认值：5）

它提供了什么：

• TAM活动概述：交叉收费总小时数和资源明细
• 战略客户的最佳资源：具有专业知识水平和建议的前5名资源
• 按角色划分的TAM覆盖范围：CSM、技术和销售TAM活动分析
• 专业知识分解：将用户分为专家（≥40小时）、经验丰富（20-40小时）或发展中（\60%置信阈值）
• 5分钟智能缓存，最大限度地减少API调用
• 修复了axios拦截器，以保留错误响应，以便正确处理404

示例提示：

• *“使用Salesforce详细信息向我展示DHL的客户分析”*
• *“分析NYCHA客户，包括CRM信息”*
• *“通过Salesforce集成获得全面的Centene客户分析”*
• *“导出亚马逊AWS Connect的客户分析PDF”*

Salesforce配置： 需要Tempo主仪表板中的环境变量：

• SALESFORCE_USERNAME：Salesforce用户名
• SALESFORCE_PASSWORD：Salesforce密码
• SALESFORCE_SECURITY_TOKEN：Salesforce安全令牌
• SALESFORCE_LOGIN_URL：登录URL（默认值：https://login.salesforce.com)

环境变量

• HAJJEFY_API_TOKEN （必需）：您的朝觐API代币
• HAJJEFY_BASE_URL （可选）：朝觐基本URL（默认值：“https://hajjefy.com")

故障排除

常见安装问题

❌ “服务器传输意外关闭”

原因：生成文件的路径错误或缺少环境变量。

解决方案:

1. 验证配置中的路径指向 dist/index.js （不是 build/index.js)
2. 使用 绝对路径 喜欢 /Users/yourname/hajjefy-mcp-server/dist/index.js
3. 检查一下 .env 文件存在且有效 HAJJEFY_API_TOKEN

❌ “生成hajjefy mcp服务器ENOENT”

原因：全局命令未安装或未在PATH中。

解决方案：请改用绝对路径方法：

{
  "command": "node",
  "args": ["/ABSOLUTE/PATH/TO/hajjefy-mcp-server/dist/index.js"]
}

❌ “需要HAJJEFY_API_TOKEN环境变量”

原因：缺少或不正确的环境变量配置。

解决方案:

1. 创建 .env 项目根目录中的文件
2. 添加： HAJJEFY_API_TOKEN=hjf_live_your_token_here
3. 或者将令牌添加到Claude Desktop配置中 env 章节

❌ 未找到构建目录

原因：项目未构建或构建到错误的目录。

解决方案:

cd hajjefy-mcp-server
npm run build
ls dist/  # Should show index.js

身份验证问题

• 验证您的 HAJJEFY_API_TOKEN 正确且未过期
• 确保令牌具有所需的作用域(tempo:read, analytics:read)
• 检查您的令牌是否以开头 hjf_live_

连接问题

• 验证 HAJJEFY_BASE_URL 正确（默认值：“https://hajjefy.com")
• 检查您的互联网连接
• 确保朝觐服务正常运行

权限问题

• 确保您的API令牌具有必要的权限
• 如果您需要其他访问权限，请联系您的Hajjefy管理员

Claude桌面问题

• 始终完全退出并重新启动 克劳德桌面（不仅仅是关闭窗口）
• 查看克劳德桌面日志：

- macOS： ~/Library/Logs/Claude/ - 窗户： %APPDATA%/Claude/logs/

• 验证JSON配置语法是否正确（没有尾随逗号！）
• 确保 mcpServers 物体形状正确

手动测试服务器

要在配置Claude Desktop之前验证服务器是否正常工作，请执行以下操作：

cd hajjefy-mcp-server
source .env  # Load environment variables
node dist/index.js

如果它等待输入没有错误，则服务器正在工作！按 Ctrl+C 退出。

发展

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run built version
npm run start

支持

关于以下问题：

• MCP服务器：在此存储库上打开一个问题
• 哈吉菲平台：联系Hajjefy支持
• 克劳德桌面版：查看Anthropic的Claude Desktop文档

许可证

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