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:

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

# 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

Integration with Spring AI

This MCP server can be integrated with Spring AI applications. Here's an example configuration:

Spring Boot Configuration

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

Java Integration Example

@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 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);
    }
}

Development

Local Development Without Docker

1. Create the server directory:

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

2. Initialize the Node.js project:

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

3. Copy the server implementation from the docker-compose.yml

4. Run locally:

npm start

Monitoring and Logs

View server logs:

docker-compose logs -f github-mcp-server

Check container status:

docker-compose ps

Configuration

Environment Variables

Docker Compose Services

• github-mcp-server: Main MCP server container
• mcp-web-ui: Optional web interface for testing

Troubleshooting

Common Issues

1. Authentication Error: Make sure your GitHub token has the required scopes

2. Port Conflicts: Change the `MCP_SERVER_PORT` in `.env` if port 3000 is in use

3. Permission Denied: Ensure Docker has permission to bind to the specified ports

Debug Mode

Enable debug logging:

NODE_ENV=development docker-compose up

Security Considerations

• Never commit your `.env` file with real tokens
• Use minimal required scopes for your GitHub token
• Consider using GitHub Apps for production deployments
• Implement rate limiting for production use

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Test with `docker-compose up`

5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• Model Context Protocol
• Spring AI
• GitHub REST API