Spring AI MCP Proof of Concept

Spring AI MCP Proof of Concept

このリポジトリには、GitHub Model Context Protocol（MCP）サーバーをローカルで実行するための、Docker ベースのセットアップが含まれています。Spring AI アプリケーションでの利用を想定しており、MCP プロトコルを通じて GitHub API とやり取りするための標準的な方法を提供します。

機能

• GitHub MCP サーバー：GitHub API へのアクセスを提供するコンテナ化された MCP サーバー
• RESTful API：Spring AI アプリケーションに簡単に統合できる HTTP エンドポイント
• Docker Compose：Docker によるシンプルなローカルデプロイ
• ヘルスモニタリング：ヘルスチェックとモニタリングを組み込みで提供
• 開発向け設定：ホットリロードと開発に適した設定

前提条件

• Docker と Docker Compose がインストールされていること
• 適切なスコープが設定された GitHub Personal Access Token
• Node.js 18 以降（ローカル開発用）

クイックスタート

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

git clone https://github.com/shesadri/spring-ai-mcp-poc.git
cd spring-ai-mcp-poc

2. 環境変数を設定する

cp .env.example .env

.env ファイルを編集し、GitHub Personal Access Token を追加します。

GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
MCP_SERVER_PORT=3000
NODE_ENV=development

3. GitHub トークンを生成する

1. GitHub Settings > Developer settings > Personal access tokens に移動します
2. 「Generate new token (classic)」をクリックします
3. 次のスコープを選択します。
   • repo（プライベートリポジトリへのフルアクセス）
   • read:user（ユーザープロフィールデータの読み取り）
   • read:org（組織データの読み取り）
4. 生成したトークンを .env ファイルにコピーします

4. サービスを起動する

docker-compose up -d

次のサービスが起動します。

• GitHub MCP サーバー（ポート 3000）
• Web UI（任意、ポート 8080）

5. セットアップを確認する

サーバーが実行中かどうかを確認します。

curl http://localhost:3000/health

次のように表示されます。

{
  "status": "healthy",
  "timestamp": "2025-06-01T04:22:00.000Z"
}

API エンドポイント

GitHub MCP サーバーは、次の REST API エンドポイントを公開します。

リポジトリ操作

• リポジトリを取得：GET /api/repos/{owner}/{repo}
• ユーザーのリポジトリ一覧を取得：GET /api/users/{username}/repos?type={all|owner|member}

Issue 操作

• Issue の一覧を取得：GET /api/repos/{owner}/{repo}/issues?state={open|closed|all}
• Issue を作成：POST /api/repos/{owner}/{repo}/issues

プルリクエスト操作

• プルリクエストの一覧を取得：GET /api/repos/{owner}/{repo}/pulls?state={open|closed|all}

API 呼び出しの例

# Get repository information
curl http://localhost:3000/api/repos/octocat/Hello-World

# List user repositories
curl http://localhost:3000/api/users/octocat/repos

# List open issues
curl http://localhost:3000/api/repos/octocat/Hello-World/issues?state=open

# Create a new issue
curl -X POST http://localhost:3000/api/repos/octocat/Hello-World/issues \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test issue",
    "body": "This is a test issue created via MCP server",
    "labels": ["bug", "help wanted"]
  }'

# List pull requests
curl http://localhost:3000/api/repos/octocat/Hello-World/pulls

Spring AI との統合

この MCP サーバーは Spring AI アプリケーションに統合できます。設定例は次のとおりです。

Spring Boot の設定

# application.yml
spring:
  ai:
    mcp:
      servers:
        github:
          url: http://localhost:3000
          enabled: true
          timeout: 30s

Java 統合の例

@Service
public class GitHubMCPService {
    
    @Value("${mcp.github.base-url:http://localhost:3000}")
    private String baseUrl;
    
    private final RestTemplate restTemplate;
    
    public GitHubMCPService(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }
    
    public Repository getRepository(String owner, String repo) {
        String url = baseUrl + "/api/repos/" + owner + "/" + repo;
        return restTemplate.getForObject(url, Repository.class);
    }
    
    public List<Issue> getIssues(String owner, String repo, String state) {
        String url = baseUrl + "/api/repos/" + owner + "/" + repo + "/issues?state=" + state;
        return Arrays.asList(restTemplate.getForObject(url, Issue[].class));
    }
    
    public Issue createIssue(String owner, String repo, CreateIssueRequest request) {
        String url = baseUrl + "/api/repos/" + owner + "/" + repo + "/issues";
        return restTemplate.postForObject(url, request, Issue.class);
    }
}

開発

Docker を使わないローカル開発

1. サーバーディレクトリを作成します。

mkdir mcp-github-server
cd mcp-github-server

2. Node.js プロジェクトを初期化します。

npm init -y
npm install @modelcontextprotocol/sdk-nodejs @octokit/rest express cors dotenv

3. サーバーの実装を docker-compose.yml からコピーします
4. ローカルで実行します。

npm start

モニタリングとログ

サーバーログを表示します。

docker-compose logs -f github-mcp-server

コンテナの状態を確認します。

docker-compose ps

設定

環境変数

変数	説明	デフォルト
GITHUB_PERSONAL_ACCESS_TOKEN	API アクセス用の GitHub PAT	必須
MCP_SERVER_PORT	MCP サーバーのポート	3000
NODE_ENV	Node.js 環境	development

Docker Compose サービス

• github-mcp-server：メインの MCP サーバーコンテナ
• mcp-web-ui：テスト用の任意の Web インターフェース

トラブルシューティング

よくある問題

1. 認証エラー：GitHub トークンに必要なスコープが設定されていることを確認してください
2. ポートの競合：ポート 3000 が使用中の場合は、.env の MCP_SERVER_PORT を変更してください
3. 権限がありません：Docker に指定したポートへのバインド権限があることを確認してください

デバッグモード

デバッグログを有効にします。

NODE_ENV=development docker-compose up

セキュリティに関する考慮事項

• 実際のトークンを含む .env ファイルを絶対にコミットしないでください
• GitHub トークンには必要最小限のスコープを使用してください
• 本番環境へのデプロイには GitHub Apps の使用を検討してください
• 本番環境での使用時にはレート制限を実装してください

コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更を加えます
4. docker-compose up でテストします
5. プルリクエストを送信します

ライセンス

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

Related Projects

• Model Context Protocol
• Spring AI
• GitHub REST API