Maven Repository MCP Server

Maven Repository MCP 服务

一个 模型上下文协议（MCP） 服务，提供搜索并与 mvnrepository.com 和 Maven Central 中的 Maven 构件交互的完整功能。

🚀 功能

• 搜索 Maven 构件：通过关键词查找 Maven 构件，并获取详细结果
• 版本管理：检索任意构件的所有可用版本
• 依赖管理：获取可直接使用的 Maven、Gradle 和 SBT 依赖代码片段
• POM 访问：直接从 Maven Central 获取完整的 POM.xml 文件
• 多种传输方式：支持 stdio 和 SSE（服务器发送事件）协议
• 速率限制：内置智能速率限制，以遵守 mvnrepository.com 的访问规则

📋 前提条件

• Node.js 18+
• npm 或 yarn 包管理器

🛠️ 安装与设置

1. 克隆仓库并安装依赖：

   git clone <repository-url>
   cd mvn-repository-mcp-server
   npm install
   

2. 构建项目：

   npm run build
   

3. 运行服务：

   npm start
   

🚀 用法

传输协议

该服务支持两种通信协议：

stdio 传输（默认）

非常适合本地开发和 MCP 客户端集成：

# Using npm scripts
npm run start:stdio
npm run dev:stdio

# Direct execution
node dist/index.js stdio
node dist/index.js  # stdio is default

SSE 传输

非常适合基于 Web 的客户端和 HTTP 集成：

# Using npm scripts (port 3000)
npm run start:sse
npm run dev:sse

# Direct execution
node dist/index.js sse
node dist/index.js sse --port 8080  # custom port

SSE 端点：

• SSE 流：http://localhost:<port>/sse
• 消息发布：http://localhost:<port>/message

可用工具

1. search_maven_artifacts

使用关键词搜索 Maven 构件。

参数：

• query（string，必填）：Maven 构件的搜索词
• maxResults（number，可选）：返回的最大结果数（默认值：10）

示例：

{
  "name": "search_maven_artifacts",
  "arguments": {
    "query": "spring-boot-starter",
    "maxResults": 5
  }
}

2. get_artifact_versions

检索指定构件的所有可用版本。

参数：

• groupId（string，必填）：Maven group ID（例如，'org.springframework.boot'）
• artifactId（string，必填）：Maven artifact ID（例如，'spring-boot-starter'）

示例：

{
  "name": "get_artifact_versions",
  "arguments": {
    "groupId": "junit",
    "artifactId": "junit"
  }
}

3. get_pom_xml

获取指定构件版本的完整 POM.xml 文件。

参数：

• groupId（string，必填）：Maven group ID
• artifactId（string，必填）：Maven artifact ID
• version（string，必填）：指定版本

示例：

{
  "name": "get_pom_xml",
  "arguments": {
    "groupId": "org.apache.commons",
    "artifactId": "commons-lang3",
    "version": "3.12.0"
  }
}

4. get_dependency_snippets

生成 Maven、Gradle 和 SBT 的依赖声明。

参数：

• groupId（string，必填）：Maven group ID
• artifactId（string，必填）：Maven artifact ID
• version（string，必填）：指定版本

示例：

{
  "name": "get_dependency_snippets",
  "arguments": {
    "groupId": "com.fasterxml.jackson.core",
    "artifactId": "jackson-core",
    "version": "2.15.2"
  }
}

🔧 开发

可用脚本

• npm run build - 将 TypeScript 编译为 JavaScript
• npm run build:watch - 以监视模式编译
• npm run start - 运行编译后的服务（stdio 传输）
• npm run start:stdio - 显式使用 stdio 传输
• npm run start:sse - 使用 SSE 传输（端口 3000）
• npm run dev:stdio - 使用 stdio 构建并运行
• npm run dev:sse - 使用 SSE 构建并运行
• npm run clean - 删除编译后的文件

项目结构

mvn-repository-mcp-server/
├── src/
│   ├── index.ts      # Main server entry point & CLI
│   ├── types.ts      # TypeScript interfaces
│   └── searcher.ts   # Core search & retrieval logic
├── dist/             # Compiled JavaScript output
├── package.json      # Project configuration
├── tsconfig.json     # TypeScript configuration
└── README.md         # This file

🎯 使用场景

面向 AI 助手

• 依赖发现：帮助用户找到合适的 Maven 依赖
• 版本管理：协助选择和更新依赖版本
• 构建文件生成：为不同的构建工具生成依赖代码块
• 安全分析：识别存在已知漏洞的构件

面向开发者

• 快速搜索：无需打开浏览器即可快速查找 Maven 构件
• 依赖分析：检查 POM 文件和依赖结构
• 多构建工具支持：同时获取 Maven、Gradle 和 SBT 的代码片段
• 版本比较：比较同一构件的不同版本

集成示例

与 AI 编码助手集成：

User: "Find me the latest Spring Boot starter for web development"
Assistant: Uses search_maven_artifacts → "spring-boot-starter-web"
Assistant: Uses get_dependency_snippets → Provides Maven/Gradle configs

用于依赖更新：

User: "Check if there are newer versions of JUnit available"
Assistant: Uses get_artifact_versions → Lists all JUnit versions with dates
Assistant: Highlights latest stable version and any security considerations

⚙️ 配置

速率限制

服务器会智能地限制请求频率，以遵守 mvnrepository.com 的要求：

• 请求之间至少间隔 3 秒
• 额外随机延迟 2-6 秒
• 遇到 403 错误时自动使用指数退避重试

超时设置

• 默认请求超时：30 秒
• Maven Central POM 请求：15 秒
• 失败请求最多重试 3 次

🔍 故障排除

常见问题

403 访问被拒绝错误：

• 服务器通过速率限制来防止此问题
• 如果遇到此问题，服务器会自动采用退避策略重试
• 如果问题持续存在，请考虑降低请求频率

网络超时：

• 检查网络连接
• 确认能否访问 mvnrepository.com
• 检查防火墙或代理设置

SSE 连接问题：

• 确保指定的端口可用
• 检查所选端口的防火墙设置
• 确认没有其他服务正在使用同一端口

调试模式

设置环境变量以启用详细日志：

DEBUG=mvn-repository-mcp-server npm start

🤝 参与贡献

欢迎贡献！欢迎提交问题、功能请求或拉取请求。

开发环境设置

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 视情况添加测试
5. 提交拉取请求

📄 许可证

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

🔗 相关链接

• Model Context Protocol
• Maven Repository
• Maven Central
• MCP SDK 文档