5分钟手把手教你开发一个MCP服务

开发一个MCP(Model Context Protocol)服务器需要遵循标准协议,结合代码实现和工具配置。以下是基于Python技术栈的MCP Server开发步骤及关键要点,综合了多个实践案例与官方文档建议:


一、环境准备

安装Python与MCP SDK

  • Python版本需≥3.10(推荐3.10+),使用pip安装MCP库:
bash 复制代码
python -m venv mcp-env  # 推荐使用虚拟环境
source mcp-env/bin/activate #Linux/Mac
pip install mcp
  • 验证安装:mcp version应返回版本号(如1.5.0)。

选择开发工具

支持MCP的客户端(如Cline、Cursor、Claude Desktop)用于测试,或使用调试工具如MCP Inspector


二、核心开发步骤

定义工具函数(Tools)

  • 使用@mcp.tool()装饰器暴露函数能力,并通过文档字符串描述功能(供大模型理解用途):
python 复制代码
# custom_mcp.py
from mcp.server.fastmcp import FastMCP
import os

mcp = FastMCP()

@mcp.tool()
def list_desktop_files() -> list:
    """获取当前用户桌面上的所有文件列表(macOS专属实现)"""
    desktop_path = os.path.expanduser("~/Desktop")
    return os.listdir(desktop_path)

@mcp.tool()
def say_hello(name: str) -> str:
    """生成个性化问候语(中英双语版)"""
    return f"🎉 你好 {name}! (Hello {name}!)"

if __name__ == "__main__":
    mcp.run(transport='stdio')  # 启用调试模式
  • 关键点:工具函数需返回JSON序列化兼容的数据类型(如字符串、列表、字典)。

扩展其他能力

  • 资源(Resources):通过URI模板暴露静态或动态数据(如数据库查询结果):
python 复制代码
@mcp.resource("config://app_settings")
def get_app_config() -> dict:
    return {"theme": "dark", "language": "zh-CN"}
  • 提示(Prompts):定义与大模型交互的上下文模板(需结合MCP协议规范)。
bash 复制代码
@mcp.prompt()
def code_review_prompt(code: str) -> str:
    return f"请审查以下代码并指出问题:\n\n{code}"

启动与传输配置

选择传输协议:

  • 本地通信transport='stdio'(适合IDE集成)。
  • 远程通信transport='sse'(基于HTTP事件流,需部署为Web服务)。

完整示例

bash 复制代码
# custom_mcp.py
from mcp.server.fastmcp import FastMCP
import os

mcp = FastMCP()

@mcp.tool()
def list_desktop_files() -> list:
    """获取当前用户桌面上的所有文件列表(macOS专属实现)"""
    desktop_path = os.path.expanduser("~/Desktop")
    return os.listdir(desktop_path)

@mcp.tool()
def say_hello(name: str) -> str:
    """生成个性化问候语(中英双语版)"""
    return f"🎉 你好 {name}! (Hello {name}!)"

@mcp.resource("config://app_settings")
def get_app_config() -> dict:
    return {"theme": "dark", "language": "zh-CN"}

@mcp.prompt()
def code_review_prompt(code: str) -> str:
    return f"请审查以下代码并指出问题:\n\n{code}"


if __name__ == "__main__":
    mcp.run(transport='stdio')

三、客户端配置与测试

配置MCP客户端

  • 以CLINE为例,在设置中添加MCP服务器路径(如cline_mcp_settings.json):
json 复制代码
{
  "mcpServers": {
    "list_desktop_files": {
      "command": "python3",
      "args": [
        "/Users/[USER_NAME]/[YOUR_PATH]/custom_mcp.py"
      ]
    }
  }
}
  • 刷新客户端后,通过自然语言指令(如"我的桌面有哪些文件")调用工具。

可视化调试

  • 使用MCP Inspector检查消息交互:
bash 复制代码
npx @modelcontextprotocol/inspector python custom_mcp.py
  • 确保服务器日志输出正常,检查权限与路径限制。

使用npx运行@modelcontextprotocol/inspector,如下所示:

打开web服务,可视化调试你所开发的Tools:


四、高级实践与优化

  1. 安全性控制
    • 限制工具访问范围(如仅允许读取特定目录)。
    • 使用Nacos等工具管理敏感配置(如API密钥加密)。
  2. 集成现有API
    • 通过Nacos + Higress 方案,将存量HTTP API转换为MCP协议,无需修改代码:
      • Nacos注册服务元数据,Higress网关处理协议转换。
    • 示例:将高德地图API封装为MCP Server,支持自然语言调用天气查询。
  3. 动态发现与扩展
    • 利用MCP市场(如AIbasemcp.so)发布或引用公共服务,实现工具动态加载。

五、常见问题与解决方案

问题类型 解决方案
工具未被客户端识别 检查@mcp.tool()装饰器及文档字符串格式,确保函数参数和返回值类型明确。
传输协议不兼容 确认客户端支持的协议类型(如SSE需配置Web服务器)。
权限不足 限制资源访问路径,使用沙箱环境运行敏感操作。

通过上述步骤,开发者可以快速构建一个功能完整的MCP Server,并结合生态工具实现高效集成。更多进阶实践可参考MCP官方文档及社区资源(如AIbase、GitHub示例仓库)。

相关推荐
乌旭几秒前
量子纠错码实战:从Shor码到表面码
人工智能·深度学习·学习·机器学习·transformer·量子计算
乌旭6 分钟前
量子计算入门:Qiskit实战量子门电路设计
人工智能·pytorch·python·深度学习·transformer·量子计算
后端小肥肠6 分钟前
港大团队开源LightRAG:知识图谱+双层检索,复杂问答准确率飙升30%
大数据·人工智能·openai
dundunmm10 分钟前
【数据集】Romanov数据集
人工智能·机器学习·支持向量机·数据挖掘·数据集·单细胞数据集
小和尚同志10 分钟前
Dify25. Dify 工作流分享 - Deep Researcher
人工智能·aigc
hjs_deeplearning33 分钟前
论文写作篇#8:双栏的格式里怎么插入横跨两栏的图片和表格
人工智能·深度学习·学习·yolo·机器学习·论文写作·论文排版
__Benco39 分钟前
OpenHarmony子系统开发 - DFX(三)
人工智能·harmonyos
新知图书1 小时前
OpenCV界面编程
人工智能·opencv·计算机视觉
小杨4041 小时前
python入门系列十五(asyncio)
人工智能·python·pycharm
hanniuniu131 小时前
技术驱动革新,强力巨彩LED软模组助力创意显示
人工智能