AI导哈

MCP服务器模板

一个使用Python和FastMCP框架构建Model Context Protocol (MCP)服务器的模板，提供完整的开发工作流、集成工具和生产就绪结构。

  • by daniel-butler-irl
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 daniel-butler-irl/mcp-server-template

使用说明

MCP服务器模板

⚠️ 桌面扩展（DXT）通知 ⚠️ Python DXT扩展目前存在严重的可靠性问题。看 DXT_ISSUES.md 了解详情。 推荐：使用传统的MCP服务器安装，而不是DXT打包。

使用Python和FastMCP创建模型上下文协议（MCP）服务器的模板存储库。

概述

此模板表示 解释 如何正确构建和管理模型上下文协议（MCP）服务器，并配备全面的自动化和工具。它提供了一个即用型基础，超越了基本的MCP服务器创建，包括：

  • 🔧 完整的开发工作流程：自动化构建流程、测试和打包
  • 📦 集成工具：用于开发和测试的内置MCP CLI工具
  • 🚀 生产就绪结构：组织代码库，适当分离关注点
  • ⚡ 最佳实践：现代Python打包、配置管理和部署策略

模型上下文协议（MCP）是一个开放标准，使AI助手能够安全地访问外部数据源和工具。此模板演示了我认为以可维护和可扩展的方式构建、开发、测试和部署MCP服务器的正确方法。

特性

  • 🚀 FastMCP集成：使用FastMCP框架构建，实现快速开发
  • 🛠️ 示例工具：包括一个示例问候工具，用于演示MCP工具模式
  • 📦 现代Python：使用现代Python打包 pyproject.toml
  • 🔧 轻松设置：安装和设置过程简单
  • 📋 标准运输：已配置stdio传输协议

先决条件

  • Python 3.10或更高版本
  • 紫外线 包管理器（推荐）或pip

安装

快速入门（推荐）

# Clone the repository
git clone <your-repo-url>
cd mcp-server-template

# Setup development environment (installs dependencies and pre-commit hooks)
make

这将自动：

  • 使用uv安装依赖项
  • 设置预提交挂钩以提高代码质量
  • 准备开发环境

手动安装

使用紫外线

# Clone the repository
git clone <your-repo-url>
cd mcp-server-template

# Install dependencies
uv sync

# Setup development environment
make setup-dev

使用pip

# Clone the repository
git clone <your-repo-url>
cd mcp-server-template

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Setup development environment
make setup-dev

用法

运行服务器

python server/main.py

服务器将通过stdin/stdout启动并监听MCP协议消息。

桌面扩展安装

⚠️ 目前不推荐Python DXT扩展存在已知的可靠性问题。请改用传统的MCP安装。

供DXT稳定后使用：

  1. 构建扩展：

    make pack-dxt

  2. 在Claude Desktop中安装：

    • 打开克劳德桌面
    • 前往“设置”>“扩展”
    • 点击“安装扩展”并选择生成的 .dxt 文件

目前推荐的方法：

  • 在Claude Desktop中使用手动MCP服务器配置 claude_desktop_config.json
  • 看 MCP文件 有关设置说明

使用MCP CLI进行测试

您可以使用此存储库中包含的MCP CLI工具测试服务器。以下是示例提示及其预期响应：

用于测试MCP服务器的CLI命令

列出可用工具：

> /tools

列出可用资源：

> /resources

列出可用提示：

> /prompts

工具示例

提示： “嗨，我是爱丽丝”

预期响应：

🚀 Greetings from the MCP Server Tool, Alice! This is your unique confirmation that the Model Context Protocol server is actively responding to your request. ✨

资源示例

步骤1-检查可用资源：

> /resources

步骤2-询问服务器状态：

> What's the server status?

预期响应（更新后）：

I can access real-time server status information via the server://status resource. To get this information, you can either use the `/resources` command to see available resources, or ask me to 'read the server status resource' and I'll guide you through accessing it.

步骤3-请求特定资源访问：

> Please read the server status resource

预期响应：

[Assistant should guide you through accessing the resource via CLI commands]

提示示例

步骤1-检查可用提示：

> /prompts

步骤2-使用助手提示：

> Can you use the greeting assistant prompt to explain your capabilities?

预期响应：

I have access to MCP tools, resources, and prompts. Use `/tools`, `/resources`, and `/prompts` commands to see what's available, then ask me to use specific capabilities.

MCP CAPABILITIES AVAILABLE:
- TOOLS: Functions I can call directly (like 'hello' for greetings)
- RESOURCES: Data I can access (like 'server://status' for server information)
- PROMPTS: Templates for guidance (like this assistant configuration)

直接MCP协议测试

您还可以使用原始MCP协议消息进行测试：

工具调用：

{
  "method": "tools/call",
  "params": {
    "name": "hello",
    "arguments": {
      "name": "Alice"
    }
  }
}

资源调用：

{
  "method": "resources/read",
  "params": {
    "uri": "server://status"
  }
}

快速呼叫：

{
  "method": "prompts/get",
  "params": {
    "name": "greeting_assistant"
  }
}

项目结构

mcp-server-template/
├── manifest.json        # Desktop extension configuration
├── icon.png            # Extension icon
├── server/             # MCP server implementation
│   ├── main.py         # Main server entry point
│   ├── tools/          # Tool implementations
│   ├── resources/      # Resource implementations
│   └── prompts/        # Prompt templates
├── pyproject.toml      # Python project configuration
├── .github/workflows/  # CI/CD automation
├── tests/              # Test suite
├── Makefile           # Build and development commands
└── mcp-cli/           # MCP CLI tools and utilities

发展

添加新工具

要向MCP服务器添加新工具，请遵循以下模式：

@mcp.tool()
async def your_tool_name(param1: str, param2: int) -> str:
    """
    Description of your tool.

    Args:
        param1: Description of parameter 1
        param2: Description of parameter 2

    Returns:
        str: Description of return value
    """
    # Your tool implementation here
    return "result"

关键考虑因素

  • 所有工具都应该是异步函数
  • 对参数和返回值使用类型提示
  • 提供清晰的文档字符串，解释何时以及如何使用该工具
  • 返回值应该是JSON可序列化的
  • 在工具中优雅地处理错误

配置

桌面扩展配置

可以通过以下方式配置扩展 manifest.json:

{
  "config": {
    "serverName": {
      "type": "string",
      "title": "Server Name",
      "description": "The display name for this MCP server",
      "default": "Template MCP Server"
    },
    "greetingPrefix": {
      "type": "string",
      "title": "Greeting Prefix",
      "description": "Custom prefix for greeting messages",
      "default": "🚀 Greetings from the MCP Server Tool"
    }
  }
}

开发配置

可以通过修改来自定义服务器名称 FastMCP 初始化中 server/main.py:

mcp = FastMCP("YourServerName")

有关更高级的配置选项，请参阅 FastMCP文档.

MCP CLI工具

此模板包括一个全面的MCP CLI工具套件 mcp-cli/ 目录提供：

  • 与MCP服务器的交互式聊天界面
  • 服务器管理和配置
  • 工具发现和测试实用程序
  • 资源管理能力
  • LLM集成以增强工作流程

看 mcp-cli/README.md 有关使用这些工具的详细文档。

许可证

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

资源

入门指南

用于桌面扩展开发

  1. 克隆此模板存储库
  2. 设置开发环境： make setup-dev
  3. 在中自定义服务器名称和配置 manifest.json
  4. 在中实现您的自定义工具 server/main.py 或 server/tools/
  5. 测试您的扩展： make test-full
  6. 构建扩展： make pack-dxt
  7. 安装 .dxt Claude Desktop 中的文件

用于传统MCP服务器开发

  1. 克隆此模板存储库
  2. 重命名项目并更新中的服务器名称 server/main.py
  3. 使用 @mcp.tool() 装饰器
  4. 使用附带的MCP CLI工具测试您的服务器
  5. 根据您的用例部署服务器

快乐建筑！ 🚀

相关 MCP