AI导哈

AI上下文管理工具

MCP上下文管理器是一款用于AI编程助手的上下文管理工具，帮助解决长对话中的上下文丢失问题，提供记忆存储、上下文摘要、项目跟踪等功能。

  • by asd412id
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 asd412id/mcp-context-manager

使用说明

MCP上下文管理器

用于AI编码代理中上下文管理的MCP（模型上下文协议）工具。有助于防止长时间对话中出现断章取义的问题。

特性

  • 记忆存储 -跨会话的持久键值存储
  • 上下文摘要生成器 -总结聊天/文本，提取关键点、决策、行动项
  • 项目追踪器 -跟踪决策、更改、待办事项、笔记、错误
  • 会话检查点 -保存/恢复会话状态
  • 智能文件加载器 -加载具有相关性过滤的文件

代理技能（推荐）

为了获得最佳的代理性能，请使用随附的 SKILL.md 将文件作为代理指令。这项技能教会代理人：

  • 尽量减少上下文窗口的使用 -通过将数据卸载到持久存储来释放RAM
  • 自动保存进度 -每10-15条消息检查一次
  • 跟踪决策和变更 -维护项目历史记录
  • 处理长时间会话 -当上下文已满时，无缝切换到新会话

如何使用该技能

选项1:克劳德代码/临床/光标 地方 SKILL.md 在项目根目录中，或在代理配置中引用它。

选项2：海关代理 包括以下内容 SKILL.md 在您的系统提示或代理指令中。

选项3：直接参考 告诉你的经纪人： “加载并遵循SKILL.md中的说明”

该技能提供：

  • 何时使用每个工具的强制触发器
  • 减少LLM内存使用的上下文清理策略
  • 最小化上下文消耗的最佳实践
  • 带示例的完整工具参考

安装

需要Node.js>=18.0.0

# Run directly with npx (recommended)
npx @asd412id/mcp-context-manager

# Or install globally
npm install -g @asd412id/mcp-context-manager

按客户端配置

克劳德桌面

配置文件位置：

  • 窗户： %APPDATA%\Claude\claude_desktop_config.json
  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux： ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"]
    }
  }
}

VS代码（GitHub复制品/Claude扩展）

选项1：工作区配置 - .vscode/mcp.json

{
  "servers": {
    "context-manager": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"]
    }
  }
}

选项2：用户设置 - settings.json

{
  "mcp.servers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"]
    }
  }
}

光标

配置文件位置：

  • 窗户： %APPDATA%\Cursor\mcp.json
  • macOS： ~/Library/Application Support/Cursor/mcp.json
  • Linux： ~/.config/Cursor/mcp.json
{
  "mcpServers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"]
    }
  }
}

帆板运动

配置文件位置：

  • 窗户： %USERPROFILE%\.codeium\windsurf\mcp_config.json
  • macOS： ~/.codeium/windsurf/mcp_config.json
  • Linux： ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"]
    }
  }
}

Cline（VS代码扩展）

配置文件位置：

  • 窗户： %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  • macOS： ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Linux： ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
{
  "mcpServers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

继续（VS代码/JetBrains扩展）

配置文件： ~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "context-manager",
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"]
    }
  ]
}

或者使用YAML(~/.continue/config.yaml):

mcpServers:
  - name: context-manager
    command: npx
    args:
      - "-y"
      - "@asd412id/mcp-context-manager"

开源代码

配置文件： opencode.json 在您的项目根目录中或 ~/.config/opencode/config.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context-manager": {
      "type": "local",
      "command": ["npx", "-y", "@asd412id/mcp-context-manager"],
      "enabled": true
    }
  }
}

Zed编辑

配置文件： ~/.config/zed/settings.json

{
  "context_servers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"],
      "env": {}
    }
  }
}

自定义上下文路径

要指定用于存储上下文数据的自定义路径，请添加环境变量。

克劳德桌面/光标/风帆/克莱恩：

{
  "mcpServers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"],
      "env": {
        "MCP_CONTEXT_PATH": "/path/to/your/project/.context"
      }
    }
  }
}

OpenCode：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context-manager": {
      "type": "local",
      "command": ["npx", "-y", "@asd412id/mcp-context-manager"],
      "environment": {
        "MCP_CONTEXT_PATH": "/path/to/your/project/.context"
      }
    }
  }
}

Zed：

{
  "context_servers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"],
      "env": {
        "MCP_CONTEXT_PATH": "/path/to/your/project/.context"
      }
    }
  }
}

提示（快捷命令）

提示 描述
ctx-init 使用上下文管理指令从上一个会话加载上下文
ctx-save 将当前状态保存到检查点
ctx-remember 将重要信息保存到内存中
ctx-todo 添加待办事项
ctx-decide 记录决策
ctx-status 显示项目状态
ctx-compress 压缩长上下文
ctx-recall 在内存中搜索
ctx-cleanup 释放上下文窗口空间并减少RAM使用
ctx-handoff 为新会话生成切换文档

可用工具（33个工具）

会话管理

工具 说明
session_init 初始化会话-在一次调用中加载检查点、跟踪器、内存、检测项目
session_handoff 生成紧凑的降价切换文档，实现无缝会话继续
project_detect 自动检测项目信息（支持20多种语言：Node、Python、Rust、Go、Java、PHP、Ruby、Elixir、.NET、Swift、Kotlin、Dart、Haskell、Scala、Clojure、Lua、Zig、Nim、V、Deno、Bun）

记忆存储

工具 说明
memory_set 将键值存储在内存中
memory_get 从内存中检索值
memory_update 部分更新/合并现有内存值
memory_search 按模式/标签搜索内存
memory_delete 删除内存条目
memory_list 列出所有记忆键
memory_clear 清除内存（全部/按标签）
memory_cleanup 删除过期的内存条目
memory_capture_candidates 从文本中提取并保留重要的内存候选项（可选）

上下文摘要生成器

工具 说明
context_summarize 总结文本，提取关键点、决策、行动项
context_get_summary 按ID获取摘要
context_list_summaries 列出所有摘要
context_merge_summaries 合并多个摘要
context_status 获取存储统计数据和令牌使用估计
context_prune_smart 对上下文项目进行评分，保持高信号，总结/修剪低信号
store_health 检查商店的完整性和建议

项目追踪器

工具 说明
tracker_log 记录决策/更改/待办事项/注释/错误
tracker_status 获取项目状态概述
tracker_get 按ID获取特定跟踪器条目
tracker_todo_update 更新待办事项状态
tracker_search 搜索跟踪条目
tracker_set_project 设置项目名称
tracker_export 将跟踪器导出为markdown
tracker_cleanup 清理旧条目，保留最新条目

会话检查点

工具 说明
checkpoint_save 保存会话状态
checkpoint_load 加载检查点
checkpoint_list 列出所有检查点
checkpoint_delete 删除检查点
checkpoint_compare 比较2个检查点

智能文件加载器

工具 说明
file_smart_read 使用智能选项（行、关键字、结构）读取文件
file_info 获取文件元数据
file_search_content 文件中的搜索模式
file_list_dir 列出目录文件

环境变量

变量 描述 默认值
MCP_CONTEXT_PATH 存储上下文数据的路径 {cwd}/.context
MCP_MAX_CHECKPOINTS 自动清理前的最大检查点 50
MCP_MAX_SUMMARIES 自动清理前的最大摘要数 100
MCP_TRACKER_MAX_ENTRIES 旋转前的最大跟踪器条目数 1000
MCP_TRACKER_ROTATE_KEEP 轮换后要保留的条目 800

用法示例

会话启动工作流

User: ctx-init
AI: *runs checkpoint_load(), tracker_status(), memory_list()*

保存重要信息

User: ctx-remember what:"API endpoint at https://api.example.com"
AI: *saves to memory with appropriate key and tags*

结束会话之前

User: ctx-save name:"feature-login-done"
AI: *creates checkpoint with current state*

当上下文变长时

User: Generate handoff for new session
AI: *runs session_handoff()* -> outputs compact markdown with all context
AI: Start a new conversation and paste this handoff, then run session_init()

最佳实践

  1. 会话开始 -始终运行 session_init() 加载以前的上下文
  2. 保存决策 -使用 tracker_log(type:"decision") 对于重要决策
  3. 跟踪全部 -使用 tracker_log(type:"todo") 待完成的任务
  4. 定期检查 -快跑 checkpoint_save() 每~15-20条消息或里程碑之后
  5. 长时间切换 -使用 session_handoff() 当上下文>50%时，启动新会话

数据存储

所有数据都存储在 .context/ 文件夹（默认：工作目录）：

.context/
├── memory.json          # Memory store
├── tracker.json         # Project tracker
├── checkpoints/         # Session checkpoints
│   ├── index.json
│   └── cp_*.json
└── summaries/           # Context summaries
    └── index.json

故障排除

服务器未启动

  1. 确保已安装Node.js>=18： node --version
  2. 尝试手动运行： npx @asd412id/mcp-context-manager
  3. 检查是否存在端口/进程冲突

工具未出现

  1. 配置更改后重新启动MCP客户端
  2. 检查配置文件语法（有效的JSON）
  3. 验证客户端的配置文件位置是否正确

权限问题

  1. 确保对上下文路径的写访问权限
  2. 尝试设置显式 MCP_CONTEXT_PATH 在环境中

许可证

麻省理工学院

贡献

欢迎在 GitHub

发行说明自动化

此存储库包括 .github/release.yml 使生成的发行说明标准化。

如何创建干净的发布说明

使用GitHub自动生成的笔记（CLI）：

gh release create vX.Y.Z --target master --generate-notes

GitHub将自动：

  • 按类别分组更改（功能、修复、安全、测试、维护）
  • 使用一致的项目符号格式
  • 包括贡献者列表

安全放行程序（必填）

为了避免重复/肮脏的npm版本，请遵循以下严格流程：

# 1) Ensure package version already final in package.json
node -p "require('./package.json').version"

# 2) Push commit first
git push origin master

# 3) Create release tag matching package version exactly
gh release create vX.Y.Z --target master --generate-notes

# 4) WAIT until publish workflow completes
gh run list --workflow publish.yml --limit 5
gh run watch <run-id> --exit-status

# 5) Verify npm registry
npm view @asd412id/mcp-context-manager version --registry=https://registry.npmjs.org
npm view @asd412id/mcp-context-manager@X.Y.Z version --registry=https://registry.npmjs.org

规则：

  • 在上次发布运行完成之前，切勿创建下一个发布标记
  • 标签版本必须相等 package.json 版本
  • 如果发布运行失败，请先修复根本原因；不要发送垃圾邮件补丁

相关 MCP