Osquery MCP 服务器与客户端

Osquery 的完整模型上下文协议（MCP）实现，包括一个 Spring Boot 服务器和一个基于 Spring AI 的 CLI 客户端，使AI助手能够通过自然语言回答系统诊断问题。

概述

Osquery MCP 服务器充当AI模型与操作系统之间的智能桥梁。它将诸如“为什么我的风扇这么热？”或“什么占用了我所有的内存？”这样的自然语言问题转换成精确的 Osquery SQL 查询，允许AI助手诊断系统问题、监控性能并调查安全问题。

该项目包括一个完整的 Spring AI MCP 客户端实现，演示了如何通过模型上下文协议使用 Spring AI 的自动配置与服务器通信，提供程序化访问和交互式CLI。

特性

MCP 服务器

• 自然语言系统诊断：询问如“什么在占用我的CPU？”等问题，并获得智能答案。
• 9种专用工具用于常见的诊断场景：
  • 执行自定义的 Osquery SQL 查询
  • 获取表模式和可用列
  • 查找高CPU/内存使用进程
  • 分析网络连接
  • 检查系统温度和风扇速度（macOS）
  • 获取全面的系统健康总结
  • 访问常见问题的示例查询
• 智能查询辅助：内置示例和模式发现帮助AI构建更好的查询。
• 基于STDIO的MCP集成：无缝地与Claude Desktop和其他兼容MCP的AI工具集成。
• Spring Boot 3.5 和 Java 21：使用Java 17+特性构建的现代、高效且易于维护的代码库。

Spring AI MCP 客户端

• Spring AI 自动配置：利用 Spring AI 的 MCP 客户端启动器进行零配置设置。
• 交互式CLI：用于探索性系统诊断的REPL接口。
• 自然语言处理：将人类问题映射到适当的服务器工具。
• 自定义SQL支持：通过MCP服务器执行直接的osquery命令。
• 自动工具发现：通过注入 SyncMcpToolCallbackProvider 发现工具。
• 内置错误处理：框架管理超时和进程管理。
• 声明式配置：基于YAML的设置，便于维护。
• 全面测试：包括查询映射逻辑的自动化单元测试。

性能与可靠性

• 查询超时：防止挂起，查询超时30秒，版本检查超时5秒。
• 进程管理：使用 ProcessBuilder 进行健壮的资源处理和适当的清理。
• 执行时间日志记录：跟踪查询性能以供监控和调试。
• 错误处理：捕获并返回失败查询的详细错误消息。
• 资源安全性：自动销毁超过超时限制的进程。

先决条件

• Java 21 或更高版本
• 已安装 Osquery，并且 osqueryi 在你的PATH中可用
• Gradle（或使用包含的Gradle包装器）

安装

1. 克隆仓库：

git clone https://github.com/yourusername/OsqueryMcpServer.git
cd OsqueryMcpServer

2. 构建项目：

./gradlew build        # 构建服务器
./gradlew bootJar      # 创建可执行JAR
cd client-springai && ../gradlew build  # 构建Spring AI客户端

3. 运行服务器：

./gradlew bootRun

4. 测试Spring AI MCP客户端：

# 自然语言查询
cd client-springai && ../gradlew run --args="\"什么在占用我的CPU？\""

# 交互模式
../gradlew run --args="--interactive"

# 自定义SQL查询
../gradlew run --args="\"SELECT name FROM system_info\""

# 运行测试套件
./test-client-springai.sh

5. 运行测试：

./gradlew test --tests OsqueryServiceTest    # 服务器测试
cd client-springai && ../gradlew test       # Spring AI客户端测试

使用方法

MCP 服务器

服务器以STDIO模式运行，并提供了九种专门的工具用于系统诊断：

Spring AI MCP 客户端

客户端提供了多种方式与服务器交互：

自然语言查询

cd client-springai
../gradlew run --args="\"什么在占用我的CPU？\""
../gradlew run --args="\"显示网络连接\""  
../gradlew run --args="\"为什么我的风扇在运转？\""
../gradlew run --args="\"显示系统健康状况\""

自定义SQL查询

../gradlew run --args="\"SELECT name, pid, cpu_time FROM processes ORDER BY cpu_time DESC LIMIT 5\""
../gradlew run --args="\"SELECT * FROM system_info\""

交互模式

../gradlew run --args="--interactive"
# 然后可以交互式地输入查询，输入'help'获取帮助，'exit'退出

可用的服务器工具

核心工具

• executeOsquery(sql)：执行任何有效的 Osquery SQL 查询
• listOsqueryTables()：获取系统上所有可用的 Osquery 表
• getTableSchema(tableName)：发现任何表的列和类型

诊断工具

• getHighCpuProcesses()：查找消耗最多CPU的进程
• getHighMemoryProcesses()：查找使用最多内存的进程
• getNetworkConnections()：显示带有进程信息的活动网络连接
• getTemperatureInfo()：获取系统温度和风扇速度（macOS）

辅助工具

• getCommonQueries()：获取常见诊断场景的示例查询
• getSystemHealthSummary()：获取关于CPU、内存、磁盘、网络和温度的综合概述

示例AI交互

无需编写复杂的SQL，现在可以通过自然语言提问：

“为什么我的电脑运行缓慢？” → AI 使用 getHighCpuProcesses() 和 getHighMemoryProcesses()

“什么连接到了互联网？” → AI 使用 getNetworkConnections()

“为什么我的风扇这么响？” → AI 使用 getTemperatureInfo() 来检查系统温度

“显示所有Chrome进程” → AI 使用 executeOsquery() 并结合模式发现

“给我一个整体的系统健康检查” → AI 使用 getSystemHealthSummary() 进行综合诊断

配置

应用程序通过 src/main/resources/application.properties 进行配置：

• 服务器名称：osquery-server
• 版本：1.0.0
• 模式：SYNC（同步操作）
• 传输：STDIO（标准输入/输出）

MCP 集成

此服务器使用 Spring AI 的 MCP 服务器启动器实现了模型上下文协议（MCP）。它可以与支持MCP的AI工具集成，例如：

• Claude Desktop 应用
• 其他兼容MCP的AI助手

示例MCP配置

对于 Claude Desktop，添加到您的配置中：

{
  "mcpServers": {
    "osquery": {
      "command": "java",
      "args": ["-jar", "path/to/osquery-mcp-server.jar"]
    }
  }
}

安全注意事项

⚠️ 警告：此服务器以运行用户的权限执行系统命令。考虑以下安全措施：

• 以最小必要的权限运行
• 在生产环境中实施查询过滤或白名单
• 监控并记录所有执行的查询
• 考虑使用只读的 Osquery 查询

开发

项目结构

├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/kousenit/osquerymcpserver/
│   │   │       ├── OsqueryMcpServerApplication.java
│   │   │       └── OsqueryService.java
│   │   └── resources/
│   │       └── application.properties
│   └── test/
│       └── java/
└── build.gradle.kts

项目架构

├── src/                                    # MCP 服务器（Spring Boot）
│   ├── main/java/com/kousenit/osquerymcpserver/
│   │   ├── OsqueryM
│   │   │   cpServerApplication.java      # 主应用程序
│   │   └── OsqueryService.java           # MCP 工具
│   └── test/java/com/kousenit/osquerymcpserver/
│       └── OsqueryServiceTest.java       # 服务器测试
├── client-springai/                       # Spring AI MCP 客户端
│   ├── src/main/java/com/kousenit/osqueryclient/springai/
│   │   └── SpringAiOsqueryClientApplication.java # CLI 应用程序
│   ├── src/test/java/com/kousenit/osqueryclient/springai/
│   │   └── QueryMappingTest.java         # 单元测试
│   ├── application.yml                   # Spring AI 配置
│   └── test-client-springai.sh           # 测试运行器
└── build.gradle.kts                       # 服务器构建配置

运行测试

./gradlew test                           # 服务器测试
cd client-springai && ../gradlew test    # Spring AI 客户端测试
./test-client-springai.sh                # 完整客户端测试套件

内置诊断查询

服务器包含了针对常见诊断场景的预构建查询。使用 getCommonQueries() 查看所有可用的示例：

性能分析

-- 消耗最多CPU的进程
SELECT name, pid, uid, (user_time + system_time) AS cpu_time FROM processes ORDER BY cpu_time DESC LIMIT 10;

-- 按进程的内存使用情况
SELECT name, pid, resident_size, total_size FROM processes ORDER BY resident_size DESC LIMIT 10;

网络分析

-- 活动网络连接
SELECT pid, local_address, local_port, remote_address, remote_port, state 
FROM process_open_sockets WHERE state = 'ESTABLISHED'

系统信息

-- 整体系统信息
SELECT hostname, cpu_brand, physical_memory, hardware_vendor, hardware_model FROM system_info;

-- 最近的文件更改
SELECT path, mtime, size FROM file WHERE path LIKE '/Users/%' 
AND mtime > (strftime('%s', 'now') - 3600)

AI 可以使用这些作为模板，或者直接调用专门的诊断工具。

贡献

欢迎贡献！请随时提交拉取请求。

许可证

MIT 许可证。详情见 许可证。

致谢

• Facebook 的 Osquery
• Spring AI MCP 用于MCP协议实现
• Spring Boot 框架