KSJ MCP Server

Knowledge Synthesis Journal v2.0 — AI 伴侣

当前版本：ksj-mcp v3.6.2 · 基于 MCP SDK v2.0.0

将你的手写日记照片变成一个可搜索、由 AI 驱动的知识库——完全私密，只存储在你自己的机器上。

获取日记本： Knowledge Synthesis Journal v2.0 在 Amazon 上

目录

• 功能简介

• AI 平台支持

• 设置（3 步）

• 使用方法

• 可用工具

• Schema 标签系统

• 多日记本（卷）

• 故障排除

• 数据位置

• 许可证

Related MCP server: agrasandhany

功能简介

KSJ MCP 服务器通过 Model Context Protocol (MCP)（一种将 AI 模型连接到本地工具和数据的开放标准），将你的知识——手写的或数字化的——连接到 AI 助手。

实体日记本 → 知识库

拍下日记页，把它展示给你的 AI 助手，它就能：

• 搜索你写过的所有内容

• 发现想法之间的联系（共享标签、@ 引用）

• 列出你未解决的问题、关键洞见和突破

• 将你的知识库导出为 Markdown 或 JSON

页面如何进来——两条路径：

1. 助手视觉（推荐）。 在聊天中分享照片，让助手阅读手写内容，确认转录结果，然后用 manual_capture 存储页面。现代 AI 视觉对手写内容的识别准确率远高于传统 OCR——这是常规工作流。

2. 本地 OCR（可选）。 upload_capture 和 bulk_upload 在你的机器上运行 Tesseract。完全离线，但 Tesseract 对草书手写识别效果很差——最适合印刷体或非常工整的文本。

无论哪种方式，识别错误都不是永久性的：correct_ocr 会替换已存储捕获的文本，并重新运行解析、标签和关联，同时保留原始识别结果。

AI 研究会话 → 结构化洞见

花一个小时与 AI 助手深入探讨某个主题，当聊天结束时，大部分思考也随之消失。extract_insights 解决了这个问题——粘贴或通过管道传入会话记录，服务器就会提取重要内容：

• 新颖的假设和种子想法

• 概念之间意想不到的联系

• 值得追求的开放问题

• 已做出的决定和待办事项

每条洞见都有置信度评分（🟢 种子 / 🔴 发展中 / 🟡 强），并在写入数据库之前展示给你审阅。获批的条目会与你的日记捕获一起存储，并支持完整标签，因此 AI 提取的洞见会与你的手写笔记一起出现在搜索、关联图和综合建议中。

AI 伴侣——对你已写内容的独立检查

三对工具比搜索和关联更进一步：每一对都会对你已手写完成的页面运行一次独立的 AI 检查，然后在存储任何内容之前引导你查看发现。流程每次都一样——扫描 → 结构化对话 → 你的批准 → 一条独立的 AI 提取条目。 你的原始页面永远不会被重写。

• 综合（Synthesis）。 surface_connections 在 SYN 页面背后的 RC 集群中重新推导关联——对页面本身内容视而不见——然后将其独立解读与你的解读进行对比：你们双方都发现了什么、它发现了而你遗漏了什么、你看到了什么而标签重叠无法呈现的内容。commit_distillation 在你批准后将对比结果存储起来，并通过 distills 边链接到 SYN 页面。

• 审阅（Review）。 audit_knowledge_status 会根据日记中仍然存在的真实证据——关于该主题的未解决问题和未引用洞见——来核验声称的知识状态（Solid / Mastered）。commit_assessment 通过 assesses 边记录结果；你的 REV 页声称的状态永远不会被重写——真正的状态变更只会发生在未来的手写页面上。

• 梦境捕获（Dream Capture）。 dream_correlation 报告梦境条目与清醒条目之间的纯粹共现——刻意标注为 共现，而非相关性，并始终显示窗口大小、匹配数量和基础发生率，因为小日记本会让任何事情看起来都很有意义。bridge_dream_research 在此基础上通过对话探讨梦境符号对你的意义，commit_observation 通过 observes 边存储结果——称为 观察，而非推断，因为这是这种规模的日记本真正能支撑的。

所有这些都在实体页面存在之后运行，绝不会提前运行——先运行检查会让 AI 替你做那些实体练习本应迫使你完成的思考。没有一个工具为这一前提条件提供覆盖标志，而且对话本身的设计是提问而非提议：提问让你思考；而给出的建议答案则让 AI 代替你思考。

默认本地化。 存储、搜索和关联全部位于你机器上的 SQLite 数据库中——不会同步或托管到任何地方。当你的 AI 助手通过视觉读取日记照片时，该图像会像任何其他聊天附件一样由助手平台处理；本地 Tesseract OCR 路径则让一切留在机器上。批量导入的可选云 OCR 确实存在，但默认关闭，除非你使用自己的密钥明确启用。

AI 平台支持

本服务器使用 MCP（Model Context Protocol），这是一个开放标准，在 AI 平台和开发者工具中获得了越来越多的支持。

目前支持：

• Claude Desktop（免费）——完整支持 MCP，推荐用于入门

其他兼容 MCP 的客户端（Cursor、VS Code + GitHub Copilot 等）可以使用相同的配置进行连接——有关设置详情，请查阅你客户端的 MCP 文档。

正在使用 ChatGPT、Gemini 或其他平台？ 使用 export_captures 工具将知识库导出为 Markdown 或 JSON，然后粘贴到你选择的 AI 助手中。随着生态系统的成长，为更多平台提供完整的原生 MCP 支持已在路线图上。

协议合规性： ksj-mcp 通过 stdio 传输运行在官方 Python MCP SDK v2.0.0 之上，使用协议的经典初始化握手模型——可协商至协议修订版 2025-11-25。（MCP 按日期发布的规范版本进行版本控制，而非语义化版本——上面的“MCP SDK v2.0.0”指的是 SDK 包自身的版本号，而不是协议修订版。）

设置（3 步）

无需 OCR 软件——你的 AI 助手负责阅读页面。（也想要完全离线的 OCR？请参阅 可选：离线 OCR 在设置之后。）

第 1 步 — 安装兼容 MCP 的 AI 客户端

最快入门方式是 Claude Desktop（在 claude.ai/download 免费获取）。

对于其他 MCP 客户端，请查阅其文档了解如何注册本地 MCP 服务器，然后使用第 3 步中的配置。

第 2 步 — 安装 uv 和 KSJ 服务器

uv 是一个快速的 Python 包管理器，用于安装和运行 KSJ 服务器。

安装 uv：

在继续之前，请在终端中用 uv --version 验证。

安装 KSJ 服务器（在终端中运行一次）：

uv tool install --from git+https://github.com/ChavezAILabs/ksj-mcp ksj-mcp

这会将 ksj-mcp 作为持久命令安装到你的机器上。此步骤必须安装 Git（Windows：Git for Windows）。

使用 uv tool list 验证——它应列出带版本号的 ksj-mcp。

以后更新：

uv tool upgrade ksj-mcp

第 3 步 — 注册服务器

Claude Desktop 配置文件位置：

Claude Desktop 以受限的 PATH 启动 MCP 服务器，因此即使裸命令 "ksj-mcp" 在终端中运行正常，也常常无法解析——请改用第 2 步中 uv tool install 创建的二进制文件的完整路径：

添加以下代码块（此处显示 Windows 示例——如适用，请换成你的 macOS/Linux 路径）：

{
  "mcpServers": {
    "ksj": {
      "command": "C:\\Users\\<you>\\.local\\bin\\ksj-mcp.exe"
    }
  }
}

保存并重启你的 AI 客户端。你应该会在工具/集成面板中看到 ksj。

可选：离线 OCR（Tesseract）

仅当你希望 upload_capture / bulk_upload 在机器上完全读取照片，而不是通过助手的视觉时，才需要此项。郑重提醒：Tesseract 对草书手写的识别效果不佳——印刷体或非常工整的文本效果最好。

安装后，重启你的 AI 客户端，以便获取更新后的 PATH。

Windows 说明： 如果你跳过了“Add to PATH”，服务器仍会在默认安装位置（C:\Program Files\Tesseract-OCR\）自动检测 Tesseract。

可选：用于批量导入的云 OCR

默认关闭——除非你启用，否则不会有任何数据离开你的机器。

使用 bulk_upload 导入整个手写页面文件夹是本地 Tesseract 真正带来困扰的地方：一页接一页的草书变成乱码。如果你的积压量很大，可以将服务器指向你自己的 Azure Document Intelligence 资源（手写文字错误率约 9%，而 Tesseract 约 95%）：

{
  "mcpServers": {
    "ksj": {
      "command": "C:\\Users\\<you>\\.local\\bin\\ksj-mcp.exe",
      "env": {
        "KSJ_OCR_BACKEND": "azure",
        "KSJ_AZURE_ENDPOINT": "https://<your-resource>.cognitiveservices.azure.com",
        "KSJ_AZURE_KEY": "<your-key>"
      }
    }
  }
}

（对于你的平台，请使用第 3 步中的 command 路径。）

这对你的数据意味着什么：每张上传的图片都会被发送到你自己的 Azure 资源（你的订阅、你的密钥、Azure 的数据条款）进行文本提取。不会向任何地方发送其他内容，无论哪种方式，你的知识库都保持本地。每次上传的输出都会明确说明云 OCR 何时处于活动状态。移除 KSJ_OCR_BACKEND 即可恢复完全本地处理。

如果只有几页，可以跳过这一切——在聊天中分享照片并让助手阅读，既免费又同样准确。

使用方法

连接后，自然地和你的 AI 助手对话。

记录页面（推荐流程）：

[在聊天中分享页面照片] “读取这个日记页面并将其加入我的知识库”

“这里是 RC-007 — 转录它，给我看你读到的内容，然后存储下来”

通过本地 OCR 捕获（可选，需要 Tesseract）：

"上传我的日记照片，来自 /Users/me/Desktop/RC-001.jpg"

"处理我 /Desktop/journal-scans 文件夹中的所有照片"

修复错误读取：

"捕获 #12 的文本有误——这是更正后的转录：…"

搜索与浏览：

"在我的笔记中搜索关于间隔重复的想法"

"显示所有标记为 #machine-learning 的内容"

"关于微积分，我有哪些未解决的问题？"

"显示所有与 RC-015 相关的内容"

综合与回顾：

"我准备好将哪些主题综合成 SYN 页面？"

"显示我的突破时间线"

"我对 #linear-algebra 的理解进展如何？"

"Run surface_connections on SYN-004" → 独立扫描其背后的 RC 集群， 然后进行对话，将它的发现与您写的内容进行比较

"Audit REV-008 against the evidence" → 检查其声称的知识状态， 与该主题上仍存在的未解决问题和未引用见解进行对照

梦境捕获：

"哪些符号和主题反复出现在我的梦中？"

"显示我这个月的所有梦境条目"

"我的清醒条目附近是否出现 #flying？" → 仅显示共现计数， 始终展示窗口、匹配数和基率

"将 DC-005 与我的研究连接起来" → 检查跨域回响，然后询问 这些梦的符号对你意味着什么（绝不提出解释）

导出与健康：

"将所有标记为 #ai 的捕获导出为 Markdown"

"根据我的未解决问题生成学习卡组"

"我的日记实践情况如何？"

"给我一个可浏览的整个知识库视图" → 生成一个自包含的 .html 文件——时间线（支持日期范围搜索和每次 25 条的加载更多）、 标签/实体索引、每条捕获的连接列表，以及一个以自我为中心的连接 图（点击标签簇或捕获可查看其局部邻居，点击 任何邻居可重新居中）——你可以在任何浏览器中打开，无需服务器或安装 即可

可用工具

下面所有 36 个工具都在 v3.6.0 发布就绪检查中单独进行了测试（包括真实数据和错误输入的情况）。在此过程中发现并修复了一个扩展性问题：export_study_deck 在非常大的知识库上可能将太多相关的见解合并到一张闪卡中——现在按连接强度排序并设有上限。

日记工具

AI 会话工具

Schema 标签系统

在您的日志页面任意位置使用这些前缀 — 服务器会自动提取它们。

RC、SYN、REV 页面：

DC（梦境捕获）页面使用特定于梦境的变体：

服务器会自动对这些执行三件事：

• 角色。 相同的字符在 DC 页面与 RC/SYN/REV 页面上的含义不同（! 在 RC 上是优先级，在 DC 上是反复出现的母题）。服务器会将含义与字符一同存储，因此按标签浏览时可以区分它们 — 例如“优先级项目”与“梦境母题”。

• 实体。 非模板 ID 的 @ 值（如 @Veronica、@the-old-house）会成为命名实体 — 可在每次捕获和每个日志卷中搜索。梦境符号和故事角色属于同一类对象。

• 标签气泡。 写在印刷标签气泡内的任何内容都算作标签，无论有没有 #。DOG MAN、Dog-Man 和 DOG-MAN 都会规范化为同一个标签。

多日志（卷）

完成一本日志并开始第二本？新书会从 RC-001 重新开始 — 这是正常的。每本实体日志都是一个卷，第 2 卷延续第 1 卷的知识库：搜索覆盖所有卷，跨卷连接也是正常的。

当您开始一本新书时，请说一次：

“我要开始我的第二本日志” → 助手运行 set_volume(current_volume=2)

或者在页面本身上写上卷号（例如模板 ID 旁边的 V2），或在单次上传时传递 volume=2。如果上传与现有页面 ID 冲突，服务器会询问是新日志还是重新捕获 — 任何内容都不会被静默覆盖。

故障排除

“未安装 Tesseract OCR” 您调用了 upload_capture/bulk_upload，它们需要可选的本地 OCR 引擎。要么安装 Tesseract（可选：离线 OCR）并重启您的 AI 客户端 — 要么完全跳过：在聊天中分享照片并让您的助手代为阅读和存储页面。

“已存储为 UNIDENTIFIED” 无法从照片中读取模板 ID，但页面及其文本仍已存储 — 不会丢失任何内容。告诉您的助手正确的 ID（“这是 RC-007”），它会用 identify_capture 修复。不规整或未补零的 ID（RC-7、RC-OO2、数字后多余字母）会自动读取，并附带确认说明。

OCR 识别文本有误 让您的助手用 correct_ocr 修复 — 给它捕获编号和更正后的文本。原始读取内容会保留，标签和连接会从更正结果中重建。

“RC-001 已存在于您的知识库中” 您正在重新上传一个已存储的页面。要用新照片替换它（例如在更清晰的补拍之后），请让您的 AI 助手以 force=True 上传：

“使用 force=True 上传 /path/to/RC-001.jpg”

“服务器传输意外关闭” / 服务器无法启动 在终端中运行 uv tool list — 它应列出带版本号的 ksj-mcp。如果缺失，请重新运行步骤 2 中的安装命令。如果已安装，问题可能出在 Claude Desktop 配置 — 请仔细检查它是有效的 JSON，并且 command 是 ksj-mcp 二进制的完整路径（参见 步骤 3），而不仅仅是 "ksj-mcp"。

服务器未出现在工具面板中 确认 uv tool list 显示已安装 ksj-mcp，验证配置文件是有效的 JSON，并在保存任何配置更改后重启 Claude Desktop。连接后，让您的助手使用 get_version 工具 — 这可以确认服务器确实在运行且可访问，而不仅仅是已安装。

数据位置

您的所有捕获内容都本地存储在 ~/.ksj-mcp/ 中：

文件：

~/.ksj-mcp/captures.db     (SQLite database — all your captures and tags)
~/.ksj-mcp/images/         (copies of uploaded journal photos)

您的数据不会发送到任何地方，并且会在更新后持续保留。Schema 升级会在服务器启动时自动运行；在首次 3.0 启动前，您的数据库会备份到同一文件夹中的 captures.db.bak-v3。

自定义位置： 在配置中设置 KSJ_DATA_DIR 环境变量以将数据存储在其他位置：

{
  "mcpServers": {
    "ksj": {
      "command": "C:\\Users\\<you>\\.local\\bin\\ksj-mcp.exe",
      "env": {
        "KSJ_DATA_DIR": "C:\\Users\\you\\Documents\\ksj-data"
      }
    }
  }
}

（对于您的平台，请使用 步骤 3 中的 command 路径。）

许可证

MIT — 可自由使用、修改和分享。

由 Chavez AI Labs LLC 创建 paul@chavezailabs.com

获取日志： Knowledge Synthesis Journal v2.0（Amazon）