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 部分。

🛠️ 可用工具

🎯 可用提示

MoCo MCP 服務器提供 8 個智能提示，可協調多個工具以提供全面的見解：

提示示例

每週時間報告：

{
  "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 問題