moco-mcp

🚀 📊 MOCO MCP Server

MOCO MCP Server 是一个模型上下文协议（MCP）服务器，它为员工提供对 MOCO API 的只读访问权限，可用于时间跟踪、项目管理、假期跟踪和考勤监控等功能。

🚀 快速开始

npx -y @niondigital/moco-mcp

就这么简单！服务器将启动并准备好与你的 MCP 客户端连接。

✨ 主要特性

• ✅ 只读访问：安全的 API 集成，不会修改数据。
• 🔄 自动分页：无缝处理大型数据集。
• 📊 智能聚合：按日期、项目和任务自动汇总数据。
• 🎯 项目过滤：按特定项目过滤活动。
• 🧩 综合工具：提供 7 种专门工具，适用于不同用例。
• 🎯 智能提示：8 个由人工智能驱动的提示，用于复杂分析和洞察。
• 🌐 多客户端支持：可与所有主要的 MCP 客户端配合使用。

📦 安装指南

前提条件

• Node.js ≥ 18.0.0
• 具有 API 访问权限的 MOCO 账户
• MOCO API 密钥和子域名

MCP 客户端集成

{
  "mcpServers": {
    "moco": {
      "command": "npx",
      "args": ["-y", "@niondigital/moco-mcp"],
      "env": {
        "MOCO_API_KEY": "your-moco-api-key",
        "MOCO_SUBDOMAIN": "your-subdomain"
      }
    }
  }
}

{
  "mcpServers": {
    "moco": {
      "command": "npx",
      "args": ["-y", "@niondigital/moco-mcp"],
      "env": {
        "MOCO_API_KEY": "your-moco-api-key",
        "MOCO_SUBDOMAIN": "your-subdomain"
      }
    }
  }
}

{
   "mcpServers": {
      "moco": {
         "command": "npx",
         "args": ["-y", "@niondigital/moco-mcp"],
         "env": {
            "MOCO_API_KEY": "your-moco-api-key",
            "MOCO_SUBDOMAIN": "your-subdomain"
         }
      }
   }
}

claude mcp add -e MOCO_API_KEY="your-moco-api-key" -e MOCO_SUBDOMAIN="your-subdomain" moco -- npx -y @niondigital/moco-mcp

{
   "mcpServers": {
      "moco": {
         "command": "npx",
         "args": ["-y", "@niondigital/moco-mcp"],
         "env": {
            "MOCO_API_KEY": "your-moco-api-key",
            "MOCO_SUBDOMAIN": "your-subdomain"
         }
      }
   }
}

{
  "mcpServers": {
    "moco": {
    "command": "npx",
    "args": [
      "-y",
      "@niondigital/moco-mcp"
    ],
    "env": {
       "MOCO_API_KEY": "your-moco-api-key",
       "MOCO_SUBDOMAIN": "your-subdomain"
    },
    "disabled": false,
    "autoApprove": []
    }
  }
}

{
  "mcpServers": {
    "moco": {
      "command": "npx",
      "args": ["-y", "@niondigital/moco-mcp"],
       "env": {
          "MOCO_API_KEY": "your-moco-api-key",
          "MOCO_SUBDOMAIN": "your-subdomain"
       }
    }
  }
}

🔑 MOCO API 设置

获取 API 凭证

1. 登录你的 MOCO 账户
2. 导航到 API 设置：
   • 转到 个人资料 → 集成
   • 或者访问：https://niondigital.mocoapp.com/profile/integrations
3. 复制列出的 API 密钥
4. 记录你的子域名：
   • 从你的 MOCO URL：https://yourcompany.mocoapp.com
   • 你的子域名是：yourcompany

环境变量

你可以通过多种方式设置环境变量：

选项 1：系统环境变量

export MOCO_API_KEY="your-moco-api-key"
export MOCO_SUBDOMAIN="your-subdomain"

选项 2：.env 文件（用于本地开发）

MOCO_API_KEY=your-moco-api-key
MOCO_SUBDOMAIN=your-subdomain

选项 3：MCP 客户端配置（推荐） 使用上述 MCP 客户端配置中的 env 部分。

🛠️ 可用工具

| 属性 | 详情 | |------|------| | 工具 | 描述 | | get_activities | 获取指定日期范围内的活动，并进行汇总，可选择按项目过滤 | | get_user_projects | 列出所有分配的项目或按查询条件搜索 | | get_user_project_tasks | 获取特定分配项目的所有任务 | | get_user_holidays | 获取一年的假期概述并进行计算 | | get_user_presences | 获取指定日期范围内的考勤数据，并进行每日汇总 | | get_user_sick_days | 获取一年的病假概述并进行计算 | | get_public_holidays | 获取一年的公共假期，并计算工作日 |

| 工具 | 描述 | 参数 | |------|-------------|------------| | get_activities | 获取指定日期范围内的活动，并进行汇总，可选择按项目过滤 | startDate, endDate (ISO 8601), projectId (可选) | | get_user_projects | 列出所有分配的项目或按查询条件搜索 | query (可选) | | get_user_project_tasks | 获取特定分配项目的所有任务 | projectId | | get_user_holidays | 获取一年的假期概述并进行计算 | year | | get_user_presences | 获取指定日期范围内的考勤数据，并进行每日汇总 | startDate, endDate (ISO 8601) | | get_user_sick_days | 获取一年的病假概述并进行计算 | year | | get_public_holidays | 获取一年的公共假期，并计算工作日 | year |

🎯 可用提示

MoCo MCP 服务器提供 8 个智能提示，可协调多个工具以提供全面的见解：

| 提示 | 描述 | 关键参数 | |--------|-------------|----------------| | weekly_time_report | 生成详细的每周时间跟踪报告，并按项目细分 | week_start, include_billable_analysis | | vacation_planning_assistant | 通过分析可用假期和节假日来协助假期规划 | planned_start_date, planned_end_date | | personal_productivity_insights | 分析工作习惯并提供生产力建议 | analysis_period, focus_area | | monthly_business_review | 创建包含趋势和指标的全面业务审查报告 | month, year, include_comparisons | | smart_work_life_balance_advisor | 评估工作与生活平衡，并提供个性化建议 | analysis_weeks, target_hours_per_week | | project_time_analysis | 对项目时间进行详细分析，并提供效率指标 | project_ids, time_period | | team_capacity_overview | 通过分析缺勤情况和资源进行团队容量规划 | planning_horizon, include_holidays | | work_hours_compliance_check | 检查工作时间是否符合规定 | check_period, max_weekly_hours, max_daily_hours |

提示示例

每周时间报告：

{
  "name": "weekly_time_report",
  "arguments": {
    "week_start": "2024-01-15",
    "include_billable_analysis": true
  }
}

假期规划助手：

{
  "name": "vacation_planning_assistant",
  "arguments": {
    "planned_start_date": "2024-07-15",
    "planned_end_date": "2024-07-29"
  }
}

个人生产力洞察：

{
  "name": "personal_productivity_insights",
  "arguments": {
    "analysis_period": "last_month",
    "focus_area": "project_X"
  }
}

合规性检查：

{
  "name": "work_hours_compliance_check",
  "arguments": {
    "check_period": "last_month",
    "max_weekly_hours": 48,
    "max_daily_hours": 10
  }
}

💻 使用示例

基础用法

获取活动

# 过滤指定日期范围内的所有活动
{
  "name": "get_activities",
  "arguments": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }
}

# 过滤特定项目的活动
{
  "name": "get_activities",
  "arguments": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "projectId": 123456
  }
}

示例输出：

2024 年 1 月 1 日至 2024 年 1 月 31 日的活动：

2024-01-15：
  项目 123（网站重新设计）：
    任务 456（前端开发）：4.5 小时（4:30）
    任务 789（后端 API）：3.25 小时（3:15）
    项目总计：7.75 小时（7:45）
  每日总计：7.75 小时（7:45）

总计：7.75 小时（7:45）

获取用户项目

# 列出所有分配的项目
{
  "name": "get_user_projects",
  "arguments": {}
}

# 搜索项目
{
  "name": "get_user_projects",
  "arguments": {
    "query": "website"
  }
}

获取用户项目任务

{
  "name": "get_user_project_tasks",
  "arguments": {
    "projectId": 123456
  }
}

获取用户假期

{
  "name": "get_user_holidays",
  "arguments": {
    "year": 2024
  }
}

示例输出：

2024 年的假期概述：

已使用的假期天数：
- 2024-03-15：1.0 天
- 2024-04-22：0.5 天
- 2024-07-08：1.0 天

总结：
- 已使用的假期：2.5 天
- 年度假期额度：25 天
- 利用率：10%（2.5/25）
- 剩余假期：22.5 天

获取用户考勤

{
  "name": "get_user_presences",
  "arguments": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-07"
  }
}

示例输出：

2024 年 1 月 1 日至 2024 年 1 月 7 日的考勤：

每日考勤：
- 2024-01-01：8.25 小时（8:15）
- 2024-01-02：7.5 小时（7:30）
- 2024-01-03：8.0 小时（8:00）

总计：23.75 小时（23:45）

统计信息：
- 工作日：3 天
- 平均每天：7.92 小时（7:55）

获取用户病假

{
  "name": "get_user_sick_days",
  "arguments": {
    "year": 2024
  }
}

获取公共假期

{
  "name": "get_public_holidays",
  "arguments": {
    "year": 2024
  }
}

示例输出：

2024 年的公共假期：

假期日期：
- 2024-01-01：元旦
- 2024-04-01：耶稣受难日
- 2024-04-03：复活节星期一
- 2024-05-01：劳动节
- 2024-05-09：升天节
- 2024-05-20：圣灵降临节星期一
- 2024-10-03：德国统一日
- 2024-12-25：圣诞节
- 2024-12-26：节礼日

总结：
- 公共假期总数：9 天
- 大约工作日：251 天

🔧 高级配置

git clone https://github.com/niondigital/moco-mcp.git
cd moco-mcp
npm install
npm run build
npm start

{
  "mcpServers": {
    "moco": {
      "command": "node",
      "args": ["/path/to/moco-mcp/dist/index.js"],
      "env": {
        "MOCO_API_KEY": "your-moco-api-key",
        "MOCO_SUBDOMAIN": "your-subdomain"
      }
    }
  }
}

FROM node:18-alpine
WORKDIR /app
RUN npm install -g @niondigital/moco-mcp
ENV MOCO_API_KEY=""
ENV MOCO_SUBDOMAIN=""
CMD ["@niondigital/moco-mcp"]

🔍 故障排除

常见问题

❌ 认证错误：

API 认证失败。请检查 MOCO_API_KEY。

• 验证你的 API 密钥是否正确，并具有必要的权限
• 检查 API 密钥是否在环境变量中正确设置
• 确保密钥未过期

❌ 子域名错误：

MOCO_SUBDOMAIN 应仅包含子域名部分

• 仅使用子域名部分：company（而不是 company.mocoapp.com）
• 从子域名中移除 https:// 和 .mocoapp.com

❌ Node.js 版本错误：

此软件包需要 Node.js >= 18.0.0

• 将 Node.js 更新到 18 或更高版本
• 检查你的版本：node --version

❌ npx 连接问题：

错误：找不到模块 '@niondigital/moco-mcp'

• 确保你有互联网连接
• 尝试：npx --yes @niondigital/moco-mcp
• 清除 npx 缓存：npx clear-npx-cache

❌ MCP 客户端找不到工具：

• 在配置更改后重启你的 MCP 客户端
• 检查环境变量是否正确设置
• 验证 JSON 配置语法是否正确

调试模式

如需调试，你可以使用额外的日志运行服务器：

NODE_ENV=development npx -y @niondigital/moco-mcp

测试连接

你可以手动测试服务器：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npx -y @niondigital/moco-mcp

🤝 贡献

1. 分叉仓库
2. 创建一个功能分支：git checkout -b feature-name
3. 进行更改并添加测试
4. 运行测试：npm test
5. 提交拉取请求

📄 许可证

本项目采用 MIT 许可证，请参阅 LICENSE 文件以获取详细信息。

🆘 支持

• MOCO API 问题：MOCO API 文档
• MCP 协议：MCP 文档
• 本软件包：GitHub 问题