AI导哈

本地聊天服务器

一个基于Spring Boot和H2的本地聊天服务器，提供任务管理和聊天界面功能。

  • by Ksawalakhe2024
  • Java
  • 本地部署
  • 更新于
在 GitHub 查看 Ksawalakhe2024/Agentic_SDLC_Advance_Task

使用说明

MCP服务器 + 本地聊天界面（Spring Boot + H2）

概述

这个项目提供了一个最小化的、仅限本地使用的MCP风格服务器，并内置了聊天用户界面。它允许你：

  • 检查任务模式
  • 生成并插入批量任务（例如，1000个）到H2文件数据库中
  • 查看汇总统计信息

它完全在您的机器上运行，使用Spring Boot和H2（文件模式）。无需外部数据库或服务。

目前（经过测试）有效的是什么

  • 可执行的Spring Boot JAR文件（已配置Spring Boot repackaged）
  • 在文件模式下，H2 位于 ./data/mcpdb
  • 位于 /mcp/… 下的 REST 端点…
  • 发送1000个任务的Java客户端
  • 本地网页聊天界面访问地址：http://127.0.0.1:8080/
  • 可选的API密钥网关，用于外部写入端点

项目结构

  • src/main/java/com/example/mcp 翻译为中文可以是：“源代码/主目录/Java/包名 com/example/mcp”。不过，为了更简洁明了，通常我们会直接说“src/main/java/com/example/mcp”这个路径，或者根据上下文简化为“该Java项目中的包路径 com/example/mcp”。如果非要一个更口语化的翻译，可以是：“源码主目录下的Java文件夹中的com.example.mcp包”。但考虑到技术文档的规范性，直接使用原路径或简要说明其位置和用途更为常见
    • Application.java（文件名，可译为“应用程序.java”或保持原样，因为文件名通常不直接翻译）
    • 控制器/
      • McpController.java（REST 端点）
      • ChatController.java（用于UI的聊天端点）
    • 服务/
      • McpService.java（模式，插入，摘要）
      • ChatAgentService.java（用于聊天界面的简单内置代理）
    • 实体/
      • Task.java（任务类文件）
    • 仓库/存储库/
      • TaskRepository.java（任务仓库/任务存储库类文件）
    • DTO（Data Transfer Object，数据传输对象）/
      • TaskDto.java 翻译为中文是：“任务数据传输对象（Java类）”。其中，“Task”表示任务，“Dto”是“Data Transfer Object”的缩写，即数据传输对象，通常用于在不同层或系统之间传递数据。
      • ChatRequest.java 翻译为中文是：“聊天请求类（Java）”
      • ChatResponse.java 翻译为中文是“聊天响应.java”或更简洁地表述为“聊天回复类.java”（如果是在描述一个Java类文件的话）。不过，通常在中文语境下，我们可能会直接说“ChatResponse.java 文件”或“ChatResponse.java 类”，具体取决于上下文和语境
    • 客户端/
      • GenerateTasksClient.java（发布1000个任务）
  • src/main/resources
    • application.yml
    • 静态/
      • index.html （聊天用户界面）
  • pom.xml（在Maven项目中，这是一个项目对象模型文件，用于配置项目的构建、依赖和插件等信息）
  • README.md（文件名，通常用于说明文件或项目文档）
  • `.gitignore` 翻译成中文是“Git忽略文件”。这个文件用于指定Git版本控制系统中应忽略的文件或文件夹，以避免将它们添加到版本控制中。

先决条件

  • Java 17及以上版本
  • Maven 3.6及以上版本

构建并运行（服务器）

1号航站楼（启动服务器）

`mvn clean package -DskipTests spring-boot:repackage` 翻译成中文是：执行 Maven 清理、打包操作，跳过测试，并执行 Spring Boot 的重新打包 运行命令：java -jar target/mcp-h2-0.0.1-SNAPSHOT.jar

2号航站楼（运行客户端） 打开一个新的终端/标签页。 切换到同一项目的根目录。 为本次终端会话设置API密钥： Windows PowerShell: $env:MCP_API_KEY="粘贴您的密钥" Windows 命令行：set MCP_API_KEY=粘贴你的密钥 macOS/Linux：export MCP_API_KEY="粘贴您的密钥"

运行客户端： `mvn exec:java -Dexec.mainClass="com.example.mcp.client.GenerateTasksClient"` 翻译成中文是：“使用 Maven 执行 Java 命令，指定主类为 com.example.mcp.client.GenerateTasksClient”

H2 控制台

  • http://127.0.0.1:8080/h2-console 翻译成中文为：“http://127.0.0.1:8080/H2控制台”。不过，通常我们不会对网址进行翻译，而是直接使用或解释其含义。这里的“h2-console”通常指的是一个用于访问和管理H2数据库的Web控制台界面。所以，也可以解释为：“访问本地主机（127.0.0.1）的8080端口上的H2数据库控制台”
  • JDBC URL: jdbc:h2:file:./data/mcpdb 翻译为中文是：JDBC 连接字符串：jdbc:h2:file:./data/mcpdb（注：这里的“JDBC URL”通常不直接翻译，因为它是一个技术术语，保持原样即可，但为了解释其含义，可以加上“连接字符串”这样的描述，不过在正式翻译中，通常只保留“JDBC URL”不变）。如果仅翻译URL部分，可以简化为：JDBC连接：jdbc:h2:file:./data/mcpdb。但考虑到上下文和可读性，原译文已足够清晰
  • 用户：sa
  • 密码：（空）

API密钥（可选，建议使用）

  • 对外部写入 /mcp/tasks 的请求，需要在请求头中包含与 application.yml（mcp.apiKey）中匹配的 X-MCP-KEY 头。
  • 为了方便起见，您可以通过环境变量来设置它：
    • 在application.yml中：mcp.apiKey: ${MCP_API_KEY:替换为仅本地安全密钥}
    • PowerShell: $env:MCP_API_KEY="your_key"
    • macOS/Linux：export MCP_API_KEY="your_key"
  • 应用内的聊天界面不使用这个标题栏；它直接调用服务，且仅限本地使用。

终点（或：结局指标）

  • GET /mcp/help — 简要说明
  • GET /mcp/schema/tasks — 简化的架构描述
  • POST /mcp/tasks — 插入 TaskDto 数组（需要 X-MCP-KEY）
  • GET /mcp/tasks/summary — 按状态汇总的总数
  • POST /chat —— Web UI 使用的聊天端点

运行聊天用户界面

  • 启动服务器后，打开 http://127.0.0.1:8080/
  • 尝试发送消息：
    • 显示模式（或架构）
    • 生成1000个任务
    • 显示摘要
    • 请检查位于 /mcp/schema/tasks 的任务模式。然后使用 /mcp/tasks 端点生成并插入1000个具有随机状态、标题和截止日期的不同任务。

Java客户端插入1000个任务

  • 在项目根目录下的第二个终端中：
    • 确保服务器正在运行
    • 选项A（配置主程序）：mvn exec:java
    • 选项B（显式指定主类）：mvn exec:java -Dexec.mainClass=com.example.mcp.client.GenerateTasksClient
  • 如果直接使用外部REST终端，请确保头部X-MCP-KEY与application.yml中的mcp.apiKey（或MCP_API_KEY环境变量）匹配。

配置（application.yml）

server:
  port: 8080
  address: 127.0.0.1
spring:
  datasource:
    url: jdbc:h2:file:./data/mcpdb;DB_CLOSE_ON_EXIT=FALSE;AUTO_RECONNECT=TRUE
    driverClassName: org.h2.Driver
    username: sa
    password:
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
mcp:
  apiKey: ${MCP_API_KEY:replace_with_secure_local_only_key}
logging:
  level:
    root: INFO
    com.example.mcp: DEBUG
spring.h2.console.enabled: true
spring.h2.console.path: /h2-console

高级设计（HLD）

组件：

  • Web 用户界面（静态 index.html）
    • 渲染一个简单的聊天界面，并将消息发布到/chat。
  • 聊天控制器
    • 接收聊天请求，并将其委托给ChatAgentService处理。
  • ChatAgentService（可译为“聊天代理服务”）
    • 基于规则的轻量级代理；理解“模式（schema）”、“生成N个（generate N）”、“摘要（summary）”。使用McpService。
  • McpController（可译为“MCP控制器”或根据具体上下文调整为更贴切的名称）
    • 用于模式、插入和摘要的公共REST端点（如有需要，可通过HTTP供代理访问）。
  • McpService（通常可译为“MCP服务”或根据具体上下文调整为更贴切的表述，如“多控制平面服务”等）
    • 核心领域逻辑：返回模式（或架构），执行插入操作，计算汇总信息。
  • 任务仓库（JPA）
    • 对任务实体进行增删改查（CRUD）操作。
  • H2 数据库（文件）
    • 本地持久化存储在 ./data/mcpdb。

数据流（典型路径）：

  1. 聊天用户界面 -> /chat -> 聊天代理服务 -> MCP服务 -> H2（插入/读取）-> 聊天用户界面回复
  2. 外部客户端 -> /mcp/tasks (X-MCP-KEY) -> McpService -> H2 -> 返回200状态码并插入计数
  3. 外部客户端 -> /mcp/schema/tasks 或 /mcp/tasks/summary -> McpService -> H2 -> JSON 结果

非功能备注：

  • 默认情况下仅绑定到本地（127.0.0.1）
  • API写入端点的密钥网关，以减少误用
  • 最小化占用空间；仅需 Java 17 + Maven

低级设计（LLD）

关键类和职责：

  • 任务（实体）
    • 字段：id（标识符）、title（标题）、description（描述）、status（状态：待办/进行中/已完成/已阻塞）、priority（优先级：低/中/高）、dueDate（截止日期）、assignee（负责人）、createdAt（创建时间）、updatedAt（更新时间）
    • 生命周期钩子：@PrePersist 用于设置默认值和时间戳；@PreUpdate 用于维护更新时间（updatedAt）
  • 任务仓库（或任务存储库）
    • `JpaRepository<Task, Long>` 翻译成中文可以是：“任务仓库接口，使用长整型作为主键”。这里，“Task”代表实体类的名称，“Long”代表主键的数据类型。在Spring Data JPA中，`JpaRepository` 是一个通用的仓库接口，用于对实体类进行数据访问操作
  • TaskDto 可以翻译为“任务数据传输对象”或简化为“任务DTO”，在中文技术文档或编程语境中，通常会使用“任务DTO”这样的表述。
    • POST /mcp/tasks 的输入数据传输对象（DTO）（验证要求：标题为必填项）
  • McpService（可译为“MCP服务”）
    • getTaskSchema(): Map<String, Object> 翻译为中文是：“获取任务模式（或任务架构）(): 键值对映射，其中键为字符串类型，值为对象类型”
    • 插入任务（List): 包含插入计数的 Map<String, Object>
    • getSummary(): 总数及各状态计数
  • McpController（可译为“MCP控制器”或根据具体上下文翻译为更具体的名称，如“多通道处理控制器”等，但在此保持通用性）
    • /mcp/help（帮助）、/mcp/schema/tasks（任务模式）、/mcp/tasks（POST方法；需要X-MCP-KEY头）、/mcp/tasks/summary（任务概要）
  • ChatAgentService（可译为）聊天代理服务
    • 处理(String): AgentResult { 回复, 数据 }
    • 生成任务(int): 列表 带有随机内容
  • 聊天控制器
    • /chat POST => ChatResponse { reply, data } 翻译为中文是：/chat POST 请求 => ChatResponse 响应 { 回复, 数据 }
  • 聊天请求/聊天响应
    • 用于聊天端点的简单请求/响应数据传输对象（DTO）

序列（通过聊天界面生成1000个任务）：

  1. 浏览器 -> 发送 POST 请求到 /chat，请求体为 { "message": "生成1000个任务" }
  2. ChatController -> ChatAgentService.handle（翻译为中文为）：聊天控制器 -> 聊天代理服务处理
  3. ChatAgentService.generateTasks(1000) -> McpService.insertTasks -> H2
  4. ChatAgentService -> McpService.getSummary -> H2（翻译为中文）：聊天代理服务 -> Mcp服务获取摘要 -> H2（或“H2数据库”，具体取决于上下文，若H2在此处指数据库则如此翻译）
  5. ChatController -> Browser { 回复, 摘要 }

序列（使用REST的外部客户端）：

  1. 客户端 -> GET /mcp/模式/任务
  2. 客户端 -> 向 /mcp/tasks 发送 POST 请求（包含 X-MCP-KEY 头），携带 1000 个 TaskDto
  3. 客户端 -> GET /mcp/tasks/summary

故障排除

  • 错误：“no main manifest attribute”（没有主清单属性）
    • 修复：使用重新打包方式构建（已配置）。运行 `mvn clean package -DskipTests` 命令，然后执行生成的 jar 文件。
  • 错误：POST /mcp/tasks 请求返回 401 未授权
    • 确保X-MCP-KEY头部与mcp.apiKey（或MCP_API_KEY环境变量）匹配。
  • 执行插件错误（未知生命周期阶段…mainClass…）
    • 确保破折号是ASCII连字符。或者运行 mvn exec:java（主类已在pom.xml中配置）。

示例 curl 调用

  • 帮助：curl http://127.0.0.1:8080/mcp/help
  • 模式：curl http://127.0.0.1:8080/mcp/schema/tasks
  • 插入（示例：空数组）：
    • curl -X POST http://127.0.0.1:8080/mcp/tasks -H "X-MCP-KEY: $MCP_API_KEY" -H "Content-Type: application/json" -d "[]"
  • 摘要：使用 curl 命令访问 http://127.0.0.1:8080/mcp/tasks/summary

许可证与说明

仅用于本地开发和测试。在未添加传输层安全（TLS）和更强认证的情况下，切勿将服务器公开暴露。

相关 MCP