Skip to content

mcp.md

Latest commit

 

History

History
295 lines (233 loc) · 7.9 KB

mcp.md

File metadata and controls

295 lines (233 loc) · 7.9 KB

MCP 工具参考

本文档描述 MCP 接入模式。如果你只需要终端命令行，请参考 CLI 参考。

配置

setup

运行以下命令完成 MCP 模式的全部初始化：

contextatlas setup:local --mode mcp

该命令会写入以下文件：

文件 说明
~/.contextatlas/.env 共享配置
~/.claude/mcp.json MCP 模式
Claude Desktop MCP config MCP 模式
~/.gemini/settings.json MCP 模式
~/.codex/config.toml MCP block，MCP 模式
~/.claude/CLAUDE.md prompt block，共享
~/.codex/AGENTS.md prompt block，共享
~/.gemini/GEMINI.md prompt block，共享
~/.codex/skills/contextatlas-mcp/SKILL.md MCP 模式

注意：MCP 模式下 不会 写入 CLI skill 文件。

Claude Desktop

{
  "mcpServers": {
    "contextatlas": {
      "command": "contextatlas",
      "args": ["mcp"]
    }
  }
}

启动服务器

contextatlas mcp

如需降低客户端的工具选择负担，可以通过环境变量切换 MCP 工具集：

{
  "mcpServers": {
    "contextatlas": {
      "command": "contextatlas",
      "args": ["mcp"],
      "env": {
        "CONTEXTATLAS_MCP_TOOLSET": "retrieval-only"
      }
    }
  }
}
  • full：默认，暴露全部 21 个工具
  • retrieval-only：仅暴露 7 个只读检索工具，适合把 ContextAtlas 当作纯 retrieval/memory reader 使用

工具总览（24 个）

代码检索

工具 用途
codebase-retrieval 混合语义+词法代码检索（核心工具）

项目记忆

工具 用途
find_memory 快速查找模块记忆
record_memory 记录模块职责、API、依赖
delete_memory 删除模块记忆
record_decision 记录架构决策
get_project_profile 获取技术栈、结构、约定
maintain_memory_catalog 目录维护（check / rebuild）
load_module_memory 渐进式按需加载模块记忆
list_memory_catalog 查看目录索引（调试用）

长期记忆

工具 用途
record_long_term_memory 记录用户偏好、协作规则、外部参考、evidence、temporal fact
manage_long_term_memory 查找/列举/清理/删除/失效长期记忆
record_agent_diary 追加 agent diary 条目
read_agent_diary 读取某个 agent 的最近 diary
find_agent_diary 按关键词搜索 diary
record_result_feedback 记录结果有帮助/没帮助/记忆过期/绑定错误等反馈

跨项目 Hub

工具 用途
query_shared_memories 跨项目搜索模块记忆
link_memories 创建记忆间关系（depends_on / extends / references / implements）
get_dependency_chain 递归依赖链分析
manage_projects 项目管理（action: register / list / stats）

自动记录

工具 用途
session_end 会话结束时自动分析并建议记录记忆
suggest_memory AI 辅助提取模块记忆

上下文生命周期

工具 用途
prepare_handoff 基于 checkpoint 组装交接/恢复包
assemble_context 按 phase/profile 组装最小可用上下文
suggest_phase_boundary 建议下一阶段及阻塞项

生命周期工具说明

prepare_handoff

  • 输入：repo_path、checkpoint_id，可选 agent_name / topic / diary_limit
  • 输出重点：handoffSummary、referencedBlockIds、unresolvedBlockIds
  • 语义：在 checkpoint 自身的 task-state block 之外，会尽量补出可解析的模块摘要、supporting refs、已检视代码引用，以及按需带上的最近 diary，便于下一位 agent 直接接手

assemble_context

  • 输入：repo_path，可选 phase / profile / checkpoint_id / moduleName / query / filePaths / includeDiary / agentName / diaryTopic / diaryLimit
  • 输出重点：selectedContext.contextBlocks、references、assemblyProfile、wakeupLayers
  • 语义：按阶段装配“最小可用上下文包”；phase=research 会映射到 overview profile，profile 当前仅支持 overview/debug/implementation/verification/handoff。输出会显式给出 L0-L3 wakeup layers，并在命中的 evidence / temporal fact / diary 存在时一并暴露

suggest_phase_boundary

  • 输入：repo_path、current_phase，可选 checkpoint_id / checkpoint / retrieval_signal / assembly_signal
  • 输出重点：recommendedPhase、transition、shouldTransition、blockers
  • 语义：这是边界判断器，不是固定推进器；当证据不足、存在 blocker 或 phase 冲突时，会明确返回保持当前阶段

推荐使用顺序

  1. 先 find_memory 定位已有模块知识
  2. 再 codebase-retrieval 查看具体实现
  3. 完成后 record_memory / record_decision / record_result_feedback / session_end 回写稳定知识
  4. 跨项目复用时 query_shared_memories 查找相似实现

典型调用示例

代码检索

codebase-retrieval 现在默认会附带一段轻量直接图谱摘要；只有在你明确不需要时，才传 include_graph_context: false 关闭。

{
  "repo_path": "/path/to/repo",
  "information_request": "Trace the execution flow of the login process",
  "technical_terms": ["AuthService", "login"]
}

记录模块记忆

{
  "name": "SearchService",
  "responsibility": "Hybrid semantic + lexical code retrieval",
  "dir": "src/search/",
  "files": ["SearchService.ts", "GraphExpander.ts", "ContextPacker.ts"],
  "exports": ["SearchService"],
  "imports": ["VectorStore", "Database"],
  "external": ["lancedb", "better-sqlite3"],
  "confirmationStatus": "human-confirmed"
}

记录架构决策

{
  "id": "2026-04-02-memory-routing",
  "title": "引入渐进式记忆路由",
  "context": "需要控制代理加载的上下文大小",
  "decision": "使用 catalog -> global -> feature 三层加载",
  "owner": "search-owner",
  "reviewer": "ops-lead",
  "rationale": "先路由再按需加载，减少 token 开销",
  "alternatives": [],
  "consequences": ["决策记录需要可追责的 owner/reviewer 元数据"]
}

管理长期记忆

{
  "action": "find",
  "query": "user preferences"
}

记录结果反馈

{
  "outcome": "memory-stale",
  "targetType": "feature-memory",
  "query": "Trace retrieval flow",
  "targetId": "SearchService",
  "details": "Memory still points to legacy path"
}
{
  "action": "prune",
  "dryRun": true
}

跨项目搜索

{
  "category": "auth"
}

依赖链分析

{
  "project": "ctx",
  "module": "AuthService",
  "recursive": true
}

交接包

{
  "repo_path": "/path/to/repo",
  "checkpoint_id": "chk_1234567890ab",
  "format": "json"
}

上下文装配

{
  "repo_path": "/path/to/repo",
  "phase": "implementation",
  "checkpoint_id": "chk_1234567890ab",
  "moduleName": "SearchService",
  "query": "Trace retrieval flow",
  "filePaths": ["src/search/SearchService.ts"],
  "format": "json"
}

阶段边界建议

{
  "repo_path": "/path/to/repo",
  "current_phase": "debug",
  "checkpoint_id": "chk_1234567890ab",
  "retrieval_signal": {
    "codeBlocks": 3,
    "memoryBlocks": 1,
    "decisionBlocks": 0,
    "confidence": "high",
    "mode": "expanded"
  },
  "assembly_signal": {
    "profile": "debug",
    "source": "phase",
    "budgetUsed": 4,
    "budgetLimit": 8
  },
  "format": "json"
}

与 CLI 模式的区别

  • MCP 模式通过标准 MCP 协议暴露工具，适合 MCP 客户端（Claude Desktop、Gemini、Codex 等）直接调用。
  • CLI 模式通过 contextatlas 命令行操作，适合终端使用和 skill 集成。
  • 两种模式的 setup 互斥：setup:local --mode mcp 不会写入 CLI skill 文件，setup:local --mode cli 不会写入 MCP 配置。