admin-mcp

@hellocoop/admin-mcp（ベータ版）

Hellō アプリケーションを作成・管理するための Model Context Protocol（MCP）サーバーです。

🚧 ベータ版：この MCP サーバーは現在ベータ版です。皆さまからのフィードバックを積極的に募集しており、コントリビューションも歓迎します！開発者エクスペリエンスの向上にご協力いただくため、問題の報告、改善案の提案、プルリクエストの送信をお願いします。

クイックインストール

📖 完全なドキュメントとインストールガイド

クイック設定

次の設定のいずれかを MCP クライアントの設定にコピーしてください。

NPM パッケージ（最新）：

{
  "hello-admin-stdio": {
    "command": "npx",
            "args": ["-y", "@hellocoop/admin-mcp@latest"],
    "type": "stdio"
  }
}

HTTP トランスポート（リモート）：

{
  "hello-admin-http": {
          "url": "https://admin-mcp.hello.coop/",
    "type": "http"
  }
}

📖 ソースから実行する方法については、ローカル開発環境のセットアップを参照してください。

使い方

この MCP サーバーは、AI アシスタントから Hellō アプリケーションを直接作成・管理できる強力な単一のツール（hello_manage_app）を提供します。従来の API とは異なり、すべての操作に開発者コンテキスト（プロフィール、チーム、アプリケーション）が自動的に含まれるため、AI アシスタントに最適です。

📖 詳しい使い方、例、トラブルシューティングについては、hello.dev/docs/admin-mcpをご覧ください。

機能

• 🏢 コンテキストを考慮した操作：すべてのツール呼び出しに現在の開発者プロフィール、チーム、アプリケーションが自動的に含まれ、コンテキストをシームレスに把握できます
• 📱 統合アプリケーション管理：すべてのアプリ操作（作成、読み取り、更新、シークレット、ロゴ）に対応する強力な単一のツール
• 🔐 セキュアな OAuth 統合：JWT トークン検証を備えたブラウザーベースの認証
• 🌐 複数のトランスポートに対応：stdio（ローカル）と HTTP（リモート）の両方の MCP トランスポートで動作します
• 📊 組み込みの分析機能：最適化のための使用状況追跡とパフォーマンス監視
• 🎨 ロゴ管理：ライトテーマとダークテーマに自動対応するロゴのアップロード
• ⚙️ 柔軟な環境設定：ドメインと管理サーバーを設定可能

利用可能なツール

🎯 コアツール：

• hello_manage_app - すべてのアプリケーション管理に使うメインツール
  • アクション：create、read、update、create_secret、update_logo_from_data、update_logo_from_url
  • 常に含まれる情報：すべての応答に現在のプロフィール、チーム、アプリケーションが含まれます
  • コンテキストの自動設定：指定がない場合、デフォルトのチームを自動的に使用します
  • スマートなデフォルト設定：名前が指定されていない場合、プロフィールからアプリ名を生成します

主なメリット

🔄 常にコンテキストを把握：従来の API とは異なり、すべてのツールの応答に開発者コンテキストがすべて含まれます。

• ユーザープロフィール（名前、メールアドレス、写真）
• すべてのチーム／組織とそのロール
• チームとの関連付けを含むすべてのアプリケーション
• 現在のチームとアプリケーションの状態

そのため、操作のたびにコンテキストを失うことがありません。開発環境全体を把握する必要がある AI アシスタントに最適です。

ツールのアクションと応答の構造

hello_manage_app アクション：

📝 create - 新しいアプリケーションを作成します

• まだチームがない場合は、自動的に生成します
• プロフィールに基づいて、適切なデフォルト名を作成します
• 戻り値：{ profile, application, action_result }

👁️ read - アプリケーションの詳細を読み取ります

• client_id を指定しない場合：プロフィールのコンテキスト全体を返します
• client_id を指定した場合：プロフィールと指定したアプリケーションを返します
• 戻り値：{ profile, application?, action_result }

✏️ update - アプリケーションの設定を更新します

• アプリケーションの任意のプロパティを変更します
• 戻り値：{ profile, application, action_result }

🔑 create_secret - クライアントシークレットを生成します

• 安全な OAuth クライアントシークレットを作成します
• 戻り値：{ profile, application, client_secret, action_result }

🎨 update_logo_from_data - base64 データからロゴをアップロードします

• ライトテーマとダークテーマに対応しています
• ロゴ URL を使ってアプリケーションを自動的に更新します
• 戻り値：{ profile, application, update_result, action_result }

🔗 update_logo_from_url - URL からロゴをアップロードします

• 指定された URL から取得してアップロードします
• ライトテーマとダークテーマに対応しています
• 戻り値：{ profile, application, update_result, action_result }

すべての応答にはプロフィールのコンテキスト全体が含まれるため、開発環境を把握し続ける必要がある AI アシスタントに最適です。

利用可能なリソース

• Hellō ドキュメント - 統合に関する包括的なドキュメント
• Hellō クイックスタート - フレームワーク別のセットアップガイド
• Hellō ボタン - ログインボタンの実装ガイド
• Hellō スコープ - 利用可能なスコープとクレームのリファレンス
• Hellō Wallet API - Wallet API のリファレンスドキュメント
• Hellō ロゴデザインガイダンス - テーマに適したロゴの作成に関する包括的なガイド

環境変数

• HELLO_DOMAIN：デフォルトのドメインを上書きします（デフォルトは hello.coop です）
• HELLO_ADMIN：管理サーバーの URL を上書きします（デフォルトは https://admin.hello.coop です）

コントリビューションと開発

フィードバックをお待ちしています！ この MCP サーバーはベータ版であり、実際の利用状況に基づいて積極的に改善しています。

コントリビューション方法

• 🐛 問題を報告：GitHub Issues - バグを見つけた場合や、機能の追加をリクエストしたい場合はこちら
• 🔧 プルリクエストを送信：GitHub PRs - サーバーの改善にご協力ください
• 💬 ディスカッションに参加：Discord - フィードバックを共有したり、サポートを受けたりできます

ローカル開発

ローカルでの開発とテストには、以下を実行してください。

# Clone the repository
git clone https://github.com/hellocoop/admin-mcp
cd admin-mcp

# Install dependencies
npm install

次に、ローカル版を実行するよう AI クライアントを設定します。

ローカル開発（Node.js）：

{
  "hello-admin-local": {
    "command": "node",
            "args": ["path/to/HelloCoop/admin-mcp/src/stdio.js"],
    "type": "stdio"
  }
}

テスト

包括的なテストスイートを実行します。

# Run all automated tests
npm test