cogmemory-mcp

CogMemory MCP 服务

一个统一的 Model Context Protocol 服务，为 AI 编码 Agent 提供四个上下文子系统：

1. Memory — 决策、约定、错误、活跃上下文、变更日志、计划、任务、会话
2. Knowledge Graph — 实体、关系、观察结果
3. Specs — 长篇文档（PRD/SRS），可选择关联到知识图谱实体
4. Code Graph — 静态结构图（符号/边）+ 命名执行跟踪 + AI 生成的注释

存储：通过 better-sqlite3 使用 SQLite。默认情况下，每个克隆版本都会在 ~/.cogmemory/projects/ 下拥有自己的数据库。

---

快速开始

安装

选项 A — npx（推荐，始终使用最新版本）：

npx -y cogmemory-mcp@latest

选项 B — 全局安装：

npm install -g cogmemory-mcp
cogmemory-mcp

选项 C — pnpm dlx：

pnpm dlx cogmemory-mcp@latest

选项 D — 从源代码安装（开发者）：

git clone https://github.com/skylarng89/cogmemory-mcp.git
cd cogmemory-mcp
pnpm install
pnpm run build

原生模块要求

CogMemory 依赖 better-sqlite3 和 tree-sitter，安装时会编译原生模块。你需要：

• Python 3（用于 node-gyp）
• C/C++ 编译器（Linux 上的 gcc/g++、macOS 上的 Xcode Command Line Tools、Windows 上的 Visual Studio Build Tools）
• make（Linux/macOS，默认已安装）

大多数平台都有预构建二进制文件，因此通常无需在以下平台上进行编译：

• Linux x64 / arm64
• macOS x64 / arm64
• Windows x64

如果安装失败，请参阅下文的故障排除。

---

IDE / 客户端配置

VS Code

添加到 .vscode/mcp.json（工作区范围）：

{
  "servers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

或者使用 --workspace 支持多根工作区（通常无需使用 — 请参阅工作区解析 — 多根支持）：

{
  "servers": {
    "cogmemory-frontend": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest", "--workspace", "/path/to/frontend"]
    },
    "cogmemory-backend": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest", "--workspace", "/path/to/backend"]
    }
  }
}

**默认零配置：**如果省略 --workspace，CogMemory 会根据工作目录自动发现 项目（优先使用 git 根目录，然后使用最近的 .cogmemory/ 父目录）。所有项目只需一个服务条目 — 每个仓库都会获得自己的记忆区。仅在需要指定 monorepo 子根目录时才固定设置 --workspace。

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Claude Desktop

添加到 ~/.config/claude/claude_desktop_config.json（Linux/macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Claude Code

添加到 ~/.claude/mcp.json（用户级）或 .claude/mcp.json（项目级）：

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Cline

在 Cline 扩展设置中添加 MCP 服务：

• 名称： cogmemory
• 命令： npx -y cogmemory-mcp@latest

或者添加到 cline_mcp_settings.json：

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Windsurf

MCP 设置 → 添加服务：

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

OpenCode

添加到 opencode.json：

{
  "mcp": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Zed

添加到 Zed 设置（settings.json）：

{
  "context_servers": {
    "cogmemory": {
      "binary": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

MCP Registry

CogMemory 已发布到 MCP Registry。支持 Registry 的客户端可以自动发现并安装它。

---

范围配置

CogMemory 按以下优先级解析范围：

1. 工作区根目录中的 .cogmemory/config.json（项目级覆盖）：

   { "scope": "project" }
   

2. 环境变量：COGMEMORY_SCOPE=project、global 或 workspace

3. 用户级回退设置：~/.cogmemory/config.json（仅范围设置）

4. 默认值：project — 每个克隆版本在 ~/.cogmemory/projects/ 下拥有一个数据库

**默认情况下，每个克隆版本各自独立。**每个克隆版本都会在 .cogmemory/config.json 中获得一个 UUID，并将数据库存储在 ~/.cogmemory/projects/memory-<project-id>.db。用于标识克隆版本的是 UUID，而不是文件夹名称或仓库来源。使用 { "scope": "global" } 或 COGMEMORY_SCOPE=global 可保留旧版共享数据库；使用 { "scope": "workspace" } 则可将数据库存储在仓库内。

路径

范围	数据库路径
项目	~/.cogmemory/projects/memory-<project-id>.db
工作区	<workspace_root>/.cogmemory/memory.db
全局	~/.cogmemory/global.db

正在升级？ 如果工作区已有 memory.db，但没有配置文件，那么当项目默认设置绕过该数据库时，CogMemory 会向 stderr 输出提示；若要继续使用该数据库，请在该项目的 .cogmemory/config.json 中添加 { "scope": "workspace" }。显式选择 COGMEMORY_SCOPE=global 时，global.db 中的现有数据仍可使用；系统不会在不通知的情况下重新分区。

---

项目身份

每个项目都会获得一个稳定且不透明的 slug（UUID），存储在 .cogmemory/config.json 的 project_id 字段下。这个 slug 才是项目的身份，而非文件夹路径或名称。所有记忆（决策、约定、错误、会话、代码图等）都会带有 project_id 外键，因此：

• 重命名和移动都是安全的。 移动项目文件夹不会切断对其记忆的访问权限——slug 会随配置文件一起移动，而路径仅作为元数据。
• 固定路径配置可正常使用。 无法展开 ${workspaceFolder} 的 IDE/客户端可以指向同一个共享数据库路径；每个项目的记忆仍通过 slug 保持隔离。
• 默认采用克隆级项目范围。 每个克隆都会打开独立的数据库，因此并发客户端不会让一个共享进程在无关的项目行之间切换。
• 仍可使用全局范围。 ~/.cogmemory/global.db 可以保存多个项目的数据，每次读取/写入都会隐式限定在当前项目的 slug 范围内。

.cogmemory/config.json 与 Git

请将 .cogmemory/config.json 加入 Git 忽略规则，以便每个克隆在首次运行时获得自己的身份。复制或提交该文件会有意共享其 UUID；启动或分支聊天不会创建新的项目身份。

项目管理工具

工具	用途
list_projects	列出所有项目及其行数、最后访问时间戳和过期标记
rename_project	更改项目的显示名称（slug 不可更改）
prune_projects	永久删除项目及其所有行（需要 confirm）
switch_project	在运行时根据工作区根目录重新解析当前项目

cogmemory_status 会报告 workspace_root、root_path_hint、resolution_source（override | git-root | dotcogmemory | cwd-fallback | runtime-switch）以及 active_project: { id, slug, label }，并在详细模式下提供各表的行数。

运行时切换项目

如果客户端固定使用的 --workspace/cwd 与你实际工作的仓库不匹配（例如，Agent 在会话中途打开了另一个仓库），请使用目标仓库的绝对根路径调用 switch_project：

{ "root_dir": "/mnt/repos/my-project" }

初始化成功后，目标工作区的配置范围、数据库、UUID、数字项目 ID 和根路径会一并切换。状态信息、索引和源代码片段都会使用新的根路径。已在进行中的异步调用会在原上下文中完成。路径无效、配置损坏或数据库初始化失败时，之前的上下文仍可使用。

分支聊天与过期 ID

开始新的聊天或分支聊天时：

1. 调用 cogmemory_status，并将 workspace_root 与实际工作区进行比较。聊天历史和缓存的数字 ID 不具权威性。
2. 如果根目录不同，使用预期的绝对根目录调用 switch_project，然后重新获取记忆。不要通过清除身份文件来解决客户端工作区不匹配问题。
3. 重用工作区 UUID。如有需要，使用 start_session 开启新的记忆会话；聊天分支并不代表新项目。

工具 JSON 响应包含 project_identity: { id, slug, workspace_root }。工具接受可选参数 expected_project_id，其值为 UUID slug，可在读取或写入前拒绝过期上下文。这一点尤其有用，因为不同数据库中的数字 ID 可能相同。遇到 PROJECT_MISMATCH 时，请检查状态并切换到预期根目录，然后重试。不带可选防护参数的现有调用仍然兼容。如果客户端既未提供正确的启动根目录，也未请求切换，CogMemory 就无法推断聊天预期使用的工作区。

记忆写入时遇到可选的过期会话或计划关联，会忽略这些关联并返回警告；记忆仍会保存到当前项目下。显式读取和更新会话时会限定项目范围；如果会话 ID 已过期，则会返回未找到响应并附上恢复说明。

恢复早期的身份漂移

早期的项目范围初始化可能会选择 memory-A.db，随后却在该数据库和工作区配置中持久化 UUID B。现在，初始化期间会始终使用同一个 UUID、串行处理并发初始化，并以原子方式发布配置更改。

对于现有受影响的存储，启动时会以只读方式检查项目数据库。如果恰好有一个已存储身份与 UUID 或精确工作区根目录匹配，则会在原处重用该数据库，保留其行 ID 和记忆。配置会将 project_database_id 记录为现有数据库文件名中的 UUID；它可以与 project_id 不同。这一过程不会重命名、合并或删除任何数据库。

如果有多个候选项匹配，PROJECT_IDENTITY_AMBIGUOUS 会列出 { databaseId, slug } 对，并保持配置不变。在 .cogmemory/config.json 中选择预期的一对，同时保留其他设置：

{
  "scope": "project",
  "project_id": "<slug from the selected candidate>",
  "project_database_id": "<databaseId from the same candidate>"
}

然后重启 MCP 服务；如果它已在运行，也可以重试 switch_project。所选数据库必须包含该 UUID。其他候选数据库仍可使用；合并分散的历史记录是另一项独立且需明确执行的操作。

格式错误的 JSON、无效 UUID 和无效本地范围会产生 PROJECT_CONFIG_INVALID，而不是静默替换身份。请从备份中恢复有效配置。初始化锁具有有限等待时间，并会报告 PROJECT_BUSY；如果进程持锁崩溃，请检查所报告目录中的 owner.json，确认对应进程已退出后，仅删除该已遗弃的锁目录，然后重试。切勿删除仍由活动进程持有的锁。

运行 pnpm test:identity，可对重启/分支连续性、并发进程、恢复、切换、过期 ID、UUID 防护和进行中的调用执行隔离回归测试。

多根目录 / 单体仓库

从 CWD 向上查找时，Git 根目录发现优先于祖先 .cogmemory/ 目录发现。在单体仓库中，请使用 --workspace <path> 或 COGMEMORY_WORKSPACE 明确指定预期根目录，以避免静默关联到错误的项目。

---

工作区解析与多根目录支持

CogMemory 按以下优先级解析工作区根目录（也就是项目身份锚点）：

1. --workspace <path> CLI 参数（显式覆盖，优先级最高）
2. COGMEMORY_WORKSPACE 环境变量（显式覆盖）
3. Git 根目录 — 从 CWD 向上遍历，查找最近的 .git/ 条目（Git 仓库的默认判定信号）
4. 从 CWD 向上遍历，查找最近一个包含 .cogmemory/ 目录的父目录
5. 回退到 CWD

对于大多数客户端，无需任何配置：启动 CogMemory 时不指定 --workspace，它就会连接到包含客户端工作目录的 Git 仓库。因此，每个仓库都会自动获得独立的项目身份。

CogMemory 拒绝从用户的主目录或文件系统根目录引导项目。这样可以避免从通用进程目录启动 MCP 服务的客户端将记忆错误地存储在错误的项目下。如果客户端无法提供正确的工作目录，请配置工作区范围的条目，或将 COGMEMORY_WORKSPACE 设为项目根目录的字面路径。

仅当身份锚点必须与 Git 根目录不同时，才固定设置 --workspace/COGMEMORY_WORKSPACE — 例如，将单体仓库中的某个子目录作为独立项目。

cogmemory_status 会报告当前的 workspace_root、root_path_hint、数据库路径和 UUID。无效的显式工作区覆盖会直接报错，而不会回退到无关目录。

---

升级与迁移

CogMemory 使用带版本的迁移系统。新版本添加列或表时，迁移会在下次启动服务时自动运行 — 无需手动操作。

首次迁移（v1.1.0 之前的数据库）

如果你要从使用旧架构的 v1.1.0 之前版本升级：

1. 系统会自动创建一个备份文件：<db_path>.backup-pre-migrate-<timestamp>
2. 迁移会在事务中执行 — 如果任何步骤失败，数据库将回滚
3. 如果出现问题，可以从备份恢复：cp memory.db.backup-* memory.db
4. 设置 COGMEMORY_SKIP_BACKUP=1 可跳过备份（例如，在 CI 或磁盘空间受限的环境中）

选择退出：更新检查遥测

默认情况下，CogMemory 每 24 小时检查一次 npm 注册表，查看是否有更新版本可用（通过 check_for_updates 工具）。此操作会向 registry.npmjs.org 发起一次只读 HTTPS GET 请求 — 与包管理器发出的请求相同。

如需禁用此检查：

• 环境变量： COGMEMORY_DISABLE_UPDATE_CHECK=1
• 配置文件： 在 .cogmemory/config.json 中添加 { "disable_update_check": true }

---

工具参考（41 个工具）

记忆工具（14）

工具	描述
start_session	开始工作会话（返回会话 ID）
end_session	结束会话并存储摘要
get_session_summary	回顾会话详情，包括决策、错误和变更日志
remember_decision	记录决策及其理由和标签
remember_convention	记录或更新约定（设计令牌、模式、风格、命名）
log_error	记录错误及其特征和解决方案
set_active_context	按键新增或更新当前焦点/任务
get_active_context	按键读取当前焦点
log_change	追加变更日志条目
add_plan_item	添加路线图条目
update_plan_status	更改计划条目状态
create_task	创建任务，可选择关联计划
update_task_status	更改任务状态
recall	跨决策/约定/错误/变更日志进行统一搜索

知识图谱工具（4）

工具	描述
create_entity	添加实体（按名称和类型去重）
create_relation	使用指定类型的关系连接两个实体
add_observation	为实体附加事实
search_knowledge	查询实体、关系和观察项

规格说明工具（3）

工具	描述
create_spec	存储长篇文档
get_spec	按 ID 或准确标题检索
update_spec	更新内容/标题，并自动递增版本

代码图谱工具（4）

工具	描述
index_codebase	遍历工作区，提取符号和边（JS/TS 使用 ts-morph，Python 使用 tree-sitter）
query_code_graph	查找符号的调用方/被调用方/导入项（1 跳）
generate_codemap	从入口符号开始广度优先搜索，生成有界子图，可选包含跟踪信息和注释
annotate_symbol	为符号或跟踪信息附加叙述性文本

自省工具（2）

工具	描述
cogmemory_status	显示运行时配置：软件包版本、架构版本、数据库路径、工作区根目录、作用域、索引覆盖率和子系统计数
check_for_updates	检查 npm 上是否有更新版本（向注册表发送 HTTPS GET 请求，缓存 24 小时）

代码分析工具（8 个）

工具	描述
semantic_code_search	基于 TF-IDF 的语义代码搜索——输入自然语言查询，按相关性返回排序后的符号
find_dead_code	查找没有任何调用方的符号，但不包括导出符号和可配置的入口点
find_duplicates	通过精确哈希和 MinHash 相似度检测重复/克隆符号对，并插入 SIMILAR_TO 边
find_related	通过共享调用方、导入项和同文件启发式规则发现语义相关的符号，并插入 SEMANTICALLY_RELATED 边
query_graph	使用递归 CTE 进行多跳结构化图查询——支持任意深度、边类型筛选和方向
analyze_impact	分析未提交更改（git diff）的影响——将更改的文件映射到符号，并计算反向传递调用闭包
get_code_snippet	根据 ID 或名称获取符号的源代码行，可选填充上下文行
check_index_coverage	按语言统计已索引、未索引和过时的文件

列出和删除工具（5 个）

工具	描述
list_items	浏览任意子系统中存储的条目，可选使用筛选条件
delete_item	按 ID 从任意子系统中删除单行
delete_by_key	按字符串键删除上下文条目
delete_by_path	从代码图的 file_index 中移除文件
purge_subsystem	删除子系统中的所有行（需要 confirm=true）

项目工具（4 个）

工具	描述
list_projects	列出所有项目及其行数和过时标记；当前活动项目会特别标出
rename_project	重命名项目的显示标签（slug 不可更改）
prune_projects	永久删除项目及其所有行（需要 confirm=true）
switch_project	运行时从工作区根目录重新解析活动项目（失败时关闭）

---

架构

cogmemory-mcp/
├── src/
│   ├── index.ts                 # entry point, server bootstrap
│   ├── version.ts               # auto-generated version constant
│   ├── config.ts                # scope resolution, path resolution
│   ├── update-check.ts          # fail-safe startup update notifier (update-notifier)
│   ├── types.ts                 # shared TS types mirroring schema
│   ├── db/
│   │   ├── connection.ts        # DB open/close, pragma setup
│   │   ├── migration-runner.ts  # versioned migration engine (PRAGMA user_version)
│   │   ├── migrate.ts           # legacy idempotent migration (deprecated)
│   │   └── migrations/
│   │       ├── 001_baseline.sql         # full v1 schema
│   │       ├── 002_symbol_export_hash.sql
│   │       ├── 003_index_errors.sql
│   │       ├── 004_symbol_embeddings.sql
│   │       ├── 005_edge_metadata.sql
│   │       ├── 006_symbol_tokens.sql
│   │       ├── 007_symbol_minhash.sql
│   │       ├── 008_project_scoping.sql
│   │       └── 009_project_scoped_uniques.sql
│   ├── tools/
│   │   ├── memory.ts            # decisions/conventions/errors/context/changelog/recall
│   │   ├── plan-tasks.ts        # plan + tasks tools
│   │   ├── sessions.ts          # start/end session, summary
│   │   ├── knowledge-graph.ts   # entities/relations/observations
│   │   ├── specs.ts             # spec CRUD
│   │   ├── code-graph.ts        # index_codebase, query_code_graph
│   │   ├── codemap.ts           # generate_codemap, annotate_symbol
│   │   ├── code-analysis.ts     # dead code, duplicates, related, graph query, impact, snippet, coverage, search
│   │   ├── introspection.ts     # cogmemory_status, check_for_updates
│   │   ├── list-delete.ts       # list_items, delete_item, purge_subsystem
│   │   └── utils.ts             # wrapHandler, jsonOk, jsonFail, jsonErr
│   └── indexing/
│       ├── ts-analyzer.ts       # ts-morph symbol/edge extraction (JS/TS)
│       ├── py-analyzer.ts       # tree-sitter symbol/edge extraction (Python)
│       ├── edge-types.ts        # edge type constants (calls, imports, extends, implements, similarto, semrelated)
│       └── walker.ts            # file discovery, gitignore respect
├── package.json
├── tsconfig.json
└── README.md

---

架构（25 张表）

基础表（21 张）：

• 记忆（8 张）： sessions、decisions、conventions、errors、context、changelog、plan、tasks
• 知识图谱（3 张）： entities、relations、observations
• 规格（1 张）： specs
• 代码图（5 张）： symbols（含 is_exported、body_hash、token_count 列）、edges（含 metadata JSON 列）、execution_traces、codemap_annotations、file_index
• 代码分析（3 张）： index_errors、symbol_tokens（TF-IDF）、symbol_minhash（MinHash 签名）
• 未来（1 张）： symbol_embeddings（存根——Phase 2 的向量嵌入）

FTS5 表（4 张）：

• Recall FTS： recall_docs（内容表）+ recall_fts（FTS5 虚拟表）——为 recall 提供支持
• 知识图谱 FTS： kg_docs（内容表）+ kg_fts（FTS5 虚拟表）——为 search_knowledge 提供支持

架构迁移通过 PRAGMA user_version 自动完成（当前版本为 9）。

---

支持的语言

代码图谱（index_codebase）使用特定语言的分析器从源文件中提取符号和边：

语言	扩展名	分析器	提取的符号
TypeScript	.ts、.tsx	ts-morph	文件、函数、类、接口、方法、类型别名、枚举、变量（包含 is_exported）
JavaScript	.js、.jsx、.mjs、.cjs	ts-morph	文件、函数、类、方法、变量
Python	.py	tree-sitter	文件、函数、类、方法（通过 __all__／下划线规则设置 is_exported）

结构边： 调用、导入、继承、实现

分析边： similarto（克隆检测）、semrelated（语义关系发现）

---

Pragmas

每次打开连接时设置：

PRAGMA journal_mode = WAL;
PRAGMA foreign_keys = ON;

---

开发

pnpm run dev        # Run with tsx (no build step)
pnpm run build      # Compile TypeScript (regenerates version.ts via prebuild)
pnpm run start      # Run compiled output
pnpm run inspect    # Launch MCP Inspector
pnpm run smoke-test # Run smoke test script (43 checks)

---

故障排除

原生模块构建失败

如果 npm install 或 pnpm install 因 node-gyp 错误而失败：

1. 安装 Python 3： python3 --version — 如果未安装，请使用包管理器安装
2. 安装 C++ 构建工具：
   • macOS： xcode-select --install
   • Ubuntu/Debian： sudo apt-get install build-essential
   • Windows： 安装包含“C++ build tools”工作负载的 Visual Studio Build Tools
3. 重试： npm rebuild better-sqlite3（或 npm rebuild tree-sitter）

迁移失败

如果服务因迁移错误而退出：

1. 检查 stderr 中的错误消息和迁移文件编号
2. 从备份恢复：cp .cogmemory/memory.db.backup-* .cogmemory/memory.db
3. 重试 — 迁移将从当前的 user_version 重新运行

大型工作区的性能

对于包含 50k+ 个文件的工作区：

1. 使用 .gitignore 排除 vendored／生成的代码（CogMemory 会遵循该文件）
2. 遍历器默认会跳过 node_modules、.git、dist、build、.next、.cogmemory、__pycache__、.venv、venv、*.min.js、*.min.css、*.map
3. 索引覆盖率：check_index_coverage 工具会将未索引文件报告分页，每页 1000 条

analyze_impact — git 不可用

如果工作区不是 git 仓库，使用自动检测的 analyze_impact 将会失败。请改为手动传入 changed_files。

---

许可证

MIT

发布工作流和恢复

.github/workflows/publish.yml 会运行四个独立作业：

作业	工作内容	重新运行时的行为
构建和验证 / 准备恢复	根据 package.json 验证标签、同步注册表元数据、构建、运行冒烟测试和身份测试，并仅打包一次	上传本次运行尝试专属的工件
发布 npm	验证工件完整性，然后使用 OIDC/来源证明发布 tarball	仅跳过 npm 元数据和 tarball 完整性均相同的现有发布
发布 MCP Registry	等待指定的 npm 版本公开可用，使用 OIDC 进行身份验证，然后注册该版本	验证匹配的现有注册；重试暂时性发布失败
发布摘要	读取实际作业结果和发布输出	报告失败或跳过的作业，并区分 npm 提交与确认可用

pnpm store 缓存以锁文件为键。各运行器之间不会共享 node_modules；已批准的原生依赖会在构建运行器上构建。经验证的 tarball、同步后的 server.json 和发布清单会作为保留 30 天的工作流工件传递，因此只重新运行 MCP 作业不会重新构建或重新发布 npm。固定版本的 MCP 发布器归档会按版本、操作系统、架构和校验和进行缓存；每次恢复时都会验证校验和。该缓存会在注册前保存，因此注册表故障不会导致缓存被丢弃。

正常发布

1. 提交预期版本，并推送与之匹配的 vX.Y.Z 标签。标签必须与 package.json 一致；工作流会拒绝不匹配的情况。
2. 构建作业会同时运行 smoke-test 和 test:identity，在软件包元数据中记录源提交，并打包经过测试的构建。
3. 发布到 npm 时会提交该 tarball，不会重新运行生命周期构建。提交成功后仍可能处于处理中。
4. MCP 作业每 15 秒检查一次公开的 npm 版本，最长等待 10 分钟。身份验证错误或发布内容不匹配会立即失败。注册表中断和暂时性 MCP 发布错误会在有限次数内重试。

发布权限仅授予 npm 和 MCP 作业。工作流文件名仍为 publish.yml，以保留现有的可信发布方工作流身份。发布仍会串行执行，以避免对 npm 的 latest 标签进行重叠更新。

重新运行失败的阶段

对于使用新工作流的运行，请在 GitHub Actions 中打开该运行，然后选择 Re-run failed jobs，或仅重新运行 Publish MCP Registry 作业。成功的上游作业及其工件会重复使用。如果工件已过期，请改为启动新的手动运行。完整重新运行时会验证现有的 npm 发布，而不会尝试覆盖它；同一版本的内容不同则会安全地失败。

恢复旧版本，包括 v1.15.0

此工作流更改进入默认分支后：

1. 打开 Actions → Publish Package → Run workflow。
2. 为工作流实现选择默认分支。
3. 输入现有发布标签，例如 v1.15.0，然后选择 mcp-only。
4. 运行工作流。它会加载当前的发布辅助程序，根据所选标签检出元数据，并跳过依赖安装、软件包构建和 npm 发布。

仅恢复 MCP 时，会在注册任何内容之前，根据所选标签验证 npm 的软件包名称、版本、MCP 名称、仓库和 gitHead。如果无法验证源提交，则会失败。旧标签中的 server.json 版本会根据该标签的 package.json 进行同步。此操作不会移动标签或更改已发布的软件包。元数据不同或状态为非活动的现有 MCP 版本需要调查，而不能自动替换。

重新运行原先的旧工作流运行仍会使用其原始工作流定义。请使用此手动恢复路径，通过新逻辑恢复旧运行。

本地发布辅助检查

node --test scripts/release.test.mjs

这些测试使用临时制品和模拟的注册表/命令；绝不会发布。测试涵盖可见性延迟、请求失败、已存在的版本、完整性不匹配、源提交验证、重试次数上限和摘要准确性。托管式 OIDC 和发布仍需通过真实的 GitHub Actions 运行。