ContextGC

基于 AST 解析的上下文智能压缩 MCP 插件 — 节省 70-90% token

ContextGC 利用 AST 语法树提取代码骨架（imports、类型定义、函数签名），省略实现细节。这是唯一支持渐进式上下文加载的 MCP 工具：骨架 → 按需展开函数 → 完整代码。

工作原理

┌──────────────────────────────────────────────────┐
│  2000 行 React 组件 (≈18,000 tokens)              │
│                                                    │
│  ┌─ read_code_skeleton ──────────────────────────┐ │
│  │  imports + 类型 + 函数签名 (≈2,000 tokens)     │ │
│  │  函数体替换为省略标记                           │ │
│  └────────────────────────────────────────────────┘ │
│                                                    │
│  ┌─ read_function_body ──────────────────────────┐ │
│  │  按需展开指定函数实现 (≈500 tokens)             │ │
│  └────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘

功能

• read_code_skeleton — 提取源文件结构骨架，减少 70-90% token 用量
• read_function_body — 按需展开指定函数的完整实现
• parse_error_log — 压缩错误日志，过滤 node_modules 栈帧
• context_gc — 垃圾回收缓存骨架，释放上下文窗口空间
• MCP Prompt 注入 — 自动引导 AI 使用 ContextGC 替代原生 read_file
• 三级降级 — AST 解析 → 正则降级 → 截断兜底
• LRU + TTL 缓存 — 骨架缓存随文件变更自动失效

快速开始

安装与运行

# 克隆
git clone https://github.com/YOUR_USERNAME/contextgc-mcp.git
cd contextgc-mcp

# 安装依赖
npm install

# 构建
npm run build

# 运行
node dist/index.js

配置 Claude Code

claude mcp add contextgc -- node /path/to/contextgc-mcp/dist/index.js

配置 Kilo Code / Cursor / Cline

在 MCP 设置中添加：

{
  "mcpServers": {
    "contextgc": {
      "command": "node",
      "args": ["/path/to/contextgc-mcp/dist/index.js"]
    }
  }
}

工具参考

read_code_skeleton

读取源文件并返回结构骨架。

参数	类型	必填	说明
filePath	string	✅	源文件绝对路径
focusFunction	string	❌	保留此函数的完整实现
focusLine	number	❌	保留此行所在函数的完整实现
maxOutputLines	number	❌	最大输出行数（默认 500）

read_function_body

展开指定函数的完整实现。

参数	类型	必填	说明
filePath	string	✅	源文件绝对路径
functionName	string	✅	要展开的函数名
includeContext	boolean	❌	包含前后 5 行上下文（默认 true）

parse_error_log

压缩错误日志，提取关键信息，过滤噪音。

参数	类型	必填	说明
logContent	string	✅	原始错误日志 / stderr 输出
workspaceRoot	string	❌	工作区根路径，用于识别业务代码
maxFrames	number	❌	最大保留堆栈帧数（默认 10）

context_gc

清除缓存骨架，释放上下文空间。

参数	类型	必填	说明
strategy	"lru" | "all" | "older-than"	❌	GC 策略（默认 lru）
ttlMinutes	number	❌	older-than 策略的过期分钟数（默认 30）

配置

在工作区根目录创建 contextgc.config.json：

{
  "skeleton": {
    "preserveComments": "doc",
    "preserveTypes": true,
    "maxOutputLines": 500
  },
  "cache": {
    "maxEntries": 100,
    "ttlMs": 1800000
  },
  "logTrimmer": {
    "maxFrames": 10,
    "filterPatterns": ["node_modules", "dist", ".next"]
  }
}

环境变量

变量	说明	默认值
CONTEXTGC_CONFIG	自定义配置文件路径	自动搜索
CONTEXTGC_ENABLED	全局开关	true
CONTEXTGC_LOG_LEVEL	日志级别（debug/info/warn/error）	warn

支持的语言

语言	解析器	状态
JavaScript / JSX	Babel	✅ 完整支持
TypeScript / TSX	Babel	✅ 完整支持
Python / Go / Rust / Java / C++	正则降级	⚠️ 基础支持
其他语言	正则降级	⚠️ 基础支持

Tree-sitter 集成（完整多语言 AST 支持）计划在 v0.2 实现。

架构

AI 编码助手 (宿主)
        │ MCP (JSON-RPC 2.0 over stdio)
        ▼
┌─────────────────────────────────┐
│       ContextGC MCP Server       │
│  ┌───────────────────────────┐  │
│  │      MCP 协议层            │  │
│  └─────────┬─────────────────┘  │
│  ┌─────────▼─────────────────┐  │
│  │     工具编排层              │  │
│  │  骨架 | 展开函数 | 日志 | GC│  │
│  └─────────┬─────────────────┘  │
│  ┌─────────▼─────────────────┐  │
│  │     解析器抽象层            │  │
│  │  Babel | Tree-sitter | 正则 │  │
│  └───────────────────────────┘  │
└─────────────────────────────────┘

开发

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

# 监听模式运行测试
npm run test:watch

# 开发模式（自动重编译）
npm run dev

Token 节省基准

场景	原始	压缩后	压缩率
2000 行 React 组件（骨架提取）	~18,000 tok	~2,000 tok	89%
1000 行 npm build 报错日志	~8,000 tok	~400 tok	95%
500 行 diff 输出	~5,000 tok	~1,500 tok	70%
综合大型项目调试会话	~80,000 tok	~15,000 tok	81%

以上为理论估算值，实际压缩率取决于代码风格和文件结构。

许可证

MIT