MCP Server

🚀 IssueBadge MCP Server

IssueBadge MCP Serverは、IssueBadge APIとやり取りするためのModel Context Protocol (MCP) サーバーです。このサーバーを使用することで、ClaudeやChatGPTなどのAIアシスタントが自然言語でデジタルバッジや証明書を管理できます。

🚀 クイックスタート

前提条件

• Node.js 18+
• npm 8+
• IssueBadge APIアカウントとAPIキー

インストール

1. リポジトリをクローンする

   git clone https://github.com/issuebadge/mcp-server.git
   cd mcp-server
   

2. 依存関係をインストールする

   npm install
   

3. 環境を設定する

   cp .env.example .env
   # .envを編集して、IssueBadge APIの認証情報を入力する
   

4. プロジェクトをビルドする

   npm run build
   

5. サーバーをテストする

   npm test
   

✨ 主な機能

• 🤖 AIによるバッジ管理：自然言語を使用してバッジを作成、発行、管理することができます。
• 🔐 二重認証：Laravel SanctumとOAuth2の両方をサポートしています。
• 🏆 完全なバッジライフサイクル：テンプレートを作成し、受信者に発行し、認証を検証することができます。
• 📊 マルチテナントサポート：エンタープライズ利用のためのセキュアなテナント分離を提供します。
• 🛡️ 冪等性保護：組み込みのセーフガードにより、重複操作を防止します。
• 📧 自動通知：検証URL付きの自動メール配信を行います。
• 🎨 カスタムフィールド：柔軟なメタデータとカスタムフィールドをサポートしています。

📦 インストール

インストール手順は「クイックスタート」の「インストール」セクションを参照してください。

💻 使用例

基本的な使用法

Claude Desktop

Claude Desktopの設定にこのサーバーを追加します。

{
  "mcpServers": {
    "issuebadge": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "ISSUEBADGE_BASE_URL": "https://app.issuebadge.com/api/v1",
        "ISSUEBADGE_API_KEY": "",
        "AUTH_METHOD": "sanctum"
      }
    }
  }
}

ChatGPT Actions

1. ChatGPTで新しいカスタムGPTを作成します。
2. IssueBadgeインスタンスからOpenAPI仕様をインポートします。
3. APIキーを使用してBearerトークン認証を設定します。
4. 会話を通じてバッジを管理し始めましょう！

高度な使用法

自然言語によるバッジ操作

バッジの作成

Human: "Create a badge for JavaScript mastery with fields for completion date and project count"

AI: I'll create a JavaScript mastery badge with the custom fields you specified.

✨ Badge Created Successfully!
🏷️ Badge Name: JavaScript Mastery Certificate
🆔 Badge ID: js_mastery_2024_001
📋 Custom fields: completion_date (date), project_count (number)

バッジの発行

Human: "Issue the JavaScript badge to Sarah Chen with completion date December 1st and 5 projects completed"

AI: I'll issue the JavaScript mastery badge to Sarah Chen with the specified details.

🎉 Badge Issued Successfully!
📧 Recipient: Sarah Chen  
🔗 Verification URL: https://yourdomain.com/verify/xyz123
📅 Completion Date: 2024-12-01
📊 Projects: 5

バッチ操作

Human: "Create completion badges for all students in my Python course who scored above 85%"

AI: I'll help you create and issue completion badges for high-performing students. First, let me create a Python Course Completion badge, then we can issue it to qualified students.

[Creates badge and processes student list]

📚 ドキュメント

利用可能なツール

1. validate_key

認証のためにIssueBadge APIキーを検証します。 パラメーター:

• api_key (文字列、必須): 検証するAPIキー

例:

"Validate my API key: 1|abcdef123456789..."

2. get_all_badges

認証された組織に利用可能なすべてのバッジを取得します。 パラメーター:

• limit (数値、オプション): 返す最大バッジ数 (デフォルト: 100)

例:

"Show me all available badges"
"List the first 50 badges"

3. create_badge

オプションのカスタムフィールドで新しいバッジテンプレートを作成します。 パラメーター:

• name (文字列、必須): バッジ名
• description (文字列、必須): バッジの説明
• issuing_organization_name (文字列、必須): 発行組織名
• idempotency_key (文字列、必須): 一意の識別子
• custom_fields (配列、オプション): カスタムフィールドの定義
• その他のオプションパラメーター...

例:

"Create a badge called 'Web Development Certificate' for completing our full-stack course"
"Create a Python certification badge with custom fields for completion date and final score"

4. issue_badge

オプションのメタデータを付けて、受信者にバッジを発行します。 パラメーター:

• badge_id (文字列、必須): 作成時のバッジID
• name (文字列、必須): 受信者の氏名
• idempotency_key (文字列、必須): 一意の識別子
• email (文字列、オプション): 受信者のメールアドレス
• metadata (オブジェクト、オプション): カスタムフィールドの値

例:

"Issue the Web Development badge to John Doe with email john@example.com"
"Issue Python certification to Alice with completion date today and score 95%"

エラーハンドリング

MCPサーバーは、一般的な問題に対する詳細なエラーメッセージを提供します。

• 認証エラー：無効なAPIキーまたは期限切れのトークン
• 検証エラー：必須パラメーターが欠落しているか、形式が無効です。
• ネットワークエラー：接続タイムアウトまたはサービス利用不可
• ビジネスロジックエラー：重複操作または権限不足

ユースケース

教育機関

• コース修了：学生がコースを修了したときに自動的にバッジを発行します。
• スキル検証：評価スコア付きのスキルベースのバッジを作成します。
• 卒業証書：学術詳細を含む卒業バッジを一括発行します。

企業トレーニング

• 認定プログラム：有効期限付きの専門資格を管理します。
• コンプライアンストレーニング：必須トレーニングの完了を追跡および検証します。
• スキル開発：社内スキル開発プログラムのバッジを発行します。

イベント管理

• 会議参加：イベントやワークショップの参加バッジを発行します。
• 達成トラッキング：進行中のプログラムのための段階的なバッジシステムを作成します。
• 講演者認定：講演者や参加者の認定バッジを管理します。

🔧 技術詳細

構成

.env.exampleに基づいて.envファイルを作成します。

# API Configuration
ISSUEBADGE_BASE_URL=https://app.issuebadge.com/api/v1
ISSUEBADGE_API_KEY=

# OAuth2 Configuration (Alternative)
ISSUEBADGE_OAUTH_URL=https://app.issuebadge.com/api/v1/oauth
ISSUEBADGE_OAUTH_TOKEN=your_oauth_token_here

# Authentication Method (sanctum or oauth2)
AUTH_METHOD=sanctum

# Server Configuration
MCP_SERVER_NAME=IssueBadge MCP Server
MCP_SERVER_VERSION=1.0.0

# Optional Settings
REQUEST_TIMEOUT=30000
DEBUG=false
MAX_RETRIES=3
RETRY_DELAY=1000

開発

ソースからビルドする

# リポジトリをクローンする
git clone https://github.com/issuebadge/mcp-server.git
cd mcp-server

# 依存関係をインストールする
npm install

# TypeScriptをビルドする
npm run build

# 開発モードで実行する
npm run dev

# コードをリントする
npm run lint

# コードを整形する
npm run format

プロジェクト構造

mcp-server/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (generated)
├── .env.example         # Environment configuration template
├── package.json         # Node.js dependencies and scripts
├── tsconfig.json        # TypeScript configuration
└── README.md           # This file

セキュリティ

• すべてのAPI通信はHTTPSを使用します。
• APIキーは、各リクエストの前に検証されます。
• 冪等性キーにより、重複操作が防止されます。
• マルチテナントデータ分離が行われます。
• リクエストタイムアウト保護があります。
• 包括的なエラーハンドリングが行われます。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細については、LICENSEファイルを参照してください。

🆘 サポート

ヘルプの取得

• 📖 ドキュメント：このREADMEとコード内のコメントを確認してください。
• 🐛 バグ報告：Open an issue
• 💬 ディスカッション：GitHub Discussions
• 📧 メール：support@issuebadge.com

トラブルシューティング

一般的な問題

1. APIキーの検証に失敗しました

# APIキーの形式を確認する (数値|で始まる必要があります)
# キーが期限切れになっていないことを確認する
# 正しいベースURLが設定されていることを確認する

2. 接続タイムアウト

# ネットワーク接続を確認する
# IssueBadgeサービスの状態を確認する
# .envでREQUEST_TIMEOUTを増やす

3. バッジ作成エラー

# 必須フィールドが提供されていることを確認する
# 冪等性キーの一意性を確認する
# 組織の権限を確認する

🔗 関連プロジェクト

• IssueBadge API：コアバッジ管理プラットフォーム
• Model Context Protocol：MCP仕様とツール
• Claude Desktop：MCPをサポートするAIアシスタント

📈 ロードマップ

バージョン1.1

• [ ] バッチバッジ操作
• [ ] 高度なフィルタリングと検索
• [ ] Webhook統合
• [ ] バッジテンプレート管理

バージョン1.2

• [ ] 分析とレポートツール
• [ ] カスタムバッジ検証ルール
• [ ] 学習管理システムとの統合
• [ ] 高度なワークフロー自動化

バージョン2.0

• [ ] ブロックチェーン検証サポート
• [ ] 多言語バッジコンテンツ
• [ ] 高度なブランディングカスタマイズ
• [ ] エンタープライズSSO統合

🤝 コントリビューション

コントリビューションを歓迎します！コントリビューションガイドラインを参照してください。

1. リポジトリをフォークする
2. 機能ブランチを作成する： git checkout -b feature/amazing-feature
3. 変更をコミットする： git commit -m 'Add amazing feature'
4. ブランチにプッシュする： git push origin feature/amazing-feature
5. プルリクエストを作成する

開発ガイドライン

• TypeScriptのベストプラクティスに従ってください。
• 包括的なエラーハンドリングを追加してください。
• 関数にJSDocコメントを含めてください。
• 新機能に対してテストを更新してください。
• セマンティックバージョニングに従ってください。

バッジ管理を革命的に変える準備はできましたか？ IssueBadge MCP Serverを使って、会話型バッジ管理の威力を体験してください！

Built with ❤️ by the IssueBadge team