Spring AI MCP Proof of Concept

Spring AI MCP 概念验证

此代码仓库包含一套基于 Docker 的配置，用于在本地运行 GitHub Model Context Protocol（MCP）服务。该配置专为与 Spring AI 应用配合使用而设计，并提供通过 MCP 协议与 GitHub API 交互的标准方式。

功能

• GitHub MCP 服务：提供 GitHub API 访问能力的容器化 MCP 服务
• RESTful API：便于与 Spring AI 应用集成的 HTTP 端点
• Docker Compose：使用 Docker 进行简单的本地部署
• 运行状况监控：内置运行状况检查和监控功能
• 适用于开发：支持热重载，配置便于开发

先决条件

• 已安装 Docker 和 Docker Compose
• 具有适当权限范围的 GitHub 个人访问令牌
• 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 个人访问令牌：

GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
MCP_SERVER_PORT=3000
NODE_ENV=development

3. 生成 GitHub 令牌

1. 前往 GitHub 设置 > 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

Pull Request 操作

• 列出 Pull Request：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. Fork 此代码仓库
2. 创建功能分支
3. 进行更改
4. 使用 docker-compose up 进行测试
5. 提交 Pull Request

许可证

此项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

Related Projects

• Model Context Protocol
• Spring AI
• GitHub REST API