您的位置: 首页> AI模型

04｜MCP 服务接口：让本地能力变成 Agent 可调用的 Tools

匿名上传

发布时间:2026-02-06 13:45:02

到目前为止，你已经知道：

数据如何存（SQLite）
事件如何来（生命周期挂钩）
日志如何变薄（摘要压缩）

但少了一个关键环节：Agent 到底怎么“摸到”这些本地能力？

答案就是：MCP（Model Context Protocol）。trae-mem 通过实现一个 MCP Server，把本地 Python 逻辑包装成一组“工具（Tools）”，让 Trae 的 Agent 能像调用内置工具一样调用它们。

本文聚焦第四块核心能力：MCP Service Interface（MCP 服务接口），核心实现位于 mcp_server.py。

1. 角色划分：Trae / Agent / MCP Server

你可以用一句话把三者关系讲清楚：

Trae（客户端/宿主）：负责启动 MCP Server，并把“工具菜单”暴露给 Agent
Agent（模型）：负责理解用户意图，决定调用哪个工具、用什么参数调用
MCP Server（服务端）：负责实现工具，接收 JSON-RPC 请求并返回结果

这也是 MCP 的核心价值：把“理解（AI）”与“执行（本地能力）”解耦。

如果你想看更完整的“三角协同”讲解，可配合阅读 mcp-architecture-deep-dive.md。

2. 传输层：为什么是 stdio？

trae-mem 选择 stdio（标准输入/输出）作为 MCP 传输方式：

Trae 启动 server 进程
Trae 通过 stdin 写入一行行 JSON（请求）
Server 通过 stdout 回写一行行 JSON（响应）

优点非常“工程”：

不需要端口（减少配置与安全风险）
跨平台稳定（macOS/Linux/Windows）
进程生命周期由宿主控制，方便自动重启

实现入口是 serve_stdio()。

3. 协议层：JSON-RPC 的最小实现

在 serve_stdio() 中，server 做了一个极简的 JSON-RPC 循环：

initialize：握手，声明能力
tools/list：返回工具清单
tools/call：执行某个工具并返回结果

对应代码片段在 mcp_server.py：

if method == "initialize":
    _write(_result(id_value, {...capabilities...}))
    continue

if method == "tools/list":
    _write(_result(id_value, {"tools": _tools()}))
    continue

if method == "tools/call":
    name = str(params.get("name") or "")
    args = params.get("arguments") or {}
    res = _handle_tool_call(name, args)
    _write(_result(id_value, res))
    continue

注意：这里没有引入任何第三方库，完全靠 Python 标准库就能跑通。

4. 工具发现：tools/list 为什么这么重要？

Agent 能调用哪些能力，取决于 tools/list 返回的“工具描述（Schema）”。在 mcp_server.py 的 _tools() 里，trae-mem 定义了 7 个工具：

trae_mem_search：全文检索
trae_mem_timeline：按 observation_id 拉时间窗
trae_mem_get_observations：按 ID 批量取详情
trae_mem_inject：生成可注入上下文块
trae_mem_start_session：创建 session
trae_mem_log：写入 observation
trae_mem_end_session：结束 session 并生成摘要
trae_mem_hook_event：适配生命周期事件（把 Trae 事件写进 DB）

每个工具都有：

name
description：给模型读的说明
inputSchema：参数结构（类型、必填字段、枚举值）

这是“模型可调用工具”的关键：description + schema 就是模型的说明书。

5. 工具执行：tools/call 如何路由到真实逻辑？

当 Trae 收到 Agent 输出的“调用某工具”的意图，它会发送 tools/call 给 server。server 在 _handle_tool_call() 内做路由（见 mcp_server.py）：

5.1 示例：trae_mem_inject（上下文注入）

参数：query/limit/project
逻辑：调用 build_injection_block 拼一段文本块

if name == "trae_mem_inject":
    text = build_injection_block(db, query=query, limit=limit, project_path=...)
    return _tool_text_result(text, structured={"context": text})

返回值是 MCP 约定的 ToolResult 结构：content: [{type:"text", text:"..."}]。

5.2 示例：trae_mem_log（写 observation）

它会：

处理 <private> 脱敏（必要时将整段标记为 private）
调用 db.add_observation(...)
返回 observation_id

见 mcp_server.py。

6. 关键桥梁：trae_mem_hook_event 怎么把 Trae 生命周期“灌进来”？

trae_mem_hook_event 是 trae-mem 的“适配器工具”。它把 Trae 的生命周期事件（SessionStart / PreToolUse 等）转换成 hooks_bridge.py 能处理的形式。

实现位于 mcp_server.py：

核心技巧只有一个：伪造 stdin，复用 hooks_bridge 的 main()。

buf = json.dumps(payload, ensure_ascii=False)
proc_argv = ["--event", event]
stdin_backup = sys.stdin
try:
    sys.stdin = io.StringIO(buf)
    rc = int(hooks_bridge_main(proc_argv))
finally:
    sys.stdin = stdin_backup

这带来两个好处：