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”代表主键的数据类型。在Spring Data JPA中，\JpaRepository\ 是一个通用的仓库接口，用于对实体类进行数据访问操作

• TaskDto 可以翻译为“任务数据传输对象”或简化为“任务DTO”，在中文技术文档或编程语境中，通常会使用“任务DTO”这样的表述。

- POST /mcp/tasks 的输入数据传输对象（DTO）（验证要求：标题为必填项）

• McpService（可译为“MCP服务”）

- getTaskSchema(): Map\ 翻译为中文是：“获取任务模式（或任务架构）(): 键值对映射，其中键为字符串类型，值为对象类型” - 插入任务（List): 包含插入计数的 Map\ - 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）和更强认证的情况下，切勿将服务器公开暴露。