项目简介

Airlift MCP 服务器框架是 Airlift 核心库的一个模块，旨在简化 Java 中 Model Context Protocol (MCP) 服务器的开发。它提供了一种声明式的方法（通过注解）来定义 LLM 可用的资源、工具和 Prompt 模板，并负责处理底层 JSON-RPC 通信和会话管理，为 LLM 应用提供一个安全、可扩展的上下文服务。

主要功能点

资源管理 (Resources): 托管和管理各种数据资源，允许 LLM 客户端按需读取数据。例如，可以暴露文件内容、数据库查询结果等作为资源。
工具注册与执行 (Tools): 允许开发者将 Java 方法定义为 LLM 可调用的工具。LLM 客户端可以通过 MCP 协议调用这些工具来执行特定功能，例如计算、数据处理等。支持结构化输入和输出。
Prompt 模板定义 (Prompts): 支持定义可定制的 Prompt 模板，用于指导 LLM 的交互。LLM 客户端可以获取这些 Prompt 模板并根据需要填充参数。
JSON-RPC 通信: 通过标准 JSON-RPC 协议与 LLM 客户端进行通信，处理客户端的请求并返回响应。
会话与身份管理: 支持通过 HTTP 请求头映射客户端身份，实现会话上下文。

安装步骤

集成到 Maven 项目: 将 Airlift MCP 模块添加到您的 Java 项目 'pom.xml' 中。通常，Airlift 是一个大型框架，您需要添加 'io.airlift:airlift-mcp' 依赖。

<dependency>
    <groupId>io.airlift</groupId>
    <artifactId>airlift-mcp</artifactId>
    <version>您选择的Airlift版本</version>
</dependency>

（请将“您选择的Airlift版本”替换为实际版本号，例如在撰写本文时可能是最新的稳定版本。）

创建 MCP 端点: 在您的 Java 类中，使用 '@McpTool'、'@McpPrompt' 和 '@McpResource' 注解来定义 LLM 可用的功能。

// 示例: 定义一个工具
import io.airlift.mcp.McpTool;
import io.airlift.mcp.McpDescription;

public class MyServiceEndpoints {
    @McpTool(name = "helloWorld", description = "Say hello to a person")
    public String hello(@McpDescription("Name of the person") String name) {
        return "Hello, " + name + "!";
    }
}

配置并启动服务器: 使用 Airlift 的 'Bootstrap' 机制和 'McpModule' 来配置和启动您的 MCP 服务器。

// 示例: 启动服务器 (类似 LocalServer.java)
import io.airlift.bootstrap.Bootstrap;
import io.airlift.mcp.McpModule;
import io.airlift.node.NodeModule;
import io.airlift.jaxrs.JaxrsModule;
import io.airlift.json.JsonModule;
import io.airlift.http.server.testing.TestingHttpServerModule; // 或 HttpExternalServerModule
import com.google.inject.Injector;
import com.google.inject.Module;
import com.google.inject.Scopes;
import java.util.Optional;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

public class Application {
    public static void main(String[] args) {
        McpModule mcpModule = McpModule.builder()
                .withAllInClass(MyServiceEndpoints.class) // 注册您的 MCP 端点类
                // .withIdentityMapper(...) // 可选: 配置身份映射
                .build();

        ImmutableList.Builder<Module> modules = ImmutableList.<Module>builder()
                .add(mcpModule)
                .add(binder -> binder.bind(MyServiceEndpoints.class).in(Scopes.SINGLETON))
                .add(new NodeModule())
                .add(new TestingHttpServerModule(8080)) // 配置服务器端口
                .add(new JaxrsModule())
                .add(new JsonModule());

        Bootstrap app = new Bootstrap(modules.build());
        Injector injector = app.setRequiredConfigurationProperties(
                ImmutableMap.of("node.environment", "production")
        ).initialize();

        System.out.println("MCP Server started on port 8080 at /mcp");
        // 服务器将持续运行，直到应用程序关闭。
    }
}

服务器配置

MCP 客户端需要配置与 Airlift MCP 服务器建立连接。以下是一个示例 JSON 配置，您需要根据实际部署调整 'command' 和 'args'：

{
  "serverName": "Airlift MCP Demo Server",
  "command": "java",
  "args": [
    "-cp", "path/to/your/application.jar",  // 替换为您的应用 JAR 路径
    "your.package.Application"            // 替换为您的主类全限定名 (包含 main 方法的类)
    // "8080"                             // 可选：如果您的主类 main 方法支持，指定端口作为参数
  ],
  "uri": "http://localhost:8080/mcp"       // MCP 服务器的基 URI
}

参数注释:

'serverName': 用户友好的服务器名称。
'command': 启动 MCP 服务器进程的命令。例如，在 Java 应用中通常是 'java'。
'args': 传递给 'command' 的参数列表。
- '-cp path/to/your/application.jar': 指定 Java 虚拟机加载类路径。'path/to/your/application.jar' 应替换为包含您编译的 Airlift MCP 服务器代码的 JAR 文件路径。
- 'your.package.Application': 您的 MCP 服务器主类的完全限定名，即包含 'public static void main(String[] args)' 方法的类。
- '8080': 如果您的 'main' 方法支持，可将端口号作为参数传递。在上述 'Application' 示例中，端口号已在 'TestingHttpServerModule(8080)' 中硬编码，无需在 'args' 中重复。
'uri': MCP 服务器的完整 URI 地址，通常是 'http://<host>:<port>/mcp'。MCP 客户端将向此 URI 发送 JSON-RPC 请求。

基本使用方法

一旦 Airlift MCP 服务器启动并运行，LLM 客户端可以通过其配置的 URI ('http://localhost:8080/mcp') 发送 JSON-RPC 请求来发现和调用服务器提供的工具、Prompt 和资源。例如：

列出工具: 发送一个 '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' 请求。
调用工具: 发送一个 '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "helloWorld", "arguments": {"name": "Alice"}}, "id": 2}' 请求。
列出 Prompt: 发送一个 '{"jsonrpc": "2.0", "method": "prompts/list", "id": 3}' 请求。
读取资源: 发送一个 '{"jsonrpc": "2.0", "method": "resources/read", "params": {"uri": "file://example1.txt"}, "id": 4}' 请求。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息