# tutorial-java

**Repository Path**: kunjs/tutorial-java

## Basic Information

- **Project Name**: tutorial-java
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-29
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

**Java后端 + MCP协议 + LLM Agent**

---

## 🎯 整体架构设计

```
┌─────────────────┐     MCP Protocol      ┌─────────────────┐
│  LLM Agent      │◄────JSON-RPC/SSE────►│  Java MCP Server│
│  (Claude/Copilot)│   (stdio/HTTP)      │  (Spring Boot)  │
└─────────────────┘                      └────────┬────────┘
                                                  │
                    ┌─────────────────────────────┼─────────────────────────────┐
                    ▼                             ▼                             ▼
            ┌─────────────┐           ┌─────────────┐           ┌─────────────┐
            │  Log Query  │           │  Log Analyze│           │  Log Export │
            │  Tool       │           │  Tool       │           │  Tool       │
            └──────┬──────┘           └──────┬──────┘           └──────┬──────┘
                   │                         │                         │
                   ▼                         ▼                         ▼
            ┌─────────────┐           ┌─────────────┐           ┌─────────────┐
            │Elasticsearch│           │  Aggregation│           │  File/JSON  │
            │/SQLite/Loki │           │  Engine     │           │  Stream     │
            └─────────────┘           └─────────────┘           └─────────────┘
```

---

## 🔧 技术选型（纯Java栈）

| 模块 | 推荐方案 | 说明 |
|------|---------|------|
| **MCP SDK** | `io.modelcontextprotocol.sdk:mcp` [[1]][[4]] | 官方Java SDK，支持stdio/SSE/HTTP传输 |
| **框架集成** | `spring-ai-starter-mcp-server` [[5]][[9]] | Spring Boot注解式开发，`@McpTool`一键暴露工具 |
| **日志存储** | **SQLite** (轻量) / **Elasticsearch** (企业级) | 教学场景用SQLite零部署，生产切ES |
| **JSON处理** | Jackson (SDK内置) [[13]] | 自动序列化工具参数/结果 |
| **传输协议** | STDIO (本地调试) / SSE (远程调用) | Claude Desktop默认用stdio，Web用SSE |

---

## 🚀 最小可运行示例（15分钟出效果）

### 1️⃣ 添加依赖（pom.xml）
```xml
<dependencies>
    <!-- Spring Boot + MCP Server (Spring AI集成) -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-mcp-server</artifactId>
        <version>1.0.0-M4</version> <!-- 使用最新Milestone -->
    </dependency>
    
    <!-- 日志存储：SQLite（教学零配置） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.xerial</groupId>
        <artifactId>sqlite-jdbc</artifactId>
        <version>3.45.1.0</version>
    </dependency>
</dependencies>
```

### 2️⃣ 定义日志实体（纯JPA注解）
```java
@Entity
@Table(name = "app_logs")
public class LogEntry {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(nullable = false)
    private String level; // INFO/WARN/ERROR
    
    @Column(nullable = false)
    private String service; // 微服务名称
    
    @Column(columnDefinition = "TEXT")
    private String message;
    
    @Column
    private LocalDateTime timestamp;
    
    @Column(columnDefinition = "JSON")
    private String context; // 额外上下文(JSON字符串)
    
    // getter/setter...
}
```

### 3️⃣ 创建MCP工具类（核心：@McpTool注解）
```java
@Service
@RequiredArgsConstructor
public class LogTools {
    
    private final LogRepository logRepo; // JpaRepository<LogEntry, Long>
    
    // 🔍 工具1：按条件查询日志
    @McpTool(
        name = "query_logs",
        description = "Query application logs with filters. Returns structured JSON for LLM analysis."
    )
    public List<LogSummary> queryLogs(
            @McpToolParam(description = "Log level: INFO/WARN/ERROR") String level,
            @McpToolParam(description = "Service name filter") String service,
            @McpToolParam(description = "Time range in hours (default: 24)") Integer hours
    ) {
        var cutoff = LocalDateTime.now().minusHours(hours != null ? hours : 24);
        var specs = LogSpecs.and(
            level != null ? LogSpecs.byLevel(level) : null,
            service != null ? LogSpecs.byService(service) : null,
            LogSpecs.afterTime(cutoff)
        );
        return logRepo.findAll(specs, Sort.by(Sort.Direction.DESC, "timestamp"))
            .stream().limit(100) // 限制返回量防token溢出
            .map(this::toSummary)
            .toList();
    }
    
    // 📊 工具2：日志聚合分析（供Agent做统计）
    @McpTool(name = "analyze_logs", description = "Aggregate logs by level/service for trend analysis")
    public LogAnalysis analyzeLogs(@McpToolParam(description = "Group by: level/service/hour") String groupBy) {
        // 使用JPA Criteria API或原生SQL实现聚合
        // 返回结构化结果，LLM可直接解读
        return logRepo.aggregateBy(groupBy); 
    }
    
    // 📤 工具3：导出日志（供Agent生成报告）
    @McpTool(name = "export_logs", description = "Export filtered logs as JSON/CSV for external use")
    public ExportResult exportLogs(
            @McpToolParam(description = "Export format: json/csv") String format,
            @McpToolParam(description = "Max entries to export") Integer limit
    ) {
        // 生成临时文件或直接返回流式JSON
        return new ExportResult("download_url_or_inline_data", format);
    }
    
    private LogSummary toSummary(LogEntry log) {
        // 精简字段，减少token消耗
        return new LogSummary(log.getTimestamp(), log.getLevel(), log.getService(), log.getMessage());
    }
}
```

### 4️⃣ 配置MCP服务器（application.yml）
```yaml
spring:
  main:
    web-application-type: none  # STDIO模式必须关闭Web容器
  ai:
    mcp:
      server:
        name: "log-agent-server"
        version: "1.0.0"
        # STDIO传输配置（本地调试用）
        stdio:
          enabled: true
        # 如需远程调用，启用SSE:
        # protocol: SSE
        # webmvc:
        #   path: /mcp

# 关闭控制台日志干扰STDIO通信
logging:
  pattern:
    console: ""
  level:
    root: WARN
```

### 5️⃣ 启动类
```java
@SpringBootApplication
public class LogAgentApp {
    public static void main(String[] args) {
        SpringApplication.run(LogAgentApp.class, args);
    }
    
    // 注册工具到MCP框架
    @Bean
    public List<ToolCallback> logTools(LogTools tools) {
        return ToolCallbacks.from(tools); // 自动扫描@McpTool方法
    }
}
```

### 6️⃣ 构建与连接测试
```bash
# 1. 打包
mvn clean package -DskipTests

# 2. 本地测试：用MCP Inspector（官方调试工具）
# 或连接Claude Desktop（配置claude_desktop_config.json）：
{
  "mcpServers": {
    "log-agent": {
      "command": "java",
      "args": ["-jar", "/path/to/log-agent-app.jar"]
    }
  }
}

# 3. Agent对话示例：
# 👤 用户: "最近2小时有哪些ERROR级别的日志？"
# 🤖 Agent: [自动调用 query_logs(level="ERROR", hours=2)]
# 🤖 Agent: "发现3条ERROR日志：[精简结果]，需要我进一步分析原因吗？"
```

---

## 📦 日志存储方案对比（按场景选择）

| 方案 | 适用场景 | 优势 | 两周教学建议 |
|------|---------|------|-------------|
| **SQLite + JPA** | 教学/原型/轻量演示 | 零部署、单文件、纯Java操作 | ✅ **首选**：聚焦MCP逻辑，避免运维复杂度 |
| **Elasticsearch** | 企业级/海量日志 | 全文检索、聚合分析、Kibana可视化 | 备选：提供docker-compose.yml一键启动 |
| **Loki + Grafana** | 云原生/K8s环境 | 轻量级、Prometheus生态集成 | 暂不推荐：需额外学习曲线 |

> 💡 **教学技巧**：先用SQLite快速跑通MCP流程，演示成功后再展示"如何切换到ES"的配置差异，体现架构扩展性。

---

## 🤖 Agent交互设计模式（关键！）

### 1. 工具描述优化（让LLM准确调用）
```java
@McpTool(
    name = "query_logs",
    description = """
        Query application logs with precise filters.
        Use this when user asks about:
        - Specific error messages
        - Service health status  
        - Time-range log review
        
        Returns: List of {timestamp, level, service, message}
        Limit: Max 100 entries per call
        """
)
```

### 2. 结果结构化（减少LLM解析负担）
```java
// 避免返回完整Entity，设计LLM友好的DTO
public record LogSummary(
    LocalDateTime timestamp,
    String level,      // 枚举值: "INFO"|"WARN"|"ERROR"
    String service,    // 服务名，便于Agent分组
    String message,    // 精简message（截断+脱敏）
    String suggestion  // 可选：预置分析建议，如"建议检查数据库连接"
) {}
```

### 3. 安全与限流（生产必备）
```java
@McpTool(name = "query_logs", ...)
@PreAuthorize("hasRole('LOG_READER')") // Spring Security集成
@RateLimit(maxCalls = 10, perSeconds = 60) // 自定义限流注解
public List<LogSummary> queryLogs(...) {
    // 业务逻辑
}
```

---

## 🗓️ 两周教学/开发节奏

| 时间 | 任务 | 交付物 |
|------|------|--------|
| **D1** | 环境搭建 + SQLite集成 + JPA实体 | 可插入/查询日志的空白服务 |
| **D2** | MCP Server配置 + `@McpTool`基础工具 | `query_logs`工具可被Inspector调用 |
| **D3** | 工具参数优化 + 结果结构化 + 错误处理 | Agent能准确理解并调用工具 |
| **D4** | 多工具开发：`analyze_logs` + `export_logs` | 支持统计/导出场景 |
| **D5** | Spring Security集成 + 工具级权限控制 | 不同角色看到不同日志 |
| **D6** | 连接Claude Desktop/Copilot实测 | 完整对话演示视频 |
| **D7** | 性能优化：结果截断/缓存/异步 | 响应时间<2s |
| **D8** | 扩展：接入Elasticsearch（可选） | 展示架构演进能力 |
| **D9** | 编写Agent Prompt模板 + 演示脚本 | 标准化交付文档 |
| **D10** | 生产打包 + `java -jar`演示 | 单文件交付，开箱即用 |

---

## 📚 开源参考与资源

| 资源 | 链接 | 价值 |
|------|------|------|
| **MCP Java SDK官方示例** | [github.com/modelcontextprotocol/java-sdk](https://github.com/modelcontextprotocol/java-sdk) [[4]][[10]] | 学习`@McpTool`/传输配置/测试方法 |
| **Spring AI MCP指南** | [docs.spring.io/spring-ai/reference/api/mcp](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html) [[5]] | Spring Boot集成最佳实践 |
| **Dan Vega教程** | [danvega.dev/creating-your-first-mcp-server-java](https://www.danvega.dev/blog/creating-your-first-mcp-server-java) [[11]] | 完整代码+Claude Desktop连接步骤 |
| **SQLite + JPA示例** | [github.com/xerial/sqlite-jdbc](https://github.com/xerial/sqlite-jdbc) | 零配置数据库集成参考 |

---

## ⚠️ 关键避坑指南

1. **STDIO模式必须关闭Web容器**  
   `spring.main.web-application-type=none` + 禁用banner/console日志，否则JSON-RPC通信会被干扰 [[11]]

2. **工具返回值要精简**  
   LLM有token限制，返回`List<LogSummary>`而非`List<LogEntry>`，message字段建议截断到200字符

3. **异步更新需用access()**  
   如果后台任务需推送日志到Agent，用`McpServerSession.sendNotification()`而非直接操作UI

4. **演示前必做生产打包**  
   `mvn clean package` 生成的JAR已包含所有依赖，`java -jar`直接运行，避免现场编译翻车

---

## 🎁 下一步：获取完整代码模板

如需以下任一资源，回复对应编号，我直接输出可克隆的工程：

1. **SQLite + MCP基础版**：含完整`@McpTool`示例 + Claude Desktop配置
2. **Elasticsearch扩展版**：docker-compose.yml + JPA Native Query聚合示例  
3. **Agent Prompt模板库**：针对日志查询/分析/报告的10+个优化提示词
4. **安全加固版**：Spring Security + 工具级RBAC + 审计日志

这个方案完全满足：**纯Java注解 + 零前端 + 企业级架构 + Agent高展示度**，且所有依赖均有官方维护，教学/生产均可放心使用。