# mcp_template

**Repository Path**: zhang_renyang/mcp_template

## Basic Information

- **Project Name**: mcp_template
- **Description**: mcp_template
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-13
- **Last Updated**: 2025-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Transport2

[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

一个基于 HTTP 协议的 Model Context Protocol (MCP) 传输实现，提供完整的客户端和服务器端功能。

## 📖 项目简介

MCP Transport2 是一个实现了 Model Context Protocol 的 Python 项目，支持通过 HTTP 协议进行 AI 模型与工具之间的通信。该项目包含：

- **MCP 客户端** (`client.py`) - 支持 HTTP 请求和 SSE 流连接
- **MCP 服务器** (`server.py`) - 提供完整的 MCP 协议服务
- **工具定义** (`tools.py`) - 可扩展的工具注册系统

## ✨ 主要特性

- 🔄 **协议兼容性**: 完全兼容 MCP 2025-06-18 协议版本
- 🌐 **HTTP 传输**: 基于标准 HTTP 协议，易于部署和集成
- 📡 **SSE 支持**: 支持 Server-Sent Events 流式通信
- 🛠️ **工具系统**: 可扩展的工具注册和执行框架
- 🔐 **会话管理**: 完整的会话生命周期管理
- 📝 **日志记录**: 详细的日志记录和调试信息

## 🚀 快速开始

### 环境要求

- Python 3.12 或更高版本
- 支持的操作系统：Windows, macOS, Linux

### 安装依赖

```bash
# 克隆项目
git clone <repository-url>
cd mcp_template

# 安装依赖
uv sync
```

### 启动服务器

```bash
# 启动 MCP 服务器
python server.py
```

服务器将在默认端口启动，您可以通过修改代码中的端口配置来自定义。

### 使用客户端

```python
# 启动 MCP 服务器
python client.py
```

## 📚 API 文档

### MCPClient 类

#### 初始化
```python
client = MCPClient(server_url: str)
```

#### 主要方法

| 方法 | 描述 | 参数 |
|------|------|------|
| `connect()` | 连接到 MCP 服务器 | - |
| `disconnect()` | 断开与服务器的连接 | - |
| `call_tool(name, arguments)` | 调用指定工具 | `name`: 工具名称, `arguments`: 工具参数 |
| `list_tools()` | 获取可用工具列表 | - |
| `open_sse_stream()` | 打开 SSE 流连接 | - |

### MCPServer 类

#### 主要功能

- **协议处理**: 处理 MCP 协议的各种请求类型
- **会话管理**: 管理客户端会话的生命周期
- **工具注册**: 支持动态工具注册和管理
- **错误处理**: 完善的错误处理和响应机制

## 🛠️ 工具系统

### 内置工具

#### calculate
执行数学计算表达式

**参数**:
- `expression` (string): 数学表达式，如 "2 + 2 * 3"

**示例**:
```python
result = client.call_tool("calculate", {"expression": "sin(45) + cos(30)"})
```

### 添加自定义工具

在 `tools.py` 文件中添加新的工具定义：

```python
tools = [
    # 现有工具...
    {
        "name": "custom_tool",
        "description": "自定义工具描述",
        "inputSchema": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "参数描述"
                }
            },
            "required": ["param1"]
        }
    }
]
```

## 🔧 配置选项

### 服务器配置

在 `server.py` 中修改以下配置：

```python
# 协议版本
self.protocol_version = "2025-06-18"

# 服务器信息
self.server_info = {"name": "MCP服务器", "version": "1.0.0"}

# 服务器能力
self.capabilities = {"tools": {}, "resources": {}, "prompts": {}}
```

### 客户端配置

在 `client.py` 中修改以下配置：

```python
# 协议版本
self.protocol_version = "2025-06-18"

# 客户端信息
self.client_info = {"name": "MCP客户端", "version": "1.0.0"}
```

## 📝 日志配置

项目使用 Python 标准 `logging` 模块，默认日志级别为 `INFO`。

### 修改日志级别

```python
import logging

# 设置为 DEBUG 级别获取更详细信息
logging.basicConfig(level=logging.DEBUG)

# 设置为 WARNING 级别减少日志输出
logging.basicConfig(level=logging.WARNING)
```

## 🧪 测试

### 运行测试

```bash
# 启动服务器
python server.py

# 在另一个终端中运行客户端测试
python client.py
```

## 📁 项目结构

```
mcp_template/
├── client.py          # MCP 客户端实现
├── server.py          # MCP 服务器实现
├── tools.py           # 工具定义
├── pyproject.toml     # 项目配置
├── uv.lock           # 依赖锁定文件
├── .python-version    # Python 版本要求
├── .gitignore        # Git 忽略文件
└── README.md         # 项目说明文档
```

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 Issue
- 发送邮件至项目维护者

## 🙏 致谢

感谢所有为 MCP 协议和本项目做出贡献的开发者和用户。


**注意**: 本项目仅供学习和研究使用，请在生产环境中谨慎使用。