AI导哈

MCP服务器模板

一个用于构建Model Context Protocol（MCP）服务器的模板项目，提供最佳实践、Docker支持和示例实现。

  • by nickweedon
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 nickweedon/mcp_server_template

使用说明

骨架MCP服务器

建筑模板项目 模型上下文协议（MCP） 服务器。该框架为最佳实践、Docker支持和示例实现提供了坚实的基础。

特性

  • FastMCP框架，便于MCP服务器开发
  • Docker和Docker Compose支持容器化部署
  • 用于一致开发环境的VS代码开发容器配置
  • 用于演示模式的示例CRUD API实现
  • 带pytest的测试套件
  • Claude Code与自定义命令的集成

快速开始

先决条件

  • Python 3.10或更高版本
  • 紫外线 包管理器（推荐）
  • Docker（可选，用于容器化部署）

安装

  1. 克隆此存储库并为您的项目重命名：
git clone <this-repo> my-mcp-server
cd my-mcp-server

  1. 重命名包：

    • 重命名 src/skeleton_mcp 到 src/your_project_name
    • 更新 pyproject.toml 包含您的项目名称和元数据
    • 更新所有Python文件中的导入

  2. 安装依赖项：

uv sync
  1. 创建环境文件：
cp .env.example .env
# Edit .env with your API credentials
  1. 运行服务器：
uv run skeleton-mcp

项目结构

skeleton_mcp/
├── src/skeleton_mcp/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # Main MCP server entry point
│   ├── client.py            # API client for backend communication
│   ├── types.py             # TypedDict definitions
│   ├── api/                  # API modules
│   │   ├── __init__.py
│   │   └── example.py       # Example CRUD operations
│   └── utils/               # Utility modules
│       └── __init__.py
├── tests/                   # Test suite
│   ├── conftest.py          # Pytest fixtures
│   ├── test_example_api.py  # API tests
│   └── test_server.py       # Server tests
├── docs/                    # Documentation
├── .claude/                 # Claude Code configuration
│   ├── commands/            # Custom slash commands
│   └── settings.local.json  # Permission settings
├── .devcontainer/           # VS Code dev container
├── Dockerfile               # Container image definition
├── docker-compose.yml       # Production compose file
├── docker-compose.devcontainer.yml  # Dev container compose
├── pyproject.toml           # Project configuration
├── CLAUDE.md               # Claude context documentation
└── README.md               # This file

发展

运行测试

uv run pytest -v

代码检查

uv run ruff check src/ tests/
uv run ruff format src/ tests/

建筑

uv build

添加您自己的工具

  1. 在中创建新模块 src/skeleton_mcp/api/:
# src/skeleton_mcp/api/my_api.py

async def my_tool(param1: str, param2: int = 10) -> dict:
    """
    Description of what this tool does.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value
    """
    # Your implementation here
    return {"result": "success"}
  1. 在中注册该工具 server.py:
from .api import my_api

mcp.tool()(my_api.my_tool)
  1. 在中添加类型 types.py 如果需要：
class MyDataType(TypedDict):
    field1: str
    field2: int

处理大文件和二进制数据

对于需要处理大文件上传、下载或二进制blob存储的MCP服务器，请使用 mcp映射资源库 图书馆：

pip install mcp-mapped-resource-lib

该库提供：

  • 具有唯一标识符的Blob管理
  • 基于TTL的自动过期和清理
  • 重复数据消除
  • 安全功能（路径遍历预防、MIME验证）
  • 共享存储的Docker卷集成

看 CLAUDE.md 查看详细的使用示例。

Docker部署

使用Docker Compose构建和运行：

docker compose up --build

对于使用VS代码开发容器进行开发：

  1. 在VS Code中打开项目
  2. 安装“开发容器”扩展
  3. 出现提示时，单击“在容器中重新打开”

Claude桌面集成

添加到您的Claude Desktop配置(claude_desktop_config.json):

{
  "mcpServers": {
    "skeleton-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/path/to/your/.env",
        "skeleton-mcp:latest"
      ]
    }
  }
}

或者为了当地发展：

{
  "mcpServers": {
    "skeleton-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/skeleton_mcp", "run", "skeleton-mcp"]
    }
  }
}

可用工具

工具 说明
health_check 检查服务器运行状况和配置状态
list_items 列出所有具有过滤和分页功能的项目
get_item 按ID获取特定项目
create_item 创建新项目
update_item 更新现有项目
delete_item 删除项目

环境变量

变量 描述 默认值
API_KEY 用于身份验证的API密钥 （必需）
API_BASE_URL 后端API的基本URL https://api.example.com/v1
API_TIMEOUT 请求超时（秒） 30
DEBUG 启用调试日志记录 false

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

  1. 复刻仓库
  2. 创建要素分支
  3. 进行更改
  4. 运行测试和梳理
  5. 提交拉取请求

相关 MCP