UteamUP CMMS

@uteamup/mcp-server

UteamUP 用の MCP サーバークライアント。OAuth 2.0 認証を自動で行い、Claude Desktop/Code との連携を実現します。

リンク

• 📦 npm パッケージ - npx -y @uteamup/mcp-server でインストール
• 📖 ドキュメント - MCP 連携の完全ガイド
• 🐛 Issue - バグの報告や機能のリクエスト
• 💬 サポート - サポートを受ける

これは何ですか？

このパッケージを使うと、Claude Desktop や Claude Code などの AI アシスタントを Model Context Protocol（MCP）経由で UteamUP CMMS システムに接続できます。OAuth 2.0 認証を自動で処理するため、自然な会話を通じて作業指示、資産、在庫などを管理できます。

Claude、Grok、Grok Bot、ChatGPT、MiniMax Code 向けの読み取り専用アクセス

本番環境の HTTPS エンドポイントを使用します。

環境	MCP サーバー URL
本番環境	https://api.uteamup.com/mcp/read-only

UteamUP アカウントでサインインしてください（推奨）。 テナント管理者（Tenant.Update）が、まず会社の API Keys タブで Allow members to connect AI assistants を有効にします。 その後、各メンバーが自分のアシスタントを接続します。API キーやシークレットは不要です。同意ページには、メンバーがオーナーであるかライセンスを保有し、かつ有効なサブスクリプションがある会社のみが表示されます。この条件を満たさなくなると、リンクは無効になります（401 invalid_token）。

• Grok： Connectors を開いて New Connector → Custom を選択し、エンドポイントを入力します。Grok が自身を登録し（RFC 7591）、UteamUP の同意ページに移動します。そこで会社を選択し、アクセスを許可します。Business/Enterprise ワークスペースでは、管理者によるコネクターのプロビジョニングが必要です。
• Grok Bot： Bot の Setup → Plugins カードで、エンドポイントを指定して Custom MCP server, Remote HTTPS を追加します。各チームメンバーは、初回使用時にサインインします。
• ChatGPT： エンドポイントを指定してカスタム MCP サーバーを追加し、OAuth を選択します。ChatGPT が自身を登録し、同じ同意ページでアクセスを承認します。
• Claude： エンドポイントを指定してカスタムコネクターを追加し、Sign in now と Register automatically を選択して、UteamUP の同意ページでアクセスを承認します。
• MiniMax Code： uteamup プラグインをインストールするか（インストールを参照）、Remote / streamable-http トランスポートを使用して Settings → MCP Servers にエンドポイントを追加します。MiniMax Code は保護対象リソースのメタデータを検出して自身を登録し（RFC 7591）、初回使用時に UteamUP の同意ページを開きます。

アシスタントは選択した会社におけるメンバー自身の権限を使用し、以下の読み取り専用ツールのみを使用します。アクセストークンの有効期間は 60 分で、リフレッシュトークンは使用のたびにローテーションされます。メンバーは Profile → Accounts で接続を解除できます。管理者は API Keys タブ、または uteamup_assistant_connection_list / uteamup_assistant_connection_revoke MCP ツールを使用して、すべてのリンクを確認および取り消せます。会社の設定をオフにすると、すべてのリンクが直ちに無効になります。 テナント API キー（サービス連携）。 API Keys → Set up UPMate Integration ウィザードでは、 引き続き ChatGPT と Grok 向けの非公開読み取り専用パイロットを利用できます。有効なロールのうち、 権限が View／Read のみに限定されているものを選択し、アシスタントごとに MCP 対応キーを個別に作成します。ChatGPT では、 事前定義されたクライアント認証情報を使って OAuth を設定します（API キーを Client ID、そのシークレットを Client Secret として指定します）。 Grok はサインインにのみ対応しているため、Grok では上記のオプションを使用してください。 テナント管理者は、通常のキーの上限数、有効期限、IP 制限、レート制限、ローテーション、失効の各制御を引き続き利用できます。

既存のアセット一覧、アセット検索、GUID によるアセット検索、作業指示一覧、作業指示検索のツールのみが公開されます。 現在の UPMate の機能設定、ロール権限、テナントの適用範囲は、検出と呼び出しの前に確認されます。推測による書き込み／管理ツールの呼び出しは、実行前に拒否されます。 保存済みのロールに書き込み権限またはワイルドカード権限が追加された場合や、キーが失効、期限切れ、またはローテーションされた場合、読み取り専用エンドポイントもそのキーを拒否します。 これらの読み取りで UteamUP AI プロバイダーが呼び出されたり、UteamUP AI クレジットが消費されたりすることはありません。

Node プロキシでは、同じエンドポイントを UTEAMUP_MCP_PATH=/mcp/read-only で使用できます。 デフォルトの /mcp トランスポートでは、既存の動作とロールベースの認可が維持されます。 CLI では引き続き、既存の API キー作成、ロール選択、失効コマンドを使用します。 別個の認証情報ストアやツール実装は必要ありません。

参考資料：OpenAI custom MCP servers および Grok connectors。

主な機能：

• ✅ OAuth 2.0 + PKCE 認証を自動化
• ✅ トークンのキャッシュと自動更新
• ✅ Claude Desktop、Claude Code、および MCP 互換クライアントに対応
• ✅ 設定不要。API 認証情報を指定するだけです
• ✅ 詳細なエラーメッセージ
• ✅ Server-Sent Events（SSE）レスポンスの解析
• ✅ JSON-RPC 2.0 通知を適切に処理
• ✅ 新機能： Pino による構造化ログ（JSON／テキスト形式）
• ✅ 新機能： Zod による設定の検証
• ✅ 新機能： パフォーマンス監視とメトリクス
• ✅ 新機能： 指数バックオフによる再試行ロジック
• ✅ 新機能： CLI ユーティリティ（--help、--version、--validate-config、--test-auth）
• ✅ 包括的なテストスイート

リリース状況： ベータ版です。上記の npm バッジには公開済みのバージョンが表示されます。 リリースの詳細は CHANGELOG.md をご覧ください。

会話の例：

You: Show me all high-priority work orders in Building A
AI: I found 5 high-priority work orders in Building A...

You: Assign them all to John Doe
AI: Done! All 5 work orders are now assigned to John Doe.

---

インストール

インストールは不要です！npx を使って直接実行できます。

npx -y @uteamup/mcp-server

または、グローバルにインストールできます。

npm install -g @uteamup/mcp-server

プラグインとしてインストール

• Claude Code：

  claude plugin marketplace add UteamUP/uteamup-mcp
  claude plugin install uteamup@uteamup
  

• Grok Build：

  grok plugin install https://github.com/UteamUP/uteamup-mcp.git --trust
  

• Gemini CLI：

  gemini extensions install https://github.com/UteamUP/uteamup-mcp
  

• MiniMax Code：

  git clone https://github.com/UteamUP/uteamup-mcp.git
  cp -R uteamup-mcp/plugins/minimax ~/.minimax/plugins/uteamup
  

  MiniMax Code にはプラグインマーケットプレイスがありません。フォルダー単位でローカルプラグインを検出し、自動的に再スキャンします。また、新たに検出されたプラグインはデフォルトで有効になります。このプラグインには、読み取り専用 MCP サーバーと、ツールを使用するタイミングと方法をエージェントに教える cmms スキルが含まれています。

  プラグインを使用しない場合は、サーバーを Settings → MCP Servers の下に直接追加し、Remote / streamable-http トランスポートと次の URL を指定してください（認証情報は保存されません）。 https://api.uteamup.com/mcp/read-only

---

クイックスタート

1. API 認証情報を取得する

1. UteamUP にログインします
2. Tenant Settings → API Keys に移動します
3. "Set up AI Integration" または "Create API Key" をクリックします
4. "MCP Enabled" の切り替えを有効にします
5. Create API Key をクリックします
6. API キーとシークレットをコピーして保存します（再表示できません）。

2. Claude Desktop を設定する

Claude Desktop で Settings → Developer → Edit Config を開きます。 設定ファイルは次の場所にあります。

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

次の設定を追加します。

{
  "mcpServers": {
    "uteamup": {
      "command": "npx",
      "args": ["-y", "@uteamup/mcp-server"],
      "env": {
        "UTEAMUP_API_KEY": "your-32-character-api-key",
        "UTEAMUP_SECRET": "your-64-character-secret"
      }
    }
  }
}

すべての UteamUP MCP 接続では https://api.uteamup.com を使用します。連携を検証する際は、 デモワークスペースの制限付きキーを使用してください。

3. Claude Desktop を再起動する

設定を保存したら、Claude Desktop を再起動します。UteamUP のツールが自動的に利用可能になります。

4. 接続をテストする

Claude で、次を試してください。

What UteamUP tools do you have access to?

または

Show me all open work orders

これで完了です！🎉

---

設定

環境変数

必須

Variable	Description
UTEAMUP_API_KEY	MCP が有効な API キー（32 文字）
UTEAMUP_SECRET	API キーのシークレット（64 文字以上）

任意

Variable	Description	Default
UTEAMUP_API_BASE_URL	API エンドポイント URL	https://api.uteamup.com
UTEAMUP_LOG_LEVEL	ログレベル：TRACE、DEBUG、INFO、WARN、ERROR	INFO
UTEAMUP_LOG_FORMAT	ログ形式：text、json	text
UTEAMUP_DEBUG	旧式のデバッグモード（1 または true）	false
UTEAMUP_REQUEST_TIMEOUT	リクエストのタイムアウト（ミリ秒）	30000
UTEAMUP_MAX_RETRIES	ネットワークエラー時の最大再試行回数	3
UTEAMUP_MAX_REQUEST_BYTES	1 つの JSON-RPC リクエストの最大バイト数	1048576
UTEAMUP_MAX_RESPONSE_BYTES	1 つのバックエンド応答からバッファーに保持する最大バイト数	10485760
UTEAMUP_TOKEN_CACHE_DIR	トークンキャッシュの永続化ディレクトリ	-
UTEAMUP_TOKEN_REFRESH_MARGIN	トークン更新の猶予時間（秒）	300

API ベース URL

設定するベース URL は、HTTPS のオリジンのみである必要があります。認証情報、パス、クエリパラメーター、フラグメント、および HTTP エンドポイントは拒否されます。

Node プロキシをローカルで実行する場合も、必ず https://api.uteamup.com を使用してください。MCP エンドポイントの完全なパスは /mcp、読み取り専用エンドポイントは /mcp/read-only です。

権限

AI アシスタントの権限は、API キーに割り当てられたロールによって制御されます。AI が実行できる操作を変更するには、次の手順に従ってください。

1. UteamUP の Tenant Settings → API Keys に移動します
2. API キーを編集します
3. Role を変更します（例：Admin、Supervisor、Read-Only）
4. 変更はすぐに反映されます。再接続は不要です

ヒント： 用途ごとに異なるロールの API キーを作成します（例：読み取り専用クエリ用と、フルアクセス用）。

---

トラブルシューティング

よくある問題

「必須の環境変数がありません」

原因： UTEAMUP_API_KEY または UTEAMUP_SECRET が MCP の設定で設定されていません。

解決方法：

1. Claude Desktop の設定ファイルを確認します（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json、Windows の場合は %APPDATA%\Claude\claude_desktop_config.json）
2. env セクションに UTEAMUP_API_KEY と UTEAMUP_SECRET の両方が含まれていることを確認します
3. 環境変数名に誤字がないことを確認します
4. 変更後、Claude Desktop を再起動します

---

「認証に失敗しました：API キーまたはシークレットが無効です」

原因： 認証情報が間違っているか、API キーが取り消されています。

解決方法：

1. UteamUP で認証情報を確認します。
   • Tenant Settings → API Keys に移動します
   • API キーが有効であることを確認します（期限切れまたは取り消し済みでないこと）
2. 認証情報を紛失した場合は、新しい API キーを作成します。
   • "Create API Key" をクリックします
   • "MCP Enabled" を有効にします
   • 新しい認証情報をコピーします
3. 新しい認証情報で MCP の設定を更新します
4. Claude Desktop を再起動します

---

「MCP アクセスが拒否されました：API キーで MCP が有効になっていません」

原因： API キーの作成時に MCP サポートが有効になっていませんでした。

解決方法：

1. MCP を有効にした新しい API キーを作成します。
   • Tenant Settings → API Keys に移動します
   • "Set up AI Integration" または "Create API Key" をクリックします
   • 重要： "MCP Enabled" の切り替えをオンにします
   • Create API Key をクリックします
2. 新しい認証情報で MCP の設定を更新します
3. Claude Desktop を再起動します

注： 既存の API キーで MCP を有効にすることはできません。新しいキーを作成する必要があります。

---

"ECONNREFUSED" または "Connection refused"

原因： API サーバーに接続できません。

解決策：

1. インターネット接続を確認します
2. ベース URL を確認します：
   • 本番環境：https://api.uteamup.com（デフォルト。環境変数は不要です）
3. UteamUP がダウンしていないか確認します：
   • [email protected] にお問い合わせください

---

"UNABLE_TO_VERIFY_LEAF_SIGNATURE" または証明書エラー

原因： サーバーの TLS 証明書を検証できません。

解決策：

1. API のベース URL が https://api.uteamup.com であることを確認します
2. デバイスの日付と信頼済み証明書の設定を確認します
3. 証明書エラーが解決しない場合は、[email protected] にお問い合わせください

---

ツールの一覧が空、または不完全

原因： 認証情報、ロール、または会社の設定で、要求されたツールが許可されていません。

解決策：

1. UteamUP で Tenant Settings → API Keys に移動します
2. キーが有効で、対象の会社に対して MCP が有効になっていることを確認します
3. ワークフローに必要な特定の読み取り権限を確認するよう、会社の管理者に依頼します
4. リモートの読み取り専用コネクターでは、制限付きの読み取り専用ロールを使用します。書き込み権限やワイルドカード権限は対象外です
5. 許可された権限を変更した後、クライアントを再接続してツールの一覧を更新します

---

デバッグ

構造化ログ

さまざまなログレベルと形式を有効にできます：

{
  "mcpServers": {
    "uteamup": {
      "command": "npx",
      "args": ["-y", "@uteamup/mcp-server"],
      "env": {
        "UTEAMUP_API_KEY": "your-key",
        "UTEAMUP_SECRET": "your-secret",
        "UTEAMUP_LOG_LEVEL": "DEBUG",
        "UTEAMUP_LOG_FORMAT": "json"
      }
    }
  }
}

ログレベル：

• TRACE：最も詳細なログです。すべてのリクエスト／レスポンス本文が含まれます（機密情報はマスキングされます）
• DEBUG：詳細なデバッグ情報
• INFO：一般的な情報メッセージ（デフォルト）
• WARN：警告メッセージ
• ERROR：エラーメッセージのみ

ログ形式：

• text：人が読みやすい形式で整形されたログ（開発用）
• json：構造化された JSON ログ（本番用）

機密データ： すべての認証情報、トークン、シークレットはログ内で自動的にマスキングされます。

注： ログは stderr に書き込まれます。JSON-RPC メッセージ用に予約されている stdout には書き込まれません。

---

それでも問題が解決しない場合

1. ログを確認します：

   • Claude Desktop：表示 → 開発者 → 開発者ツール → コンソール
   • [MCP Proxy] メッセージを探します

2. 認証情報の形式を確認します：

   • API Key：正確に 32 文字
   • Secret：64 文字以上
   • 余分なスペースや引用符がないこと

3. 手動でテストします：

   export UTEAMUP_API_KEY="your-key"
   export UTEAMUP_SECRET="your-secret"
   export UTEAMUP_DEBUG="1"
   echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx @uteamup/mcp-server
   

4. サポートを受けます：

   • メール：[email protected]
   • ドキュメント：https://github.com/UteamUP/uteamup-mcp#readme
   • GitHub の Issue：https://github.com/UteamUP/uteamup-mcp/issues

---

開発

ローカル開発環境のセットアップ

# Clone the repository
git clone https://github.com/UteamUP/uteamup-mcp.git
cd uteamup-mcp

# Install dependencies
npm install

# Run tests only at the final whole-goal gate (see MCPGuidelines.md)
UTEAMUP_FINAL_GOAL_GATE=1 npm test

# Test with debug logging
export UTEAMUP_LOG_LEVEL=DEBUG
export UTEAMUP_API_KEY="your-demo-workspace-key"
export UTEAMUP_SECRET="your-demo-workspace-secret"
export UTEAMUP_API_BASE_URL="https://api.uteamup.com"
node index.js

# CLI Utilities
node index.js --help                # Show help
node index.js --version             # Show version
node index.js --validate-config     # Validate environment variables
node index.js --test-auth           # Test OAuth authentication

# Test with a sample request
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node index.js

Claude Desktop を使ったローカルテスト

# Create a local link
npm link

# Update Claude Desktop config to use local version
{
  "mcpServers": {
    "uteamup-local": {
      "command": "node",
      "args": ["/absolute/path/to/uteamup-mcp/index.js"],
      "env": {
        "UTEAMUP_API_KEY": "your-key",
        "UTEAMUP_SECRET": "your-secret",
        "UTEAMUP_DEBUG": "1"
      }
    }
  }
}

プロジェクト構成

uteamup-mcp/
├── index.js           # Main entry point (OAuth + MCP client)
├── package.json       # Package metadata
├── README.md          # This file
├── LICENSE            # MIT license
├── CHANGELOG.md       # Version history
├── .gitignore         # Git ignore rules
├── .npmignore         # Files to exclude from npm package
└── test/              # Test files (not published)
    ├── oauth.test.js
    └── integration.test.js

テストの実行

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run only integration tests (requires credentials)
npm run test:integration

# Run with coverage
npm test -- --coverage

コードスタイル

このプロジェクトでは、以下を使用します：

• ESLint による lint
• Prettier によるフォーマット
• 最大限の互換性を確保するための CommonJS モジュール（ESM ではありません）

# Lint code
npm run lint

# Format code
npm run format

---

コントリビューション

コントリビューションを歓迎します。以下の手順に従ってください：

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更を加えます
4. 新しい機能のテストを追加します
5. すべてのテストに合格することを確認します（npm test）
6. 変更をコミットします（git commit -m 'Add amazing feature'）
7. ブランチにプッシュします（git push origin feature/amazing-feature）
8. Pull Request を作成します

コミットメッセージの形式

type(scope): subject

Types: feat, fix, docs, refactor, test, chore
Scope: oauth, client, docs, etc.

Example:
feat(oauth): add automatic token refresh on expiry
fix(client): handle network timeouts gracefully
docs(readme): update troubleshooting section

---

ライセンス

MIT © UteamUP

詳細は LICENSE を参照してください。

---

サポート

• ドキュメント： https://github.com/UteamUP/uteamup-mcp#readme
• メール： [email protected]
• Issue： https://github.com/UteamUP/uteamup-mcp/issues

---

関連リンク

• UteamUP のウェブサイト
• Model Context Protocol の仕様
• Claude Desktop
• OAuth 2.0 PKCE