设计并实现一个 MCP Server

设计并实现一个 MCP Server 其实比你想象的要简单，特别是 Anthropic 最近推出了简化版的 SDK。

实现一个 MCP Server 主要分为三个阶段：设计（定义能力） -> 编码（Python/TS实现） -> 配置（连接到客户端）。

我们将以一个 Python 版本的简单示例------"一个能查询股票并记录笔记的助手"------来带你走完全流程。

第一阶段：设计 (Design Phase)

在写代码之前，你需要明确你的 Server 要通过 MCP 协议暴露什么能力给 AI。

确定工具 (Tools): AI 需要主动执行什么动作？
- 示例: get_stock_price(symbol) ------ 输入股票代码，返回价格。
确定资源 (Resources): AI 需要被动读取什么数据？
- 示例: daily_note://today ------ 读取今天的笔记内容。
确定提示词 (Prompts): 是否需要预设模板？
- 示例: summarize_stock ------ 一个帮助分析股票数据的预设 Prompt。

第二阶段：编码实现 (Implementation Phase)

我们将使用 Python 的 mcp 官方库。为了最快上手，我们使用 FastMCP（这是 SDK 中用于快速构建的高级接口）。

1. 环境准备

你需要安装 Python 和 mcp 库：

复制代码

pip install mcp

2. 编写代码 (server.py)

创建一个 server.py 文件，写入以下代码：

python 复制代码

from mcp.server.fastmcp import FastMCP

# 1. 初始化 Server 名称
mcp = FastMCP("StockHelper")

# 模拟的数据库数据
stock_data = {
    "AAPL": 180.50,
    "GOOGL": 140.20,
    "MSFT": 410.00
}

# 2. 定义工具 (Tool) - AI 会调用这个函数
@mcp.tool()
def get_stock_price(symbol: str) -> str:
    """
    获取指定股票代码的当前价格。
    Args:
        symbol: 股票代码 (例如 AAPL, MSFT)
    """
    # 实际开发中这里会调用真实的 API (如 Yahoo Finance)
    price = stock_data.get(symbol.upper())
    if price:
        return f"{symbol.upper()} 当前价格是 ${price}"
    else:
        return f"未找到股票代码 {symbol}"

# 3. 定义资源 (Resource) - AI 可以直接读取这个 URI
@mcp.resource("note://daily_log")
def get_daily_log() -> str:
    """获取今天的交易日志"""
    return "今日日志：关注科技股动向，特别是 AI 板块的波动。"

# 4. 运行服务
if __name__ == "__main__":
    mcp.run()

第三阶段：连接与测试 (Integration Phase)

代码写好了，现在需要把这个 Server 挂载到宿主应用（Host）上，最常用的宿主是 Claude Desktop。

1. 修改配置文件

找到 Claude Desktop 的配置文件：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

用文本编辑器打开它，添加你的 Server 配置（注意修改 python 的路径和文件路径）：

json 复制代码

{
  "mcpServers": {
    "stock-helper": {
      "command": "python", 
      "args": ["/绝对路径/path/to/your/server.py"]
    }
  }
}

注意：建议使用绝对路径，或者使用 uv / venv 环境里的 python 可执行文件路径。

2. 重启 Claude 并测试

完全关闭并重启 Claude Desktop。
你会看到输入框旁边多了一个"插头"或工具图标，点击可以看到 stock-helper 已连接。
开始对话：

你: "帮我查一下 AAPL 的价格。"
Claude: (内部调用 get_stock_price("AAPL")) -> "AAPL 当前价格是 $180.50"。
你: "看看今天的日志里写了什么？"
Claude: (内部读取 note://daily_log) -> "今日日志显示要关注科技股动向..."

第四阶段：调试与优化 (Debugging & Best Practices)

在实际开发中，你不可能一次就写对，这里有两个关键工具和原则：

1. 使用 MCP Inspector (调试神器)

Anthropic 提供了一个网页版调试器，不用重启 Claude 就能测代码。

bash 复制代码

npx @modelcontextprotocol/inspector python server.py

这会启动一个本地网页，你可以在上面手动点击你的 Tool，查看返回值是否符合预期。

2. 关键设计原则

详细的 Docstring: 注意看上面代码里的 """文档字符串"""。LLM 是通过阅读这些文字来理解如何使用你的工具的。如果你写得不清楚，AI 就不知道该传什么参数。
错误处理: 你的函数不要直接抛出 Python 异常（Crash），而是应该返回一个清晰的错误信息字符串（如 Error: Connection timeout），这样 AI 可以看到错误并尝试自我修正。
安全性: 因为是本地执行，千万小心 不要暴露类似 execute_shell_command 这样危险的工具，否则 AI 被提示词注入攻击后可能会删除你电脑的文件。