# mcp-server-demo

**Repository Path**: cleanarch/mcp-server-demo

## Basic Information

- **Project Name**: mcp-server-demo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-28
- **Last Updated**: 2025-12-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Server Demo

MCP (Model Context Protocol) 服务器测试示例项目，用于暴露 MCP 服务接口。

## 📋 功能特性

- ✅ 支持 **Streamable HTTP** 和 **SSE** 两种传输方式
- ✅ 三个工具分组：天气查询、IP 查询、笑话
- ✅ 使用免费 API，无需申请 API Key
- ✅ 完整的 Maven 项目配置
- ✅ 支持多种编程客户端接入

## 🏗️ 项目结构

```
mcp-server-demo/
├── pom.xml                                    # Maven 配置
├── src/
│   ├── main/
│   │   ├── java/cn/clenarch/mcp/demo/
│   │   │   ├── McpServerApplication.java      # 启动类
│   │   │   ├── config/
│   │   │   │   └── McpServerConfig.java       # MCP 配置
│   │   │   ├── group/
│   │   │   │   ├── WeatherGroup.java          # 天气工具分组
│   │   │   │   ├── IpGroup.java               # IP 查询工具分组
│   │   │   │   └── JokeGroup.java             # 笑话工具分组
│   │   │   └── client/
│   │   │       └── McpClientExample.java      # 客户端调用示例
│   │   └── resources/
│   │       └── application.yml                # 应用配置
```

## 🚀 快速开始

### 1. 环境要求

- JDK 17+
- Maven 3.6+

### 2. 编译运行

```bash
# 编译项目
mvn clean package

# 运行服务
mvn spring-boot:run
```

### 3. 访问服务

服务启动后，访问以下地址：

- **MCP 端点**: `http://localhost:8080/mcp`
- **健康检查**: `http://localhost:8080/actuator/health`

## 📦 工具分组详情

### 1. WeatherGroup (天气查询)

| 工具名称 | 描述 | 参数 |
|---------|------|------|
| `get_current_weather` | 获取指定城市的当前天气 | `city`: 城市名称 |
| `get_weather_forecast` | 获取指定城市的天气预报 | `city`: 城市名称, `days`: 天数 |

**使用的 API**: Open-Meteo (免费,无需 API Key)

### 2. IpGroup (IP 查询)

| 工具名称 | 描述 | 参数 |
|---------|------|------|
| `query_ip_location` | 查询 IP 地址的地理位置 | `ipAddress`: IP 地址 |
| `get_public_ip` | 获取当前公网 IP | 无 |
| `validate_ip` | 验证 IP 地址格式 | `ipAddress`: IP 地址 |

**使用的 API**: ip-api.com (免费,无需 API Key)

### 3. JokeGroup (笑话)

| 工具名称 | 描述 | 参数 |
|---------|------|------|
| `get_random_joke` | 获取随机笑话 | 无 |
| `get_joke_by_type` | 按类型获取笑话 | `type`: 类型 (General/Programming/Misc/Dark/Pun) |
| `get_programming_joke` | 获取编程笑话 | 无 |
| `get_pun_joke` | 获取冷笑话 | 无 |

**使用的 API**: Official Joke API (免费,无需 API Key)

## 🔌 客户端接入方式

### 方式 1: MCP Streamable HTTP 客户端

```java
// Spring AI 客户端配置
spring:
  mcp:
    client:
      streamable-http:
        connections:
          my-server:
            url: http://localhost:8080/mcp
```

### 方式 2: SSE 客户端

```bash
# 建立 SSE 连接
curl -X GET http://localhost:8080/mcp \
     -H "Accept: text/event-stream"
```

### 方式 3: HTTP POST 调用

```bash
# 调用天气工具
curl -X POST http://localhost:8080/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "get_current_weather",
         "arguments": {"city": "北京"}
       }
     }'
```

### 方式 4: Python 客户端

```python
import requests

# 调用 MCP 工具
url = "http://localhost:8080/mcp"
payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get_current_weather",
        "arguments": {"city": "上海"}
    }
}

response = requests.post(url, json=payload)
print(response.json())
```

## 📝 配置说明

### application.yml

```yaml
spring:
  ai:
    mcp:
      server:
        protocol: STREAMABLE              # 使用 Streamable HTTP 协议
        name: mcp-server-demo
        version: 1.0.0
        type: SYNC
        instructions: "MCP 服务器测试示例 - 提供天气查询、IP查询、笑话等工具"
        capabilities:
          tool: true                      # 启用工具功能
          resource: false
          prompt: false
          completion: false
        streamable-http:
          mcp-endpoint: /mcp              # MCP 端点路径
          keep-alive-interval: 30s        # 保活间隔
```

## 🔧 依赖版本

| 组件 | 版本 |
|------|------|
| Spring Boot | 3.4.0 |
| Spring AI | 1.1.0-M1 |
| Spring AI Alibaba | 1.0.0.2 |
| JDK | 17+ |

## 📚 参考资料

- [Spring AI Alibaba 官方文档](https://java2ai.com)
- [MCP 协议规范](https://modelcontextprotocol.io)
- [Open-Meteo API](https://open-meteo.com)
- [ip-api.com](https://ip-api.com)
- [Official Joke API](https://official-joke-api.appspot.com)

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！