MDDock 如何通过 MCP 让 Codex 检索和编辑本地知识库？

MDDock 与 Codex 的组合方式并不是把整个知识库上传给模型，而是让 MDDock 在本机启动一个 MCP 服务，再由 Codex 按需调用检索、读取和编辑工具。正确的使用顺序是：先在 MDDock 中打开并完成知识库索引，取得桌面端提供的 MCP 启动命令；再把这条命令登记到 Codex 的 MCP 配置；最后用一次只读检索确认连接，确认结果正确后才允许写入。这样既保留 Markdown 文件的本地可控性，也避免每次对话手工粘贴大量笔记。

MDDock、MCP 与 Codex 各自负责什么

MDDock 把知识库存放为普通 Markdown 文件，并在本地维护全文、语义和关联信息。MCP，也就是 Model Context Protocol，负责把这些能力包装成客户端可以发现和调用的工具。Codex 是调用方：它理解用户任务，决定何时检索、读取哪一篇笔记，以及是否发起修改。三者之间传递的是工具请求和必要的结果，而不是要求用户把整个目录复制进提示词。

按照 MDDock 官方文档，当前统一工具包括 mddock_recall、mddock_read、mddock_remember 和 mddock_propose。其中 recall 用于从 workspace 找相关片段，支持混合检索、纯关键词检索、向量检索和图扩展；read 用路径或 MDDock URI 读取 Markdown 内容；remember 用于写入记忆页、记录 agent 身份或编辑已有文档，并留下审计记录；propose 用于提出需要审核的知识库变更。理解这个分工很重要，因为“检索”和“编辑”并不是同一个权限等级。

连接前先准备知识库

先在 MDDock 桌面端打开实际要使用的 Markdown 文件夹。已有的 Markdown 文件不需要重新导入，打开文件夹后即可进入索引流程。若资料来自 Word、PDF、PPT 或 Excel，可以先通过 MDDock 转为 Markdown；扫描型 PDF 仍需要先做 OCR，不能把没有文本层的文件当作已经可检索。建议先在 MDDock 内搜索一个确定存在、且不容易与其他内容混淆的词，例如项目代号或会议决策，确认索引确实返回目标笔记。

知识库目录应当保持边界清晰。工作资料、个人笔记和敏感凭据不要因为方便而混在同一个 workspace。MCP 工具看到的是当前知识库允许它看到的内容；本地优先并不等于任何内容都适合交给自动化工具。还应当用 Git、同步盘历史版本或定期备份保护 Markdown 文件，因为审计记录能说明发生过什么，但不能替代可靠备份。

在 Codex 中登记 MDDock MCP

在 MDDock 的 MCP 连接页面或桌面端设置中找到它为当前安装生成的启动命令。MDDock 使用标准输入输出上的 JSON-RPC 作为传输方式，因此 Codex 侧需要新增的是本地 stdio MCP 服务，而不是填写一个网页地址。把可执行文件路径放入命令字段，把其余启动项逐个放入参数列表，并给连接取一个容易识别的名称，例如 mddock。

名称：mddock
传输：stdio
命令：使用 MDDock 桌面端显示的实际可执行文件路径
参数：使用 MDDock 为当前版本显示的 MCP 启动参数

不要照抄别人的绝对路径，也不要猜测二进制名称。macOS、Windows 和 Linux 的安装位置不同，桌面版升级后入口也可能变化。若当前 Codex 版本提供 MCP 设置界面，就在界面中填写上述字段；若使用命令行配置，则以该版本自身的帮助信息为准，把同一组命令和参数登记进去。核心要求只有两个：服务类型是 stdio，启动的确实是本机 MDDock 所给出的 MCP 入口。

登记完成后重启或重新加载 Codex 会话，使客户端重新发现工具。工具列表中应能看到以 mddock_ 开头的四个工具。若只看到服务器名称却看不到工具，说明进程可能启动后立即退出，或者客户端没有读到正确的工具清单，此时不应直接开始编辑。

先用只读任务验证检索链路

第一次测试应当是范围明确的只读问题，例如“在 MDDock 中查找关于项目 A 发布条件的笔记，列出命中的文件和相关段落，不要修改文件”。Codex 应先调用 mddock_recall 获取候选片段，再在需要上下文时调用 mddock_read。如果问题只要求定位资料，通常没有理由调用 remember 或 propose。

检索结果需要由用户核对三个方面：文件是否来自预期 workspace，片段是否真正回答问题，结论是否能回到具体笔记。混合检索适合大多数自然语言问题；精确的编号、函数名或错误文本更适合关键词检索；概念相近但用词不同的笔记可尝试向量检索；需要沿人物、项目或链接关系继续寻找时，再考虑图扩展。不要一开始就扩大检索范围，否则相似但无关的旧笔记容易混入答案。

一个更稳健的提示方式是把任务拆成“召回、读取、总结”三步，并要求 Codex 在信息不足时停止推断。例如：

请在 MDDock 中检索“上线回滚条件”。
只读取最相关的三篇笔记，按文件名列出原有结论。
如果笔记之间冲突，请指出冲突，不要自行合并，也不要修改知识库。

这种约束能减少一次读取过多文件，也让用户看到结论与原始记录之间的关系。MDDock 的价值不是替模型替你做事实判断，而是给模型提供可追溯的本地上下文。

让 Codex 安全编辑本地笔记

只读链路稳定后，再处理编辑任务。编辑前应当说清目标文件、允许修改的章节、要保留的内容和验收条件。对现有文档的直接修改由 mddock_remember 承担，并带有审计记录；需要用户审阅后再落地的变更应优先通过 mddock_propose 提出。官方文档明确区分了直接写入和提议式变更，目的就是防止 agent 在没有边界的情况下悄悄重写笔记。

读取“项目A/发布清单.md”。
只在“回滚检查”章节末尾补充三项检查项，保留其他段落原文。
先展示拟修改内容并说明依据，得到确认后再写入。
写入后重新读取该章节，核对标题、列表层级和原有内容。

即使工具支持写入，也不应给出“整理整个知识库”这类无限范围的指令。更合适的做法是一次限定一个目录或文件，先提出差异，再执行修改，最后回读验证。涉及删除、批量重命名、合并笔记或调整 frontmatter 时，应额外检查链接、标签和引用是否仍然有效。对于事实性内容，还要区分“从旧笔记提取出的事实”和“模型新生成的表述”，避免把推测写成历史记录。

常见故障如何定位

Codex 中没有出现 MDDock 工具

先确认 MDDock 桌面端可以正常打开目标 workspace，再检查 Codex 中登记的命令路径和参数是否与当前安装一致。官方文档建议使用 MDDock 自带的诊断能力检查 workspace、数据结构和二进制版本，并查看本机 MDDock 日志目录中的 MCP 日志。若手工启动入口也立即报错，应先解决 MDDock 端问题；若手工入口正常而 Codex 不显示工具，则重点检查 Codex 的配置是否被当前会话加载。

能连接但搜不到已有笔记

确认打开的是正确 workspace，目标文件确实是可解析的 Markdown，并且索引已经完成。先用精确关键词搜索文件中的独特字符串，再尝试混合或向量模式。由 PDF 或 Office 导入的内容还要检查转换结果，而不是只看原文件存在。若扫描 PDF 没有 OCR 文本，检索为空是预期现象。

检索正确但回答偏离原文

缩小召回数量，要求先列出命中文件和原始片段，再生成总结。对于日期、决策、负责人等容易造成实际影响的信息，应让 Codex 指明来自哪篇笔记，并在写回前让用户确认。知识库里存在多个版本时，不要让模型自行把冲突内容拼成一个新结论，而应先标出时间和差异。

编辑后内容不符合预期

停止后续批量操作，利用版本控制或备份恢复，再把任务缩小到单个章节。检查指令是否明确了“保留未涉及内容”和“写后回读”。如果希望所有变更都先经人工审核，应改用提议式流程，不要继续授权直接编辑。审计日志适合追踪操作，文件历史则负责真正的恢复，两者应同时保留。

一套可重复使用的工作流

日常使用可以固定为五步：在 MDDock 中维护和索引 Markdown；在 Codex 中连接本地 stdio MCP；先 recall 定位候选内容；再 read 获取必要上下文；需要修改时先提出差异，经确认后 remember 写入并回读。搜索问题使用最小必要范围，编辑问题限定文件和章节，高风险变更始终保留人工确认。

这套方式的关键并不是让 Codex“拥有”知识库，而是给它一条受约束、可检查的访问路径。MDDock 负责本地文件、索引和审计，MCP 负责标准化工具边界，Codex 负责理解任务和编排调用。只要连接信息来自当前安装、检索先于写入、写入之后回读验证，就能在保持本地知识库可控的前提下，让 Codex 更高效地查资料和维护 Markdown。