> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirobody.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ChatGPT Apps

> 通过 HTTP Remote MCP server 把 Mirobody 接入 ChatGPT App

## 概览

ChatGPT Apps 通过与外部 MCP 服务器对话来扩展 ChatGPT 的能力。Mirobody 开箱即是一个支持 OAuth 的 **HTTP Remote MCP server** —— 你需要做的，仅仅是把一个公网 HTTPS URL 指向你的 Mirobody 实例。

<Info>
  背景阅读：<a href="https://openai.com/index/introducing-apps-in-chatgpt/">ChatGPT Apps 官方公告</a> 与 <a href="https://modelcontextprotocol.io">Model Context Protocol 规范</a>。
</Info>

## 工作原理

Mirobody 的 MCP 服务器是一个一等的 HTTP 服务。当你在配置里设置 `MCP_PUBLIC_URL` 时，Mirobody 会把它作为其 `/mcp` 端点对外可达的 URL。ChatGPT（或任何远程 MCP 客户端）连过来后走 OAuth 验证，然后就可以开始调工具了。

## 前置要求

你需要一个能转发到 Mirobody 实例的公网 HTTPS URL。独立二进制监听 `HTTP_HOST:HTTP_PORT`（默认 `0.0.0.0:8080`）。

<Steps>
  <Step title="确认 Mirobody 正在运行">
    本地 `http://localhost:8080/mcp` 应该返回 MCP JSON。可用以下命令验证：

    ```bash theme={null}
    curl -X POST http://localhost:8080/mcp \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
    ```
  </Step>

  <Step title="选择公网 URL 方案">
    **方案 A —— 临时演示（隧道到笔记本）：**

    ```bash theme={null}
    # ngrok
    ngrok http 8080

    # 或者 cloudflared
    cloudflared tunnel --url http://localhost:8080
    ```

    用得到的 HTTPS URL（如 `https://abc123.ngrok.io`）。

    **方案 B —— 生产部署（自己的域名）：** 在反向代理（Caddy / nginx / 托管 LB）上做 TLS 终止，转发到你的 Mirobody 实例。
  </Step>

  <Step title="设置 MCP_PUBLIC_URL">
    在 `config.yml` 里加：

    ```yaml theme={null}
    MCP_PUBLIC_URL: "https://abc123.ngrok.io/mcp"   # or your production domain + /mcp
    ```

    重启 Mirobody。公网 MCP 端点现在就是 `https://abc123.ngrok.io/mcp`。

    <Warning>
      这个 URL 等同于秘密 —— 拿到它的人都可以尝试 OAuth 登录你的 Mirobody 实例。
    </Warning>
  </Step>
</Steps>

## 创建 ChatGPT App

`MCP_PUBLIC_URL` 配好、隧道/域名可达之后，去 ChatGPT 注册 App：

<Steps>
  <Step title="进入 ChatGPT Apps">
    打开 ChatGPT，进入 Apps 页面。你会看到已有的 App 以及新增入口。

    <Frame>
      <img src="https://mintcdn.com/thetahealth/MyyYFLspPSiFRB9w/images/ChatGPT%20App%20Main.png?fit=max&auto=format&n=MyyYFLspPSiFRB9w&q=85&s=b4c75ab31578d4779b9b0c71333918e1" alt="ChatGPT Apps main interface showing available apps" width="686" height="607" data-path="images/ChatGPT App Main.png" />
    </Frame>
  </Step>

  <Step title="启用开发者模式">
    点击"创建你自己的"或进入开发者模式，开始构建自定义 App。这会打开 App 创建界面，你可以在其中配置到 Mirobody 的连接。

    <Frame>
      <img src="https://mintcdn.com/thetahealth/MyyYFLspPSiFRB9w/images/ChatGPT%20App%20Dev%20Mode.png?fit=max&auto=format&n=MyyYFLspPSiFRB9w&q=85&s=c608c36f01ac4793639bc8d382c31413" alt="ChatGPT Developer Mode for creating custom apps" width="491" height="153" data-path="images/ChatGPT App Dev Mode.png" />
    </Frame>
  </Step>

  <Step title="填入 MCP 端点">
    在 App 配置里：

    1. **App 名称**：例如 "Mirobody"
    2. **MCP 端点**：你的 `MCP_PUBLIC_URL` 加 `/mcp`（如 `https://abc123.ngrok.io/mcp`）
    3. **描述**（可选）：简述这个 App 能做什么
    4. **测试连接**：ChatGPT 会校验连通性并发现工具

    <Frame>
      <img src="https://mintcdn.com/thetahealth/MyyYFLspPSiFRB9w/images/ChatGPT%20App%20Add%20New%20App.png?fit=max&auto=format&n=MyyYFLspPSiFRB9w&q=85&s=7524b0bf0007970a32a6e5dbe7c0dfc3" alt="Adding a new ChatGPT app with MCP endpoint configuration" width="451" height="787" data-path="images/ChatGPT App Add New App.png" />
    </Frame>

    <Tip>
      ChatGPT 会自动发现你 Mirobody 实例中注册的每一个工具 —— [九个内置工具](/zh/tools/built-in) 外加你在 `res/mcp_tools/` 中添加并重新构建的任何 C++ 工具。
    </Tip>
  </Step>

  <Step title="OAuth 登录">
    首次调用时 ChatGPT 会跳转到 Mirobody 内置的 OAuth 登录页。登录一次即可，token 会被复用整个 ChatGPT 会话。
  </Step>

  <Step title="开始使用">
    连接好后，这个 ChatGPT 会话可以：

    * 通过 `family_health` 读取用户的健康记录（FHIR `Observation`）
    * 通过 `list_files` / `read_file` 列出并读取用户上传的文件
    * 通过 `remember` / `recall_memory` 存储与检索长期记忆
    * 调用你在 `res/mcp_tools/` 中添加并重新构建的任何自定义工具

    <Check>
      你的 ChatGPT App 已接入 Mirobody。
    </Check>
  </Step>
</Steps>

## 可用能力

接入后，ChatGPT 可以访问 Mirobody 的 [内置 MCP 工具](/zh/tools/built-in)：

<CardGroup cols={2}>
  <Card title="健康记录" icon="user">
    用户或已共享护理圈成员的近期 FHIR `Observation`（`family_health`）
  </Card>

  <Card title="上传文件" icon="file">
    列出并读取上传文件，包括从图片和 PDF 中抽取的文本（`list_files`、`read_file`）
  </Card>

  <Card title="长期记忆" icon="brain">
    存储与检索关于用户的持久事实（`remember`、`recall_memory`）
  </Card>

  <Card title="图表" icon="chart-line">
    在聊天中渲染 Apache ECharts 可视化（`render_chart`）
  </Card>

  <Card title="自定义工具" icon="wrench">
    你在 `res/mcp_tools/` 中添加并重新构建的任何 C++ 工具
  </Card>

  <Card title="对话标题" icon="tag">
    为当前对话设置一个简短标签（`summarize_conversation`）
  </Card>
</CardGroup>

## 示例用例

ChatGPT 能跨设备、病历和上传文件做整体合成。一些真实示例：

### 简单查询

对于简单的问题，你可以问：

```
"我最近睡得怎么样？"
"昨天我的心率是多少？"
"总结我最近的化验结果"
"画出我上个月的体重"
```

### 进阶分析：糖尿病管理

**Prompt：** "总结我糖尿病的历史和近期进展。使用 Theta 从设备、记录和其他相关来源查找数据。"

<CardGroup cols={2}>
  <Card title="查看完整对话" icon="comments" href="https://chatgpt.com/share/6945032b-86f8-8002-9bc1-03a19f890dca">
    完整的糖尿病分析对话
  </Card>

  <Card title="交互式图表" icon="chart-line" href="https://chatgpt.com/canvas/shared/6945031a455c8191885abb2f1d4deb39">
    交互式血糖趋势可视化
  </Card>
</CardGroup>

### 进阶分析：疼痛模式识别

**Prompt：** "帮我理解膝盖疼痛的全貌和进展。使用所有相关数据并找到潜在驱动因素。如果有帮助的话，使用可视化说明。"

<Card title="查看完整分析" icon="magnifying-glass-chart" href="https://chatgpt.com/share/6944b5aa-38fc-8002-932f-bdf60b690eba">
  ChatGPT 如何用多源数据分析复杂的疼痛模式
</Card>

<Tip>
  同一个 MCP 端点也能接 Claude Desktop、Cursor 等任意 MCP 客户端 —— 参见 [MCP 集成](/zh/tools/mcp-integration)。
</Tip>

## 安全注意事项

<Info>
  **OAuth 是内置的。** 任何对 MCP 端点的调用都必须先走完 Mirobody 的 OAuth 流程，所以即便 URL 泄露，没有合法会话也无法被使用。
</Info>

<Warning>
  **额外加固建议：**

  * 把 `MCP_PUBLIC_URL` 当作机密，不要公开
  * 在反向代理或 Mirobody 的 `src/server/` 中间件层加限流
  * 监控 `/mcp` 的访问日志
  * 仅在确实需要使用时再开隧道
  * 生产环境：托管代理上做 TLS 终止、尽量做 IP 白名单、对 `/mcp` 做可观测性
  * OAuth token 会过期 —— 用户需要周期性重新登录
</Warning>

## 故障排查

### 连接失败

1. 验证隧道 / 域名可达：`curl -I https://<your-domain>/mcp`
2. 确认 Mirobody 绑定的是 `0.0.0.0:8080`（或你配置的 `HTTP_PORT`）
3. 确认 `MCP_PUBLIC_URL` 与你填给 ChatGPT 的 URL 一致
4. 改了配置之后重启 Mirobody —— 它只在启动时重新读取一次

### 工具不显示

1. 直接用 `tools/list` 调用 `/mcp`，确认有工具返回
2. 检查 Mirobody 启动日志里有没有工具加载错误
3. 如果你添加了一个 C++ 工具，确认该文件位于 `res/mcp_tools/` 下，并已用 `./build.sh` 重新构建（参见 [添加工具](/zh/tools/adding-tools)）