Ygdria MCP Server

一个轻量的 MCP ↔ Ygdria ETAPI 适配器。AI 客户端通过标准 MCP 协议搜索、读取和编辑 Ygdria 笔记；本项目不实现笔记数据库，也不会绕过 Ygdria ETAPI。

AI Client ── MCP/stdio ──> Ygdria MCP Server ── HTTP ETAPI ──> Ygdria Desktop

要求与安装

• Node.js 18 或更高版本

• 正在运行且已启用 ETAPI 的 Ygdria Desktop

• 用户自己创建的 ETAPI Token

git clone <this-repository-url> ygdria-mcp
cd ygdria-mcp
npm install
npm run build
Copy-Item ygdria-mcp.example.ini ygdria-mcp.ini  # PowerShell

不要把 Token 写入代码、提交到 Git，或放进 MCP 客户端配置。Token 过期后只需更新 INI，并重启 MCP 服务进程。

Related MCP server: triliumnext-mcp

配置

推荐复制 INI 模板并填写：

[etapi]
token = 你的 ETAPI Token
url = http://127.0.0.1:4318
allowWrite = false

模板文件是 ygdria-mcp.example.ini，复制后实际配置文件名为 ygdria-mcp.ini，且已经加入 .gitignore。默认会读取项目根目录中的该文件。

环境变量主要保留给自动化或临时调试使用，优先级高于 INI。日常使用请把短期 Token 放在 ygdria-mcp.ini，不要放在 MCP 客户端配置中：

默认是只读模式。只有显式设置 YGDRIA_ALLOW_WRITE=true 并重启服务后，写工具才会注册到 MCP 客户端。建议日常保持只读，仅在确实需要编辑时临时开启。

填写 INI 后可直接启动：

npm start

stdio 的 stdout 专用于 MCP 消息；启动错误只会写到 stderr。本项目不启动 HTTP Server。

MCP Tools

服务还提供动态 MCP Resource：

ygdria://note/{noteId}

读取 Resource 时固定通过 GET /etapi/notes/:noteId?format=markdown 返回 Markdown 正文。

安全模型

• 默认只注册五个只读工具；写入需要进程级显式授权。

• 只访问 /etapi/*。配置 URL 不允许携带路径，因此不能被配置成 /api/v1/*。

• 认证请求只发送 Authorization: Bearer <ETAPI_TOKEN>，不使用 X-Ygdria-Local-Token。

• 不访问 SQLite，不实现删除笔记或清空回收站，不添加缓存、同步或新的认证系统。

• ETAPI 不返回受保护笔记正文时，本服务直接保留权限边界，不尝试获取主密码、设备 Token 或 Local Token。

• 401 要求停止并重新配置 Token；403 停止且不绕过权限；404 报告目标不存在；写操作的 409 重新读取最新状态；415 提示检查 Content-Type；422 表示精确编辑无法唯一、完整地定位目标，须重新读取后生成补丁。

客户端配置

下面示例中的绝对路径请替换成你的 dist/index.js 路径。Windows JSON 路径中的反斜杠需要写成 \\。Token 和写权限均从项目根目录的 ygdria-mcp.ini 读取，不写入 MCP 客户端配置。

Claude Desktop

编辑 Claude Desktop 的 MCP 配置并重启客户端：

{
  "mcpServers": {
    "ygdria": {
      "command": "node",
      "args": ["D:\\path\\to\\ygdria-mcp\\dist\\index.js"]
    }
  }
}

Cursor

在项目的 .cursor/mcp.json 或 Cursor 的用户级 MCP 配置中添加：

{
  "mcpServers": {
    "ygdria": {
      "command": "node",
      "args": ["D:\\path\\to\\ygdria-mcp\\dist\\index.js"]
    }
  }
}

OpenAI Codex CLI（本地 stdio）

Codex CLI、IDE 扩展和桌面端共用 MCP 配置。可通过 CLI 注册本地 stdio 服务：

codex mcp add ygdria -- node /absolute/path/to/ygdria-mcp/dist/index.js

也可在 Codex 的 config.toml 中配置等价的 [mcp_servers.ygdria] 项。可参考 OpenAI Codex MCP 文档。

VS Code Codex 扩展

VS Code 中的 Codex 扩展与 Codex CLI 共用 MCP 配置，因此不需要维护另一份 JSON 文件。推荐使用以下任一方式。

方式一：在扩展界面添加。

1. 打开 VS Code 中的 Codex 面板。

2. 点击齿轮菜单，选择 MCP servers。

3. 点击 Add server。

4. 名称填写 ygdria，类型选择 STDIO。

5. 如果界面分别提供命令和参数字段，填写：

   • Command：node

   • Arguments：D:\path\to\ygdria-mcp\dist\index.js

6. 如果界面只提供一个命令字段，填写：

   node "D:\path\to\ygdria-mcp\dist\index.js"

7. 保存，然后选择 Restart extension。

这里不要填写 YGDRIA_ETAPI_TOKEN。Token 继续保存在项目根目录的 ygdria-mcp.ini 中。

方式二：编辑 Codex 配置文件。全局配置默认位于 C:\Users\<用户名>\.codex\config.toml；也可以在受信任的项目中使用 .codex/config.toml：

[mcp_servers.ygdria]
command = "node"
args = ["D:\\path\\to\\ygdria-mcp\\dist\\index.js"]
cwd = "D:\\path\\to\\ygdria-mcp"
enabled = true
default_tools_approval_mode = "writes"

default_tools_approval_mode = "writes" 会让 Codex 对非只读工具请求确认；Ygdria MCP 本身仍以 ygdria-mcp.ini 中的 allowWrite 为最终写入开关。修改配置后重启 Codex 扩展。在 VS Code 集成终端运行以下命令可以检查是否已注册：

codex mcp list

官方说明见 Codex MCP：IDE extension 配置。

ChatGPT Web

ChatGPT Web 的自定义 MCP App 连接远程 MCP 服务，不能直接启动本地 stdio 进程。因此本项目遵守“不实现 HTTP Server”的要求，不能直接粘贴到 ChatGPT Web 的 App endpoint 中。若账户和组织已提供 Secure MCP Tunnel，可用它把本地服务安全接入；否则需要一个独立、受控的远程传输桥接层（不属于本项目范围）。参见 OpenAI 关于 ChatGPT Developer Mode 与 MCP Apps 的说明。

开发与验证

npm run typecheck
npm test

测试覆盖只读默认值、禁止 /api/v1 风格 base URL、Bearer 认证、不发送 Local Token、受保护搜索结果过滤、Markdown If-Match，以及创建请求网络失败不重试。