# Test FastMCP

一个使用 FastMCP 框架构建的 MCP 服务器，提供基本的数学运算功能。

## 🚀 功能特性

- **加法运算** (`add`) - 计算两个整数的和
- **减法运算** (`subtract`) - 计算两个整数的差
- **乘法运算** (`multiply`) - 计算两个整数的积
- **除法运算** (`divide`) - 计算两个整数的商

## 📋 系统要求

- Python 3.12+
- uv 包管理器
- Cursor IDE (用于MCP集成)

## 🛠️ 安装和设置

### 1. 安装 uv

如果你还没有安装 uv，请先安装：

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或者使用 pip
pip install uv
```

### 2. 项目设置

1. **克隆项目**：
   ```bash
   git clone <repository-url>
   cd test_fast_mcp
   ```

2. **安装依赖**：
   ```bash
   uv sync
   ```

3. **激活虚拟环境**：
   ```bash
   uv shell
   ```

4. **运行服务器**：
   ```bash
   uv run python main.py
   ```

## 🔧 开发命令

- **启动开发服务器**：
  ```bash
  uv run dev
  ```

- **运行测试**：
  ```bash
  uv run test
  ```

- **代码格式化**：
  ```bash
  uv run format
  ```

- **代码检查**：
  ```bash
  uv run lint
  ```

- **导入排序**：
  ```bash
  uv run sort
  ```

### 添加新依赖

```bash
# 添加生产依赖
uv add package-name

# 添加开发依赖
uv add --dev package-name
```

### 更新依赖

```bash
uv lock --upgrade
```

## 🔌 Cursor 集成

### 配置 MCP 服务器

![](./images/cursor-test-fast-mcp.png)

将以下配置添加到你的 Cursor MCP 配置文件 (`~/.cursor/mcp.json`) 中：

```json
{
  "mcpServers": {
    "test-fast-mcp": {
      "command": "uv",
      "args": ["run", "python", "/Users/guosong/Desktop/Sina/Code/test_fast_mcp/main.py"],
      "env": {
        "PYTHONPATH": ".",
        "TRANSPORT": "stdio"
      }
    }
  }
}
```

**重要配置说明：**
- 使用**绝对路径**指向 `main.py` 文件
- 添加 `"TRANSPORT": "stdio"` 环境变量
- 确保 `PYTHONPATH` 设置正确

### 验证集成

1. 重启 Cursor IDE
2. 检查 MCP 服务器状态（应该显示 "4 tools enabled"）
3. 测试工具调用

## 📁 项目结构

```
test_fast_mcp/
├── main.py          # 主服务器文件，包含所有工具定义
├── pyproject.toml   # 项目配置和依赖管理
├── uv.lock         # 依赖锁定文件
├── mcp.json        # Cursor MCP 配置示例
├── test_tools.py   # 工具测试文件
└── README.md       # 项目说明文档
```

## 🧪 测试工具

运行测试脚本来验证数学函数：

```bash
python test_tools.py
```

预期输出：
```
Testing math functions:
add(5, 4) = 9
subtract(10, 3) = 7
multiply(6, 7) = 42
divide(15, 3) = 5.0
```

## 🔍 故障排除

### 常见问题

1. **"No tools or prompts" 错误**
   - 确保使用绝对路径配置
   - 添加 `TRANSPORT: "stdio"` 环境变量
   - 重启 Cursor IDE

2. **构建错误**
   - 运行 `uv sync` 重新安装依赖
   - 检查 `pyproject.toml` 配置

3. **工具无法调用**
   - 确认 MCP 服务器正在运行
   - 检查工具名称格式：`mcp_test-fast-mcp_<tool_name>`

### 调试步骤

1. 检查服务器状态：
   ```bash
   ps aux | grep "python main.py"
   ```

2. 查看服务器日志：
   ```bash
   uv run python main.py
   ```

3. 测试工具功能：
   ```bash
   python -c "from main import add; print(add(5, 4))"
   ```

## 🏗️ 开发指南

这个项目使用 FastMCP 框架，它简化了 MCP 服务器的创建过程。

### 添加新工具

1. 在 `main.py` 中定义新函数
2. 使用 `@mcp.tool` 装饰器
3. 添加详细的文档字符串
4. 重启服务器

示例：
```python
@mcp.tool
def new_tool(param: str) -> str:
    """Tool description.
    
    Args:
        param: Parameter description
        
    Returns:
        Return value description
    """
    return f"Processed: {param}"
```

### 工具命名规范

- 使用小写字母和下划线
- 提供清晰的参数类型注解
- 包含详细的文档字符串
- 添加适当的错误处理

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 支持

如果遇到问题，请：
1. 检查故障排除部分
2. 查看项目 Issues
3. 提交新的 Issue