MCP 服务器

MCP Server Development Framework

这是一个专为开发企业级 MCP 服务器而设计的通用开发框架。

mlzoo

开发者工具

访问服务器

README

MCP 服务端开发框架

English Document

概述

一个专业级的框架，专为企业级模型上下文协议 (MCP) 工具开发而设计，旨在标准化 MCP 服务端开发流程，帮助开发者快速构建高质量的 AI 工具。通过将 FastAPI 与 FastAPI-MCP 集成，该框架能够实现从传统 API 到 AI 可调用工具的无缝转换。

主要特性

MCP 工具标准化: 自动将传统的 FastAPI 端点转换为 AI 模型可调用的 MCP 工具
接口-实现分离: 支持接口定义和实现之间的清晰分离，方便测试和环境切换
依赖注入设计: 利用 FastAPI 的依赖注入机制，实现灵活的组件组合和解耦
完整开发流水线: 提供从开发到测试和部署的全面工具链支持
示例驱动文档: 通过实际示例演示最佳实践，加速上手

此框架特别适用于：

AI 工具开发团队
希望将现有 API 转换为 AI 工具的开发者
实施标准化微服务架构的组织

架构

核心架构

┌─────────────┐      ┌───────────────┐      ┌─────────────────┐
│   API 层   │ ──→ │  服务层  │ ──→ │  实现层  │
└─────────────┘      └───────────────┘      └─────────────────┘
       ↓                                            
┌─────────────┐                                     
│  MCP 端点  │ ←── FastAPI-MCP 自动转换    
└─────────────┘

关键组件

FastAPI 应用: 提供 HTTP API 服务的基础
FastAPI-MCP: 将 API 端点转换为 MCP 工具
服务接口层: 通过抽象基类定义服务契约
依赖注入提供者: 管理服务实例的创建和注入
实现类: 包括 Mock 和 Real 实现，支持基于环境的切换

技术栈

Python 3.10+: 利用最新的语言特性和类型注解
FastAPI: 高性能异步 Web 框架
FastAPI-MCP: 自动将 FastAPI 端点暴露为 MCP 工具
开发工具链: 包括代码质量检查和测试工具

快速开始

环境设置

此框架使用 uv 作为其包管理器，提供更快的依赖解析和虚拟环境管理。有关安装说明，请参阅 uv 官方文档。

# 安装依赖并设置开发环境
make install

启动示例服务

# 启动开发服务器
make dev

服务运行后，您可以：

访问 API 文档，地址为 http://localhost:5000/docs
使用 MCP 客户端（例如，Cursor, Claude Desktop）连接到 MCP 端点，地址为 http://localhost:5000/mcp

项目结构

.
├── main.py                    # 应用入口点和路由定义
├── services/                  # 服务层实现
│   └── parking_service.py     # 示例服务（可替换为自定义服务）
├── pyproject.toml             # 项目配置和依赖定义
└── Makefile                   # 开发和构建任务

MCP 工具开发指南

开发流程概述

定义服务接口: 创建抽象基类来定义服务契约
实现服务: 基于需求开发 Mock 或 Real 实现
创建 API 端点: 使用 FastAPI 开发 API 接口
启用 MCP 服务: 通过 FastAPI-MCP 将端点暴露为 AI 工具

服务接口和实现

# 1. 服务接口定义
from abc import ABC, abstractmethod
from typing import Dict, Any

class DataService(ABC):
    @abstractmethod
    def get_data(self, id: str) -> Dict[str, Any]:
        """数据检索接口"""
        pass

# 2A. Mock 实现 - 用于开发和测试
class DataServiceMockImpl(DataService):
    def get_data(self, id: str) -> Dict[str, Any]:
        return {"id": id, "name": "Test Data", "mock": True}

# 2B. Real 实现 - 用于生产环境
class DataServiceImpl(DataService):
    def __init__(self, database_url: str):
        self.db = Database(database_url)
    
    def get_data(self, id: str) -> Dict[str, Any]:
        return self.db.query("SELECT * FROM data WHERE id = :id", {"id": id})

# 3. 依赖注入配置
def get_data_service() -> DataService:
    # 根据环境选择实现
    return DataServiceMockImpl() # or return DataServiceImpl(settings.DATABASE_URL)

API 和 MCP 工具定义

from fastapi import FastAPI, Depends
from fastapi_mcp import add_mcp_server
from pydantic import BaseModel, Field

app = FastAPI()

# 请求模型
class ItemRequest(BaseModel):
    query: str = Field(..., description="搜索查询参数")
    limit: int = Field(10, description="结果限制")

# API 端点 - 自动转换为 MCP 工具
@app.post("/items/search", operation_id="search_items")
async def search_items(
    request: ItemRequest,
    service: DataService = Depends(get_data_service)
):
    result = service.search_items(request.query, request.limit)
    return {"items": result["items"], "total": len(result["items"])}

# 启用 MCP 服务
add_mcp_server(
    app,
    mount_path="/mcp",
    name="example-mcp-service",
    base_url="http://localhost:5000",
)

依赖注入详解

FastAPI 的依赖注入系统是此框架不可或缺的一部分，提供了强大而灵活的依赖管理能力。

依赖注入基础

依赖注入是一种设计模式，它允许将依赖项（例如服务、数据库连接等）注入到使用它们的组件中，而不是让组件自己创建和管理依赖项。在 FastAPI 中，依赖注入通过 Depends 函数实现。

from fastapi import Depends

def get_db():
    """数据库连接提供者"""
    db = connect_to_db()
    try:
        yield db  # 使用 yield 可以实现依赖项的生命周期管理
    finally:
        db.close()

@app.get("/items/")
async def get_items(db = Depends(get_db)):
    return db.query(Item).all()

依赖类型

FastAPI 支持多种类型的依赖注入：

函数依赖: 如上所示，使用函数作为依赖提供者
类依赖: 使用类作为依赖项，以实现更复杂的依赖管理

class DatabaseDependency:
    def __init__(self, settings = Depends(get_settings)):
        self.settings = settings
    
    def __call__(self):
        db = connect_to_db(self.settings.db_url)
        try:
            yield db
        finally:
            db.close()

@app.get("/users/")
async def get_users(db = Depends(DatabaseDependency())):
    return db.query(User).all()

嵌套依赖: 依赖项可以依赖于其他依赖项，形成依赖树

在 MCP 工具开发中的应用

在此框架中，依赖注入主要用于：

服务实例管理: 将服务实现注入到 API 端点中
环境适配: 根据运行时环境选择不同的服务实现
资源生命周期管理: 管理数据库连接等资源的创建和释放

FastAPI-MCP 特性

自动 MCP 工具生成

FastAPI-MCP 可以自动将 FastAPI 端点转换为 MCP 工具，无需额外配置：

from fastapi import FastAPI
from fastapi_mcp import add_mcp_server

app = FastAPI()

# 定义一个标准的 FastAPI 端点
@app.post("/predict", operation_id="predict_sentiment")
async def predict_sentiment(text: str):
    return {"sentiment": "positive", "confidence": 0.92}

# 添加 MCP 服务 - 自动将上述端点转换为 MCP 工具
add_mcp_server(
    app,
    mount_path="/mcp",
    name="sentiment-analysis",
    base_url="http://localhost:5000",
)

工具命名最佳实践

MCP 工具名称默认为 API 端点的 operation_id。我们建议遵循以下命名约定：

使用清晰、描述性的名称
采用 verb_noun 格式（例如，predict_sentiment，find_nearby_parking）
显式设置 operation_id，而不是依赖自动生成

# 推荐：显式设置 operation_id
@app.post("/parking/nearby", operation_id="find_nearby_parking")
async def find_nearby(request: NearbyRequest):
    # 实现逻辑...
    pass

# 不推荐：依赖自动生成的 operation_id（生成类似 "find_nearby_parking_nearby_post" 的名称）
@app.post("/parking/nearby")
async def find_nearby(request: NearbyRequest):
    # 实现逻辑...
    pass

测试和质量保证

此框架支持多层次的测试策略：

# 运行代码质量检查
make check

# 运行测试套件
make test

测试策略

单元测试: 使用 Mock 服务实现测试单个组件
集成测试: 测试组件之间的交互
API 测试: 验证 HTTP 接口行为
MCP 工具测试: 验证 AI 工具功能

性能优化

为了确保 MCP 工具的高性能，我们建议：

异步处理: 利用 FastAPI 的异步特性来处理并发请求
缓存策略: 为频繁请求的数据实现缓存
批量处理: 设计支持批量操作的 API，以减少调用频率

贡献指南

欢迎对此框架做出贡献：

Fork 仓库
创建一个特性分支 (git checkout -b feature/amazing-feature)
提交您的更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
创建一个 Pull Request

许可证

MIT License

参考

FastAPI - 高性能 Web 框架
FastAPI-MCP - MCP 工具自动生成库