# test-mcpserver

**Repository Path**: magein/test-mcpserver

## Basic Information

- **Project Name**: test-mcpserver
- **Description**: mcp-server的三种模式服务代码
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-04-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP 服务器测试项目

## 项目介绍

test-mcp 是一个基于 MCP (Model Context Protocol) 协议的测试服务器项目，主要用于测试 FastMCP 服务器的三种运行模式：

- **stdio 模式**：通过标准输入输出进行通信
- **SSE 模式**：通过 HTTP Server-Sent Events 进行通信
- **StreamableHTTP 模式**：通过流式 HTTP 连接进行通信

[fastmcp官网](https://gofastmcp.com/)

项目使用uv进行依赖管理,且使用虚拟环境运行, python版本为^3.10

```
#安装uv 存在则跳过
pip install uv
# 创建虚拟环境
uv venv venv
# 安装包
uv sync
# 加速安装
uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple
# Linux / Mac 激活虚拟环境
source venv/bin/activate
# Windows 激活虚拟环境
venv\Scripts\activate

# windows powershell 激活虚拟环境
venv\Scripts\activate.ps1
# 退出虚拟环境
deactivate

```

## 端口配置

项目使用 `.env` 文件统一管理服务器端口配置，配置文件位于项目根目录。

### 配置说明

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| sse_host | SSE 服务器监听地址 | 0.0.0.0 |
| sse_port | SSE 服务器监听端口 | 9600 |
| stream_http_host | StreamableHTTP 服务器监听地址 | 0.0.0.0 |
| stream_http_port | StreamableHTTP 服务器监听端口 | 9610 |

### 修改端口

1. 编辑项目根目录的 `.env` 文件
2. 修改对应的端口号
3. 保存文件
4. 重启服务器

## 模式说明

### 1. stdio 模式

- **通信方式**：通过标准输入输出（stdin/stdout）进行通信
- **特点**：
  - 不需要网络连接，轻量级
  - 适用于命令行工具、脚本调用等场景
  - 一次只能处理一个客户端的请求
- **功能**：
  - 读取 `document` 目录下的文本文件
  - 基于文件内容回答问题
  - 提供文件列表、文件读取、关键词搜索等工具
- **启动方式**：

```bash
 # 启动 stdio 模式服务器
  # 如果是虚拟环境,需要使用虚拟环境中的python解释器
  # 如根目录/.venv/Scripts/python.exe
  项目根目录/.venv/Scripts/python.exe 项目根目录/src/mode/stdio/main.py
```

![cherry配置](./media/cherry-config.png)

### 2. SSE 模式

- **通信方式**：通过 HTTP Server-Sent Events 进行双向通信
- **特点**：
  - 需要网络连接，支持浏览器客户端
  - 支持服务器主动向客户端推送消息
  - 保持会话状态
- **功能**：
  - 与 stdio 模式相同的文件操作功能
  - 通过 HTTP 端点提供服务
  - 支持实时通信
- **端口配置**：通过 `.env` 文件的 `sse_host` 和 `sse_port` 配置
- **启动方式**：
  ```bash
  python src/mode/sse/main.py
  ```
- **连接端点**：
  - SSE 连接：`http://localhost:9600/sse`
  - 消息发送：`http://localhost:9600/messages/`

### 3. StreamableHTTP 模式(推荐)

- **通信方式**：通过流式 HTTP 连接进行通信
- **特点**：
  - 需要网络连接，支持高性能场景
  - 低延迟，支持全双工通信
  - 适用于实时数据处理系统
- **功能**：
  - 与 stdio 模式相同的文件操作功能
  - 通过流式 HTTP 连接提供服务
- **端口配置**：通过 `.env` 文件的 `stream_http_host` 和 `stream_http_port` 配置
- **启动方式**：
  ```bash
  python src/mode/streamablehttp/main.py
  ```

  推荐使用asgi模式启动
  ```bash
  python src/mode/streamablehttp/asgi.py
  ```
- **连接端点**：
  - StreamableHTTP 连接：`http://localhost:9610/mcp`

/mcp可以在.env中配置，默认/mcp

## 客户端

1. 可以使用cherry连接
2. 可以使用极简的nodejs客户端连接 
```
# 请注意node版本, 请使用>=22.0.0版本
npx @modelcontextprotocol/inspector  
```

## 技术栈

使用 uv 进行管理。

| 依赖 | 版本 | 说明 |
|------|------|------|
| FastMCP | 3.0.0 | MCP 协议的 Python 实现，版本已锁定以避免破坏性变更 |
| Cyclopts | 5.0.0a1 | 命令行工具库，使用测试版以避免许可证合规性问题 |
| python-dotenv | 最新 | 环境变量管理 |

## 安装说明

### 1. 安装依赖

使用 uv 包管理器安装依赖：

```bash
# 1. 先安装 Cyclopts v5 的 Alpha 版本（避免许可证问题）
uv add "cyclopts>=5.0.0a1"

# 2. 再安装 FastMCP
uv add fastmcp==3.2.0

# 3. 安装 python-dotenv（用于环境变量管理）
uv add python-dotenv
```

### 2. 安装扩展功能（可选）

FastMCP 提供了一些可选插件，如后台任务处理：

```bash
pip install "fastmcp[tasks]"
```

### 3. 验证安装

```bash
# 检查 Python 版本
python --version

# 检查已安装的包
uv pip list | grep fastmcp
```

## 配置管理

### 配置文件结构

配置文件位于 `src/config.py`，提供了以下功能：

```python
from src.config import (
    get_sse_config,           # 获取 SSE 服务器配置
    get_streamablehttp_config, # 获取 StreamableHTTP 服务器配置
    get_document_dir          # 获取文档目录路径
)
```

### 配置加载流程

1. `config.py` 自动加载项目根目录的 `.env` 文件
2. 各模式服务器从 `config.py` 获取配置
3. 支持默认值，配置缺失时使用默认值

### 修改配置

#### 修改 SSE 端口

编辑 `.env` 文件：

```env
sse_port=9700
```

#### 修改 StreamableHTTP 端口

编辑 `.env` 文件：

```env
stream_http_port=9710
```

#### 修改监听地址

```env
sse_host=127.0.0.1
stream_http_host=127.0.0.1
```

## 使用指南

### stdio 模式使用

#### 1. 启动服务器

```bash
python src/mode/stdio/main.py
```

#### 2. 发送 MCP 请求

```bash
echo '{"jsonrpc": "2.0", "method": "list_document_files", "params": [], "id": 1}' | python src/mode/stdio/main.py
```

#### 3. 可用工具

- `list_document_files()`：列出 document 目录下的所有文件/文件夹
- `read_document_file(filename)`：读取指定文件的完整内容
- `search_document_files(keyword)`：搜索包含指定关键词的文件

### SSE 模式使用

#### 1. 启动服务器

```bash
python src/mode/sse/main.py
```

服务器启动后显示：

```
启动 MCP SSE Server...
服务器地址: http://0.0.0.0:9600
SSE 端点: http://0.0.0.0:9600/sse
消息端点: http://0.0.0.0:9600/messages/
Document 目录: ...\src\document
服务已启动，等待连接...
```

#### 2. 客户端连接

使用 MCP 客户端连接：

```python
from mcp.client import Client

client = Client("http://localhost:9600")
```

#### 3. 可用工具

- `list_document_files()`：列出 document 目录下的所有文件/文件夹
- `read_document_file(filename)`：读取指定文件的完整内容
- `get_server_info()`：获取服务器信息
- `add_numbers(a, b)`：计算两个数的和

### StreamableHTTP 模式使用

#### 1. 启动服务器

```bash
python src/mode/streamablehttp/main.py
```

服务器启动后显示：

```
启动 MCP StreamableHTTP Server...
服务器地址: http://0.0.0.0:9610
Document 目录: ...\src\document
服务已启动，等待连接...
```

#### 2. 客户端连接

使用支持 StreamableHTTP 的 MCP 客户端连接。

#### 3. 可用工具

- `list_document_files()`：列出 document 目录下的所有文件/文件夹
- `read_document_file(filename)`：读取指定文件的完整内容
- `get_server_info()`：获取服务器信息
- `add_numbers(a, b)`：计算两个数的和
- `hello(name)`：问候语

## 测试步骤

### 1. 环境准备

```bash
# 克隆项目
cd test-server

# 安装依赖
uv sync
```

### 2. 配置端口（可选）

根据需要修改 `.env` 文件中的端口配置。

### 3. 测试 stdio 模式

```bash
# 终端 1：启动 stdio 服务器
python src/mode/stdio/main.py

# 终端 2：发送测试请求
echo '{"jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 1}' | python src/mode/stdio/main.py
```

### 4. 测试 SSE 模式

```bash
# 终端 1：启动 SSE 服务器
python src/mode/sse/main.py

# 终端 2：测试连接（使用 curl）
curl http://localhost:9600/sse
```

### 5. 测试 StreamableHTTP 模式

```bash
# 终端 1：启动 StreamableHTTP 服务器
python src/mode/streamablehttp/main.py

# 终端 2：测试连接
curl http://localhost:9610/
```

## 文档目录

`src/document` 目录包含以下文档：

- `stdio.md`：stdio 模式详细说明
- `sse.md`：SSE 模式详细说明
- `stream.md`：Stream 模式详细说明
- `tool.md`：Tool 功能详细说明
- `prompt.md`：Prompt 功能详细说明
- `resource.md`：Resource 功能详细说明

## 许可证合规性

FastMCP 依赖 Cyclopts 库处理命令行功能。为避免 docutils 许可证的合规性问题，使用了 Cyclopts v5 的 Alpha 版本。

### 情况 A：个人开发者 / 小团队

直接按照正常流程安装 FastMCP 即可。

### 情况 B：需要通过合规扫描的大公司

使用 Cyclopts v5 的 Alpha 版本：

```bash
uv add "cyclopts>=5.0.0a1"
uv add fastmcp
```

## 注意事项

- FastMCP 版本更新比较激进，可能会在小版本更新中引入破坏性变更，因此建议锁定版本
- 所有模式的服务器都使用统一的 `src/document` 目录存放文档文件
- stdio 模式服务器只能读取 document 目录下的文本文件，不会访问目录外的文件
- 所有模式的服务器都会基于文件内容回答问题，不会编造信息
- 修改 `.env` 文件后需要重启服务器才能生效
- 确保配置的端口没有被其他服务占用

## 故障排除

### 端口占用

如果启动时提示端口被占用：

```bash
# Windows 查看端口占用
netstat -ano | findstr :9600

# 结束占用进程
taskkill /PID <进程ID> /F
```

### 导入模块失败

如果出现 `ModuleNotFoundError: No module named 'src'`：

确保在项目根目录运行 Python 脚本，或检查 `sys.path` 配置。

### 环境变量未生效

确保 `.env` 文件位于项目根目录，并且 `config.py` 能够正确加载。