跳转到主要内容

​
概览

Mirobody 默认提供 9 个内置 MCP 工具。每个都是 res/mcp_tools/ 中一个小小的 C++ 文件，在编译时自注册（参见 添加自定义工具）。它们通过 /mcp 端点 暴露给外部客户端，同时也作为 function-call 描述符交给内置 Agent，因此 OpenAI 和 Gemini 客户端可以在本地进程内调用它们。
标注 需要 auth 的工具只对已认证的调用者运行 —— 引擎会在分发前解析调用者身份（JWT 或个人 MCP secret）并将其作为 UserInfo 注入。无需 auth 的工具（如 echo 和 render_chart）对任何人都可运行。
工具Auth作用
list_files✅列出用户已上传的文件
read_file✅按 file_key 读取一个上传文件
family_health✅读取用户或已共享护理圈成员的近期 FHIR Observation
whoami✅确认认证状态并返回 session id
recall_memory✅检索用户最相关的长期记忆
remember✅在长期记忆中存储一条事实
render_chart—在聊天界面绘制图表（Apache ECharts）
summarize_conversation✅为当前对话设置一个简短标题
echo—回显文本（示例 / 连通性测试）

​
文件工具

​
list_files

列出已认证用户上传的文件。每个条目包含文件的名称、MIME 类型、file_key 和上传时间。当文件在上传时被抽取出文本（图片、PDF、扫描件），该条目的 MIME 会报告为 text/plain，且 read_file 会将抽取出的文本作为 content 返回 —— 即便原始文件并非文本格式。
​
(无参数)
调用者由 auth 解析得出；无需任何参数。
返回一个由 { filename, file_key, mime, uploaded_at } 组成的 JSON 数组。

​
read_file

按 file_key（由 list_files 返回）读取用户的某个上传文件。所有权通过按用户维护的文件索引强制执行，因此调用者无法通过猜测 key 来读取其他用户的对象。文本类文件（以及任何带有抽取文本的文件）会以 content 内联返回；其它二进制类型则返回一个临时的签名 url，而不是内联模型无法使用的字节。
​
file_key
string
必填
要读取文件的 file_key，由 list_files 返回。
文本返回 { filename, mime, content }，二进制返回 { filename, mime, url, note }。

​
健康工具

​
family_health

读取近期健康记录 —— FHIR Observation 资源 —— 属于用户本人，或已共享其健康数据的护理圈成员。Agent 正是借此回答诸如*“我睡得怎么样？“或”妈妈最近怎么样？“*之类的问题。 member 参数解析到一个目标用户：为空或 "me" 表示调用者本人；数字 id、姓名、昵称或邮箱则匹配某位已共享其数据的人。读取会被两次把关 —— 此人必须在调用者的健康共享列表中，且 can_read_health 会再次授权此次读取。只有已共享其数据的成员才可访问。
​
member
string
要读取谁的健康数据：某位护理圈成员的姓名 / 昵称 / 邮箱 / id，或 "me"（或省略）表示调用者。当聊天输入框的”当前为谁”选择器已选中某位成员时，默认使用该成员。
​
count
integer
返回多少条近期 observation。默认 20，最大 100。
返回 { subject, observation_count, observations: [{ code, value, time }, …] }。

​
记忆工具

​
recall_memory

针对某个查询，检索用户最相关的长期记忆（已存储的事实、偏好和过往上下文），使模型能在作答前基于它对用户已了解的信息来立足。需在服务端启用长期记忆（否则会返回一个干净的工具错误）。
​
query
string
必填
要在用户记忆中检索的内容。
​
top_k
integer
返回记忆的最大数量（默认 5）。
返回 { memories: [{ id, text, kind, score, created_at }, …] }。

​
remember

在长期记忆中存储一条关于用户的持久事实（一个稳定的偏好、目标或值得日后回忆的个人细节），以便未来某一轮可以用 recall_memory 取回。由模型决定什么值得保留。
​
text
string
必填
要记住的事实，写成一句自包含的话。
​
kind
string
类别标签：fact | preference | episode（默认 fact）。
返回 { id, stored }。

​
聊天 / UI 工具

​
render_chart

直接在用户的聊天中绘制图表。模型以一个完整的 Apache ECharts option 对象调用它；聊天流会把该调用转成一个图表事件，前端用 echarts.setOption() 渲染。该 option 通过调用参数带外传给客户端，因此模型的上下文不会因回显它而膨胀 —— 工具本身只校验该 option 并返回一个简短确认。
​
option
object
必填
一个完整的 Apache ECharts option 对象，例如 {"xAxis":{"type":"category","data":["Mon","Tue"]},"yAxis":{"type":"value"},"series":[{"type":"line","data":[70.1,70.4]}]}。
​
title
string
可选的简短说明文字，显示在图表旁边。

​
summarize_conversation

为当前对话记录一段简明摘要（一个简短标题，≤ 200 字符），用作用户聊天历史里的标签。它会覆盖引擎根据开场问题生成的占位标题。一旦模型理解了用户的诉求，就会自行撰写这段摘要。
​
summary
string
必填
对话的简短、自包含摘要（≤ 200 字符）。
返回 { updated: true }。

​
示例 / 测试工具

​
whoami

确认调用者已认证，并返回其（不透明的）session 标识。当本轮”当前为”某位调用者可读取的护理圈成员时，它还会标记 acting_for_member。它从不回显任何内部用户主键。
​
(无参数)
返回 { authenticated: true, session_id, acting_for_member? }。

​
echo

回显所提供的文本。它是参考工具 —— 丢文件即注册模式最小可能的示例（见 echo.cpp）—— 同时兼作连通性检查。
​
text
string
必填
要回显的文本。
返回 { echo: "<text>" }。

​
一个工具是如何定义的

每个工具都是一个 res/mcp_tools/<name>.cpp，声明一个 Tool —— 名称、描述、一个 auth 标志、一张小小的 Param 表以及一个 handler —— 然后用 MIROBODY_REGISTER_TOOL(...) 自注册。C++11 没有运行时反射，因此参数显式声明（它们会展开成 MCP 的 inputSchema 以及 OpenAI / Gemini 的 function 描述符），并在编译期检查。以下是 echo 的全部内容：
res/mcp_tools/echo.cpp
#include "mcp/tool.hpp"
#include <rapidjson/document.h>

namespace {
using namespace mirobody::mcp;

Result echo(const Args& args, const UserInfo&, const ToolContext&) {
    const std::string text = args.str("text");
    rapidjson::Document d;
    d.SetObject();
    rapidjson::Document::AllocatorType& a = d.GetAllocator();
    d.AddMember("echo",
                rapidjson::Value(text.c_str(),
                                 static_cast<rapidjson::SizeType>(text.size()), a),
                a);
    return Result::ok(to_json(d));
}

const Tool kEcho = {
    "echo",
    "Echo back the provided text.",
    false,                                                    // auth
    { Param("text", Type::String, Required, "Text to echo back") },
    &echo,
};
}   // namespace

MIROBODY_REGISTER_TOOL(kEcho);
完整流程见 添加自定义工具。

​
下一步

添加自定义工具

在 res/mcp_tools/ 中添加你自己的 C++ 工具

MCP 集成

将 Claude、Cursor 或 ChatGPT 连接到 /mcp 端点

工具与 Agent 概览

Agent、工具与 MCP 如何协同