MCP 清单总表

2026-04-19 起，本文作为 docs/agent 下 MCP 管理的 canonical 文档，吸收 MCP 体系与安装管理规范.md 与 MCP 安装记录（2026-04-17）.md；..\codex-knowledge\50-tools\docx-automation-guide.md 与 ..\codex-knowledge\50-tools\epub-reading-options.md 因不属于同一项目/同一交付物，保持独立。

如需继续修改、整合或扩写这份文档的结构与归并方式，先遵循 C:\Users\ASUS-KL\.codex\AGENTS.md 中的文档规则层；维护说明见 C:\Users\ASUS-KL\.codex\AGENTS.annotated.md，不要再并行长出新的总表壳或说明壳。

0. 使用导航

这份文档现在是 docs/agent 下 MCP 管理的 canonical 文档，负责两类信息：

• 当前 live MCP 注册状态
• MCP 管理规范与历史安装记录的可追溯归档

边界说明：本文只负责 MCP 专题，不承担项目总体 current-state 三件套职责；项目当前总体状态仍先看 PROJECT-CONTEXT.md、SESSION-HANDOFF.md、plan.md。

如果你来这里是为了找资料，直接按下面进：

• 想看当前这台机器实际启用的 MCP -> 继续看本文第 1~5 节
• 想看“哪些旧说法已经过时” -> 看本文第 6 节
• 想看 2026-04-17 的历史规范与安装记录原文 -> 看本文后半部分“整合补编（2026-04-19）”
• 想回到多服务器总体系 -> Server Operation & Maintenance Manual.md

1. 当前 live 判定基准（2026-04-20）

本页当前以“这台机器现在怎么配”为准，不再以 2026-04-17 的旧快照为准。

当前真源：

• 实际配置文件：C:\Users\ASUS-KL\.codex\config.toml
• 当前 managed block 生成脚本：E:\My Project\Atramenti-Console\codex\scripts\register-codex-paths.ps1
• 当前 repo-managed MCP 根目录：E:\My Project\Atramenti-Console\codex\mcps
• 当前受托管的配置块标记：
  • # BEGIN self-debug-closed-loop managed mcp servers
  • # END self-debug-closed-loop managed mcp servers

这意味着：

1. 当前 Codex 的 live MCP 清单，应以 config.toml 里的 managed block 为准。
2. 当前路径真源已经切到 E:\My Project\Atramenti-Console\codex\mcps，不是更早文档里写的 E:\My Project\Atramenti-Console\mcps。
3. 旧的 provision-codex-integration.mjs 叙述现在只能视为历史来源材料，不能再当作当前注册真源。

2. 当前已注册并生效的 MCP 总表

下表按 live config.toml 整理；当前 live 条目以实际 managed block 为准。

3. 当前 live 注册结构怎么理解

3.1 代码与工程检查层

这批是当前默认常用的工程型 MCP：

• cloud-repo-mcp
• dev-quality-mcp
• ripgrep-search
• workspace-toolkit-mcp
• agent-runtime-mcp
• github-workflow-mcp

3.2 GitHub 交付层

当前 GitHub 相关能力现在是明确拆层，而不是继续把远端 API、CI 审计、本地提交发布混成一个入口：

• github
• github-workflow-mcp
• github-delivery-mcp

分工规则：

• github：官方 remote GitHub MCP，负责 GitHub 平台面 API
• github-workflow-mcp：workflow、job、PR 健康 / 失败调查
• github-delivery-mcp：从 canonical repo / 本机工作副本起步的 prepare_working_copy、retire_working_copy、repo_context、gh_auth_status、publish_changes、create_pull_request

3.3 文档与媒体输入层

当前已经不是只有 fetch-mcp 和 markitdown-mcp 两个输入点，媒体链也已经接进 live 配置：

• fetch-mcp
• markitdown-mcp
• ffmpeg-mcp
• yt-dlp-mcp
• video-audio-mcp

这也意味着：

• “当前没有默认预装 ffmpeg”这类旧说法已经过时
• 当前文档 / 视频 / 字幕 / 音频链路已经是同一批 live 已注册工具的一部分

3.4 浏览器与设计层

• chrome-devtools-mcp
• pencil

前者负责页面、控制台、网络面验证；后者负责 .pen 设计文档读写。

4. 当前未注册但仓库内仍存在的典型 MCP / 能力

E:\My Project\Atramenti-Console\codex\mcps 下现在还有大量 MCP 或模块目录，但它们不应自动视为“已注册”。

典型例子：

• context-store
• database-ops-mcp
• log-diagnose
• orchestration-pipeline
• output-guard
• playwright-browser
• prompt-compressor
• repo-inspector
• standards-guard
• chrome-devtools-mcp-wrapper
• drawio-diagrams
• plantuml-diagrams

这些目录说明“仓库里有能力实现或包装”，但是否当前启用，仍然只看 C:\Users\ASUS-KL\.codex\config.toml。

5. 当前管理方式（按现在的设置）

如果后续要新增、删除或改路径，当前正确做法是：

1. 修改 E:\My Project\Atramenti-Console\codex\scripts\register-codex-paths.ps1
2. 运行该脚本回写 C:\Users\ASUS-KL\.codex\config.toml
3. 再核对 managed block 与实际路径是否一致

当前管理要点：

• 以 codex 为能力真源，不以仓库根 mcps 为真源
• 不要只手改 config.toml 后就认为长期生效
• 当前 live 注册以 PowerShell 路径重写脚本为准，而不是旧的 provision 口径
• 如果文档写“已注册”，必须能在当前 config.toml 里找到对应项
• GitHub 提交相关能力的当前 canonical 组合是：github + github-workflow-mcp + github-delivery-mcp，不要再并行长出一个职责重复的大而全 GitHub MCP

6. 这份文档中哪些旧口径已经过时

以下旧口径现在都不再准确：

• E:\My Project\Atramenti-Console\mcps 是当前 MCP 真源目录 -> 已过时，现应为 E:\My Project\Atramenti-Console\codex\mcps
• self-debug-closed-loop/scripts/provision-codex-integration.mjs 是当前 Codex 配置托管入口 -> 已过时，现应以 register-codex-paths.ps1 为准
• 当前 live 注册包含 context-store / db-readonly / repo-inspector / notion 等 -> 已过时；其中数据库链路现已收口为 database-ops-mcp，db-readonly 只保留兼容层，不再作为 live 一等注册项
• 当前重点仍不包含 ffmpeg -> 已过时，ffmpeg-mcp、yt-dlp-mcp、video-audio-mcp 已在当前 live 配置中注册
• GitHub 提交 / 推送 / PR 仍主要靠手工 shell 串命令、没有 MCP 收口 -> 已过时，当前 live 组合已经是 github + github-workflow-mcp + github-delivery-mcp

下面的“整合补编”继续保留，是为了保留规范来源和历史安装记录，不代表这些历史叙述仍然是当前真源。

7. 整合补编（2026-04-19）

• canonical target：MCP 清单总表.md
• absorbed sources：MCP 体系与安装管理规范.md、MCP 安装记录（2026-04-17）.md
• excluded after topical-coherence audit：..\codex-knowledge\50-tools\docx-automation-guide.md、..\codex-knowledge\50-tools\epub-reading-options.md

并入文件：MCP 体系与安装管理规范.md

• 整合方式：保留原文全文与 frontmatter 来源信息，不做信息删减；仅修复已失效的内部文件指向。

title: "MCP 体系与安装管理规范"
tags:
- "类-系统运维"
- "项目-MCP"
- "形态-规范"
project: "MCP"
type: "规范"
aliases:
- "文档治理__MCP 体系与安装管理规范手册__MCP 体系与安装管理规范"

MCP 体系与安装管理规范

1. 文档目的

本文用于说明你当前环境中的 MCP 应该如何安装、如何归档、如何在文档中记录，以及文档类 MCP 应该怎样纳入你现有工程规范。

2. 核心原则

2.1 MCP 本体不放在 Obsidian 文档目录

Obsidian 文档目录只适合放：

• MCP 说明文档
• 架构图
• 使用手册
• 安装记录

不适合放：

• node_modules
• npm 安装依赖
• MCP 服务源码副本
• 临时调试脚本
• 构建中间产物

2.2 MCP 配置与 MCP 文档分离

建议分三层：

1. 运行配置层：Codex / OpenClaw / Atramenti-Console 的实际 MCP 配置
2. 代码实现层：真正的 MCP 服务实现目录
3. 说明文档层：Obsidian 中的手册与记录

2.3 文档类 MCP 也要和普通 MCP 一样管理

不要把“文档写作增强工具”视为一次性脚本。像：

• fetch-mcp
• markitdown-mcp
• plantuml-diagrams
• drawio-diagrams

这类都应该按 MCP 规范管理，而不是散落在文档目录里。

3. 推荐落位

3.1 MCP 代码实现目录

推荐继续以工程目录为准，例如：

• E:\My Project\Atramenti-Console\codex\mcps
• C:\Users\ASUS-KL\.codex\config.toml 中的 MCP 注册项
• 其他专用工作区中的 MCP 项目目录

3.2 MCP 文档目录

推荐在 Obsidian 中统一放到：

• E:\My Project\Atramenti-Console\codex\plugins\obsidian\data\docs\agent
• E:\My Project\Atramenti-Console\codex\plugins\obsidian\data\docs

这里只记录：

• MCP 列表
• 用途说明
• 输入输出能力
• 安装位置
• 配置方式
• 故障处理
• 是否已注册生效

4. 你当前环境中的 MCP 分类建议

4.1 内部工程型 MCP

这类 MCP 已经纳入你的工程体系，应该优先按项目管理：

• cloud-repo-mcp
• context-store
• context-store-reranker
• database-ops-mcp
• dev-quality-mcp
• experience-mcp
• github-workflow-mcp
• log-diagnose
• orchestration-pipeline
• output-guard
• playwright-browser
• prompt-compressor
• repo-inspector
• ripgrep-search
• standards-guard

4.2 外部能力但已工程收编的 MCP

这类原本来自 npm、远程服务或外部仓库，但现在已经纳入本地工程规范：

• chrome-devtools-mcp-wrapper
• drawio-diagrams
• plantuml-diagrams
• fetch-mcp
• markitdown-mcp

4.3 远程 SaaS 型 MCP

• notion

这类 MCP 的代码本体不在本地，但配置、使用说明、风险说明仍应进入文档体系。

5. 安装规范建议

5.1 优先级顺序

推荐安装优先级：

1. 优先复用现有工程目录中的 MCP
2. 其次使用官方源或官方仓库中的 MCP
3. 再考虑稳定的 npm 包或远程 MCP
4. 最后才临时接第三方、无稳定维护的包装器

5.2 安装后必须记录的字段

每新增一个 MCP，都建议在文档里记录：

• MCP 名称
• 作用
• 来源
• 安装方式
• 实际配置位置
• 实际代码目录
• 是否属于本地工程
• 是否含外部依赖
• 是否已验证可用
• 当前是否已注册生效

5.3 文档类 MCP 的额外建议

对文档类 MCP，最好额外记录：

• 支持的输入类型
• 是否需要额外依赖（例如 ffmpeg）
• 是否需要代理
• 是否有本地包装脚本
• 是否附带使用模板

6. 稳定注册规范

6.1 不要只手改 config.toml

如果某个 MCP 只是手动写进 C:\Users\ASUS-KL\.codex\config.toml，而没有进入统一托管流程，后续在受管路径重写或环境刷新时就可能出现“注册漂移”。

6.2 以受管路径重写脚本为准

当前应以这个脚本作为 Codex MCP 配置的托管入口：

• E:\My Project\Atramenti-Console\codex\scripts\register-codex-paths.ps1

它当前不是“扫描整个 MCP 根目录自动发现”，而是按脚本里显式受管的 MCP 条目重写 config.toml 的 managed block，并把这些条目统一指向 repo-managed launcher 路径。

当前这类受管条目包括：

• cloud-repo-mcp
• dev-quality-mcp
• ripgrep-search
• workspace-toolkit-mcp
• agent-runtime-mcp
• github-workflow-mcp
• fetch-mcp
• markitdown-mcp
• ffmpeg-mcp
• yt-dlp-mcp
• video-audio-mcp
• pencil

6.3 文档类 MCP 的推荐做法

对于需要长期稳定保留的文档类 MCP，推荐目录内至少具备：

• README.md
• server.json
• start.cmd
• server.mjs

其中：

• start.cmd 负责本地启动细节与环境变量封装
• server.mjs 负责作为稳定 launcher 入口；是否进入 live 注册仍以 register-codex-paths.ps1 中的受管条目为准

7. 文档建议结构

建议为 MCP 单独维护以下文档：

• MCP 清单总表.md：当前 canonical 文档，已吸收总规范、总表与安装记录
• C:\Users\ASUS-KL\.codex\AGENTS.md：文档类任务的默认操作规范；如果要继续改这份总表的结构、合并方式或 companion 层，先按它执行
• MCP 安装记录（YYYY-MM-DD）：若后续再有新变更，可继续作为并入本文的单次记录标题规范

8. 本次整理结论

本次已经明确：

• 文档目录中继续只保留说明文档与展示资源
• 文档类 MCP 应放在 E:\My Project\Atramenti-Console\codex\mcps
• fetch-mcp 已完成本地包装，并补了使用模板
• markitdown-mcp 已完成基于官方仓库固定 commit 的稳定包装
• 两者已经通过 server.mjs + register-codex-paths.ps1 纳入受管配置链路，并稳定注册进 Codex 配置
• 后续再遇到类似 MCP，应优先修复托管链路，而不是只改 config.toml

9. 后续建议

1. 以后新增文档类 MCP，都优先放进 E:\My Project\Atramenti-Console\codex\mcps
2. MCP 总表里始终区分“当前已注册生效”“已收编但未托管”“仅文档记录”
3. 如后面继续扩展文档 / 媒体链，按同一受管方式补新的音视频 / OCR / 转写类 MCP
4. 每次新增或修复 MCP，都补一份 MCP 安装记录（YYYY-MM-DD）.md

并入文件：MCP 安装记录（2026-04-17）.md

• 整合方式：保留原文全文与 frontmatter 来源信息，不做信息删减。

title: "MCP 安装记录（2026-04-17）"
tags:
- "类-系统运维"
- "项目-MCP"
- "形态-记录"
project: "MCP"
type: "记录"
topics:
- "MCP 管理"
aliases:
- "服务器体系__MCP 管理__MCP 安装记录（2026-04-17）"

MCP 安装记录（2026-04-17）

1. 本次变更目标

本次新增并稳定化两项文档类 MCP：

• fetch-mcp
• markitdown-mcp

目标有两层：

1. 提升网页资料抓取与多格式文档转 Markdown 的能力
2. 解决这两个 MCP 在 Codex 中“注册漂移”的问题，让它们能稳定出现在配置里

2. 新增原因

2.1 fetch-mcp

新增 fetch-mcp 的原因：

• 文档写作经常需要先抓网页正文
• 需要把在线资料变成可整理、可归档的 Markdown 输入材料
• 后续写方案、写操作说明、写调研稿时更方便做多源整合

2.2 markitdown-mcp

新增 markitdown-mcp 的原因：

• 需要把 PDF、Word、PPT、网页、本地文件统一转成 Markdown
• 便于把外部资料纳入 Obsidian 与现有文档生产链路
• 便于在转换后继续做章节重组、手册化重写和知识卡片化整理

3. 安装位置

3.1 MCP 工程目录

• E:\My Project\Atramenti-Console\codex\mcps\fetch-mcp
• E:\My Project\Atramenti-Console\codex\mcps\markitdown-mcp

3.2 Codex 实际配置位置

• C:\Users\ASUS-KL\.codex\config.toml

3.3 Codex 配置托管脚本

• E:\My Project\Atramenti-Console\codex\scripts\register-codex-paths.ps1

4. 本次落地的封装文件

4.1 fetch-mcp

已落地文件：

• E:\My Project\Atramenti-Console\codex\mcps\fetch-mcp\README.md
• E:\My Project\Atramenti-Console\codex\mcps\fetch-mcp\server.json
• E:\My Project\Atramenti-Console\codex\mcps\fetch-mcp\start.cmd
• E:\My Project\Atramenti-Console\codex\mcps\fetch-mcp\server.mjs
• E:\My Project\Atramenti-Console\codex\mcps\fetch-mcp\USAGE-TEMPLATE.md

封装要点：

• 增加固定默认 User-Agent
• 预留代理环境变量 FETCH_MCP_PROXY_URL
• 预留自定义 User-Agent 环境变量 FETCH_MCP_USER_AGENT
• 附带使用说明模板，便于沉淀网页抓取工作流

4.2 markitdown-mcp

已落地文件：

• E:\My Project\Atramenti-Console\codex\mcps\markitdown-mcp\README.md
• E:\My Project\Atramenti-Console\codex\mcps\markitdown-mcp\server.json
• E:\My Project\Atramenti-Console\codex\mcps\markitdown-mcp\start.cmd
• E:\My Project\Atramenti-Console\codex\mcps\markitdown-mcp\server.mjs

封装要点：

• 来源为 microsoft/markitdown 官方仓库中的 packages/markitdown-mcp
• 固定 commit：604bba13da2f43b756b49122cb65bdedb85b1dff
• 采用本地封装方式，避免依赖不稳定的第三方包装层

5. 注册漂移问题与根因

5.1 现象

最初这两个 MCP 虽然已经封装好，但它们没有稳定留在 Codex 配置里；手动改完 config.toml 后，后续受管路径重写或环境刷新时仍可能消失。

5.2 根因

根因不是 MCP 本身无法启动，而是 C:\Users\ASUS-KL\.codex\config.toml 并不是唯一事实来源。

当前已经确认的托管入口是：

• E:\My Project\Atramenti-Console\codex\scripts\register-codex-paths.ps1

该脚本会按显式受管条目重写 Codex 配置托管区块，并把当前 live MCP 指向 E:\My Project\Atramenti-Console\codex\mcps 下的 launcher 路径。

如果一个 MCP 没有被纳入这个脚本的受管条目，即使手动写进 config.toml，后续也会发生“注册漂移”。

6. 解决办法

本次采用的稳定化做法是：

1. 保留每个 MCP 自己的 start.cmd，承接本地启动逻辑
2. 新增 server.mjs 作为稳定 launcher 入口
3. 让 register-codex-paths.ps1 把这两个 MCP 的 canonical 路径写进 managed block
4. 通过该脚本回写 C:\Users\ASUS-KL\.codex\config.toml

本次新增的托管入口为：

• E:\My Project\Atramenti-Console\codex\mcps\fetch-mcp\server.mjs
• E:\My Project\Atramenti-Console\codex\mcps\markitdown-mcp\server.mjs

7. 验证结果

7.1 配置托管结果

执行路径重写脚本之后，C:\Users\ASUS-KL\.codex\config.toml 中已出现：

• fetch-mcp
• markitdown-mcp

对应入口为：

• fetch-mcp -> node E:\My Project\Atramenti-Console\codex\mcps\fetch-mcp\server.mjs
• markitdown-mcp -> node E:\My Project\Atramenti-Console\codex\mcps\markitdown-mcp\server.mjs

7.2 当前结论

当前可以认为：

• 两个 MCP 已完成本地封装
• 两个 MCP 已纳入 Codex 托管配置链路
• 两个 MCP 已注册并生效
• 后续如再次执行 register-codex-paths.ps1，理论上仍会保留，而不是被回写掉

8. 当前能力收益

本次补齐后，文档生产链路新增了两段稳定输入能力：

• fetch-mcp：网页正文抓取
• markitdown-mcp：多格式资料转 Markdown

这使得“网页 / PDF / Word / PPT / 本地文件 -> Markdown -> 结构化文档 / 知识库条目”的流程更顺。

9. 暂缓项

本次没有默认预装 ffmpeg。

原因：

• 当前重点是文档资料、网页资料、PDF / Office 资料的稳定摄入
• 音频、视频、语音稿转 Markdown 暂未成为当前主链路
• 等后续确实要做音频 / 视频 / 语音稿处理时，再补 ffmpeg 更合适

10. 后续维护建议

1. 以后新增 MCP，优先先看它是否能被 provision 脚本自动发现
2. 若要长期稳定注册，优先补 server.mjs，不要只手改 config.toml
3. 文档类 MCP 每次新增或修复后，都同步更新 MCP 清单总表.md
4. 重要变更单独补一份 MCP 安装记录（YYYY-MM-DD）.md