ctxshot-mcp 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +211 -16
- package/dist/server.js +8 -5
- package/package.json +9 -5
package/README.md
CHANGED
|
@@ -1,17 +1,60 @@
|
|
|
1
1
|
# ctxshot-mcp
|
|
2
2
|
|
|
3
|
+
> ⭐ **推荐：** [`npx ship-skills init`](https://github.com/G12789/ai-ship)（已登录 `gh` 会自动支持作者）
|
|
4
|
+
|
|
5
|
+
[](https://github.com/G12789/ctxshot-mcp/actions/workflows/ci.yml)
|
|
3
6
|
[](https://www.npmjs.com/package/ctxshot-mcp)
|
|
4
7
|
[](https://modelcontextprotocol.io)
|
|
8
|
+
[](https://nodejs.org)
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
|
|
11
|
+
> **给 Cursor / Claude Code 的轻量项目简报 MCP。**
|
|
12
|
+
> 每天开会话 ~400 token 交代项目结构，不是 Repomix 全库打包。
|
|
13
|
+
>
|
|
14
|
+
> Tools: `session_brief` · `pack_context` · `context_stats`
|
|
15
|
+
|
|
16
|
+
[ctxshot](https://github.com/G12789/ctxshot) 的 MCP 封装。让 Agent **原生调用**打包逻辑，自动写 `.ai/context.md`，不用你每次手动 `npx ctxshot`。
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## 解决什么问题
|
|
21
|
+
|
|
22
|
+
| 场景 | 笨办法 | ctxshot-mcp |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| 每天新开会话 | 反复贴 README、glob 目录 | Agent 调 `session_brief` → `@.ai/context.md` |
|
|
25
|
+
| 想知道简报多大 | 跑完再看 | `context_stats` 先看 token 估算 |
|
|
26
|
+
| 临时要结构 | 复制终端输出 | `pack_context` 直接返回 Markdown |
|
|
27
|
+
| 要读全库 | Repomix 一把梭 | **仍用 Repomix**，本 MCP 不替代 |
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 实测（同仓库 benchmark）
|
|
5
32
|
|
|
6
|
-
|
|
7
|
-
> Tools: `pack_context` · `session_brief` · `context_stats`
|
|
33
|
+
基于 [ctxshot](https://github.com/G12789/ctxshot) 自身仓库：
|
|
8
34
|
|
|
9
|
-
|
|
35
|
+
| 工具 | 耗时 | 估 token |
|
|
36
|
+
|---|---:|---:|
|
|
37
|
+
| ctxshot / session_brief | **356ms** | **423** |
|
|
38
|
+
| README 手贴 | <1ms | 685 |
|
|
39
|
+
| repomix --stdout | **3.6s** | **7,023** |
|
|
40
|
+
|
|
41
|
+
<p align="center">
|
|
42
|
+
<img src="https://raw.githubusercontent.com/G12789/ctxshot/main/docs/benchmark-chart.svg" alt="ctxshot vs Repomix" width="860" />
|
|
43
|
+
</p>
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## 30 秒接入
|
|
48
|
+
|
|
49
|
+
### Cursor
|
|
50
|
+
|
|
51
|
+
`~/.cursor/mcp.json` 或项目 `.cursor/mcp.json`：
|
|
10
52
|
|
|
11
53
|
```json
|
|
12
54
|
{
|
|
13
55
|
"mcpServers": {
|
|
14
56
|
"ctxshot": {
|
|
57
|
+
"type": "stdio",
|
|
15
58
|
"command": "npx",
|
|
16
59
|
"args": ["-y", "ctxshot-mcp@latest"]
|
|
17
60
|
}
|
|
@@ -19,36 +62,188 @@
|
|
|
19
62
|
}
|
|
20
63
|
```
|
|
21
64
|
|
|
22
|
-
|
|
65
|
+
**Developer: Reload Window** 后，Settings → **Tools & MCPs** 看到绿色 `ctxshot` 即成功。
|
|
66
|
+
|
|
67
|
+
### Claude Code
|
|
23
68
|
|
|
24
69
|
```bash
|
|
25
70
|
claude mcp add ctxshot -- npx -y ctxshot-mcp@latest
|
|
26
71
|
```
|
|
27
72
|
|
|
28
|
-
|
|
73
|
+
### 验证
|
|
29
74
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
75
|
+
```bash
|
|
76
|
+
npx ctxshot-mcp # stdio server（由 IDE 拉起，勿手动交互）
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
或在项目里：
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
git clone https://github.com/G12789/ctxshot-mcp
|
|
83
|
+
cd ctxshot-mcp && npm install
|
|
84
|
+
npm run test:mcp
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## MCP Tools 完整说明
|
|
90
|
+
|
|
91
|
+
### `session_brief`（推荐：每日起手）
|
|
92
|
+
|
|
93
|
+
打包 compact + diff 简报，写入 `.ai/context.md`，并返回全文。
|
|
94
|
+
|
|
95
|
+
| 参数 | 类型 | 说明 |
|
|
96
|
+
|---|---|---|
|
|
97
|
+
| `root` | string? | 项目根目录（默认：server cwd） |
|
|
98
|
+
| `out` | string? | 输出路径，相对 root（默认 `.ai/context.md`） |
|
|
99
|
+
|
|
100
|
+
**典型用法：** 新会话开头让 Agent 调用，然后 `@.ai/context.md`。
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
### `pack_context`
|
|
105
|
+
|
|
106
|
+
返回 Markdown 简报，不写文件。
|
|
107
|
+
|
|
108
|
+
| 参数 | 类型 | 默认 | 说明 |
|
|
109
|
+
|---|---|---|---|
|
|
110
|
+
| `compact` | boolean? | `true` | 浅树 + 截断 README |
|
|
111
|
+
| `diff` | boolean? | `false` | 包含 git 摘要 |
|
|
112
|
+
| `depth` | number? | compact=2 | 目录树深度 (1–6) |
|
|
113
|
+
| `maxEntries` | number? | compact=50 | 最多树节点 (10–500) |
|
|
114
|
+
| `root` | string? | cwd | 项目根目录 |
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
### `context_stats`
|
|
119
|
+
|
|
120
|
+
只返回 JSON 统计，不拉全文。适合对比 token 成本。
|
|
35
121
|
|
|
36
|
-
|
|
122
|
+
| 参数 | 类型 | 说明 |
|
|
123
|
+
|---|---|---|
|
|
124
|
+
| `compact` | boolean? | 同 pack_context |
|
|
125
|
+
| `diff` | boolean? | 同 pack_context |
|
|
126
|
+
| `root` | string? | 项目根目录 |
|
|
127
|
+
|
|
128
|
+
返回示例：
|
|
129
|
+
|
|
130
|
+
```json
|
|
131
|
+
{
|
|
132
|
+
"estimatedTokens": 423,
|
|
133
|
+
"lineCount": 76,
|
|
134
|
+
"treeLineCount": 22,
|
|
135
|
+
"compact": true,
|
|
136
|
+
"hasGit": true,
|
|
137
|
+
"manifestCount": 1,
|
|
138
|
+
"root": "/your/project",
|
|
139
|
+
"hint": "Use pack_context for full brief; Repomix for entire codebase."
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## 推荐工作流
|
|
146
|
+
|
|
147
|
+
```
|
|
148
|
+
┌─────────────────────────────────────────────────────┐
|
|
149
|
+
│ 1. 打开项目（或传 root 参数） │
|
|
150
|
+
│ 2. 新会话 → Agent 调用 session_brief │
|
|
151
|
+
│ 3. 生成 .ai/context.md + ledger-events.jsonl │
|
|
152
|
+
│ 4. 对话 @.ai/context.md │
|
|
153
|
+
│ 5. 读具体实现 → @文件 或 Repomix │
|
|
154
|
+
└─────────────────────────────────────────────────────┘
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
`.ai/ledger-events.jsonl` 记录每次调用的 token 估算，为后续 token 账本功能预埋。
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## 架构
|
|
162
|
+
|
|
163
|
+
```
|
|
164
|
+
Cursor / Claude Code
|
|
165
|
+
│ stdio MCP
|
|
166
|
+
▼
|
|
167
|
+
ctxshot-mcp (本仓库)
|
|
168
|
+
├── index.ts stdio 入口
|
|
169
|
+
└── server.ts 注册 3 个 Tool
|
|
170
|
+
│
|
|
171
|
+
▼
|
|
172
|
+
ctxshot/core (npm 依赖)
|
|
173
|
+
packContext() — 与 CLI 共用同一套逻辑
|
|
174
|
+
│
|
|
175
|
+
▼
|
|
176
|
+
.ai/context.md
|
|
177
|
+
.ai/ledger-events.jsonl
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
与 CLI 的关系：
|
|
181
|
+
|
|
182
|
+
| | [ctxshot](https://github.com/G12789/ctxshot) CLI | ctxshot-mcp |
|
|
183
|
+
|---|---|---|
|
|
184
|
+
| 调用方 | 人 / 脚本 | Agent / IDE |
|
|
185
|
+
| 传输 | 终端 | MCP stdio |
|
|
186
|
+
| 核心 | `packContext()` | 同左 |
|
|
187
|
+
| 输出 | stdout 或 `-o` 文件 | Tool 返回 + `session_brief` 写文件 |
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## 和 Repomix 怎么选
|
|
37
192
|
|
|
38
193
|
| | ctxshot-mcp | Repomix |
|
|
39
194
|
|---|---|---|
|
|
40
195
|
| Token | ~200–2k | 可达 100k+ |
|
|
41
196
|
| 速度 | <1s | 大仓库慢 |
|
|
42
|
-
|
|
|
197
|
+
| 内容 | 树 + 脚本 + 摘要 | 全文件内容 |
|
|
198
|
+
| 场景 | **每日开会话** | 全库 refactor / 审计 |
|
|
199
|
+
| 关系 | **互补** | 互补 |
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## 常见问题
|
|
204
|
+
|
|
205
|
+
**Q: MCP 绿灯但扫错目录？**
|
|
206
|
+
全局 MCP 的 cwd 可能是用户主目录。解法：
|
|
207
|
+
- 把目标项目作为 Cursor 工作区根目录打开
|
|
208
|
+
- 或调用时传 `root`: `"/path/to/your/project"`
|
|
209
|
+
|
|
210
|
+
**Q: 和 CLI 有什么区别？**
|
|
211
|
+
逻辑完全一样（共用 `ctxshot/core`）。MCP 让 Agent 在会话里自动调用，不用你记命令。
|
|
212
|
+
|
|
213
|
+
**Q: 能替代 Repomix 吗？**
|
|
214
|
+
不能。简报 ≠ 全库。需要 AI 读每一行代码时请用 Repomix。
|
|
215
|
+
|
|
216
|
+
**Q: 离线能用吗？**
|
|
217
|
+
能。纯本地扫描，不联网，不上传任何内容。
|
|
218
|
+
|
|
219
|
+
---
|
|
43
220
|
|
|
44
221
|
## 开发
|
|
45
222
|
|
|
46
223
|
```bash
|
|
47
|
-
|
|
48
|
-
cd
|
|
49
|
-
npm run
|
|
224
|
+
git clone https://github.com/G12789/ctxshot-mcp
|
|
225
|
+
cd ctxshot-mcp && npm install
|
|
226
|
+
npm run build
|
|
227
|
+
npm run test:smoke # 单元 smoke
|
|
228
|
+
npm run test:mcp # MCP 客户端端到端
|
|
229
|
+
npm run inspect # MCP Inspector
|
|
50
230
|
```
|
|
51
231
|
|
|
232
|
+
依赖 [ctxshot@0.2.1+](https://www.npmjs.com/package/ctxshot) 的 `ctxshot/core` 导出。
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## 相关项目
|
|
237
|
+
|
|
238
|
+
| 项目 | 链接 |
|
|
239
|
+
|---|---|
|
|
240
|
+
| ctxshot CLI | https://github.com/G12789/ctxshot |
|
|
241
|
+
| evaldrift | https://github.com/G12789/evaldrift |
|
|
242
|
+
| mcp-quickstart | https://github.com/G12789/mcp-quickstart |
|
|
243
|
+
| ship-skills | https://www.npmjs.com/package/ship-skills |
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
52
247
|
## License
|
|
53
248
|
|
|
54
|
-
MIT
|
|
249
|
+
MIT · [ctxshot CLI](https://github.com/G12789/ctxshot) · [npm](https://www.npmjs.com/package/ctxshot-mcp)
|
package/dist/server.js
CHANGED
|
@@ -23,11 +23,7 @@ function recordLedger(root, tool, stats) {
|
|
|
23
23
|
/* ledger optional */
|
|
24
24
|
}
|
|
25
25
|
}
|
|
26
|
-
export function
|
|
27
|
-
const server = new McpServer({
|
|
28
|
-
name: "ctxshot-mcp",
|
|
29
|
-
version: VERSION,
|
|
30
|
-
});
|
|
26
|
+
export function registerCtxshotTools(server, cwd) {
|
|
31
27
|
const packSchema = {
|
|
32
28
|
compact: z
|
|
33
29
|
.boolean()
|
|
@@ -135,5 +131,12 @@ export function createCtxshotMcpServer(cwd) {
|
|
|
135
131
|
],
|
|
136
132
|
};
|
|
137
133
|
});
|
|
134
|
+
}
|
|
135
|
+
export function createCtxshotMcpServer(cwd) {
|
|
136
|
+
const server = new McpServer({
|
|
137
|
+
name: "ctxshot-mcp",
|
|
138
|
+
version: VERSION,
|
|
139
|
+
});
|
|
140
|
+
registerCtxshotTools(server, cwd);
|
|
138
141
|
return server;
|
|
139
142
|
}
|
package/package.json
CHANGED
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ctxshot-mcp",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "MCP server — lightweight daily project brief for Claude Code & Cursor (pack_context, session_brief, context_stats).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"ctxshot-mcp": "dist/index.js"
|
|
8
8
|
},
|
|
9
|
+
"exports": {
|
|
10
|
+
".": "./dist/index.js",
|
|
11
|
+
"./register": "./dist/server.js"
|
|
12
|
+
},
|
|
9
13
|
"files": [
|
|
10
14
|
"dist",
|
|
11
15
|
"README.md",
|
|
@@ -17,7 +21,8 @@
|
|
|
17
21
|
"start": "node dist/index.js",
|
|
18
22
|
"inspect": "npx @modelcontextprotocol/inspector tsx src/index.ts",
|
|
19
23
|
"prepublishOnly": "npm run build && npm run test:smoke",
|
|
20
|
-
"test:smoke": "node scripts/ci-smoke.mjs"
|
|
24
|
+
"test:smoke": "node scripts/ci-smoke.mjs",
|
|
25
|
+
"test:mcp": "node scripts/test-mcp-client.mjs"
|
|
21
26
|
},
|
|
22
27
|
"keywords": [
|
|
23
28
|
"mcp",
|
|
@@ -33,15 +38,14 @@
|
|
|
33
38
|
},
|
|
34
39
|
"repository": {
|
|
35
40
|
"type": "git",
|
|
36
|
-
"url": "git+https://github.com/G12789/ctxshot.git"
|
|
37
|
-
"directory": "packages/mcp"
|
|
41
|
+
"url": "git+https://github.com/G12789/ctxshot-mcp.git"
|
|
38
42
|
},
|
|
39
43
|
"publishConfig": {
|
|
40
44
|
"access": "public"
|
|
41
45
|
},
|
|
42
46
|
"dependencies": {
|
|
43
47
|
"@modelcontextprotocol/sdk": "^1.12.0",
|
|
44
|
-
"ctxshot": "^0.2.
|
|
48
|
+
"ctxshot": "^0.2.2",
|
|
45
49
|
"zod": "^3.23.8"
|
|
46
50
|
},
|
|
47
51
|
"devDependencies": {
|