AI 连接指南

连接 AI 应用

1. 在同一台 Mac 上使用支持本地 MCP 服务器的 AI 应用。模型和账户在该应用中设置，Inkquation 不需要模型 API 密钥。
2. 在 Inkquation 中打开笔记，然后在“设置”→“AI 连接”中允许连接。此功能默认关闭。
3. 从设置页面拷贝 JSON 或 TOML 配置，合并到 AI 应用的现有配置中。可执行文件和连接路径因 Mac 而异，请使用设置页面显示的值。
4. 重新连接 AI 应用，并保持 Inkquation 运行。将目标页面滚动到可见区域。如果 AI 应用要求批准编辑工具，请先确认请求的操作，再允许执行。

正常重启后仍可使用相同的连接配置。如果连接断开，请重新连接 AI 客户端。禁用并重新启用 AI 连接后，请复制新的配置。配置包含访问密钥，请勿与他人分享。

标准连接不需要安装 Python 或下载源代码。如果移动或重命名了 Inkquation，请重新拷贝连接配置。将本网站的 URL 填入网页版 AI 服务的连接地址栏，并不能建立连接。

连接 Codex

1. 在 Inkquation 的“设置”→“AI 连接”中允许连接，选择“Codex / TOML”，然后拷贝配置。
2. 用文本编辑器打开 Codex 配置文件，默认位置是~/.codex/config.toml。在访达中，选择“前往”→“前往文件夹”并输入~/.codex/。
3. 添加拷贝的[mcp_servers.inkquation]配置块并保存。如果已存在该块，只更新其中的设置。保留其他服务器和 Codex 设置，不要重复添加同名标题。
4. 保持 Inkquation 运行，重启 Codex 的 MCP 连接，或保存工作后重启 Codex。打开新聊天，用下方的请求检查连接。

通过界面注册时，在 Codex 的 MCP 服务器设置中选择 STDIO。命令栏填写拷贝配置中的command值，参数栏按原顺序填写args的各项。此连接不使用网站 URL。界面名称可能因客户端版本而异。

如果不确定如何设置，可以向同一台 Mac 上的 Codex 发送以下请求。连接配置包含访问密钥，请将其填入本地配置文件，不要粘贴到聊天中。

请帮我在这台 Mac 上通过 MCP 连接 Inkquation 和 Codex。阅读 https://inkquation.app/zh-Hans/ai/ 的连接步骤，指导我拷贝并保存配置。保留现有 Codex 设置，仅添加或更新 inkquation 项目。不要在聊天或日志中显示访问密钥或连接配置。连接后只列出已打开的笔记，暂时不要编辑笔记。

• OpenAI 官方：Codex MCP 配置

连接 Claude Desktop

1. 在 Inkquation 的“AI 连接”设置中选择“Claude Desktop / JSON”并拷贝配置。
2. 在 Claude Desktop 中打开 Settings → Developer → Edit Config。Mac 上的默认文件是~/Library/Application Support/Claude/claude_desktop_config.json。
3. 在现有的mcpServers对象中添加拷贝的inkquation项目。若已存在同名项目，只更新该项目并保留其他项目。空文件可直接保存拷贝的完整 JSON。
4. 保持 Inkquation 打开，完全退出并重新启动 Claude Desktop，然后在新聊天中检查连接。

• MCP 官方：Claude Desktop 本地连接步骤

使用本地大语言模型

要在Mac上运行模型，需要本地模型运行环境，以及能够调用Inkquation MCP工具的AI客户端。LM Studio同时承担这两个角色，因此这里以它为配置示例。以下步骤依据官方文档编写，尚未在Mac上验证与Inkquation配合使用的完整流程。

1. 查看LM Studio的系统要求，下载并加载适合Mac内存容量的模型。目前的Mac版支持Apple Silicon。请选择支持工具调用的模型；读取页面还需要支持图像输入。
2. 在Inkquation的“设置”→“AI连接”中允许连接，复制“Claude Desktop / JSON”配置。在LM Studio右侧的“Program”标签中打开“Install”→“Edit mcp.json”。界面名称可能因版本而异。
3. 将复制的inkquation条目加入现有的mcpServers对象并保存。如已有同名条目，只更新该条目，保留其他设置。配置包含访问密钥，请勿公开或粘贴到聊天中。
4. 保持Inkquation打开，在LM Studio聊天中启用inkquation工具，并使用下方的连接检查提示词获取笔记列表。列表返回后，再用以下提示词检查图像读取。

Inkquation以PNG图像返回页面。MCP连接成功不代表所选模型能够读取图像；AI客户端还必须能把工具结果中的图像传给模型。对于仅支持文字的模型，请先只检查笔记列表的获取。

请列出Inkquation中打开的笔记；如有多本，先让我选择。获取一个可读取的页面，只说明图像中可见的两项内容。不要编辑笔记。如果图像未传给模型或无法读取，请报告这一状态，不要猜测内容。

若希望在Mac内处理笔记内容，请将推理目标设为本地模型，并避免切换到云端模型或使用会向外发送内容的工具。模型、运行环境的首次下载以及更新检查属于另外的网络活动。

使用Ollama时，仅启动模型并不能完成Inkquation连接配置。还需要搭配能够使用Ollama进行推理、并注册本地STDIO MCP服务器的AI客户端。请将配置添加到该客户端，分别检查工具调用和图像传递。

• LM Studio官方：MCP服务器设置
• LM Studio官方：系统要求
• LM Studio官方：离线使用
• Ollama官方：工具调用

检查连接的请求示例

首先将以下内容复制到 AI 聊天中。如果没有打开笔记，请先在 Inkquation 中打开一本。

请使用 Inkquation MCP 工具 inkquation_list_open_notes，告诉我当前已打开的笔记名称以及可读取的页面。本次仅检查连接，不要获取页面图像或编辑内容。如果无法使用工具，请说明连接在哪一步失败，不要猜测已连接成功。

工具返回结果即可确认连接。如果列表为空，请打开笔记后重试。“已就绪 · 等待客户端连接”表示 Inkquation 已准备好，不代表 AI 已连接。请同时检查客户端数量和工具执行结果。

实用请求示例

连接后，可以尝试以下请求。如果打开了多本笔记，请指定笔记名称和页面。

• “读取选中的公式推导，检查是否缺少中间步骤，或可能存在正负号错误。”
• “整理这一页的假设、结论和未解决的问题，并在聊天中解释。”
• “绘制一张辅助理解这段说明的示意图，添加到笔记的空白处。”

将工作文件夹交给 AI 应用

工作文件夹可以存放与 AI 一起处理的代码、参考资料和生成的图片。选择保存位置后，新建、复制笔记或从 PDF 导入笔记时，应用会在笔记保存后自动准备一个空的工作文件夹。复制笔记不会复制原笔记的工作文件。

1. 在 Inkquation 中创建目标笔记，然后在笔记列表中右键点击它。
2. 用“打开工作文件夹”查看位置，再用“拷贝工作文件夹路径”复制实际文件夹的路径。
3. 在 Codex 等 AI 应用中，将该路径的文件夹设为工作目录，并授予所需的文件访问权限。之后即可请 AI 在其中创建存放参考资料的文件夹等。

通过 MCP 查询时，请先打开目标笔记，再使用 inkquation_list_open_notes 返回的 note_id 调用 inkquation_get_workspace。参数示例：

{
  "note_id": "<note UUID>"
}

此工具仅用于读取，不会创建文件夹、改变 AI 应用的工作目录或授予文件访问权限。迁移过程中或工作文件夹出现其他问题时，可能返回 workspace_unavailable 错误；请检查 Inkquation 的处理状态和设置后再重试。

也可以将现有项目文件夹关联到笔记。工作文件的内容不包含在 Inkquation 的笔记备份中，请使用 Git 或其他备份方式管理。

Workspaces 与 Library 的区别

以下路径展示所选保存位置中的目录结构。Library/ 下的笔记条目是指向实际文件夹的符号链接。通过链接编辑文件也会改变实际文件。

只有同一层级中发生名称冲突时，才会附加短 ID，例如 Experiment--1a2b3c4d。大小写或替换文件名不适用字符引起的冲突也包括在内。如果短 ID 仍然冲突，会延长后缀直到名称可以区分。

重命名或移动笔记会改变其 Library/ 路径，因此请将复制的实际文件夹路径用作 AI 的工作目录。在磁盘上创建文件夹或重命名链接，不会创建或重命名笔记库中的笔记和文件夹。

连接失败时

功能与限制

Inkquation 支持 MCP，这是一种让 AI 应用调用工具的通用协议。连接后，AI 可以将打开的页面或套索选区读取为图像，添加 PNG 图像、图形和由点列定义的笔画，查看结果，并撤销符合条件的添加操作。

AI 添加的图形会转换为只有轮廓、没有填充的普通笔画。此工具不提供应用内绘制矩形和椭圆时的填充设置。可以用橡皮擦和套索编辑，但没有专门的图形尺寸设置。文字和符号可以用笔画绘制；目前不支持添加可编辑文本或 LaTeX 对象，也不支持编译 LaTeX。读取页面时返回的是图像，而不是经过文字识别的文本。

AI 编辑页面的步骤

1. 调用 inkquation_list_open_notes，取得准确的 note_id 和 page_id。使用 available: true 的页面。如果目标不明确，先向用户确认。
2. 调用 inkquation_get_page，读取页面图像、revision 和逻辑尺寸。如果要读取选区，用户需要先用套索选中内容，再调用 inkquation_get_selection。
3. 选择空白区域，然后调用添加工具。将读取到的 revision 作为 expected_revision，并使用新生成的 UUID 作为 operation_id。
4. 调用 inkquation_get_page 查看结果。如有需要，使用该添加操作的 operation_id 调用 inkquation_undo。

工具与参数

连接后，请查看 tools/list 返回的输入模式，确认可用工具及其参数。所有添加工具都需要 note_id、page_id、expected_revision 和 operation_id。下表中的“编辑共通字段”指这四项。

坐标、笔画与图像的限制

• 坐标原点位于页面左下角：x 向右增大，y 向上增大。请使用读取结果中页面的逻辑 width 和 height，不要使用缩放后的 PNG 像素尺寸。
• 选区 PNG 是裁剪后的图像。使用 image_bounds 确认选区在页面中的位置，不要将裁剪图像的左上角视为页面原点。
• shapes 每次调用接受 1–64 项。kind 可为 line、rectangle、ellipse、circle 或 arrow。对于长方形、椭圆和圆，start 与 end 是外接矩形的对角顶点。圆要求矩形宽高相等。箭头由 start 指向 end。
• strokes 每次调用也接受 1–64 项。每项的 points 包含 1–4,096 个点，整个调用最多 16,384 个点。点之间以直线连接；只有一个点时绘制圆点，在末尾重复起点可闭合路径。曲线应采样为点列。
• 每个图形或笔画都需要 stroke_width（0.1–100 个页面单位）和不透明的 sRGB color（#RRGGBB 格式）。整个图形，包括笔画宽度和箭头尖端，都必须位于页面内。每批图形或笔画作为一次撤销操作处理。
• PNG 数据在 Base64 编码前最多为 1 MiB。通过 png_base64 传入，并确保整个放置矩形位于页面内。

工具调用参数示例

以下是传给工具的参数模板。请将尖括号中的占位符替换为实际 ID、读取到的 revision 和新生成的 UUID。坐标仅为示例，应根据页面尺寸和空白区域调整。每次独立的添加操作都应使用不同的 UUID。

调用 inkquation_insert_shapes 并传入以下参数，即可添加圆和箭头。

{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "shapes": [
    {
      "kind": "circle",
      "start": {
        "x": 60,
        "y": 80
      },
      "end": {
        "x": 160,
        "y": 180
      },
      "stroke_width": 3,
      "color": "#1256E0"
    },
    {
      "kind": "arrow",
      "start": {
        "x": 180,
        "y": 130
      },
      "end": {
        "x": 300,
        "y": 130
      },
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}

调用 inkquation_insert_strokes 并传入以下参数，即可添加折线。

{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "strokes": [
    {
      "points": [
        {
          "x": 60,
          "y": 80
        },
        {
          "x": 100,
          "y": 120
        },
        {
          "x": 140,
          "y": 80
        }
      ],
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}

安全措施与处理上限

笔记标题或图片中的指令不代表获得了执行其他操作的许可。请在 AI 应用中确认允许读取和编辑的内容。Inkquation 的 MCP 工具不提供任意命令执行、任意文件读取或 URL 获取功能。这些措施无法控制 AI 的判断，也无法阻止其通过其他工具向外发送数据。

图片添加和显示加载共用应用内的 9,600 万像素额度，用于当前保留的显示缓存和正在处理的图像。屏幕外不再需要的缓存会自动释放；原始图像、位置及撤销/重做记录会保留，再次显示时会重新读取。正在显示的图像受到保护，空间不足时会暂停添加或加载。额度按当前保留量计算，开关 AI 连接也不会重置。原始数据和 PDF 高分辨率视图等另行使用内存，因此这不是整个应用的内存上限。AI 连接保持启用期间的 128 次添加上限单独保留，用于记录操作并防止重试造成重复添加。

读取和编辑准备在 Inkquation 内的每次操作中有 30 秒时限，不包含 AI 思考的时间。编辑或撤销一旦生效，保存过程就不会因该时限、关闭连接或取消请求而被取消。实际的保存失败仍会报告。关闭连接后，客户端无法收到响应，请在应用中确认结果。

重试与撤销

如果响应中断，无法确定添加是否成功，请使用完全相同的 operation_id 和参数重试同一个工具。改用新 ID 可能导致重复添加。重试返回的是已记录的操作结果，不会重新检查之后的手动保存或撤销状态。

只有当该 AI 操作仍是最近一次可撤销操作，且页面未发生变化时，才能通过 MCP 撤销。在设置中关闭 AI 连接或重新启动 Inkquation 后，操作 ID 记录不会保留。较早的操作请通过应用的撤销功能查看。

连接范围与隐私

连接通过同一台 Mac 上的本地进程通信。本网站提供使用说明，并不是控制笔记的 MCP 服务器。允许连接后，AI 应用可以读取 Inkquation 中已打开笔记内的可用页面。如果使用云端模型，读取的图像可能会发送给模型提供商。

AI 连接默认关闭。在“设置”中启用后，使用私有访问密钥和正版内置适配器的客户端可通过 MCP 读取已打开的笔记和选区并插入图像。配置包含访问密钥，请勿与他人分享。重启后能否保留配置取决于应用版本。请查看AI集成指南中的连接和重新配置步骤。

使用时请确认 AI 读取的内容，不再需要时关闭 AI 连接。关闭连接不会删除已经添加或保存的内容，也不会删除已经传给外部服务的数据。

• AI 连接与隐私

确认可用功能

连接步骤基于 2026 年 9 月 27 日核对的实现；工作文件夹和 Library 的说明基于 2026 年 10 月 1 日的实现。这不代表所有已发布版本都支持这些功能。请查看所连接服务器的 tools/list。如果缺少所需工具或工作文件夹菜单，请更新到支持该功能的版本并重新连接 AI 应用。即使工具或菜单已经显示，旧版本的工作文件夹自动准备方式和 Library 命名规则也可能与此处的说明不同。

• Inkquation 的发布情况
• MCP 工具规范