📖 项目简介

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

🎯 核心价值

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

🏗️ 系统架构

🎯 核心组件

🔄 数据流向

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

✨ 核心特性

🚀 快速开始

📦 安装方式

🎯 使用 uv 安装（推荐）

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

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

# 3. 验证安装
minder --version

🐳 Docker 部署

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

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

💡 使用示例

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

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

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 服务器：

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}")

异步操作示例：

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())

使用上下文管理器：

# 同步上下文管理器
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 服务器：

# 基本用法
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 界面

# 启动Web界面
mcp-web

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

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

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

3. 启动 API 服务器

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

# 指定主机和端口



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

4. RESTful API 使用

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

# 健康检查
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 使用

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 客户端使用

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())

运行示例

# 运行基本使用示例
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}

启动器命令

# 按文件路径启动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

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)

📁 项目结构

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配置

⚙️ 参数说明

🧪 开发指南

🚀 快速开始

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

# 运行测试
pytest

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

开发命令

# 运行测试
pytest

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

# 代码检查
flake8 minder tests
mypy minder

# 构建包
python -m build

手动运行

# 运行所有测试
pytest

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

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

# 格式化代码
black .

# 排序导入
isort .

# 类型检查
mypy minder/

# 代码风格检查
flake8 minder/

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

🤝 贡献

我们欢迎所有形式的贡献！请查看 贡献指南 了解如何参与项目开发。

贡献方式

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

📄 许可证

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

🙏 致谢

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

📞 支持与贡献