内容
# mdEdit
一款本地优先的macOS Markdown编辑器，其**打开的文档可直接由AI读取和编辑**，通过本地MCP（模型上下文协议）传输 - 中间没有服务器。干净、受iA Writer启发的写作界面；完全原生（菜单、键等效、macOS 26上的Liquid Glass）。
一个已签名的、经过公证的构建版本可在 [lyr3.com/Products/mdedit](https://www.lyr3.com/Products/mdedit) 找到，
或者您可以从此仓库自行构建（需要macOS 26和Xcode 26；无外部依赖）。
## 布局
- `mdEdit/` — macOS应用程序（SwiftUI `DocumentGroup`，Xcode项目 `mdEdit/mdEdit.xcodeproj`）。
- `mcp-server/` — `mdedit-mcp`，Claude Desktop启动的stdio↔Unix-socket桥（SwiftPM）。
## 如何协同工作
```
Claude Desktop ──stdio JSON-RPC──▶ mdedit-mcp ──Unix socket──▶ mdEdit.app
(无状态) (真实来源：
实时缓冲区、修订记录、
文件协调)
```
应用程序拥有所有内容。桥梁是一个薄管道，因此**每个工具调用都通过应用程序并在屏幕上可见** - 没有屏幕外的影响。套接字路径：
`~/Library/Application Support/mdEdit/mcp.sock`.
## 安装（个人构建）
运行 `./install.sh` - 它在 **Release** 中构建应用程序，将其复制到 `/Applications/mdEdit.app`
（独立于Xcode/DerivedData），构建 `mdedit-mcp` 桥并打印Claude Desktop配置片段。
每次更改代码后，请重新运行它。
## 分发（lyr3.com）
`dist/release.sh` 生成一个经过公证、附有印章的DMG用于公开下载 - 使用 hardened runtime的开发者ID签名，
`mdedit-mcp` 捆绑在应用程序内。参见 [dist/README.md](dist/README.md) 获取一次性notary-credential设置和最终用户Claude Desktop配置。
## 构建
**应用程序** （Xcode 或 CLI）：
```sh
cd mdEdit
xcodebuild -project mdEdit.xcodeproj -scheme mdEdit -configuration Release build
# 然后将构建的mdEdit.app复制到/Applications（推荐使用稳定路径）
```
> MCP服务器仅在真正的`@main`应用程序中运行 - **不**在Xcode预览中。如果您从Xcode启动，请使用运行（⌘R），而不是预览画布。当从脚本驱动套接字时，请直接启动二进制文件（`mdEdit.app/Contents/MacOS/mdEdit`）。
**桥梁**：
```sh
cd mcp-server
swift build -c release # -> .build/release/mdedit-mcp
```
## 连接到Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` （参见 `claude_desktop_config.sample.json`），指向您构建的二进制文件和应用程序：
```json
{
"mcpServers": {
"mdedit": {
"command": "/absolute/path/to/mdEdit/mcp-server/.build/release/mdedit-mcp",
"env": { "MDEDIT_APP_PATH": "/Applications/mdEdit.app" }
}
}
}
```
`MDEDIT_APP_PATH` 允许桥梁在应用程序未运行时启动它；如果省略，则回退到通过包ID `com.lyr3.mdEdit` 启动（需要应用程序已向Launch Services注册，即至少运行一次）。
## 工具
| 工具 | 用途 |
|---|---|
| `list_open_files()` | 当前在应用程序窗口中活跃的文件路径 |
| `open_file(path)` | 将现有文件磁盘提升为活跃；打开/聚焦其窗口（不创建文件） |
| `read_file(path)` | 打开文件返回 `{content, revision}`；其他文件从磁盘读取 |
| `edit_file(path, edit, base_revision)` | 范围替换 `[start,end)`→`text` （UTF-16）。需要 `base_revision` |
| `get_selection(path)` | 打开文件的当前光标/选择 |
**提升规则。** 对未打开的文件执行 `edit_file` 返回 `{"error":"not_open"}` —
AI应 `open_file` 然后重试，并且该序列在工具跟踪中可见。
**过时写入检测。** 每个打开的文档都有一个单调的 `revision` （不是时间戳）。
如果人类自AI上次读取后输入，`edit_file` 将被拒绝，并带有 `{"error":"stale","current_revision":N,"current_content":"..."}`，以便AI可以协调而无需另一次往返。
## 编辑和查看
- **预览** （⇧⌘P）原生渲染Markdown - 调整大小的标题、缩进的列表、带边框的代码、
引用、表格、图像和内联样式 - 通过应用程序自己的渲染器使用Apple的Markdown解析器（无外部依赖）。
- **插入菜单** - 粗体（⌘B）、斜体（⌘I）、内联代码（⇧⌘C）、链接（⌘K）、图像（⇧⌘K）、
标题1-6（⌃⌘1-6）、列表、块引用、代码块、表格、水平线。每个都包装
所选内容或前缀当前行，并且可撤销。
- **帮助 ▸ mdEdit Markdown语法** （⌘?）打开实时备忘单（语法与其呈现结果并排）。
- AI编辑 **立即刷新到磁盘**；人类输入在短延迟后自动保存。
## 设计笔记
- 应用程序沙盒 **关闭** - mdEdit是一个个人工具，打开任意AI命名的路径
并通过套接字与外部启动的子进程会面。不是应用商店绑定。
- 写作界面是一个宁静的纯色画布；仅在chrome和字数统计上使用Liquid Glass，按照HIG。
- 字体排版（字体系列/大小/行间距）和外观在设置（⌘,）中。
## Markdown作为文档类型
应用程序声明并声称Markdown UTI（`net.daringfireball.markdown`，通过 `Info.plist`），
因此它打开 `.md`/`.markdown`/`.mdown`/`.markdn`，并且 **新文档默认保存为 `.md`**。mdEdit注册为Markdown的候选编辑器。
要使其成为您的 **默认** `.md` 应用程序（可选 - 操作系统保留TextEdit，直到您选择）：
Finder ▸ 选择一个 `.md` 文件 ▸ 获取信息 ▸ *打开方式* ▸ mdEdit ▸ **全部更改...**。将 `mdEdit.app` 放在 `/Applications` 中首先推荐，以便关联稳定。
## 尚未完成
- “推送到Kyle”推广操作。
- 焦点模式/打字机滚动改进。
## 许可证
MIT - 参见 [LICENSE](LICENSE)。 fork 它，构建它，使它成为你自己的。
