Spring AI MCP Poc

Spring AI MCP概念验证

此存储库包含一个基于Docker的设置，用于在本地运行GitHub模型上下文协议（MCP）服务器。它旨在与Spring AI应用程序配合使用，并提供了一种通过MCP协议与GitHub API交互的标准化方式。

特性

• GitHub MCP服务器：提供GitHub API访问的容器化MCP服务器
• RESTful API：HTTP端点，便于与Spring AI应用程序集成
• 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 Token

1. 首选
2. 点击“生成新令牌（经典）”
3. 选择以下范围：

- repo （完全控制私有存储库） - read:user （读取用户配置文件数据） - read:org （读取组织数据）

1. 将生成的令牌复制到您的 .env 文件

4.启动服务

docker-compose up -d

这将开始：

• GitHub MCP服务器 在港口3000
• Web用户界面 （可选）在端口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}

问题操作

• 列出问题: GET /api/repos/{owner}/{repo}/issues?state={open|closed|all}
• 创建问题: 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应用程序集成。以下是一个配置示例：

弹簧启动配置

# 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 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

1. 初始化Node.js项目：

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

1. 从docker-compose.yml复制服务器实现
2. 在本地运行：

npm start

监控和日志

查看服务器日志：

docker-compose logs -f github-mcp-server

检查集装箱状态：

docker-compose ps

配置

环境变量

Docker编写服务

• github mcp服务器：主MCP服务器容器
• mcp网络用户界面：用于测试的可选web界面

故障排除

常见问题

1. 认证错误：确保您的GitHub令牌具有所需的作用域
2. 端口冲突：更改 MCP_SERVER_PORT 在……里面 .env 如果端口3000正在使用中
3. 权限不足：确保Docker有权绑定到指定的端口

调试模式

启用调试日志记录：

NODE_ENV=development docker-compose up

安全考虑

• 永远不要承诺你的 .env 带有真实令牌的文件
• 使用GitHub令牌所需的最小范围
• 考虑使用GitHub Apps进行生产部署
• 对生产使用实施限速

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 测试用 docker-compose up
5. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

相关项目

• 模型上下文协议
• 春季AI

-