ctxshot-mcp

给 Cursor / Claude Code 的轻量项目简报 MCP。 每天开会话 ~400 token 交代项目结构，不是 Repomix 全库打包。

Tools: session_brief · pack_context · context_stats

ctxshot 的 MCP 封装。让 Agent 原生调用打包逻辑，自动写 .ai/context.md，不用你每次手动 npx ctxshot。

---

解决什么问题

场景	笨办法	ctxshot-mcp
每天新开会话	反复贴 README、glob 目录	Agent 调 session_brief → @.ai/context.md
想知道简报多大	跑完再看	context_stats 先看 token 估算
临时要结构	复制终端输出	pack_context 直接返回 Markdown
要读全库	Repomix 一把梭	仍用 Repomix，本 MCP 不替代

---

实测（同仓库 benchmark）

基于 ctxshot 自身仓库：

工具	耗时	估 token
ctxshot / session_brief	356ms	423
README 手贴	<1ms	685
repomix --stdout	3.6s	7,023

<p align="center"> <img src="https://raw.githubusercontent.com/G12789/ctxshot/main/docs/benchmark-chart.svg" alt="ctxshot vs Repomix" width="860" /> </p>

---

30 秒接入

Cursor

~/.cursor/mcp.json 或项目 .cursor/mcp.json：

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

Developer: Reload Window 后，Settings → Tools & MCPs 看到绿色 ctxshot 即成功。

Claude Code

claude mcp add ctxshot -- npx -y ctxshot-mcp@latest

验证

npx ctxshot-mcp   # stdio server（由 IDE 拉起，勿手动交互）

或在项目里：

git clone https://github.com/G12789/ctxshot-mcp
cd ctxshot-mcp && npm install
npm run test:mcp

---

MCP Tools 完整说明

session_brief（推荐：每日起手）

打包 compact + diff 简报，写入 .ai/context.md，并返回全文。

参数	类型	说明
root	string?	项目根目录（默认：server cwd）
out	string?	输出路径，相对 root（默认 .ai/context.md）

典型用法： 新会话开头让 Agent 调用，然后 @.ai/context.md。

---

pack_context

返回 Markdown 简报，不写文件。

参数	类型	默认	说明
compact	boolean?	true	浅树 + 截断 README
diff	boolean?	false	包含 git 摘要
depth	number?	compact=2	目录树深度 (1–6)
maxEntries	number?	compact=50	最多树节点 (10–500)
root	string?	cwd	项目根目录

---

context_stats

只返回 JSON 统计，不拉全文。适合对比 token 成本。

参数	类型	说明
compact	boolean?	同 pack_context
diff	boolean?	同 pack_context
root	string?	项目根目录

返回示例：

{
  "estimatedTokens": 423,
  "lineCount": 76,
  "treeLineCount": 22,
  "compact": true,
  "hasGit": true,
  "manifestCount": 1,
  "root": "/your/project",
  "hint": "Use pack_context for full brief; Repomix for entire codebase."
}

---

推荐工作流

┌─────────────────────────────────────────────────────┐
│  1. 打开项目（或传 root 参数）                        │
│  2. 新会话 → Agent 调用 session_brief                │
│  3. 生成 .ai/context.md + ledger-events.jsonl      │
│  4. 对话 @.ai/context.md                             │
│  5. 读具体实现 → @文件 或 Repomix                    │
└─────────────────────────────────────────────────────┘

.ai/ledger-events.jsonl 记录每次调用的 token 估算，为后续 token 账本功能预埋。

---

架构

Cursor / Claude Code
        │  stdio MCP
        ▼
ctxshot-mcp (本仓库)
  ├── index.ts   stdio 入口
  └── server.ts  注册 3 个 Tool
        │
        ▼
ctxshot/core (npm 依赖)
  packContext() — 与 CLI 共用同一套逻辑
        │
        ▼
.ai/context.md
.ai/ledger-events.jsonl

与 CLI 的关系：

	ctxshot CLI	ctxshot-mcp
调用方	人 / 脚本	Agent / IDE
传输	终端	MCP stdio
核心	packContext()	同左
输出	stdout 或 -o 文件	Tool 返回 + session_brief 写文件

---

和 Repomix 怎么选

	ctxshot-mcp	Repomix
Token	~200–2k	可达 100k+
速度	<1s	大仓库慢
内容	树 + 脚本 + 摘要	全文件内容
场景	每日开会话	全库 refactor / 审计
关系	互补	互补

---

常见问题

Q: MCP 绿灯但扫错目录？
全局 MCP 的 cwd 可能是用户主目录。解法：

• 把目标项目作为 Cursor 工作区根目录打开
• 或调用时传 root: "/path/to/your/project"

Q: 和 CLI 有什么区别？
逻辑完全一样（共用 ctxshot/core）。MCP 让 Agent 在会话里自动调用，不用你记命令。

Q: 能替代 Repomix 吗？
不能。简报 ≠ 全库。需要 AI 读每一行代码时请用 Repomix。

Q: 离线能用吗？
能。纯本地扫描，不联网，不上传任何内容。

---

开发

git clone https://github.com/G12789/ctxshot-mcp
cd ctxshot-mcp && npm install
npm run build
npm run test:smoke    # 单元 smoke
npm run test:mcp      # MCP 客户端端到端
npm run inspect       # MCP Inspector

依赖 ctxshot@0.2.1+ 的 ctxshot/core 导出。

---

相关项目

项目	链接
ctxshot CLI	https://github.com/G12789/ctxshot
evaldrift	https://github.com/G12789/evaldrift
mcp-quickstart	https://github.com/G12789/mcp-quickstart
ship-skills	https://www.npmjs.com/package/ship-skills

---

License

MIT · ctxshot CLI · npm