[Java] Java实战：手把手构建跨平台系统监控MCP服务器

如果你想了解 MCP 协议并亲手实践，那么这篇教程正适合你。我们将从零开始，逐步讲解 MCP 是什么，并手把手教你构建一个真实可用的跨平台系统监控服务。

什么是 MCP

MCP 全称是 Model Context Protocol（模型上下文协议）。它的核心理念其实很简单。

用大白话说：MCP 就是让 AI（例如 Claude）能够调用你编写的工具的一种标准化方式。

想象一下这个场景：

你：Claude，帮我查一下服务器的 CPU 使用率
Claude：好的，让我调用监控工具... 你的 CPU 使用率是 23.5%

这里的“监控工具”就是通过 MCP 提供的。AI 并非万能，它需要你为其提供扩展能力的接口，MCP 就是定义这个“工具箱”接入方式的标准协议。

一个生活化的类比

把 AI 想象成一个非常聪明但没有手脚的大脑：

• 没有 MCP：AI 只能与你进行对话，就像一个坐在沙发上的朋友，无法实际操作。
• 有了 MCP：AI 可以帮你开门、查询信息、操作设备，就像给这位朋友装上了灵活的手脚，能够执行具体任务。

为啥要用 MCP

在 MCP 出现之前，每个 AI 平台或应用通常都有自己的一套插件或工具系统：

• Claude 有 Claude 插件
• ChatGPT 有 GPTs 和插件
• 其他 AI 工具又有各自不同的标准

这就带来了一个痛点：开发者需要为不同的 AI 平台重复编写功能相似的代码。

MCP 带来的好处

• 一次编写，到处使用：开发一个 MCP 服务，所有支持 MCP 协议的 AI 客户端都能调用。
• 标准化：无需学习每个 AI 平台特有的插件开发体系。
• 灵活：支持 HTTP、Stdio（标准输入输出）等多种通信传输方式。
• 开源开放：由 Anthropic（Claude 的创造者）主导并维护的开放标准。

MCP 的核心概念

1. MCP 的三个角色

在 MCP 体系结构中，主要包含三个核心角色：

MCP Host（主机）

• 指 AI 应用本身，例如 Claude Desktop、Cursor IDE 等。
• 它负责创建和管理 MCP Client。
• 可以理解为“老板”或“调度中心”，负责发起任务请求。

MCP Client（客户端）

• 由 Host 创建，专门负责与 Server 进行通信。
• 负责发送请求、接收并解析响应。
• 可以理解为“秘书”或“传令官”，负责在 Host 和 Server 之间传递信息。

MCP Server（服务器）

• 这就是我们要动手编写的部分！
• 提供具体的工具（Tools）、资源（Resources）等实际能力。
• 可以理解为“员工”或“执行者”，负责处理具体的工作。

一个简单的交互示例：

Host (Claude Desktop) 说：“我需要查询系统状态”
  ↓
Client 说：“好的老板，让我去联系 MCP Server”
  ↓
Server 说：“收到指令！我立刻去读取 CPU、内存数据”
  ↓
Server 将数据返回给 Client
  ↓
Client 把数据整理后交给 Host
  ↓
Host (Claude) 最终对你说：“你的 CPU 使用率为 23%”

2. MCP 的四大能力

MCP Server 可以提供四种核心能力，就像一个多功能的工具箱：

能力 1：Tools（工具）

这是最常用、最核心的能力！就像给 AI 装备了一套瑞士军刀，让它能够执行具体的操作。

工具名：get_system_status
功能：获取服务器状态
输入：无
输出：CPU、内存、磁盘信息

使用场景：查询数据库、读写文件、调用外部 API、执行系统命令等。

特点：由 AI 主动发起调用、可以传递参数、并返回结构化的结果。

能力 2：Resources（资源）

可以理解为给 AI 提供了一个只读的文件柜。

Resources 是静态或动态的数据源，AI 可以读取其中的内容，但通常不能直接修改。

资源 URI：file:///var/log/app.log
资源类型：text/plain
内容：应用程序日志内容

使用场景：提供文档内容、暴露数据库查询结果、分享配置文件、提供 API 的历史响应数据等。

特点：通过 URI 进行标识和访问、主要是只读操作、Server 可以列出所有可用的资源列表。

能力 3：Prompts（提示词模板）

相当于为 AI 提前准备好的“剧本”或“话术模板”。

Prompts 是预定义的提示词模板，用于让 AI 按照预设的套路和格式进行工作。

提示词名：code-review
模板：
"""
请审查以下代码：
{code}

请重点关注：
1. 安全性问题
2. 性能瓶颈
3. 代码可维护性
"""

使用场景：代码审查、内容生成、报告总结等需要标准化流程的场景。

特点：支持变量插值、能够标准化 AI 的工作流、确保输出内容的一致性。

能力 4：Sampling（采样）

这个能力比较特殊，它允许 MCP Server 反过来请求 AI 生成内容。

简单说，就是让你的工具也能“求助”于 AI。

场景：你的工具需要生成一段产品描述文案
      ↓
你的 Server 向 AI 发出请求：“请基于这些特性生成一段产品介绍”
      ↓
AI 生成文案内容
      ↓
你的工具拿到 AI 生成的文本，再继续后续处理流程

使用场景：工具需要 AI 辅助进行决策、需要生成高质量的自然语言、需要对复杂数据进行初步分析等。

特点：实现了 Server 与 AI 的双向交互，适合构建复杂的协作工作流。

能力对比表

能力	通信方向	特点	常用程度
Tools	AI → Server	执行操作，返回结果	⭐⭐⭐⭐⭐
Resources	AI ← Server	读取数据	⭐⭐⭐⭐
Prompts	AI ← Server	使用模板	⭐⭐⭐
Sampling	AI ↔ Server	双向协作	⭐⭐

本教程将重点讲解 Tools 的实现，因为它是最实用、应用最广泛的的能力。

3. MCP 的通信协议

MCP 基于 JSON-RPC 2.0 协议进行通信。简单来说，就是使用 JSON 格式来封装请求和响应消息。

JSON-RPC 请求的三要素：

1. method（方法）：指定要执行的操作，例如 tools/call。
2. params（参数）：执行该方法所需要的具体信息。
3. id（请求 ID）：一个唯一标识符，用于将请求和对应的响应匹配起来。

一个请求示例：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_system_overview",
    "arguments": {}
  },
  "id": 1
}

对应的成功响应示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"cpu_usage\": 23.5, \"memory_usage\": 67.2}"
      }
    ]
  }
}

整个流程非常清晰：

1. AI（通过 Client）发送一个 JSON-RPC 请求，说“我要调用 xxx 工具”。
2. 你的 MCP Server 收到请求，执行相应的业务逻辑。
3. Server 将执行结果封装成 JSON-RPC 响应格式返回。

MCP 的工作流程

完整的连接和调用过程

MCP Server 与 Client 的完整交互通常包含几个阶段：连接建立、初始化握手、能力协商，最后才是具体的工具调用。

关键的 JSON-RPC 方法

MCP 协议定义了一系列标准方法，我们的 Server 需要根据提供的能力来实现对应的方法：

方法	说明	必需性 (对于本教程)
initialize	初始化握手，交换服务器信息和双方支持的能力	✅ 必须实现
tools/list	列出 Server 提供的所有可用工具	✅ 必须实现 (因为我们提供Tools)
tools/call	调用指定的工具	✅ 必须实现 (因为我们提供Tools)
resources/list	列出所有资源	❌ 可选
resources/read	读取指定资源	❌ 可选
prompts/list	列出所有提示词模板	❌ 可选
prompts/get	获取指定提示词模板	❌ 可选

我们的监控项目只实现 Tools 能力，因此核心是处理好以下三个方法：

1. initialize - 建立连接时的初始化握手
2. tools/list - 告知客户端本服务器有哪些工具可用
3. tools/call - 执行客户端请求调用的具体工具

传输方式

MCP 支持两种主流的传输方式：

1. Stdio（标准输入输出）

AI 程序 → 启动你的 Server 进程 → 通过 stdin（标准输入）/stdout（标准输出）进行通信

• 优点：实现简单，适合本地化的命令行工具。
• 缺点：通常仅限于本地进程间通信。

2. HTTP

AI 程序 → 发送 HTTP 请求 → 你的 HTTP 服务器 (MCP Server)

• 优点：可以远程调用，方便使用浏览器、Postman、curl 等工具进行独立测试和调试。
• 缺点：需要处理网络连接、超时等问题。

本实战项目将采用 HTTP 传输方式，原因是：

• 便于使用 curl 命令或 Postman 进行接口测试。
• 可以直接在浏览器中访问健康检查等端点。
• 未来更容易部署到云服务器或容器中。

项目实战：构建跨平台系统监控 MCP 服务

项目架构

我们的系统监控 MCP 服务器主要包含三个层次：HTTP服务器层、MCP协议处理器层和系统监控能力层。

技术选型

Javalin（轻量级 HTTP 服务器）

选择 Javalin 是因为它极其轻量且API简洁，能让我们聚焦于MCP逻辑而非框架细节。

// 启动一个 HTTP 服务器只需要两行代码！
Javalin app = Javalin.create();
app.start(8080);

// 添加路由也非常直观
app.get("/hello", ctx -> ctx.result("Hello World"));
app.post("/api", ctx -> {
    String body = ctx.body();
    // 处理请求逻辑...
});

• 轻量：核心依赖非常小。
• 简单直观：API 设计符合直觉，学习成本低。
• 高性能：基于 Jetty 服务器。
• 现代：完美支持 Java 的 Lambda 表达式和函数式编程风格。

OSHI（跨平台系统信息库）

OSHI (Open System and Hardware Information) 是一个 真正的跨平台 系统信息获取库。它的核心优势在于，用同一套 Java 代码 就能在主流操作系统上运行并获取硬件信息：

• Linux (各种发行版)
• Windows (7/8/10/11/Server)
• macOS (Intel 和 Apple Silicon)

OSHI 能做什么？

SystemInfo si = new SystemInfo();

// 获取 CPU 信息（跨平台）
CentralProcessor cpu = si.getHardware().getProcessor();
cpu.getLogicalProcessorCount(); // 逻辑核心数
cpu.getSystemCpuLoad();        // 系统CPU使用率

// 获取内存信息（跨平台）
GlobalMemory memory = si.getHardware().getMemory();
memory.getTotal();             // 总内存
memory.getAvailable();         // 可用内存

// 获取进程列表
List<OSProcess> processes = si.getOperatingSystem().getProcesses();

// 获取磁盘信息
List<HWDiskStore> disks = si.getHardware().getDiskStores();

• 真正的跨平台：无需为不同操作系统编写特定代码。
• 信息全面：覆盖 CPU、内存、磁盘、网络、进程等几乎所有关键指标。
• API 友好：设计清晰，易于使用。
• 生态活跃：项目持续维护更新。

Gson（JSON 处理库）

Google 出品的 Gson 库，用于在 Java 对象和 JSON 数据之间进行序列化和反序列化，简单而强大。

// Java 对象 → JSON 字符串
Map<String, Object> data = new HashMap<>();
data.put("name", "server-1");
data.put("cpu", 23.5);
String json = new Gson().toJson(data); // 结果: {"name":"server-1","cpu":23.5}

// JSON 字符串 → Java 对象
String json = "{\"name\":\"server-1\"}";
Map map = new Gson().fromJson(json, Map.class);

核心实现流程

1. Maven 依赖配置 (pom.xml)

首先，在项目的 pom.xml 文件中声明我们所需的依赖。

<dependencies>
    <!-- Javalin: 轻量级 HTTP 服务器 -->
    <dependency>
        <groupId>io.javalin</groupId>
        <artifactId>javalin</artifactId>
        <version>5.6.3</version>
    </dependency>

    <!-- OSHI: 跨平台系统信息库 -->
    <dependency>
        <groupId>com.github.oshi</groupId>
        <artifactId>oshi-core</artifactId>
        <version>6.4.10</version>
    </dependency>

    <!-- Gson: JSON 处理 -->
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.10.1</version>
    </dependency>

    <!-- SLF4J: 简单日志门面 -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-simple</artifactId>
        <version>2.0.9</version>
    </dependency>
</dependencies>

2. 系统监控模块 (SystemMonitor.java)

这个类是业务核心，负责利用 OSHI 获取真实的系统数据。它不包含任何 MCP 协议相关的代码，只专注于监控功能。

核心职责划分：

public class SystemMonitor {
    private final SystemInfo systemInfo; // OSHI 主入口
    private final Gson gson;             // JSON 转换器

    // 获取系统概览（CPU、内存、磁盘、负载）
    public String getSystemOverview() {
        // 1. 使用 OSHI 读取各类硬件信息
        // 2. 将数据组装成 Map 结构
        // 3. 使用 Gson 转换为 JSON 字符串并返回
    }

    // 列出资源占用最高的 N 个进程
    public String listTopProcesses(int limit) {
        // 1. 获取所有进程列表
        // 2. 按 CPU 使用率或内存使用率排序
        // 3. 截取前 limit 个进程
        // 4. 转换为 JSON 格式返回
    }

    // 检查指定系统服务的状态
    public String inspectServiceStatus(String serviceName) {
        // 1. 根据服务名搜索匹配的进程
        // 2. 返回该服务是否在运行及其详细信息
    }

    // 分析磁盘空间使用压力和趋势
    public String analyzeDiskPressure() {
        // 1. 遍历所有磁盘分区
        // 2. 计算使用率并评估压力等级（如：危险/高/中/低）
        // 3. 提供简要的优化建议
    }
}

示例代码片段 (获取系统概览)：

public String getSystemOverview() {
    Map<String, Object> result = new LinkedHashMap<>();
    HardwareAbstractionLayer hardware = systemInfo.getHardware();

    // 获取并封装 CPU 信息
    CentralProcessor cpu = hardware.getProcessor();
    Map<String, Object> cpuInfo = new LinkedHashMap<>();
    cpuInfo.put("model", cpu.getProcessorIdentifier().getName());
    cpuInfo.put("cores", cpu.getLogicalProcessorCount());

    // 计算 CPU 使用率（需要时间间隔采样）
    long[] prevTicks = cpu.getSystemCpuLoadTicks();
    Thread.sleep(1000); // 等待1秒进行采样
    long[] ticks = cpu.getSystemCpuLoadTicks();
    double usage = cpu.getSystemCpuLoadBetweenTicks(prevTicks) * 100;
    cpuInfo.put("usage_percent", Math.round(usage * 100.0) / 100.0);

    result.put("cpu", cpuInfo);

    // 获取并封装内存信息
    GlobalMemory memory = hardware.getMemory();
    Map<String, Object> memInfo = new LinkedHashMap<>();
    memInfo.put("total", formatBytes(memory.getTotal()));
    memInfo.put("available", formatBytes(memory.getAvailable()));
    result.put("memory", memInfo);

    // 转换为 JSON 字符串
    return gson.toJson(result);
}

3. MCP 协议服务器 (SystemMonitorMcpServer.java)

这是项目的主体，负责实现 MCP 协议，并通过 HTTP 暴露服务。它依赖于上面的 SystemMonitor 来执行实际监控任务。

整体结构：

public class SystemMonitorMcpServer {
    private static final SystemMonitor monitor = new SystemMonitor();
    private static final Gson gson = new Gson();

    public static void main(String[] args) {
        int port = 8080;

        // 创建并配置 Javalin HTTP 服务器
        Javalin app = Javalin.create(config -> {
            config.showJavalinBanner = false; // 不显示启动横幅
            config.http.defaultContentType = "application/json";
        }).start(port);

        // 路由 1: 健康检查端点 (便于运维)
        app.get("/health", ctx -> {
            ctx.json(Map.of("status", "healthy"));
        });

        // 路由 2: 工具列表端点 (用于调试，非MCP协议必须)
        app.get("/tools", ctx -> {
            // 返回一个人类可读的工具列表页面或JSON
        });

        // 路由 3: MCP JSON-RPC 主端点 (处理所有MCP请求)
        app.post("/", ctx -> handleMcpRequest(ctx));
    }

    // 处理所有 MCP 请求的核心方法
    private static void handleMcpRequest(Context ctx) {
        // 1. 解析请求体中的 JSON
        JsonObject request = JsonParser.parseString(ctx.body()).getAsJsonObject();

        // 2. 提取 method 和 id 等字段
        String method = request.get("method").getAsString();
        JsonElement id = request.get("id");

        // 3. 根据 method 分发到对应的处理方法
        JsonObject response = switch (method) {
            case "initialize" -> handleInitialize(id);
            case "tools/list" -> handleToolsList(id);
            case "tools/call" -> handleToolsCall(id, request.getAsJsonObject("params"));
            default -> createErrorResponse(id, "未知方法: " + method);
        };

        // 4. 将响应序列化为 JSON 并返回
        ctx.result(gson.toJson(response));
    }
}

MCP 协议方法的具体实现：

① initialize - 初始化握手

private static JsonObject handleInitialize(JsonElement id) {
    JsonObject result = new JsonObject();

    // 声明支持的协议版本
    result.addProperty("protocolVersion", "2024-11-05");

    // 服务器元信息
    JsonObject serverInfo = new JsonObject();
    serverInfo.addProperty("name", "system-monitor-mcp");
    serverInfo.addProperty("version", "1.0.0");
    result.add("serverInfo", serverInfo);

    // 声明本服务器支持的能力（这里只支持 tools）
    JsonObject capabilities = new JsonObject();
    capabilities.add("tools", new JsonObject()); // 存在此key即表示支持tools能力
    result.add("capabilities", capabilities);

    return createSuccessResponse(id, result);
}

② tools/list - 列出所有可用工具

private static JsonObject handleToolsList(JsonElement id) {
    JsonArray tools = new JsonArray();

    // 定义工具1：获取系统概览
    JsonObject tool1 = new JsonObject();
    tool1.addProperty("name", "get_system_overview");
    tool1.addProperty("description", "获取系统 CPU、内存、磁盘及负载的全面概览信息");
    tool1.add("inputSchema", new JsonObject()); // 空对象表示此工具无需参数
    tools.add(tool1);

    // 定义工具2：列出Top进程
    JsonObject tool2 = new JsonObject();
    tool2.addProperty("name", "list_top_processes");
    tool2.addProperty("description", "列出按 CPU 或内存使用率排序的进程，可指定数量");

    // 定义该工具的参数模式
    JsonObject schema = new JsonObject();
    schema.addProperty("type", "object");
    JsonObject properties = new JsonObject();

    JsonObject limitParam = new JsonObject();
    limitParam.addProperty("type", "integer");
    limitParam.addProperty("description", "希望返回的进程数量");
    limitParam.addProperty("default", 10);
    properties.add("limit", limitParam);

    schema.add("properties", properties);
    tool2.add("inputSchema", schema);
    tools.add(tool2);

    // ... 可以继续添加更多工具，如 inspect_service_status, analyze_disk_pressure

    JsonObject result = new JsonObject();
    result.add("tools", tools);
    return createSuccessResponse(id, result);
}

③ tools/call - 调用具体工具

这是最核心的方法，负责将 MCP 请求中的工具调用指令，路由到 SystemMonitor 中对应的业务方法。

private static JsonObject handleToolsCall(JsonElement id, JsonObject params) {
    // 解析请求参数
    String toolName = params.get("name").getAsString();
    JsonObject arguments = params.has("arguments") ? params.getAsJsonObject("arguments") : new JsonObject();

    String resultText;
    // 根据工具名路由到具体的监控方法
    switch (toolName) {
        case "get_system_overview":
            resultText = monitor.getSystemOverview();
            break;
        case "list_top_processes":
            int limit = arguments.has("limit") ? arguments.get("limit").getAsInt() : 10;
            resultText = monitor.listTopProcesses(limit);
            break;
        case "inspect_service_status":
            String serviceName = arguments.get("service_name").getAsString();
            resultText = monitor.inspectServiceStatus(serviceName);
            break;
        case "analyze_disk_pressure":
            resultText = monitor.analyzeDiskPressure();
            break;
        default:
            return createErrorResponse(id, "未知工具: " + toolName);
    }

    // 按照 MCP 协议要求的格式封装结果
    JsonArray content = new JsonArray();
    JsonObject textContent = new JsonObject();
    textContent.addProperty("type", "text");
    textContent.addProperty("text", resultText);
    content.add(textContent);

    JsonObject result = new JsonObject();
    result.add("content", content);

    return createSuccessResponse(id, result);
}

调试、测试与接入

启动你的 MCP Server

完成编码后，启动你的 SystemMonitorMcpServer 主类。服务器启动后，会在控制台输出监听地址。

使用 MCP Inspector 进行调试

Anthropic 官方提供了一个非常实用的可视化调试工具：MCP Inspector。你可以通过 npx 直接运行它来连接和测试你的服务器。

在终端中执行以下命令：

npx @modelcontextprotocol/inspector

这个命令会：

• 自动下载并启动 MCP Inspector。
• 启动一个代理服务器。
• 在浏览器中自动打开调试界面 http://localhost:6274。

在 Inspector 的界面中，配置 Transport Type 为 Streamable HTTP，URL 填写你的服务器地址（如 http://localhost:8080），然后点击 Connect。

在 Inspector 中测试工具

连接成功后，你可以在 Inspector 界面中：

• 查看所有可用工具：界面会显示从 tools/list 方法返回的工具列表（如 get_system_overview、list_top_processes）。
• 手动调用工具：点击任意工具，设置参数，然后执行。这非常有助于独立验证每个工具的返回结果是否符合预期。
• 检查通信详情：Inspector 会完整地显示每一轮 JSON-RPC 请求和响应的原始数据，是排查协议层问题的利器。

点击 List Tools 按钮，Inspector 会向你的 Server 发送 tools/list 请求，并在界面中展示返回的工具列表。

你还可以在 Inspector 中直接调用某个工具，例如 list_top_processes，并观察返回的 JSON 数据。

这对应了服务器端 tools/call 方法的处理逻辑。

接入 Cherry Studio (或其他 MCP 客户端)

调试无误后，就可以在支持 MCP 的 AI 应用中使用你的服务器了。这里以 Cherry Studio 为例。

对话流程示例：

你：帮我查看一下系统状态

Cherry Studio：好的，让我调用系统监控工具查看...
【Cherry Studio 内部自动调用 get_system_overview 工具】

Cherry Studio：你的系统状态如下：
- CPU: Intel Core i7，8核心，当前使用率 23.5%
- 内存: 总共 16GB，已使用 8.5GB，使用率约 53%
- 磁盘: 根分区使用率 45%，还有 55GB 可用空间

在 Cherry Studio 中的配置步骤：

1. 添加 MCP 服务器：在设置中找到 MCP 配置区域，选择添加新服务器。

2. 配置服务器参数：
   • 名称：例如“跨平台系统监控”。
   • 类型：选择 Streamable HTTP。
   • URL：填写你的服务器地址 http://localhost:8080。

3. 保存并启用：保存后，Cherry Studio 会自动连接到你的服务器并拉取工具列表。你可以在界面中看到所有已发现的工具，并选择启用它们。

4. 创建或配置助手：新建一个助手，或者编辑现有助手，在其配置中启用你刚刚添加的“跨平台系统监控” MCP 服务器。

5. 开始对话：现在，你就可以和这个助手进行自然对话，让它调用系统监控工具了。例如，你可以问“当前系统负载高吗？”或“内存占用最高的进程是什么？”

至此，一个完整的、由 Java 编写的跨平台系统监控 MCP 服务器，从开发、调试到最终集成使用的全流程就完成了。

总结

MCP (Model Context Protocol) 是一个新兴的、由社区推动的开放协议，旨在统一 AI 与外部工具和数据的交互方式。通过本教程，我们不仅理解了 MCP 的核心概念（Host/Client/Server 模型，Tools/Resources 等能力），更重要的是亲手实践，使用 Java 生态中的 Javalin、OSHI、Gson 等库，构建了一个实用的跨平台系统监控服务。

这个项目的意义在于，你掌握的不是一个特定功能的实现，而是一套方法论。你可以遵循同样的模式（实现 initialize, tools/list, tools/call 这三个核心方法），将任何你已有的 Java 功能或服务——无论是查询Java应用状态、操作数据库/中间件，还是调用其他内部系统API——快速封装成标准的 MCP 工具，从而赋能给 Claude、Cursor 以及未来更多支持此协议的 AI 应用。

希望这篇教程能帮助你打开思路。技术实践是学习的最佳路径，欢迎在云栈社区分享你的 MCP 作品或探索中遇到的问题。