✅ 什么是 MCP？

MCP，全称 Model Context Protocol，是一种为大模型（如 GPT）设计的工具协议标准，常用于：

• 在本地/远程运行 AI 工具服务
• 通过统一格式暴露工具接口，供客户端调用（如 Windsurf, Cherry Studio, DeepChat）

MCP 工具支持多种运行模式，其中最常见的是：

• fetch 模式：通过 HTTP 访问工具（通常为本地服务，如 http://localhost:8000）
• stdio 模式：通过命令行双向通信（适合 CLI 工具）

✅ 你要做的是：以 Fetch 模式 运行本地 MCP 服务，并让 Windsurf 调用这个服务

✅ 第一步：本地搭建一个 MCP Fetch 服务

📦 安装依赖（macOS 上建议使用 uv 工具）

# 初始化项目
mkdir my_mcp_tool && cd my_mcp_tool

# 创建虚拟环境
uv venv
source .venv/bin/activate

# 安装 mcp 库和 httpx（如需请求外部 API）
uv pip install "mcp" httpx

🧠 创建 server.py 示例

from mcp.server import FastMCP
import uvicorn

app = FastMCP("web-search")

@app.tool()
async def search_web(query: str) -> str:
    return f"你搜索的是：{query}"

if __name__ == "__main__":
    uvicorn.run("server:app", host="127.0.0.1", port=8000)

▶️ 启动服务

python server.py

你会看到输出类似：

Uvicorn running on http://127.0.0.1:8000

你现在可以访问：

http://localhost:8000/.well-known/mcp/web-search

这是 MCP 工具暴露的标准路径。

✅ 第二步：Windsurf 中配置 MCP 服务（Fetch 模式）

你需要在 Windsurf 中填写一个 MCP 工具的配置项，格式如下：

📄 示例 JSON 配置（Windsurf 中的 mcp_config.json 片段）

{
  "name": "Local Web Search",
  "mode": "fetch",
  "endpoint": "http://localhost:8000/.well-known/mcp/web-search",
  "headers": {},
  "enabled": true,
  "description": "本地运行的 Web 搜索 MCP 工具（fetch 模式）",
  "icon": "🔍"
}

👇 配置方法：

1. 打开 Windsurf
2. 点击 MCP 管理（图标类似积木）
3. 点击“添加工具”
4. 选择模式：fetch
5. 填写 endpoint、描述等字段（如上）
6. 启用 ✅

⚠️ 注意：Windsurf 的 fetch 工具不会帮你启动本地服务，它只会去访问 endpoint。你要 确保 server.py 正在运行。

✅ 总结全流程：一图胜千言

[你本地运行的 MCP 工具]
   │
   │  uvicorn 启动
   ▼
http://localhost:8000/.well-known/mcp/web-search
   ▲
   │
[Windsurf MCP fetch 工具配置：mode: fetch, endpoint: 上面这个 URL]

✅ 常见问题 FAQ

❓为什么我填了 endpoint 但 Windsurf 提示请求失败？

• MCP 服务没有运行或启动失败
• endpoint 拼错了（少了 .well-known/mcp/tool-name）
• 使用了 npx 启动 Python 工具（错误）
• 防火墙或端口占用

❓我能不能自动用 Windsurf 启动服务？

• 推荐不要，你只需要在终端里自己 python server.py 启动即可。
• Windsurf 不适合用来运行 Python 服务，只负责调工具。

❓我能跑多个 MCP 工具吗？

• 可以，使用多个 @app.tool() 定义多个工具即可。

✅ Bonus：完整项目结构示例

my_mcp_tool/
├── server.py              # MCP 工具代码（fetch 模式）
├── .venv/                 # 虚拟环境目录
├── requirements.txt       # 可选依赖导出

是否需要我为你打包一个 zip 模板？或者部署到 HuggingFace Space？欢迎继续提问！