mcp-minder 0.1.3
MCP服务器管理框架 - 用于管理和监控MCP (Model Context Protocol) 服务器
License: MIT
Requires Python: >=3.12
Keywords: framework, management, mcp, model-context-protocol, server

<div align="center">

# 🚀 MCP Minder

**简单而强大的 MCP 服务器管理框架**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat&logo=fastapi)](https://fastapi.tiangolo.com/)
[![Gradio](https://img.shields.io/badge/Gradio-FF4B4B?style=flat&logo=gradio)](https://gradio.app/)
[![Docker](https://img.shields.io/badge/Docker-2496ED?style=flat&logo=docker&logoColor=white)](https://www.docker.com/)

[📖 文档](docs/) • [🚀 快速开始](#-快速开始) • [💡 示例](#-使用示例) • [🤝 贡献](docs/contributing.md)

</div>

---

## 📖 项目简介

**MCP Minder** 是一个专为 MCP (Model Context Protocol) 服务器设计的全栈管理框架。它提供了从代码生成到服务部署的完整解决方案，让您能够快速构建、管理和扩展 MCP 服务器。

### 🎯 核心价值

- **⚡ 极速开发**: 基于模板的快速代码生成
- **🔧 链式构建**: 直观的 MCPBuilder API
- **🌐 全栈管理**: 从开发到部署的完整工具链
- **📦 开箱即用**: 多种部署方式，满足不同需求

## 🏗️ 系统架构

### 🎯 核心组件

<table>
<tr>
<td width="25%" align="center">

**🎨 用户交互层**
- 💻 CLI 工具
- 🖥️ Web 界面
- 📚 Python 客户端

</td>
<td width="25%" align="center">

**🌐 API 服务层**
- ⚡ FastAPI 服务器
- 🔄 RESTful API
- 📋 Pydantic 模型

</td>
<td width="25%" align="center">

**⚙️ 核心业务层**
- 🔧 服务管理器
- 🚀 进程启动器
- 📝 代码生成器
- 🔗 MCPBuilder

</td>
<td width="25%" align="center">

**💾 数据存储层**
- 📄 服务配置
- 📋 日志文件
- 📁 MCP 文件

</td>
</tr>
</table>

### 🔄 数据流向

<div align="center">

**用户交互** → **API 服务** → **核心业务** → **数据存储**

</div>

> 💡 **架构特点**: 分层设计，职责清晰，易于扩展和维护

## ✨ 核心特性

<table>
<tr>
<td width="50%">

### 🚀 快速开发
- **模板生成**: 基于模板快速生成 MCP 服务器
- **链式构建**: MCPBuilder 提供直观的链式 API
- **函数解析**: 自动解析函数签名和参数类型
- **一键部署**: 支持本地生成和远程部署

</td>
<td width="50%">

### 🔧 服务管理
- **进程管理**: 内置服务启动器和进程监控
- **状态跟踪**: 实时服务状态和日志管理
- **配置持久化**: JSON 格式的服务配置存储
- **错误处理**: 完善的异常处理和错误提示

</td>
</tr>
<tr>
<td width="50%">

### 🌐 多端支持
- **CLI 工具**: 命令行快速操作
- **Web 界面**: 基于 Gradio 的友好界面
- **Python API**: 完整的编程接口
- **REST API**: 标准化的 HTTP 接口

</td>
<td width="50%">

### 📦 部署灵活
- **本地开发**: 支持本地文件生成和测试
- **远程部署**: 支持镜像源远程部署
- **Docker 支持**: 容器化部署方案
- **异步支持**: 完整的异步/同步 API

</td>
</tr>
</table>

## 🚀 快速开始

### 📦 安装方式

<div align="center">

| 方式 | 命令 | 适用场景 |
|------|------|----------|
| **uv** (推荐) | `uv add mcp-minder` | 开发环境 |
| **pip** | `pip install mcp-minder` | 生产环境 |
| **Docker** | `docker-compose up -d` | 容器部署 |
| **源码** | `git clone && uv sync` | 开发贡献 |

</div>

#### 🎯 使用 uv 安装（推荐）

```bash
# 1. 激活虚拟环境
uv venv
source .venv/bin/activate  # Linux/macOS
# 或 .venv\Scripts\activate  # Windows

# 2. 安装项目依赖
uv pip install -e .

# 3. 验证安装
minder --version
```

#### 🐳 Docker 部署

```bash
# 快速启动（同时启动 API 和 Web 界面）
docker-compose up -d

# 访问 Web 界面
open http://localhost:8000
```

## 💡 使用示例

### 🎯 方式一：MCPBuilder 链式 API（推荐）

最直观的构建方式，支持函数自动解析和链式调用：

```python
from minder import MCPBuilder

# 定义函数
async def query_weather(city: str) -> str:
    """查询城市天气"""
    return f"{city}的天气是晴天"

# 使用链式 API 构建和部署
builder = (MCPBuilder()
           .for_mcp_server("天气查询服务")
           .add_tool(query_weather)  # 直接传入函数，自动解析
           .from_market("http://localhost:8000", "your-token")  # 设置镜像源
           .set_up("开发者"))  # 设置作者

# 生成本地模板
template = builder.generate_template_content()
print(template)

# 保存到文件
builder.save_template("weather_server.py")

# 或者直接部署到镜像源
success = await builder.generate_and_deploy()
print(f"部署成功: {success}")
```

### 🔧 方式二：客户端库管理

使用客户端库来远程管理 MCP 服务器：

```python
from minder.client import McpMinder

# 创建客户端实例
minder = McpMinder.get_service(
    url="http://localhost:8000",  # MCP Minder API 服务器地址
    servername="my_mcp_server"    # 要管理的 MCP 服务名称
)

# 同步操作
info = minder.get_info_sync()
print(f"服务信息: {info}")

# 启动服务
result = minder.start_sync(port=7860)
print(f"启动结果: {result}")

# 检查状态
status = minder.get_status_sync()
print(f"服务状态: {status}")

# 停止服务
result = minder.stop_sync()
print(f"停止结果: {result}")
```

**异步操作示例：**

```python
import asyncio

async def manage_service():
    minder = McpMinder.get_service("http://localhost:8000", "my_mcp_server")
    
    # 获取服务信息
    info = await minder.get_info()
    print(f"服务信息: {info}")
    
    # 启动服务
    result = await minder.start(port=7860)
    print(f"启动结果: {result}")
    
    # 停止服务
    result = await minder.stop()
    print(f"停止结果: {result}")

# 运行异步函数
asyncio.run(manage_service())
```

**使用上下文管理器：**

```python
# 同步上下文管理器
with McpMinder.get_service("http://localhost:8000", "my_mcp_server") as minder:
    info = minder.get_info_sync()
    result = minder.start_sync(port=7860)
    print(f"服务启动: {result}")

# 异步上下文管理器
async def use_context_manager():
    async with McpMinder.get_service("http://localhost:8000", "my_mcp_server") as minder:
        info = await minder.get_info()
        result = await minder.start(port=7860)
        print(f"服务启动: {result}")

asyncio.run(use_context_manager())
```


### 💻 方式三：命令行工具

快速启动和管理 MCP 服务器：

```bash
# 基本用法
minder my_server.py

# 完整自定义
minder my_server.py \
  -s "user_service" \
  -t "get_user_info" \
  -p "user_id" \
  --param-type "int" \
  --return-type "dict" \
  -d "获取用户信息" \
  -c "output = f'用户ID: {user_id}'" \
  --port 7860 \
  -a "张三"
```

### 2. 启动 Web 界面

```bash
# 启动Web界面
mcp-web

# 指定端口
mcp-web --port 7860

# 启用分享链接
mcp-web --share

# 启用调试模式
mcp-web --debug
```

### 3. 启动 API 服务器

```bash
# 启动API服务器
mcp-api-server

# 指定主机和端口



# 启用调试模式
mcp-api-server --debug
```

### 4. RESTful API 使用

启动API服务器后，可以通过HTTP请求管理服务：

```bash
# 健康检查
curl http://localhost:8000/health

# 创建服务
curl -X POST http://localhost:8000/api/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_service",
    "file_path": "my_server.py",
    "port": 7860,
    "description": "我的MCP服务"
  }'

# 启动服务 (按ID)
curl -X POST http://localhost:8000/api/services/{service_id}/start

# 启动服务 (按名称，推荐)
curl -X POST http://localhost:8000/api/services/by-name/{service_name}/start

# 停止服务 (按名称)
curl -X POST http://localhost:8000/api/services/by-name/{service_name}/stop

# 删除服务 (按名称)
curl -X DELETE http://localhost:8000/api/services/by-name/{service_name}

# 获取服务日志 (按名称)
curl http://localhost:8000/api/services/by-name/{service_name}/logs?lines=100

# 获取服务信息 (按名称)
curl http://localhost:8000/api/services/by-name/{service_name}

# 获取服务列表
curl http://localhost:8000/api/services

# 生成MCP服务器
curl -X POST http://localhost:8000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "output_path": "new_server.py",
    "service_name": "new_service",
    "tool_name": "new_tool",
    "tool_code": "output = f\"处理结果: {input_data}\""
  }'
```

### 5. API 文档

启动服务后，访问以下地址：
- API文档: http://localhost:8000/docs
- Web界面: http://localhost:7860

### 6. Python API 使用

```python
from minder import MCPGenerator, MCPLauncher, ServiceManager

# 生成MCP服务器
generator = MCPGenerator()
success = generator.generate(
    output_path="my_server.py",
    service_name="user_service",
    tool_name="get_user_info",
    tool_param_name="user_id",
    tool_param_type="int",
    tool_return_type="dict",
    tool_description="获取用户信息",
    tool_code="output = f'用户ID: {user_id}'",
    service_port=7860,
    author="张三"
)

# 服务管理
service_manager = ServiceManager()
service_id = service_manager.register_service(
    name="user_service",
    file_path="my_server.py",
    port=7860,
    description="用户服务"
)

# 启动服务 (按ID)
result = service_manager.start_service(service_id)
if result['success']:
    print(f"服务启动成功，PID: {result['pid']}")

# 启动服务 (按名称，推荐)
result = service_manager.start_service_by_name("my_service")
if result['success']:
    print(f"服务启动成功，PID: {result['pid']}")

# 停止服务 (按名称)
result = service_manager.stop_service_by_name("my_service")
if result['success']:
    print("服务停止成功")

# 删除服务 (按名称)
result = service_manager.delete_service_by_name("my_service")
if result['success']:
    print("服务删除成功")

# 获取服务日志 (按名称)
logs = service_manager.get_service_logs_by_name("my_service", lines=100)
if logs['success']:
    print(f"日志内容: {logs['logs']}")
```

### 7. API 客户端使用

```python
import asyncio
from minder.examples.api_usage import MCPMinderAPIClient

async def main():
    client = MCPMinderAPIClient("http://localhost:8000")
    
    # 健康检查
    health = await client.health_check()
    print(f"服务状态: {health['status']}")
    
    # 生成MCP服务器
    result = await client.generate_mcp_server({
        "output_path": "api_server.py",
        "service_name": "api_service",
        "tool_name": "api_tool"
    })
    
    # 创建并启动服务
    service = await client.create_service({
        "name": "api_service",
        "file_path": "api_server.py",
        "port": 7860
    })
    
    # 启动服务 (按ID)
    await client.start_service(service['service']['id'])
    
    # 启动服务 (按名称，推荐)
    await client.start_service_by_name("api_service")
    
    # 停止服务 (按名称)
    await client.stop_service_by_name("api_service")
    
    # 获取服务日志 (按名称)
    logs = await client.get_service_logs_by_name("api_service", lines=100)
    
    await client.close()

asyncio.run(main())
```

### 运行示例

```bash
# 运行基本使用示例
python -m minder.examples.basic_usage

# 运行启动器使用示例
python -m minder.examples.launcher_usage
```

## 服务启动器

MCP Generator 还提供了内置的服务启动器，用于管理生成的MCP服务器进程。

### 按名称操作服务 (推荐)

MCP Minder 支持按服务名称直接操作服务，无需记住复杂的服务ID。这种方式更加直观和便捷：

**优势：**
- 🎯 **直观易用**: 直接使用服务名称，无需查找服务ID
- 🚀 **快速操作**: 减少查找步骤，提高操作效率
- 🔍 **易于记忆**: 服务名称比UUID更容易记忆
- 📝 **脚本友好**: 在自动化脚本中使用更简单

**支持的操作：**
- 启动服务: `mcp-launcher start-by-name my_service`
- 停止服务: `mcp-launcher stop-by-name my_service`
- 删除服务: `mcp-launcher delete-by-name my_service`
- 查看日志: `mcp-launcher logs-by-name my_service`
- 获取信息: API `/api/services/by-name/{service_name}`

### 启动器命令

```bash
# 按文件路径启动MCP服务
mcp-launcher start my_server.py
mcp-launcher start my_server.py --port 7860 --host 127.0.0.1

# 按文件路径停止MCP服务
mcp-launcher stop my_server.py

# 按服务名称启动服务 (推荐)
mcp-launcher start-by-name my_service

# 按服务名称停止服务 (推荐)
mcp-launcher stop-by-name my_service

# 按服务名称删除服务
mcp-launcher delete-by-name my_service

# 按服务名称查看日志
mcp-launcher logs-by-name my_service --lines 100

# 列出运行中的服务
mcp-launcher list

# 列出所有服务 (包括状态信息)
mcp-launcher list-services
mcp-launcher list-services --status running

# 停止所有服务
mcp-launcher stop-all

# 同步服务状态
mcp-launcher sync-services

# 按文件路径查看服务日志
mcp-launcher logs my_server.py
mcp-launcher logs my_server.py --lines 100
```

### 启动器Python API

```python
from minder import MCPLauncher

launcher = MCPLauncher()

# 启动服务
result = launcher.start_service(
    script_path="my_server.py",
    use_uv=True,
    host="127.0.0.1",
    port=7860,
    background=True
)

# 列出运行中的服务
services = launcher.list_running_services()

# 停止服务
launcher.stop_service("my_server.py")

# 查看日志
logs = launcher.get_service_logs("my_server.py", lines=50)
```

## 📁 项目结构

<div align="center">

```
mcp-minder/
├── 🎯 minder/                # 主包
│   ├── core/              # ⚙️ 核心功能
│   │   ├── generator.py   # 📝 MCP生成器核心
│   │   ├── launcher.py    # 🚀 MCP服务启动器
│   │   ├── service_manager.py # 🔧 服务管理器
│   │   └── mcp_builder.py # 🔗 MCPBuilder 链式构建器
│   ├── cli/               # 💻 命令行接口
│   │   ├── main.py        # 🎯 生成器CLI
│   │   ├── launcher_cli.py # 🚀 启动器CLI
│   │   ├── api_cli.py     # 🌐 API服务器CLI
│   │   └── web_cli.py     # 🖥️ Web界面CLI
│   ├── api/               # 🌐 FastAPI接口
│   │   ├── main.py        # ⚡ FastAPI应用
│   │   ├── models.py      # 📋 API数据模型
│   │   └── routers/       # 🛣️ API路由
│   ├── web/               # 🖥️ Web界面
│   │   └── gradio_app.py  # 🎨 Gradio应用
│   └── client/            # 📚 客户端库
│       └── api_client.py  # 🔌 API客户端
├── 📖 docs/               # 文档
├── 🧪 tests/              # 测试
├── 💡 examples/           # 使用示例
└── 🐳 docker-compose.yml  # Docker配置
```

</div>

## ⚙️ 参数说明

<div align="center">

| 参数 | 短选项 | 说明 | 默认值 |
|------|--------|------|--------|
| output | - | 输出文件路径 | 必需 |
| service-name | -s | 服务名称 | 从文件名提取 |
| tool-name | -t | 工具函数名称 | 从服务名生成 |
| param-name | -p | 工具参数名称 | path |
| param-type | - | 工具参数类型 | str |
| return-type | - | 工具返回类型 | str |
| description | -d | 工具描述 | MCP工具 |
| port | - | 服务端口 | 随机 |
| author | -a | 作者 | 开发者 |

</div>

## 🧪 开发指南

### 🚀 快速开始

```bash
# 安装开发环境
uv pip install -e ".[dev]"

# 运行测试
pytest

# 启动开发服务器
mcp-api-server --host 0.0.0.0 --port 8000 --reload
```

### 开发命令

```bash
# 运行测试
pytest

# 代码格式化
black minder tests
isort minder tests

# 代码检查
flake8 minder tests
mypy minder

# 构建包
python -m build
```

### 手动运行

```bash
# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_generator.py

# 运行测试并显示覆盖率
pytest --cov=minder

# 格式化代码
black .

# 排序导入
isort .

# 类型检查
mypy minder/

# 代码风格检查
flake8 minder/

# 安装 pre-commit 钩子
pre-commit install
```

## 🤝 贡献

我们欢迎所有形式的贡献！请查看 [贡献指南](docs/contributing.md) 了解如何参与项目开发。

### 贡献方式

- 🐛 报告 Bug
- 💡 提出新功能建议
- 📝 改进文档
- 🔧 提交代码修复
- 🧪 添加测试用例

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

感谢所有为这个项目做出贡献的开发者们！

## 📞 支持与贡献

<div align="center">

### 🤝 获取帮助

如果您遇到任何问题或有任何建议，请：

| 方式 | 链接 | 说明 |
|------|------|------|
| 🐛 **问题反馈** | [提交 Issue](https://github.com/your-org/mcp-minder/issues) | 报告 Bug 或功能请求 |
| 💬 **社区讨论** | [参与讨论](https://github.com/your-org/mcp-minder/discussions) | 技术交流和使用心得 |
| 📖 **查看文档** | [项目文档](docs/) | 详细的使用指南 |
| 🔗 **MCPBuilder** | [使用指南](docs/MCP_BUILDER_README.md) | 链式 API 详细说明 |

### ⭐ 如果这个项目对您有帮助，请给我们一个 Star！

</div>