Skip to main content
Glama

English | 简体中文

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

v0.9.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.

Inputs: repo, model. Returns: result

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.

Inputs: repo, model. Returns: result

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).

Inputs: question (required), repo, model. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
      59 npm
      5
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Local-first MCP server that gives any AI coding agent per-project memory, workflow intelligence, and always-on, lossless token & context optimization.
      37
      31 npm
      6
      MIT
    • A
      license
      A
      quality
      D
      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
    • A
      license
      Not graded
      quality
      C
      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.
      9 npm
      MIT