MCP 学习笔记

MCP 三角色架构

一次完整的 Tool Calling 流程

两种传输模式

Server 提供三种能力

Tool：最核心的能力

每个 Tool 有三个要素，description 是最关键的——LLM 靠它决定"什么时候用"：

Tool(
    name="get_weather",              # 1. 名称：LLM 用来标识
    description="获取指定城市的天气信息",  # 2. 描述：LLM 用来理解"什么时候用"
    inputSchema={                       # 3. 参数 Schema：LLM 用来生成"正确的参数"
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "城市名称"}
        },
        "required": ["city"],
    },
)

Tool vs Resource：什么时候用哪个

Prompt：预定义的提示词模板

Prompt(
    name="write_weekly_report",
    description="生成周报的提示词模板",
    arguments=[
        {"name": "project", "description": "项目名称", "required": True},
    ],
)

# LLM 收到 Prompt 模板后，按照专业结构生成内容
# 比用户手写"帮我写周报"质量更高

我们的 MCP Server：文件系统 + SQLite

一个 Server 提供两组共 8 个工具，LLM 根据用户意图自动选择：

Server 的最小结构

from mcp.server import Server
from mcp.types import Tool, TextContent
from mcp.server.stdio import stdio_server

# 1. 创建 Server
server = Server("my-server")

# 2. 声明 Tool 列表（LLM 的"工具菜单"）
@server.list_tools()
async def list_tools() -> list[Tool]:
    return [Tool(name=..., description=..., inputSchema=...)]

# 3. 实现 Tool 调用（执行逻辑）
@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    if name == "my_tool":
        return [TextContent(type="text", text=result)]

# 4. 启动 Server（监听 stdin/stdout）
async with stdio_server() as (read_stream, write_stream):
    await server.run(read_stream, write_stream, ...)

两个层次的工具设计

安全是 MCP Server 的第一要务

防护 1：路径穿越攻击防御

用户可能对 LLM 说"读取 /etc/passwd"，LLM 可能传入 ../../../etc/passwd：

def read_file(user_path: str):
    # 危险！直接拼接用户路径
    full = Path("/workspace") / user_path
    return full.read_text()

# user_path = "../../../etc/passwd"
# → /etc/passwd ← 系统文件泄露！

def safe_path(user_path: str) -> Path:
    full = Path(allowed_root) / user_path
    resolved = full.resolve()  # 展开 ../ 和符号链接

    if not str(resolved).startswith(str(allowed_root)):
        raise PermissionError("路径越界！")

    return resolved

# user_path = "../../../etc/passwd"
# → PermissionError: 路径穿越检测！

防护 2：SQL 注入和危险操作拦截

def _handle_db_query(args: dict):
    sql = args["sql"].strip()

    # 检查 1：只允许 SELECT
    if not sql.upper().startswith("SELECT"):
        return [TextContent(text="⛔ 只允许 SELECT 查询")]

    # 检查 2：禁止危险关键词
    dangerous = ["DROP", "DELETE", "INSERT", "UPDATE", "ALTER"]
    for kw in dangerous:
        if kw in sql.upper():
            return [TextContent(text=f"⛔ 禁止 {kw}")]

    # 检查 3：只读连接（即使绕过前两步，数据库也不允许写）
    conn = sqlite3.connect(f"file:{DB_PATH}?mode=ro", uri=True)

安全设计清单

两种配置方式

方式 1：项目级配置（推荐）

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "local-tools": {
      "command": "python3",
      "args": ["mcp_server.py"],
      "env": {
        "WORKSPACE_DIR": "/path/to/your/workspace",
        "DB_PATH": "/path/to/your/database.db"
      }
    }
  }
}

方式 2：全局配置

编辑 ~/.claude/settings.json：

{
  "mcpServers": {
    "local-tools": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp_server.py"]
    }
  }
}

验证连接 + 使用示例

配置完成后，在 Claude Code 中验证：

# 验证连接成功
/list_tools

# 应该看到 list_directory, read_file, db_query 等工具

然后直接用自然语言操作：

MCP vs Function Calling vs LangChain Tool

决策树：什么时候用什么

它们可以共存

核心收获

配套资源