7. PinSlip AI 与 MCP 集成

7. AI 集成（MCP）

PinSlip 内置一个 MCP 服务器（Model Context Protocol，MCP 标准协议）。
你的 AI 助手（Claude Code / Kimi Work / 任何兼容 MCP 的客户端）可以搜索、读、写、删除你的便签。
默认开启，监听 127.0.0.1 固定端口。

7.1 什么是 MCP

MCP（Model Context Protocol）是 Anthropic 提出的开放协议，让 AI 助手可以调用本地工具。PinSlip 的 MCP 服务器暴露 12 个工具，涵盖「读 + 写 + 同步」三大场景。

生命周期

• 与 PinSlip 应用同进退——应用没启动，MCP 不可用

• 监听 127.0.0.1 的固定端口（仅本机通信，外部不可达）

• 协议：Streamable HTTP（MCP 标准）

总开关

• 设置 → MCP 服务

• 默认开

• 关闭后服务侧 /mcp 端点 404

7.2 接入发现

PinSlip 启动时把发现信息写到 <vault>/.pinslip/mcp.json：

{
  "port": 17639,
  "pid": 12345,
  "version": "1.0.1",
  "mcpPath": "/mcp",
  "startedAt": "2026-07-31T14:00:00+08:00"
}

• 客户端怎么知道怎么连？ 直接读这个文件即可（PnP 的 AI 助手必须能读）

• pid 死亡 → 提示「启动 PinSlip 应用」

• 设置抽屉 有「一键复制接入信息」按钮，把 mcpServers JSON 复制到剪贴板

7.3 客户端配置示例

Claude Code

{
  "mcpServers": {
    "pinslip": {
      "url": "http://127.0.0.1:17639/mcp",
      "type": "http"
    }
  }
}

<port> 替换为你 mcp.json 里那个。

复制接入信息

设置 → MCP 服务 → 「复制接入信息」 → 直接贴到客户端配置即可。

7.4 12 个工具

数据面（10 个）

同步面（2 个）

时间过滤

search_notes / list_notes 支持：

• since / until闭区间

• 接受 YYYY-MM-DD（本地时区）或完整 RFC3339

• timeField = updated（默认）/ created

7.5 AI 能做什么 / 不能做什么

✅ AI 可以做

• 搜索任何便签（全文 + 标签 + 文件夹 + 时间）

• 读任何便签的完整内容

• 新建便签（落到指定文件夹、指定标签）

• 修改便签（整段替换 / 内联替换 / 追加）

• 删除便签（仍走回收区，永远不会绕过回收区）

• 触发同步、查询同步状态

❌ AI 不能做

• UI 状态：置顶、颜色、折叠、组关系

• 同步配置：仓库地址、token、分支

• 物理删除：绕过回收区直接删除

• 修改 vault 外的文件（仅扫 vault 目录）

7.6 典型使用场景

让 AI 写日报

你：今天做了哪些事？帮我写日报。

AI 思路：
1. list_notes(since: 2026-07-31)
2. read_note 候选便签
3. 提炼摘要
4. create_note(folder="日报", title="日报 2026-07-31", content=摘要)

让 AI 整理 inbox

你：把 inbox 里今天的便签按主题分类到对应文件夹。

AI 思路：
1. list_notes(folder="inbox")
2. 每条 read_note
3. 分类、判断目标文件夹
4. update_note(folder=目标)

让 AI 找遗忘的想法

你：我之前记过一个关于「后端性能优化」的便签，找出来。

AI 思路：
1. search_notes("后端性能优化")
2. read_note 匹配项

让 AI 监督任务清单

你：我今天有哪些任务没完成？

AI 思路：
1. search_notes "- [ ]" 或读所有便签后 grep
2. 列出未完成

让 AI 批量改标签

你：把标签 #work 的所有便签加一个 #2026Q3 标签。

AI 思路：
1. list_notes(tag="work")
2. 逐条 update_note / patch_note 增加标签

7.7 安全注意事项

• MCP 只监听 127.0.0.1：外部网络无法访问，只能使用本地agent客户端

• 没有 token 鉴权：因为绑回环即认证（OS 层面保证）

• 应用退出 → 服务关闭：不存在长期暴露

• 删除走回收区：误删可恢复

• 建议：在公共电脑 / 共享账号时关闭 MCP 开关

7.8 故障排查