# SpringAIMCPStdioServer

**Repository Path**: wwkwesley/spring-aimcpstdio-server

## Basic Information

- **Project Name**: SpringAIMCPStdioServer
- **Description**: SpringAIMCPStdioServer 是一款基于 Spring Boot 官方 MCP 规范构建的标准 STDIO 服务端，专注实现Model Context Protocol（模型上下文协议），通过标准输入 / 输出（STDIO）与 AI 客户端（如 Claude、Cursor、Solo Coder 等）直接通信。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: MCP

## README

# MCP Weather STDIO Service

基于纯 Java 实现的标准 MCP（Model Context Protocol）天气查询服务，仅支持 STDIO 传输模式。

## 功能特性

- 符合 MCP 协议规范（2024-11-05）
- 仅支持 STDIO 传输模式（Claude Desktop / Trae 推荐）
- JSON-RPC 2.0 通信格式
- JSON Schema 工具参数描述
- 参数校验和标准错误码
- 无 Spring Boot 依赖，轻量高效

## 快速开始

### 1. 配置 API 密钥

**必须配置** OpenWeatherMap API 密钥（无默认值），支持两种方式：

| 方式 | 说明 |
|------|------|
| JVM 参数 | `-Dopenweathermap.api.key=你的密钥` |
| 环境变量 | `set OPENWEATHERMAP_API_KEY=你的密钥` |

### 2. 编译项目

```bash
mvn clean package -DskipTests
```

### 3. STDIO 模式（Claude Desktop / Trae）

#### 方式一：使用启动脚本（推荐）

`run_mcp_server.bat` 内容：

```batch
@echo off
:: 请在运行前设置环境变量：set OPENWEATHERMAP_API_KEY=你的密钥
:: 或将下面一行取消注释并填写你的密钥：
:: set OPENWEATHERMAP_API_KEY=你的密钥
java -jar "%~dp0target/mcp-weather-stdio-0.0.1-SNAPSHOT.jar"
```

`.mcp.json` 配置：

```json
{
  "mcpServers": {
    "my-springboot-mcp": {
      "type": "stdio",
      "command": "D:/codes/spring-aimcpstdio-server/run_mcp_server.bat"
    }
  }
}
```

#### 方式二：直接指定 java 命令

`.mcp.json` 配置：

```json
{
  "mcpServers": {
    "my-springboot-mcp": {
      "type": "stdio",
      "command": "java",
      "args": [
        "-Dopenweathermap.api.key=${OPENWEATHERMAP_API_KEY}",
        "-jar",
        "D:\\codes\\spring-aimcpstdio-server\\target\\mcp-weather-stdio-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}
```

#### 手动测试 STDIO

PowerShell 环境：

```powershell
$env:OPENWEATHERMAP_API_KEY='你的密钥'
$json = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"Test","version":"1.0.0"}}}'
$json | java -jar target/mcp-weather-stdio-0.0.1-SNAPSHOT.jar
```

## MCP 协议规范

### 支持的方法

| 方法名 | 描述 | 是否需要响应 |
|--------|------|-------------|
| `initialize` | MCP 握手，返回服务器信息和能力 | 是 |
| `notifications/initialized` | 初始化完成通知 | 否 |
| `tools/list` | 列出所有可用工具（含 JSON Schema） | 是 |
| `tools/call` | 调用指定工具（通过 params.name 指定工具名） | 是 |

### initialize

**请求**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "Test",
      "version": "1.0.0"
    }
  }
}
```

**响应**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {
        "listChanged": false
      }
    },
    "serverInfo": {
      "name": "mcp-weather-service",
      "version": "1.0.0"
    }
  }
}
```

### tools/list

**请求**:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
```

**响应**:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "获取指定城市的实时天气信息",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称，支持中文或英文"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }
}
```

### tools/call

**请求**（注意：方法名是 `tools/call`，不是工具名）：

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "Beijing"
    }
  }
}
```

**响应**（结果必须包装在 `content` 数组中）：

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"city\":\"Beijing\",\"temperature\":\"21°C\",\"feels_like\":\"19°C\",\"humidity\":\"45%\",\"pressure\":\"1016 hPa\",\"description\":\"晴\",\"main\":\"Clear\",\"wind_speed\":\"3.2 m/s\",\"wind_direction\":\"180°\",\"sunrise\":\"2025-05-04T05:30:00\",\"sunset\":\"2025-05-04T19:15:00\"}"
      }
    ]
  }
}
```

### notifications/initialized

客户端发送此通知表示初始化完成，**服务器不需要响应**。

```json
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}
```

## 支持的工具

### get_weather

获取指定城市的实时天气信息。

**参数**：

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| city | string | 是 | 城市名称，推荐使用英文（如 Beijing、Shanghai） |

> 注意：OpenWeatherMap API 对中文城市名支持有限，建议使用英文城市名查询。

**返回字段**：

| 字段名 | 类型 | 描述 |
|--------|------|------|
| city | string | 城市名称 |
| temperature | string | 当前温度（如 "21°C"） |
| feels_like | string | 体感温度（如 "19°C"） |
| humidity | string | 湿度（如 "45%"） |
| pressure | string | 气压（如 "1016 hPa"） |
| description | string | 天气描述（中文） |
| main | string | 主要天气状况 |
| wind_speed | string | 风速（如 "3.2 m/s"） |
| wind_direction | string | 风向角度（如 "180°"） |
| sunrise | string | 日出时间 |
| sunset | string | 日落时间 |

## 错误码

| 错误码 | 描述 |
|--------|------|
| -32601 | 方法未找到 |
| -32602 | 参数无效或缺失 |
| -32603 | 内部错误 |

## 项目结构

```
spring-aimcpstdio-server/
├── src/main/java/com/weather/mcp/
│   └── McpStdioServer.java              # 唯一实现类，纯 STDIO 服务器
├── run_mcp_server.bat                   # STDIO 模式启动脚本
├── .mcp.json                            # Claude Desktop / Trae 配置
├── pom.xml                              # Maven 项目配置
└── README.md                            # 本文档
```

### 核心类说明

| 类 | 职责 |
|----|------|
| `McpStdioServer` | 唯一入口类，直接读写 stdin/stdout 实现 MCP 协议 |

## 开发信息

| 项目 | 说明 |
|------|------|
| Java 版本 | 21 |
| 外部 API | OpenWeatherMap API |
| MCP 协议版本 | 2024-11-05 |
| 构建工具 | Maven |
| 传输模式 | STDIO 仅支持 |