cuemap-mcp

CueMap MCP 服务 v0.7.5

一款优质的 MCP 桥接工具，提供可解释、了解代码库的 Agent 记忆功能。

CueMap 的 模型上下文协议（MCP） 服务，可让 AI 编码助手（如 Claude Desktop、Cursor、Windsurf 和 Antigravity）使用 CueMap 引擎即时回忆代码库上下文。

有关面向 Agent 的操作指南，包括代码库授权、支持的内容类型、回忆模式、以准确性为导向的参数选择以及故障排除，请参阅 SKILL.md。

零配置部署

CueMap MCP 服务旨在开箱即用。启动后，它会在后台自动管理高性能的 Rust 版 CueMap 服务实例。v0.7.3 引擎默认捆绑 qint8 MiniLM-L3，边缘配置则使用 q4 MiniLM-L3；运行时不会下载模型。

你无需手动安装或运行 CueMap CLI。系统会通过可选 NPM 依赖自动下载适用于你操作系统的预编译二进制文件。嵌入式启动支持 Linux x64/ARM64、macOS x64/ARM64 和 Windows x64。

安装

# Global installation makes the `cuemap-mcp` command available
npm install -g cuemap-mcp

（注意：请确保包管理器已配置为下载 optionalDependencies，以便包含本地 Rust 二进制文件。）

Agent 插件

CueMap 还提供独立的 cuemap-agent-plugin 包，适用于兼容 Agent Plugins 的客户端。该包捆绑了便携式 plugin.json 清单、stdio mcp.json 配置以及代码库记忆技能。此插件会以匹配的发行版本启动此 MCP 服务，且必须与 cuemap-mcp 分开安装或下载。

配置（环境变量）

默认情况下，嵌入式引擎运行在端口 8735。你可以在 MCP 配置中传递以下环境变量，自定义服务行为：

• CUEMAP_PORT：覆盖嵌入式引擎绑定的端口（默认值：8735）。
• CUEMAP_CONFIG_PATH：自定义 server_config.toml 的绝对路径，用于配置高级引擎调优、后台任务和 RAG 搜索参数。
• CUEMAP_URL：如果你想绕过嵌入式引擎，连接远程托管或单独运行的 CueMap 服务，请在此指定其 URL（例如 http://localhost:8735）。
• CUEMAP_PROJECT：覆盖默认项目。若未设置此项，CueMap 会根据当前 Git 远程地址或工作目录，推导出稳定且限定于代码库的项目标识。
• CUEMAP_LOG_PATH：覆盖嵌入式引擎的日志路径。默认值为 ~/.cuemap/server.log，cuemap logs 会读取此文件。

服务生命周期

Codex 启动插件进程后，MCP 服务会立即调用 EmbeddedCueMap.start()，此时尚未调用任何 CueMap 工具。它会连接到已在 CUEMAP_URL 或所配置端口监听的兼容引擎；否则会自动启动并管理本地引擎。cuemap_init 不会启动服务——引擎就绪后，它会预览或应用已确认的代码库范围。由 MCP 进程管理的引擎会在该进程退出时优雅停止。

与 AI Agent 搭配使用

若要将此 MCP 服务与 AI 助手搭配使用，请将其添加到助手的 MCP 配置文件中。

配置示例（Claude Desktop）

{
  "mcpServers": {
    "cuemap": {
      "command": "npx",
      "args": [
        "-y",
        "cuemap-mcp"
      ],
      "env": {
        "CUEMAP_PORT": "8735"
      }
    }
  }
}

可用工具

• cuemap_init_preview：执行只读的仓库元数据扫描，并返回受支持的顶层文件夹／根目录文件、数量、稳定的仓库项目 ID，以及任何现有的已保存范围。开始摄取前，先向用户展示此预览。

  • path（字符串）：仓库根目录的绝对路径。
  • projectName（字符串，可选）：项目 ID 覆盖值。默认使用稳定的仓库范围 ID。
  • includedPaths（字符串数组，可选）：要预览的仓库相对文件或文件夹。留空表示包含所有符合忽略规则的受支持文件。
  • ignoredPatterns（字符串数组，可选）：其他 gitignore 风格的排除规则。
  • ignoredExtensions（字符串数组，可选）：其他要排除的扩展名。

• cuemap_init：应用用户确认的仓库摄取范围，启动初始扫描，并持续监视该范围内新增、已更改、已删除、新近忽略或取消忽略的受支持文件。只有在观察到摄取活动、任务进入终止阶段并完成意图标注后，才会报告已验证完成；初始状态为 idle 且写入数为 0/0 不视为完成。

  • path（字符串）：仓库根目录的绝对路径。
  • projectName（字符串，可选）：项目 ID 覆盖值。默认使用稳定的仓库范围 ID。
  • includedPaths（字符串数组，可选）：用户批准的仓库相对文件或文件夹。留空表示包含所有符合忽略规则的受支持文件。
  • ignoredPatterns（字符串数组，可选）：其他 gitignore 风格的排除规则。
  • ignoredExtensions（字符串数组，可选）：其他要排除的扩展名。
  • confirmed（布尔值）：仅在用户明确确认预览的范围后才能设为 true。

• cuemap_status：返回项目范围内的后台摄取进度，以及派生的监控字段。在调用 cuemap_init 后轮询此工具，直到 verified_complete 为 true。

  • project（字符串，可选）：项目 ID 覆盖值。默认使用稳定的仓库范围 ID。
  • active：当前阶段是否尚未终止，或是否仍有待处理的写入／意图标注。
  • observed_activity：此 MCP 进程是否已观察到该项目处于活动阶段，或存在正数的写入／意图标注计数。
  • pending_writes：根据最新总数计算的剩余写入数。
  • pending_intents：剩余的记忆意图标注数。
  • verified_complete：仅当已观察到活动、项目进入 done 或 idle、没有工作失败或仍待处理，且 intent_ready 不为 false 时，值才为 true。

项目检查与内存生命周期

• cuemap_projects：列出项目及其摘要元数据，包括每个项目当前是否已加载到 RAM 中。
• cuemap_project_load：在对延迟敏感的操作前，显式预热已持久化的项目。普通项目请求会在需要时按需加载。
• cuemap_project_save：持久化当前快照，但不卸载项目。
• cuemap_project_unload：持久化并卸载项目，以减少内存用量。正在进行的工作可能会导致可重试的繁忙响应。
• cuemap_project_pack / cuemap_project_package_load：写入或加载可供查询的本地 .cuemap 包。
• cuemap_project_push / cuemap_project_pull：通过 S3 传输包，使用引擎主机上配置的 AWS CLI。
• cuemap_project_sync：快进不可变的 S3 历史记录，并拒绝分歧。
• cuemap_stats：读取仓库项目统计信息；或使用 global: true 读取引擎全局统计信息。
• cuemap_memory_get：通过数字 memory_id 和所属 project，以解码文本和来源信息的形式读取一条记忆。需要支持 GET /memories/:id?decoded=true 的引擎；较旧的引擎会通过此工具返回升级错误。
• cuemap_memory_reinforce：强化一条记忆，可选择指定 cues。
• cuemap_memory_delete：永久删除一条记忆。需在用户明确确认后设置 confirmed: true。
• cuemap_project_export：导出项目中通过游标分页的页面，并可配置是否包含内容、线索和元数据。
• cuemap_project_artifacts：检查 CueBridge 工件元数据，无需重新加载。

显式摄取

• cuemap_ingest_url：摄取一个 URL，或使用 depth 和 same_domain_only 控制递归抓取。
• cuemap_ingest_content：摄取提供的文本，并支持指定文件名、来源键、元数据、结构线索、分段方式，以及为每个生成的分块提供一个可选的 embeddings 向量。
• cuemap_ingest_file：摄取一个经用户批准的本地文件路径。

这些工具用于显式摄取请求。仓库初始化仍使用上述预览、确认和监视器工作流。

别名和词库管理

• cuemap_alias_list、cuemap_alias_add、cuemap_alias_merge：检查和管理手动线索别名。合并需要设置 confirmed: true。

• cuemap_lexicon_inspect、cuemap_lexicon_graph、cuemap_lexicon_wire、cuemap_lexicon_delete：检查和管理词库关系。删除需要设置 confirmed: true。

• cuemap_add：存储一条自然语言记忆。如果项目不存在，则会自动创建。

  • content（string）：要存储的记忆内容。
  • project（string，可选）：拥有该记忆的项目 ID。默认为当前仓库范围内的项目。
  • cues（string[]，可选）：要与记忆关联的显式线索／标签。
  • metadata（object，可选）：与记忆一同存储的 JSON 元数据。
  • source_key（string，可选）：用于确定性更新／去重的稳定来源键。
  • event_time（number，可选）：原始事件时间戳，以 Unix 秒为单位。默认为摄取时间。
  • embedding（number[]，可选）：预计算的记忆嵌入向量。
  • disable_temporal_chunking（boolean，可选）：对此记忆禁用时间分块。
  • async_ingest（boolean，可选）：在后台处理摄取并立即返回。

• cuemap_intent_classify：使用引擎的本地意图模型对文本进行分类。接受 target: "query" 或 "memory"，并返回相对意图分数、是否符合召回／记忆条件、置信度权重，以及模型／分类体系版本。分数用于排序，并非经过校准的概率。

• cuemap_recall：从 CueMap 集成大脑中召回代码库相关上下文。使用自然语言和语义搜索查找相关信息。

  • query（字符串）：用于搜索的自然语言查询。
  • limit（数字，可选）：返回结果的最大数量（默认值：10）。
  • response_mode（full | preview，可选）：默认值为 full。广泛探索时使用 preview；每条命中会返回开头的摘录，而非完整内容，并保留 ID 和元数据。
  • preview_chars（整数，可选）：预览长度上限，范围为 100–2000 个 UTF-16 代码单元（默认值：200）。在完整模式下忽略。元数据和诊断信息不受此上限限制。
  • projects（字符串数组，可选）：用于限定搜索范围的项目 ID 列表。指定多个项目可进行跨项目查询。
  • cues（字符串数组，可选）：用于筛选搜索结果的特定 cue 标签。
  • query_time（字符串，可选）：v0.7 时间查询意图的时间戳或自然语言时间锚点。
  • depth（数字，可选）：多跳召回扩展器的深度（默认值：1）。
  • expansion_depth（数字或 "conversation_round"，可选）：邻近上下文扩展（默认值："conversation_round"）。值大于 1 时，如果存在关联关系，则会纳入相邻的父级分块或按来源顺序排列的上下文，半径为 expansion_depth - 1。当记忆包含会话、轮次和角色元数据时，"conversation_round" 会在每条结果前添加对其作出回复的消息（对于助手回复，即提示该回复的用户消息），例如使用 segmenter: "conversation" 导入后。排名最高的结果也会附带对其作出回复的消息（对于用户消息，即助手的回答）。没有会话元数据的记忆会按原样返回；传入 1 则仅返回匹配的记忆。如果某条消息也会出现在结果列表的较后位置，则会将其提前，而不是重复返回，因此返回结果可能少于 limit。
  • auto_reinforce（布尔值，可选）：自动强化检索到的记忆（默认值：false）。
  • min_intersection（数字，可选）：要求的最小 cue 交集数量（默认值：0）。
  • explain（布尔值，可选）：在结果中包含评分解释数据（默认值：false）。
  • trace_timing（布尔值，可选）：包含 v0.7 计时诊断信息。
  • disable_salience_bias（布尔值，可选）：禁用显著性评分偏置。
  • disable_alias_expansion（布尔值，可选）：查询时禁用词典同义词注入（默认值：true）。
  • parent_fusion（off | auto | force，可选）：分块与父级融合模式。
  • ordered_reconstruction（off | auto | force，可选）：有序会话重建模式。
  • evidence_coverage（off | auto | force，可选）：多证据覆盖模式。
  • disable_cuebridge_artifacts（布尔值，可选）：禁用 CueBridge 工件扩展。
  • cuebridge_gap_limit（数字，可选）：CueBridge 间隙扩展的最大数量。
  • semantic_mode（lexical、semantic 或 hybrid，可选）：选择仅基于 cue 的召回、向量候选发现，或对词法候选进行本地语义重排。引擎默认值为 hybrid。

• query_embedding（数字数组，可选）：当调用应用负责提供嵌入服务时，传入预先计算的查询向量。

Recall 响应与后续检查

Recall 会在 MCP structuredContent 和与之匹配的 JSON 文本块中返回引擎 JSON。这取代了早期仅包含散文的格式。每条识别出的记忆都包含 project_id 和 memory_id；元数据、来源位置以及请求的诊断信息均按引擎提供的内容保留。显式项目查询可能返回包含各自 results 或 error 的项目块，也可能包含空分组。普通的非限定查询则会在 results 中直接返回记忆记录。

需要已存储记录时，使用命中项的项目和 ID 调用 cuemap_memory_get。该工具会返回可读内容，不包含向量或压缩存储字节；它不会展开相邻区块，也不会读取实时文件。如果 Recall 已返回相关文本，请优先打开其引用的来源。后续 Recall 应针对新的证据缺口。有关编码调查工作流和有界 Recall 控制，请参见 SKILL.md。

进行广泛探索时，传入 response_mode: "preview"。命中项的 content 会替换为 preview、content_truncated 和 content_length（UTF-16 代码单元）。这是开头部分的摘录，不是生成的摘要，也不是按查询选出的片段。两种 MCP 输出形式都会省略完整内容；请通过项目/ID 获取有价值的记忆，或读取实时来源。默认模式仍为完整模式。引擎会在发送响应前生成预览。这不会改变排序或检索过程，也不会限制元数据或诊断信息。

许可证

MCP 服务包采用 MIT 许可证。其可选的原生引擎依赖项是独立的软件包：v0.7.3 及更高版本的引擎包采用 Apache-2.0 许可证，而 v0.7.3 之前的引擎包仍采用 BSL-1.1 许可证。有关 MCP 服务许可证，请参见 LICENSE。