Java MCP注释和API
一个与框架无关的Java库，提供核心注释和API以实现 模型上下文协议（MCP） 服务器和客户端。
概述
此存储库为MCP实现提供了通用的Java构建块，而不会将您绑定到任何特定的运行时框架（Spring、Quarkus、Micronaut、WildFly、Open Liberty等）。它使开发人员能够创建可跨不同Java生态系统工作的可移植MCP集成。
什么是MCP？
模型上下文协议（MCP）是一个开放协议，它规范了应用程序如何向大型语言模型（LLM）提供上下文。它实现了人工智能助手与数据源、工具和服务之间安全、可控的交互。
项目结构
该存储库分为三个核心模块：
mcp-model
代表MCP协议规范的完整Java模型：
- JSON-RPC：请求、响应、通知和错误类型
- 工具：工具定义、调用请求/结果、模式
- 提示：提示消息、参数和响应
- 资源：资源内容、模板和订阅
- 内容：文本、图像、音频和嵌入式资源内容类型
- 完成：对提示和资源的自动完成支持
- 采样和采集：LLM采样和用户交互请求
- 常见类型：角色、根、图标、元数据、进度跟踪
包裹： org.mcp_java.model.*
mcp-annotations
用于声明性构建MCP服务器的框架无关注释：
工具:
@Tool-将方法标记为MCP工具@ToolArg-配置刀具参数
包裹： org.mcp_java.annotations.tools
资源:
@Resource-公开静态资源@ResourceTemplate-使用URI模板公开动态资源@ResourceTemplateArg-配置模板URI变量
包裹： org.mcp_java.annotations.resources
提示:
@Prompt-定义可重用的提示模板@PromptArg-配置提示参数
包裹： org.mcp_java.annotations.prompts
完成:
@CompleteArg-自定义完成参数名称@CompletePrompt-为提示参数提供完整性@CompleteResourceTemplate-为资源模板URI提供完整性
包裹： org.mcp_java.annotations.completion
核心:
@McpServer-将类标记为MCP服务器组件@MetaField-将自定义元数据添加到定义中
包裹： org.mcp_java.annotations
mcp-server-api
MCP服务器实现的基本框架无关运行时API：
Cancellation-处理请求取消的界面ClientCapability-客户能力表示ContentEncoder-自定义内容编码接口McpException-MCP相关错误的基本异常- 包装文件和合同
包裹： org.mcp_java.server
设计原则
- 框架不可知：对Spring、Quarkus或其他框架零依赖
- 便携的：在任何Java运行时使用这些注释和模型
- 清洁分离：注释、模型和服务器API位于单独的模块中
- 可扩展：特定框架的实施可以建立在这些基础之上
- 基于标准的：完全符合官方MCP规范
- 现代Java：使用Java 17+功能（记录、密封接口等）
模块依赖关系图
mcp-server-api
↓ (depends on)
mcp-annotations
↓ (depends on)
mcp-model框架实现（Quarkus、Spring等）通常依赖于所有三个模块。
入门指南
备注：该项目提供基础注释和模型。特定于框架的运行时实现（连接处理、JSON-RPC处理等）由单独的项目提供，如 Quarkus MCP服务器.
需求
- Java 17或更高版本
- Maven 3.9+
建筑
mvn clean install运行测试
mvn test用法示例
下面是一个使用注释的简单示例：
import org.mcp_java.annotations.McpServer;
import org.mcp_java.annotations.tools.Tool;
import org.mcp_java.annotations.tools.ToolArg;
import org.mcp_java.annotations.resources.Resource;
import org.mcp_java.annotations.prompts.Prompt;
import org.mcp_java.annotations.prompts.PromptArg;
@McpServer(name = "my-server", description = "Example MCP server")
public class MyMcpServer {
@Tool(
name = "calculate",
description = "Perform a calculation"
)
public int calculate(
@ToolArg(name = "a", description = "First number") int a,
@ToolArg(name = "b", description = "Second number") int b) {
return a + b;
}
@Resource(
uri = "config://settings",
name = "Application Settings",
description = "Current application configuration"
)
public String getSettings() {
return "{ \"theme\": \"dark\", \"language\": \"en\" }";
}
@Prompt(
name = "greet",
description = "Generate a greeting message"
)
public String greet(@PromptArg(name = "name") String name) {
return "Hello, " + name + "!";
}
}框架实现将处理这些注释，并通过MCP协议公开它们。
与其他项目的关系
该库的设计灵感来自以下内容，并与之兼容：
- Quarkus MCP服务器 -Quarkus特定的MCP实施
- OpenMCPTools -MCP工具和集成的集合
特定于框架的扩展可以基于这些核心注释构建，以提供特定于运行时的功能，如依赖注入、生命周期管理和协议处理。
贡献
我们欢迎捐款！该项目旨在服务于更广泛的Java MCP生态系统。
如何做出贡献
- 分叉 存储库
- 创建 特征分支(
git checkout -b feature/amazing-feature) - 提交 您的更改(
git commit -m 'Add some amazing feature') - 推 到分行(
git push origin feature/amazing-feature) - 打开 拉取请求
开发指南
- 保持框架独立性——没有特定于框架的依赖关系
- 遵循Java命名约定和代码风格
- 添加新功能的测试
- 根据需要更新文档
- 保持API表面最小化和集中
持续集成
此项目使用GitHub Actions进行持续集成，运行：
- 编译检查
- 单元和集成测试
- 代码质量分析
许可证
此项目根据Apache许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。