MCP服务器模板

一个基于FastAPI的Python模板,用于构建符合Model Context Protocol (MCP)标准的服务器,支持AI应用程序安全访问外部数据和工具。

  • by gmogmzGithub
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 gmogmzGithub/mcp-python-skeleton

使用说明

MCP Python框架

建筑骨架/模板 模型上下文协议(MCP) 使用FastAPI的Python服务器。

什么是MCP?

模型上下文协议(MCP)是一个开放标准,使AI应用程序能够安全地访问外部数据和工具。MCP服务器提供了一种向AI模型公开功能的标准化方法。

特性

  • 基于FastAPI:具有自动API文档的现代快速web框架
  • MCP集成:使用FastMCP内置对MCP协议的支持
  • 简单架构:干净、可扩展的代码库,易于理解和修改
  • 健康检查:用于监控的内置健康检查端点
  • Docker支持:已准备好部署Docker配置
  • 测试设置:使用pytest和tox进行预配置测试
  • 代码质量:用于格式化和linting的预提交钩子

入门指南

先决条件

  • Python 3.12+
  • 诗歌(用于依赖管理)

安装

  1. 克隆此存储库:

    git clone https://github.com/your-username/mcp-python-skeleton.git
    cd mcp-python-skeleton
    
  2. 安装依赖项:

    poetry install
    

    备注:The poetry.lock git中故意忽略该文件。运行时,Poetry将生成一个新的锁文件 poetry install 这是第一次。

  3. 安装预提交挂钩(可选但推荐):

    poetry run pre-commit install
    

运行服务器

选项1:使用诗歌

# Run with default settings
poetry run python -m mcpskeleton

# Run with custom port
PORT0=9000 poetry run python -m mcpskeleton

# Run in debug mode
poetry run python -m mcpskeleton --debug

选项2:使用诗歌脚本

poetry run start

服务器将在以下时间启动 http://0.0.0.0:8080 默认情况下。

可用端点

  • GET /health -基本健康检查
  • GET / -根端点(JSON响应)
  • /mcp/* -MCP协议端点

添加MCP工具

MCP工具定义见 mcpskeleton/mcp/mcp_tools.py。以下是如何添加新工具:

def my_custom_tool(param1: str, param2: int) -> str:
    """
    Description of what this tool does.

    Args:
        param1: Description of first parameter
        param2: Description of second parameter

    Returns:
        Description of return value
    """
    return f"Processed {param1} with value {param2}"

# Add your tool to the base_tools list
base_tools = [
    my_custom_tool,  # Add your function here
]

重要提示:

  • 始终包含参数和返回值的类型提示
  • 添加全面的文档字符串-它们有助于LLM了解如何使用您的工具
  • 函数名称将用作MCP协议中的工具名称

配置

环境变量

  • PORT0:服务器端口(默认值:8080)
  • HOST0:服务器主机(默认值:0.0.0.0)
  • WORKERS:工作进程数(默认值:1)

发展

运行测试

# Run all tests with coverage
poetry run tox

# Run tests only (no linting)
poetry run pytest

# Run specific test file
poetry run pytest mcpskeleton/tests/test_specific.py

代码质量

此项目使用预提交挂钩进行代码格式化和linting:

# Run all hooks manually
poetry run pre-commit run --all-files

# Auto-format code
poetry run black .
poetry run isort .

# Run linting
poetry run flake8

项目结构

mcpskeleton/
├── __main__.py              # Application entry point
├── daemon/                  # Web server components
│   ├── fastapi_webapp.py   # FastAPI application setup
│   ├── implementation.py   # Main app factory
│   ├── routes.py           # Basic routes
│   ├── health_checks.py    # Health check endpoints
│   └── dependencies.py     # Simple dependency management
├── mcp/                    # MCP-specific components
│   ├── __init__.py         # MCP server setup
│   └── mcp_tools.py        # MCP tool definitions
└── tests/                  # Basic test files

定制

添加依赖关系

将您的依赖项添加到 pyproject.toml:

[tool.poetry.dependencies]
requests = "^2.31.0"
my-package = "^1.0.0"

然后运行 poetry lock 更新锁文件。

添加健康检查

扩展简单的健康检查 mcpskeleton/daemon/dependencies.py:

def check_dependencies():
    """Add your custom dependency checks here."""
    # Example: check database connection, external APIs, etc.
    return {"status": "healthy", "dependencies": ["service1", "service2"]}

贡献

  1. 复刻仓库
  2. 创建要素分支: git checkout -b feature/amazing-feature
  3. 进行更改
  4. 运行测试: poetry run tox
  5. 提交您的更改: git commit -m 'Add amazing feature'
  6. 推到分支: git push origin feature/amazing-feature
  7. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

资源

支持

如果您遇到任何问题或有疑问,请:

  1. 检查 现有问题
  2. 使用有关您问题的详细信息创建新问题
  3. 包括再现步骤、预期行为和实际行为