Spring AI MCP Proof of Concept

This repository contains a Docker-based setup for running a GitHub Model Context Protocol (MCP) server locally. It's designed to work with Spring AI applications and provides a standardized way to interact with GitHub APIs through the MCP protocol.

Features

- GitHub MCP Server: A containerized MCP server that provides GitHub API access
- RESTful API: HTTP endpoints for easy integration with Spring AI applications
- Docker Compose: Simple local deployment with Docker
- Health Monitoring: Built-in health checks and monitoring
- Development Ready: Hot-reload and development-friendly configuration

Prerequisites

- Docker and Docker Compose installed
- GitHub Personal Access Token with appropriate scopes
- Node.js 18+ (for local development)

Quick Start

1. Clone the Repository

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

2. Set Up Environment Variables

cp .env.example .env

Edit the .env file and add your GitHub Personal Access Token:

GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
MCP_SERVER_PORT=3000
NODE_ENV=development

3. Generate GitHub Token

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Click "Generate new token (classic)"
3. Select the following scopes:
- repo (Full control of private repositories)
- read:user (Read user profile data)
- read:org (Read organization data)
4. Copy the generated token to your .env file

4. Start the Services

docker-compose up -d

This will start:
- GitHub MCP Server on port 3000
- Web UI (optional) on port 8080

5. Verify the Setup

Check if the server is running:

curl http://localhost:3000/health

You should see:

{

  "status": "healthy",

  "timestamp": "2025-06-01T04:22:00.000Z"

}

API Endpoints

The GitHub MCP server exposes the following REST API endpoints:

Repository Operations

- Get Repository: GET /api/repos/{owner}/{repo}
- List User Repositories: GET /api/users/{username}/repos?type={all|owner|member}

Issues Operations

- List Issues: GET /api/repos/{owner}/{repo}/issues?state={open|closed|all}
- Create Issue: POST /api/repos/{owner}/{repo}/issues

Pull Request Operations

- List Pull Requests: GET /api/repos/{owner}/{repo}/pulls?state={open|closed|all}

Example API Calls

```bash