MOCO agency and project management platform

📊 MOCO MCP Server

勤怠時間の記録、プロジェクト管理、休暇の追跡、出勤状況の確認に使える、MOCO API への従業員向け読み取りアクセスを提供する Model Context Protocol（MCP）サーバーです。

⚡ クイックスタート

npx -y @niondigital/moco-mcp

これで完了です！サーバーが起動し、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 設定に移動します。
   • Profile → Integrations に移動します
   • または、次の URL にアクセスします。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": "smart_work_life_balance_advisor",
  "arguments": {
    "analysis_weeks": 6,
    "target_hours_per_week": 40
  }
}

コンプライアンス確認：

{
  "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
  }
}

出力例：

Activities from 2024-01-01 to 2024-01-31:

2024-01-15:
  Project 123 (Website Redesign):
    Task 456 (Frontend Development): 4.5h (4:30)
    Task 789 (Backend API): 3.25h (3:15)
    Project total: 7.75h (7:45)
  Daily total: 7.75h (7:45)

Grand total: 7.75h (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
  }
}

出力例：

Holiday overview for 2024:

Taken holiday days:
- 2024-03-15: 1.0 day
- 2024-04-22: 0.5 day
- 2024-07-08: 1.0 day

Summary:
- Taken vacation: 2.5 days
- Annual entitlement: 25 days
- Utilization: 10% (2.5/25)
- Remaining vacation: 22.5 days

ユーザーの勤務状況を取得

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

出力例：

Presences from 2024-01-01 to 2024-01-07:

Daily presences:
- 2024-01-01: 8.25h (8:15)
- 2024-01-02: 7.5h (7:30)
- 2024-01-03: 8.0h (8:00)

Grand total: 23.75h (23:45)

Statistics:
- Working days: 3
- Average per day: 7.92h (7:55)

ユーザーの病欠日を取得

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

祝日を取得

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

出力例：

Public holidays for 2024:

Holiday dates:
- 2024-01-01: New Year's Day
- 2024-04-01: Good Friday
- 2024-04-03: Easter Monday
- 2024-05-01: Labor Day
- 2024-05-09: Ascension Day
- 2024-05-20: Whit Monday
- 2024-10-03: German Unity Day
- 2024-12-25: Christmas Day
- 2024-12-26: Boxing Day

Summary:
- Total public holidays: 9 days
- Approximate working days: 251 days

🔧 詳細設定

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 authentication failed. Please check MOCO_API_KEY.

• API キーが正しく、必要な権限があることを確認してください
• API キーが環境変数に正しく設定されているか確認してください
• キーの有効期限が切れていないことを確認してください

❌ サブドメインエラー：

MOCO_SUBDOMAIN should only contain the subdomain name

• サブドメイン部分のみを使用してください：company（company.mocoapp.comではありません）
• サブドメインからhttps://と.mocoapp.comを削除してください

❌ Node.js バージョンエラー：

This package requires Node.js >= 18.0.0

• Node.js をバージョン 18 以降に更新してください
• バージョンを確認します：node --version

❌ npx の接続問題：

Error: Cannot find module '@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

🌟 機能

• ✅ 読み取り専用アクセス： データを変更しない安全な API 統合
• 🔄 自動ページネーション： 大規模なデータセットをシームレスに処理
• 📊 スマート集計： 日付、プロジェクト、タスクごとに自動集計
• 🎯 プロジェクトによる絞り込み： 特定のプロジェクトでアクティビティを絞り込み
• 🧩 包括的なツール： さまざまな用途に対応する 7 つの専用ツール
• 🎯 高度なプロンプト： 複雑な分析や洞察に対応する、AI を活用した 8 つのプロンプト
• 🌐 マルチクライアント対応： 主要なすべての MCP クライアントで動作

🤝 貢献

1. リポジトリをフォークします
2. 機能ブランチを作成します：git checkout -b feature-name
3. 変更を加え、テストを追加します
4. テストを実行します：npm test
5. プルリクエストを送信します

📄 ライセンス

MIT ライセンスについては、LICENSE ファイルを参照してください。

🆘 サポート

• MOCO API の問題： MOCO API ドキュメント
• MCP プロトコル： MCP ドキュメント
• このパッケージ： GitHub の課題