内容
高级主机-客户端-服务器应用程序
[](https://github.com/yourusername/advanced-mcp-host-client-server-app/actions)
[](https://www.python.org/downloads/)
[
[](TESTING.md)
基于HTTP的模型上下文协议（MCP）生产就绪实现，集成LLM工具，支持OpenAI GPT模型，具有全面的安全功能、弹性模式和企业级测试。
## 🎯 主要功能
### 核心能力
- ✅ **基于HTTP的MCP** - 分布式工具协议基于HTTP
- ✅ **LLM集成** - Open模型与函数调用
- ✅ **文件系统工具** - 安全的文件读写
- ✅ **Web UI** - Gradio界面用于探索和测试
- ✅ **AI代理** - 基于用户自主工具执行
### 生产就绪
- ✅ **配置管理** - JSON配置与环境变量替换
- ✅ **安全 路径遍历预防，输入验证，UTF-8强制
- ✅ **弹性** - 连接重试，心跳验证，错误恢复
- ✅ **日志** - 可配置级别的结构化日志
- ✅ **测试** - 75+测试用例，90%+覆盖率，CI/CD流水线
- ✅ **文档** - 配置和测试的综合指南
## 📦 包含内容
```
🎯 mcp_http_server.py HTTP MCP服务器（FastMCP）
🎨 mcp_http_client_app.py Web UI（Gradio）用于探索
🤖 mcp_http_host_app.py OpenAI集成的AI代理
📋 mcp_config.py 配置管理与优先级解析
⚙️ mcp_config.json 生产配置
🧪 tests/ 75+测试用例，使用pytest
🔄 .github/workflows/ci_cd.yml GitHub Actions CI/CD流水线
📚 Documentation 快速入门，配置，测试和评审指南
```
## 🚀 快速入门（5分钟）
### 前置条件
```bash
python 3.9+ # 用于异步/等待和类型提示
pip 包管理器 # 用于依赖安装
OpenAI API密钥 # 用于GPT模型访问
```
### 安装
1. **克隆和设置**
```bash
git clone <仓库>
cd advanced-mcp-host-client-server pip install -r requirements.txt
```
2. **设置API密钥**
```bash
export OPENAI_API_KEY=sk-your-key-here
```
3. **启动服务器**
```bash
python mcp_http_server.py
服务器运行在 http://127.0.0.1:8000
```
4. **启动AI主机**（新终端）
```bash
python mcp_http_host_app.py http://127.0.0.1:8000 ./workspace
# 访问 http://127.0.0.1:7862
```
5. **与AI聊天**
- 访问 `http://127.0.0.1:7862`
- 输入: "列出工作空间中的文件"
- AI自动调用 `list_files` 工具！
参见 [QUICKSTART.md](QUICKSTART.md) 获取详细的设置说明。
## 📖 文档
| 文档 | 目的 |
|----------|---------|
| [QUICKSTART.md](QUICKSTART.md) | 5分钟设置和常见任务 |
| [CONFIG.md](CONFIG.md) | 配置参考与示例 |
| [TESTING.md](TESTING.md) | 测试指南与75+测试用例 |
| [PROJECT_REVIEW.md](PROJECT_REVIEW.md) | 完整的技术评审和架构 |
## 🏗️ 架构
### 组件图
```
┌──────────────────────────────────────────────────────┐
│ MCP应用套件 │
└──────────────────────────────────────────────────────┘
GUI客户端 AI主机应用 API客户端
(Gradio UI) (GPT + 工具调用) (自定义客户端)
│ │ │
└─────────────────────┼────────────────────────┘
│
HTTP/Streamable
│
┌─────────▼──────────┐
│ HTTP MCP服务器 │
│ (FastMCP) │
│ │
│ • 文件工具 │
│ • 资源 │
│ • 提示 │
│ • 分析 │
└────────────────────┘
│
工作空间
(./workspace文件)
```
### 组件职责
- **mcp_http_server.py**: 通过HTTP MCP公开文件系统和分析工具
- **mcp_http_client_app.py**: 用于探索工具、资源和提示的Web UI
- **mcp_http_host_app.py**: 调用工具的LLM代理
- **mcp_config.py**: 具有优先级解析的集中式配置
- **tests/**: 用于可靠性的综合测试套件
## 🔒 安全功能
| 功能 | 目的 | 示例 |
|---------|---------|---------|
| **根验证** | 防止目录遍历 | 阻止 `../../etc/passwd` |
| **路径检查** | 阻止绝对路径 | 拒绝 `/etc/passwd` |
| **输入验证** | 净化参数 | 检查特殊字符 |
| **UTF-8编码** | 防止编码攻击 | 强制UTF-8文件 |
| **错误安全** | 无路径泄露 | 返回安全错误消息 |
## ⚙️ 配置
### 三层（优先级）
```
1. 命令行参数 (最高优先级)
└─ python app.py --model gpt-4o
2. 配置文件
└─ mcp_config.json with "model": "gpt-4o-mini"
3. 环境变量
└─ export OPENAI_MODEL=gpt-4o-mini
4. 硬编码默认值 (最低优先级)
└─ DEFAULT_MODEL = "gpt-4o-mini"
```
### 示例mcp_config.json
```json
{
"openai": {
"api_key": "${OPENAI_API_KEY}",
"model": "gpt-4"
},
"server": {
"host": "127.0.0.1",
"port": 8000
},
"gui": {
"host": "127.0.0.1",
"port": 7862
},
"logging": {
level": "INFO"
}
```
参见 [CONFIG.md) 获取指南。
##
### 运行所有测试
pip install-test.txt
pytest -v
```
### 测试覆盖率
- **整体**: 90%+
- **配置模块**: 95%+
- **服务器模块**: 90%+
- **客户端模块**: 85%+
### 测试类型
- **单元测试** (60%): 快速、隔离的组件测试
- **安全测试** (20%): 漏洞和攻击预防
- **集成测试**): 现实 [TESTINGING.md) 获取综合测试指南。
## 功能
| 影响 | 详情 |
|---------|--------|---------|
| **连接重试** | 自动恢复 | 3次尝试，1秒延迟 |
| **心跳** | 检测死连接 | 2秒验证超时 |
| **历史记录限制** | 防止令牌溢出 | 最大20条消息 |
| **错误恢复** | 优雅降级 | 记录错误，继续 |
## 📊 性能
| 指标 | 值 |
|--------|-------|
| **服务器吞吐量** | ~100+ 请求/秒 |
| **工具调用延迟** | <50毫秒（本地网络） |
| **连接时间** | <1秒（带重试） |
| **内存基准** | ~100MB |
| **最大历史记录** | 20条消息（有界） |
## 🚀 部署
### 本地开发
```bash
# 终端1: 服务器
python mcp_http_server.py
# 终端2: GUI客户端
python mcp_http_client http://localhost:workspace
# : AI主机
cp_http_host_app.py http://localhost:8000 ./workspace
```
### Docker
docker build -cp-app .
docker run OPENAI_API_KEYAI_API_KEY -p 8000:8000 -p 7862:7862 mcp-app
```
Hub Actions CI/CD
- ✅ Python 3.9-3.11的自动化测试
- ✅ 在LinuxOS、Windows上运行 ✅ 代码质量检查ylint，black，，mypy）
- ✅ 安全检查（bandit，safety）
- ✅ 覆盖率报告
参见 [PROJECT_REVIEW.md](PROJECT_REVIEW.md) 获取部署详情。
## 🛠️ 工具与技术
### 核心
- **FastMCP** 2.12.5: MCP服务器框架
- **OpenAI SDK** 2.6.1: GPT模型集成
- **G 5.49.1: Web UI框架
- **Uvicorn** 0.38.0: ASGI服务器
- **HTTPx**: HTTP客户端
### 测试
- **Pytest** 7.4.3: 测试框架
- **Pytest-asyncio**: 异步测试支持
- **Pytest-cov**:率报告
- ** Pylint,8, MyPy质量
📝 API参考 服务器工具
read_file(filepath: -> str
空间读取文件(filepath: str,) -> str 写入文件空间
list_files(directory: str List[str # 列出目录内容_code(code: str: str = "")
# 使用LL代码
```
###方法
```python client.connect()
await client.list_tools()
await client.call, arguments)
await_resources()
await client.read)
await client.list()
await client.get_prompt(name, arguments)
```
## 🔐 安全考虑
###实施
- 路径
- 输入验证
- UTF-
- 错误消息- 依赖安全CI/CD）
### ⚠️ 待实施
- API身份验证
- BAC
- 速率- 请求签名 数据加密存储
参见 [PROJECT_REVIEW.md](PROJECT_REVIEW.md#security-checklist) 获取安全详情。
🤝 贡献
复刻仓库
创建功能分支 (`gitb feature/amazing3. 提交更改 commit -m ' feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature. 打开拉取请求
所有PR必须：
- ✅ 通过所有测试
- ✅ 保持90%+覆盖率
- ✅ 通过代码质量检查
- ✅
## 📋
### ✅ 已完成 HTTP MCP服务器与文件系统工具
- Gr UI用于工具探索
- OpenAI集成与函数调用
- 配置管理系统
- 75+测试用例与CI/CD流水线
- 综合文档
- 安全强化
- 弹性模式
### 🚧 进行中
- 增强监控和指标
- 性能优化
- 扩展日志
### 📋 计划中
- 多实例负载均衡
- 持久化对话存储
- 数据库支持的文件存储
- 身份验证/授权
- WebSocket支持
- 批量操作
- 自定义工具模板
## 📄 许可证
该项目使用MIT许可证 - 参见 [LICENSE](LICENSE) 文件获取详情。
## 👥 作者
Deepak Upadhyay - 工程
## 🙏 致谢
- FastMCPMCP服务器- OpenAI的GPT模型API
- Gradio的Web UI组件
- Python等待生态系统
## 📞 支持
如有问题、疑问或功能请求：
1.文档**
-ICKSTART.md](QUICKSTART.md) - 常见任务
- [CONFIG.md](CONFIG.md) - 配置帮助
- [TESTING.md](TESTING.md) - 测试文档
2. **查看示例**
- 查看 [tests/](tests/) 获取使用示例
- 查看 [mcp_config.json](mcp_config.json) 获取设置
3. **调试问题**
- 启用调试日志：`LOG_LEVEL=DEBUG`
- 查看 [PROJECT_REVIEW.md](PROJECT_REVIEW.md) 获取架构
- 运行测试：`pytest -v` 验证设置
## 🎓 学习资源
- [模型上下文协议规范](https://modelcontextprotocol.io/)
- [OpenAI函数调用](https://platform.openai.com/docs/guides/function-calling)
- [FastMCP文档](https://github.com/jlowin/fastmcp)
-
