Skip to main content
Glama
SuperMarioYL

ctxfeed

by SuperMarioYL
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

English | 简体中文

按 token 预算组织仓库文件，跟踪内容变化，并通过 CLI 或 MCP 提供项目上下文。

v0.8.0 · Python 3.12+ · MIT

Website · Demo record

为什么使用

把很多文件交给模型之前，先要知道哪些文件会被纳入、顺序是什么、相对上次修改了哪些内容。ctxfeed 用 ShardPlan 表达这些选择，保留稳定前缀、正文和变化集合，方便检查一次查询实际组织了什么。

Related MCP server: knitbrain

架构

ingest 扫描并计数文件，shard 按预算和稳定顺序构建计划，CachePlan 将文件哈希写到仓库自己的 SQLite 缓存。CLI 和 MCP 共用该路径，模型适配器在查询时发送组装后的上下文。delta 是本地变化账本，不代表仅发送变化内容，也不是服务端 prefix cache 遥测。

源码入口：src/ctxfeed/cli.py · src/ctxfeed/cache_plan.py · src/ctxfeed/ingest.py · src/ctxfeed/shard.py · src/ctxfeed/mcp_server.py · src/ctxfeed/models/glm.py · src/ctxfeed/models/deepseek.py

安装

需要 Python 3.12+ 与 uv。演示只构建本地计划，无需 API key；首次 tokenizer 使用可能需要缓存其编码文件。

git clone https://github.com/SuperMarioYL/ctxfeed.git
cd ctxfeed
uv venv --python 3.12
uv pip install --python .venv/bin/python -e .

快速开始

完整脚本创建两份临时文件，连续构建三次计划。结果中的 cached_fraction 是本地文件哈希复用比例，不是模型缓存命中或实测费用。

.venv/bin/python examples/presentation-demo.py

完整输入与执行步骤见上方命令及 Demo 记录。

使用

.venv/bin/ctxfeed init --repo .
.venv/bin/ctxfeed add ./src/ctxfeed/cli.py
.venv/bin/ctxfeed cost --repo .
.venv/bin/ctxfeed mcp --repo .

init 在没有对应模型密钥时使用 dry-run；设置密钥后该命令可能调用服务。MCP 客户端应将 command 配置为本仓库 .venv/bin/ctxfeed 的绝对路径，args 为 ["mcp", "--repo", "/absolute/repo"]。

实际 Demo

查看三次计划

首次、未修改、修改一次的变化集合分别是 2、0、1。

$ .venv/bin/python examples/presentation-demo.py
[
  {
    "stage": "first",
    "files": 2,
    "delta_hashes": 2,
    "cached_fraction": 0.0,
    "stable_prefix": [
      "README.md"
    ]
  },
  {
    "stage": "unchanged",
    "files": 2,
    "delta_hashes": 0,
    "cached_fraction": 1.0,
    "stable_prefix": [
      "README.md"
    ]
  },
  {
    "stage": "edited",
    "files": 2,
    "delta_hashes": 1,
    "cached_fraction": 0.5,
    "stable_prefix": [
      "README.md"
    ]
  }
]

能力与接入

CLI 提供 init、add、cost、mcp。MCP 的 list_files 展示文件与缓存标记，query_repo 提交问题，cost_delta 按仓库内的静态费率估算。GLM 与 DeepSeek 是可选适配器，不会自动完成模型供应商间的运行时故障切换。

配置

--model 优先于 CTXFEED_MODEL，可选 glm 或 deepseek。GLM 读取 ZHIPU_API_KEY/GLM_API_KEY，DeepSeek 读取 DEEPSEEK_API_KEY。IngestConfig 管理 window、headroom、max_file_bytes 和 cache_db；默认缓存为 .ctxfeed/cache.db。供应商模型名、窗口和费率是适配器中的配置假设，应按实际账户核对。

路线图与范围

已实现预算计划、增量账本、两个适配器与 MCP。后续扩展应以真实仓库问答质量、服务端缓存遥测和供应商配置验证为依据。

  • 文件可能因忽略规则、大小或预算被跳过；不能保证任意仓库完整进入上下文。

  • dry-run 答案是内置模拟结果，cost 是静态估算；本示例没有调用模型。

Terminal recording · Recording script

许可证

MIT

Available Tools

3 tools
cost_deltaC

Per-query token cost vs Claude Opus at equal repo size.

The m3 "star-able" number: GLM-5.2 + DeepSeek V4 vs Opus, plus files-accepted vs ChatGPT's 40-file cap. Read-only (v0.2): does not mutate the cache store.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoNo
modelNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.4/5.0
Behavior3/5

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

With no annotations, the description carries the full burden, and it does disclose crucial safety context: 'Read-only (v0.2): does not mutate the cache store.' That is a genuinely useful read-only declaration. However, it omits what the comparison output contains, any rate limits, or how cost is computed, so the behavioral picture is partial.

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

Conciseness2/5

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

The prose is fragmented into odd line breaks and phrasing ('The m3 "star-able" number', 'files-accepted vs ChatGPT's 40-file cap') that reads as marketing rather than specification. The read-only constraint, the most actionable fact, is buried at the end instead of front-loaded.

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?

For a two-parameter comparison tool with no schema documentation, no annotations, and no parameter coverage, the description must compensate and does not. It omits what 'repo' and 'model' expect, what triggers the cost computation, and how results are shaped. An output schema exists, so return values need not be explained, but the input contract is left entirely unresolved.

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

Parameters2/5

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

Schema description coverage is 0% and neither parameter is documented. The description mentions 'repo' only obliquely via 'equal repo size' and never explains the 'model' parameter or its default empty-string behavior. Both parameters are effectively undocumented, so an agent cannot know what to pass.

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

Purpose3/5

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

The description states the tool compares per-query token cost against Claude Opus at equal repo size, which gives a resource and a comparison dimension. However, it's cluttered with marketing language ('m3 star-able number') and tangential claims (file caps), so the core purpose is muddled. It is distinguishable from query_repo and list_files, but only loosely.

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

Usage Guidelines2/5

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

There is no explicit statement of when to use this tool versus query_repo or list_files, nor any precondition (e.g., must a repo already be indexed?). Usage is only implied by 'per-query' and 'equal repo size'. No exclusions or alternatives are named.

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

list_filesB

List the ingestible files ctxfeed would serve in-context.

One line per file: path · tokens · layer · cached?. Useful for an agent to see what's about to be served before querying.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoNo
modelNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses the output format ('One line per file: path · tokens · layer · cached?') and the purpose, but lacks details about permissions, rate limits, or whether it is a read-only 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?

The description is three short sentences, front-loaded with the core purpose and immediately followed by output format and usage hint. Every sentence earns its place.

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?

While an output schema exists and reduces the need to explain return values, the description does not explain the repo or model parameters at all, and with no annotations, it leaves significant gaps for an agent trying to invoke the tool 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 description coverage is 0% for two parameters (repo, model), and the description does not mention or explain either parameter. The description fails to compensate for the complete lack of parameter documentation.

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 states a specific verb+resource: 'List the ingestible files ctxfeed would serve in-context.' It is clear what the tool does, though it does not explicitly name or differentiate from sibling tools like query_repo or cost_delta.

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?

It provides clear usage context: 'Useful for an agent to see what's about to be served before querying.' This implies when to use it relative to querying, but does not explicitly name alternatives or when-not to use.

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

query_repoA

Answer question using the whole repo's files in-context.

Ingests the repo's ingestible files into the selected model's context window (cache-aware ShardPlan ordering; GLM-5.2 1M by default, DeepSeek V4 128k via model="deepseek") and asks the question in a single model round-trip. Returns the answer prefixed with a one-line context summary (files + tokens). Transient API errors (429/5xx) are retried with backoff; a terminal failure returns a structured error (v0.2).

Args: question: the repo-wide question (e.g. "where is the auth middleware handled?"). repo: optional repo root override (defaults to the --repo arg or CTXFEED_REPO_ROOT env var). model: optional model override ("glm" | "deepseek"; defaults to the server's --model / CTXFEED_MODEL).

ParametersJSON Schema
NameRequiredDescriptionDefault
repoNo
modelNo
questionYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations, the description carries the full disclosure burden and does so well: it explains the ingestion model (ShardPlan ordering, model context windows), the single round-trip behavior, the retry policy on 429/5xx, and the structured terminal-error shape. These are exactly the operational traits an agent needs beyond a bare schema.

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

Conciseness4/5

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

Front-loaded with the core purpose, then behavior, then args, which is a sensible ordering. The parenthetical detail around model IDs and version tags is dense but each clause carries real information; slightly heavy for a three-parameter tool.

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

Completeness5/5

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

Given no annotations, 0% schema coverage, and an existing output schema, the description supplies everything an agent needs: purpose, scope, model selection, retry/error semantics, and arg defaults. Nothing required for correct invocation is missing.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate and it fully does: it documents question (with an example), repo (defaults to --repo arg or env var), and model (enum-like 'glm'|'deepseek' with default resolution). All three parameters gain meaning not present 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?

States a specific verb (answer question) over a clearly-scoped resource (the whole repo's files in-context), which cleanly separates it from siblings like list_files and cost_delta. The core action and scope are unambiguous, though it never explicitly names the siblings it is not.

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 'whole repo's files in-context' framing makes the use case (repo-wide questions) clear, reinforced by the example question. It does not name alternatives or state when-not to use it, so no exclusions are provided.

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.8.0
    • First observedcost_delta
    • First observedlist_files
    • First observedquery_repo
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

B3.4/5.0

Scored across 3 tools

Disambiguation5/5

query_repo, list_files, and cost_delta each perform a clearly distinct action: answering a question, inventorying served files, and reporting cost metrics. There is no overlap, so an agent can easily select the right tool.

Naming Consistency4/5

All names use snake_case consistently and are readable. However, query_repo and list_files follow a verb_noun pattern while cost_delta is a noun phrase, which is a minor deviation from a fully predictable convention.

Tool Count4/5

Three tools is a tight but reasonable scope for a read-only repo-context server. Each tool has a distinct role, though cost_delta is more auxiliary than the core query/list functions, making the set feel slightly minimal rather than perfectly balanced.

Completeness4/5

The surface covers listing ingestible files, querying the whole repo in-context, and comparing per-query cost. Gaps exist for targeted file queries, filtering, or partial-repo selection, but the whole-repo query and file listing let agents work around these limitations.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • parecode

    BasilSkyWalk
    A
    license
    A
    quality
    C
    maintenance
    An MCP server giving coding agents context-window-aware code search and safe, atomic multi-file edits — built to cut token usage on large codebases without sacrificing correctness.
    3
    132 npm
    5
    MIT

  • knitbrain

    PDgit12
    A
    license
    A
    quality
    A
    maintenance
    Local-first MCP server that gives any AI coding agent per-project memory, workflow intelligence, and always-on, lossless token & context optimization.
    37
    12 npm
    5
    MIT

  • reflens

    cybertronayush
    A
    license
    A
    quality
    B
    maintenance
    An MCP server that indexes reference repositories and provides tools for AI coding agents to retrieve lossless code context, enabling reasoning over codebases larger than the agent's context window.
    8
    2
    Apache 2.0

  • 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.
    14 npm
    MIT