Skip to main content
Glama
G12789

ctxshot-mcp

by G12789
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

ctxshot-mcp

⭐ 推荐： npx ship-skills init（已登录 gh 会自动支持作者）

CI npm MCP node license

给 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 不替代

Related MCP server: cctx-mcp

实测（同仓库 benchmark）

基于 ctxshot 自身仓库：

工具

耗时

估 token

ctxshot / session_brief

356ms

423

README 手贴

<1ms

685

repomix --stdout

3.6s

7,023

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

Available Tools

3 tools
context_statsContext pack statisticsA

Estimate token cost of a context pack without returning full markdown. Useful before/after comparisons.

ParametersJSON Schema
NameRequiredDescriptionDefault
compactNo
diffNo
rootNo

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It indicates a non-destructive read ('estimate token cost') but fails to disclose return format, side effects, or auth needs. The added context is minimal beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences efficiently convey purpose and usage guidance. Front-loaded: first sentence states the core action, second adds context. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 3 undocumented parameters and no output schema or annotations, the description is insufficient. It does not clarify parameter effects, return value, or tie to sibling tools beyond implied differentiation. More detail is needed for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% with no parameter descriptions. The description offers no explanation of 'compact,' 'diff,' or 'root,' leaving agents to guess their meaning. It fails to compensate for the schema's lack of documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool estimates token cost of a context pack, without returning full markdown. It distinguishes itself from siblings: pack_context likely returns full markdown, session_brief provides a session summary. The verb 'estimate' specifies the operation type.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description suggests usefulness for before/after comparisons, indicating when to use. It implicitly differentiates from pack_context by noting it does not return full markdown. However, it lacks explicit exclusions or alternative suggestions beyond the sibling context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pack_contextPack project contextA

Generate a lightweight markdown project brief (~200-2000 tokens): tree, npm scripts, README/AGENTS excerpt, optional git diff. Use at session start instead of reading the whole repo or running Repomix.

ParametersJSON Schema
NameRequiredDescriptionDefault
compactNoShorter tree and truncated README (default true)
diffNoInclude recent commits and uncommitted diff (default false)
depthNoDirectory tree depth
maxEntriesNoMax tree entries
rootNoProject root path (default: server cwd)

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses the output size range (200-2000 tokens) and contents, implying a read-only operation. Missing details include potential side effects (none expected), auth needs, and whether it caches or reads files beyond what's listed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the core output and purpose. Every sentence adds value with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the description covers the main use case and output. With 5 optional parameters and no output schema, it provides enough context for an agent. Minor gaps exist (e.g., no mention of whether it modifies any state), but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning beyond the schema; parameters are already well-documented in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a lightweight markdown project brief with specified contents (tree, npm scripts, README/AGENTS excerpt, optional git diff). It distinguishes from general repo reading or Repomix but does not explicitly differentiate from sibling tools context_stats and session_brief.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises using the tool 'at session start instead of reading the whole repo or running Repomix,' providing clear context for when to use it. It does not, however, state when not to use it or compare directly to sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_briefDaily session briefA

Pack compact context with git diff and write to .ai/context.md in the project root. Call when starting a new AI coding session or switching tasks.

ParametersJSON Schema
NameRequiredDescriptionDefault
rootNoProject root (default: server cwd)
outNoOutput file relative to root (default .ai/context.md)

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses that it writes to a file using git diff, but does not mention whether it overwrites, if a git repo is required, or any side effects. Lacks important safety details for a write operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no extraneous information. Front-loaded with the action and purpose, and ends with usage guidance. Highly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and two optional parameters, the description covers the basic purpose and usage context. However, it omits details like whether the file is overwritten, the format of the packed context, and dependencies (e.g., git). Marginally adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. Description does not add much beyond the schema's parameter descriptions, but does hint at defaults (e.g., output file relative to root). Not enough to raise the score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it packs compact context with git diff and writes to .ai/context.md. Differentiates from sibling tools by specifying a specific output file and use of git diff, though does not explicitly contrast with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to call: starting a new AI coding session or switching tasks. Does not provide when-not-to-use or alternative tools, but the given context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedcontext_stats
    • First observedpack_context
    • First observedsession_brief
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: context_stats estimates token cost, pack_context generates a project brief, and session_brief writes context to a file. No overlap or ambiguity.

Naming Consistency4/5

All names use lowercase underscores and are descriptive. However, pack_context is verb-noun while context_stats and session_brief are noun-noun, showing minor inconsistency.

Tool Count4/5

With only 3 tools, the server is tightly scoped for context management. The number is slightly low but covers the essential operations, making it appropriate.

Completeness4/5

The tools cover the main use cases: estimating cost, generating a brief, and writing session context. Minor gaps like viewing or deleting context could exist, but the core workflow is complete.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Plus

    David3u
    F
    license
    Not graded
    quality
    D
    maintenance
    A lightweight MCP server that enhances AI agents with tools for codebase analysis, task delegation to sub-agents, multi-agent coordination through chatrooms, and project todo management.
    -

  • cctx-mcp

    nikondrat
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that provides structure-aware code analysis (symbol trees, dependencies, docs) to reduce AI agent token consumption by up to 99%, along with Git commit intelligence.
    MIT

  • rlm-tools

    stefanoshea
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that provides a persistent sandbox for AI coding agents to explore codebases server-side, returning only compact summaries to reduce context consumption.
    3
    8
    MIT

  • contextsliver

    DevMuneeb
    A
    license
    Not graded
    quality
    A
    maintenance
    An MCP server that indexes codebases into a local graph and provides on-demand context retrieval for AI coding agents, reducing token usage by tracking session history and delivering only relevant code subgraphs.
    7 npm
    MIT