ctxfw

Name: ctxfw
Author: heuristicolab

本地服务

github.com/heuristicolab安全7今天更新

代码仓库

关于 ctxfw

ctxfw 是面向编码 Agent 的本地上下文防火墙和 MCP 网关。它将外围代码裁剪为接口级上下文，检查输入是否满足指定架构约束，并防御间接提示词注入；标准模式下在本机运行。

主要功能

01基于 AST 裁剪外围代码
02确定性输入约束检查
03SARA 提示词注入防御
04本地 MCP 工具边界治理
05自动配置 MCP 客户端

适用场景

01减少编码任务的依赖上下文
02在接收前筛查架构说明
03过滤 MCP 边界处的间接提示词注入
04为支持的编码环境配置 MCP

MCP 相关

ctxfw 作为 MCP 网关，在本地检查工具边界，并支持为编码客户端配置 MCP。其代理还为不原生支持 MCP 的工具提供本地网关。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "heuristicolab-ctxfw": {
      "command": "uvx",
      "args": [
        "ctxfw"
      ]
    }
  }
}

启动命令uvx ctxfw

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypictxfw4.1.1stdio

工具

收录的工具列表 · 更新于 3 天前

参数	类型	必填	说明
path	string	是	源文件的绝对路径或相对路径
depth	string	否	裁剪深度：'full'、'interface' 或 'nominal'
language	string	否	编程语言（python、typescript、javascript、go、java）
strip_docs	boolean	否	是否完全剥离文档字符串

详细介绍

CTXFW // 上下文防火墙

面向 MCP 编码 Agent 的 AI Agent 治理、提示词注入防火墙（`SARA`）与内存 AST 上下文压缩器

在概率性大模型幻觉、间接提示词注入与生产基础设施之间建立确定性的零外发边界。

安装 • 基准测试 • CTXFW 与云 WAF 的对比 • 诊断 • 架构 • 企业治理

CTXFW v4.1.1 实时终端演示 — SARA 提示词注入闸门（0.38ms）、AST 上下文裁剪器（-66.1%）与 M2M 主权保险库

执行摘要

自主编码 Agent（Claude、Gemini、Cursor、Antigravity）会消耗大量上下文窗口，其中充斥着臃肿的外围依赖，导致令牌耗尽、上下文漂移和安全性下降。

CTXFW 是一款开源核心上下文防火墙和模型上下文协议（MCP）守门器。它结合了内存多语言 AST 裁剪器与确定性公理式输入筛选器：

压缩外围代码（令牌减少 72.4%）：将距离为 1 和距离为 2 及以上的模块实现替换为简洁的接口签名、类型定义和函数桩。
维护公理完整性（ACI $\ge$ 0.9000）：拒绝缺乏依据或不完善的架构说明，尤其是缺少负不变量（$N \ge 5$）、有界变量域、确定性状态机或形式化错误分类的说明。
零遥测外发：标准运行模式下保证在本地执行，不会通过网络泄露遥测数据。

AST 裁剪基准测试

CTXFW 使用原生多语言语法，直接在语法树层运行：

基准维度	原始上下文摄取	CTXFW 拓扑压缩器	性能提升 / 影响
令牌消耗	100%（原始文件）	27.6%（接口桩）	消除 72.4% 的冗余
引擎压缩开销	—	原生内存解析器	< 5.0 ms
热缓存命中开销	—	SQLite WAL 语义缓存	< 0.8 ms
Stdio 遥测外发	未净化的 stdout	纯隔离 JSON-RPC	零外发（100% 隔离）
公理验证延迟	—	筛选器评估	< 12.0 ms
CI/CD 提交前延迟	—	无头 git 哨兵	< 85.0 ms

实证案例研究：`ctxfw/cli.py` 核心依赖图

通过运行 ctxfw.resolve_context_bundle，针对 16 个内部依赖生成的上下文缩减实测指标：

维度	原始上下文摄入量	CTXFW 拓扑筛选	性能变化
上下文总大小	49,096 tokens	20,014 tokens	净缩减 59.5%
消除的 tokens	0 tokens	29,222 tokens	剪除了 29,222 个冗余 tokens
传递依赖（$D_{2+}$）	7,275 tokens	4,763 tokens	最高缩减 91.9%
FinOps 成本影响	基础成本	每条提示词减少 $0.0877 USD	每 1K 次调用约节省 $87.70 USD
AST 压缩延迟	—	1,407.96 ms	内存中的 Tree-Sitter 解析
证明完整性	无	SHA-256 封存	严格保留接口

拓扑层级细分：

$D_0$ 目标（ctxfw/cli.py）：保留 100% 的完整实现。
$D_1$ 直接依赖（例如 gatekeeper.py、mcp.py）：将实现截断为带类型的存根（...）。节省 tokens：73% – 86%。
$D_2$ 传递依赖（例如 polyglot.py）：精简的带类型接口签名。节省 tokens：91.9%。
$D_3$ 环境映射与清单：确定性的零语法扁平符号目录（$\le 1,000$ tokens），映射整个深层边界（$\text{depth} \in [0, 3]$）。无需污染上下文，即可即时提供导入依据，确保复杂重构（AXIOM-17 至 AXIOM-21）的首次运行成功率达到 100%。

实证验证三部曲（多代码库破坏性 A/B 测试）

在远程 Linux 环境（root@isolated-runner、Ubuntu 24.04 LTS、临时 Docker 容器）中，在无网络条件下针对主要生产代码库进行了审计。完整取证报告：docs/benchmarks/TRILOGY_EMPIRICAL_BENCHMARK.md。

目标代码库	架构类型	活跃焦点 $D_0$	外围边界 $D_1$	原始上下文（$D_0 + D_1$）	剪枝后上下文（$D_0 + D_1^*$）	$D_1$ 边界节省量	上下文总节省量	语法 AST 检查	延迟 / 吞吐量
`zulip/zulip`	耦合式 Django 单体架构	`users.py` (12.9k tok)	`realms.py`、`clients.py`、`prereg_users.py` (16.8k tok)	29,689	22,481	-42.96% (接口) -78.20% (名义值)	-24.28% (接口) -44.20% (名义值)	`100% PASS`	44.1 ms ~380k tok/s
`PostHog/posthog`	现代 COSS / 数据操作系统	`team.py` (14.3k tok)	`organization.py`、`user.py`、`project.py` (20.6k tok)	34,894	22,637	-59.53% (接口)	-35.13% (接口)	`100% PASS`	50.2 ms ~410k tok/s
`apache/airflow`	异步编排单体代码库	`dag.py` (9.4k tok)	`baseoperator.py`、`taskinstance.py`、`dagrun.py` (60.4k tok)	69,861	29,433	-66.90% (接口) -90.26% (名义值)	-57.87% (接口) -78.08% (名义值)	`100% PASS`	138.2 ms 437,351 tok/s

实证要点：

压缩率随规模提升（$43% \to 60% \to 67%$）：规模更大的真实代码库可实现更高的边界缩减率（Airflow 的 D1 从 $60.4\text{k}$ 降至 $20.0\text{k}$ tokens，净消除 40,428 个冗余 tokens）。
吞吐量与速度：以 437,351 tokens/秒 的速度切分 AST，处理延迟 < 140 ms。
焦点零退化（AXIOM-3）：对用户正在编辑的活动文件（$D_0$）实现 100% 逐字节保留。
零 Stdio 污染（AXIOM-1）：纯隔离 JSON-RPC stdio，不泄漏调试日志（leak_bytes == 0）。

AI Agent 治理与提示词注入防御：CTXFW 与云运行时 WAF

云运行时防火墙（Lakera Guard、Palo Alto Networks Prisma AIRS、Protect AI Guardian、Cloudflare Firewall for AI）会在云 API 边缘检查 HTTP 流量，而 CTXFW 会在上下文离开开发者机器或 CI 运行器之前，在本地通过 预摄入代码、AST 与 MCP 工具边界（Zero-Egress） 提供安全防护。完整的对比报告：docs/benchmarks/SECURITY_VS_CLOUD_WAFS.md。

能力 / 安全维度	CTXFW（`Context Firewall v4.1.0`）	Lakera Guard（`Check Point`）	Palo Alto Prisma AIRS	Protect AI / Cloudflare AI WAF
执行边界	摄入前的本地 AST 与 MCP 工具 `stdio` / 代理	云 HTTP 提示词 API	云网络与运行时 API	云边缘 / ML 推理代理
代码与数据主权	100% 零出站（隔离环境中的本地 RAM 与 SQLite WAL）	需要向云 API 发送出站流量	云端 / 设备检查	云代理出站流量
间接提示词注入（`MCP` / 工具）	确定性 `ctxfw.sara`：100.0% 召回率 / 0.0% FPR（隔离 `<system>`、`[INST]`、Trojan-Source `U+202E`）	概率型 ML 分类器	运行时网络策略	边缘 WAF / 启发式分类器
FinOps 令牌成本削减	剪除 42.96% – 90.26% 的 $D_1$ AST 膨胀（约每 1K 次调用节省 $87.70）	节省 0% 令牌	节省 0% 令牌	节省 0% 令牌
焦点代码信号损失（$D_0$）	损失 0.00%（`AXIOM-3`：100% 逐字节保留 $D_0$）	不适用（直通）	不适用（直通）	不适用（直通）
检查延迟（P50 / P95）	0.33 ms P50 / 1.72 ms P95（SARA）· < 0.8 ms（热 WAL 缓存）	`35 ms – 120 ms`（网络 RTT）	`25 ms – 90 ms`	`15 ms – 150 ms`
部署复杂度	1 条命令（< 10s）：`pipx install ctxfw && ctxfw init`	SDK 封装 + API 密钥	TLS 解密 + 路由	DNS / 代理路由

在本地运行可复现的 24 向量 OWASP AISVS C02-01 与 arXiv:2510.05244v2 间接提示词注入及 Trojan-Source 基准测试，全程无网络出站流量：

python benchmarks/run_sara_security_benchmark.py

安装与多界面配置

1. PyPI 安装

pip install --upgrade ctxfw
# or via pipx for dedicated binary isolation:
pipx install ctxfw

2. 多界面 MCP 自动配置（v4.1.0）

运行 ctxfw init 或专用安装命令 ctxfw install --claude，即可自动发现已安装的编码界面，并以幂等方式注入配置，无需手动操作：

# Targeted Claude Code CLI & Claude Desktop auto-installation:
ctxfw install --claude

# Or full multi-surface discovery (Claude, Cursor, Windsurf):
ctxfw init

自动检测的界面（三界面架构）：

Claude Code CLI：直接注入 ~/.claude.json。
Claude Desktop：动态跨平台检测：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%/Claude/claude_desktop_config.json
- Linux / POSIX：~/.config/Claude/claude_desktop_config.json
Cursor IDE：在工作区范围内注入 .cursor/mcp.json。
Windsurf IDE：当存在 .codeium 目录标识时，注入 ~/.codeium/windsurf/mcp_config.json。

不可违背的安全与可靠性不变量：

原子备份快照（.bak.<timestamp>）：修改任何现有配置文件前，都会创建带时间戳的不可变备份。
非破坏性合并：100% 保留现有第三方 MCP 服务、顶层设置和自定义键。
零失败执行：动态将解释器解析为 sys.executable，并使用 ["-m", "ctxfw.mcp"]（若通过 PyInstaller 冻结，则使用规范的绝对二进制路径），彻底消除环境中的 $PATH 与虚拟环境解析失败问题。
3 倍幂等性：多次运行不会造成配置漂移，也不会产生重复键。

3. 零 MCP 互操作网关（Aider、OpenCode、Continue、CLI）

适用于缺少原生 Model Context Protocol 支持的 AI 开发工具和终端 Agent：

# 1. Start the zero-egress local proxy server:
ctxfw proxy --port 8765

# 2. Point your tool's Anthropic or OpenAI endpoint to localhost:
export ANTHROPIC_BASE_URL="http://localhost:8765/v1"
export OPENAI_BASE_URL="http://localhost:8765/v1"

4. 已验证的注册表、MCP 生态目录与 Agent 技能

CTXFW 已通过独立审计，并在官方 Glama MCP 注册表（TDQS 4.5/5.0 · Security 100/100）和 技能目录（120 项静态安全模式，Security: A 100/100）中获评 A级，并已收录于 7 个 MCP 生态目录：

Glama.ai MCP 目录（获评 A 级认证）：glama.ai/mcp/servers/heuristicolab/ctxfw
MCPMarket 目录：mcpmarket.com/server/ctxfw
GTMStacker 工具注册表：gtmstacker.com/registry/tool/ctxfw/index.json
VibeLeaderboard：vibeleaderboard.ai/app/e109eca4-858b-41ed-816b-d932f45a7677
官方 Anthropic MCP 注册表（server.json）：registry.modelcontextprotocol.io
PulseMCP 目录：pulsemcp.com/servers?q=ctxfw

将经过验证的 Claude Code / Agent 技能直接安装到 .claude/skills/：

npx -y skills add heuristicolab/ctxfw --skill context-firewall --agent claude-code
npx -y skills add heuristicolab/ctxfw --skill axiom-sieve --agent claude-code
npx -y skills add heuristicolab/ctxfw --skill eval-benchmark --agent claude-code
npx -y skills add heuristicolab/ctxfw --skill precommit-sentry --agent claude-code

可在 Glama 和技能目录中直接查看工具、架构以及实时诊断遥测数据。

系统诊断

只需运行一条命令，即可验证本地环境就绪状态、stdio 隔离纯净度、SQLite WAL 并发能力以及 Tree-Sitter 语法：

ctxfw doctor

========================================================================
  CTXFW DOCTOR // HIGH-ASSURANCE HEALTH & ISOLATION DIAGNOSTIC
========================================================================
[PASS]   Python Package & sys.path        ctxfw v4.1.0 loaded cleanly.
[PASS]   MCP stdio Stream Isolation       100% pure JSON-RPC on stdout. Diagnostic logs isolated to stderr.
[PASS]   Global CLI Executable (PATH)     Binary 'ctxfw' found in PATH.
[PASS]   Axiomatic Sieve Engine           Evaluation verified (ACI: 1.0000, Invariants: 5).
[PASS]   SQLite WAL Cache & Concurrency   Journal mode: WAL, Busy timeout: 5000ms.
[PASS]   Polyglot Tree-Sitter Grammars    Initialized language parsers (typescript, go, java).
[PASS]   TraceKit Ledger Audit            Chain status: INTACT (1275 blocks).
[PASS]   Sovereign Pentad WAL Ledgers     SARA scans: 331 | TokenCast turns: 1 (FinOps rows: 3872) | Rules: 1056 | SWE-Gate: 13.
------------------------------------------------------------------------
Overall Verdict:            [HEALTHY] [ATTESTED] Perimeter defense operational.
========================================================================
CTXFW // 72.4% AST Bloat Eliminated. Zero Telemetry Egress.
Export FinOps ROI: 'ctxfw report --share' | CI Merge Gate: 'ctxfw gate'
Team Squad ($199/mo flat up to 15 devs): https://ctxfw.heuristicolab.com/pricing/
========================================================================

架构

CTXFW 通过严格的确定性边界，将概率型 Agent 代码与核心代码库隔离开来：

PROBABILISTIC DOMAIN                      DETERMINISTIC PERIMETER
┌───────────────────────┐                  ┌────────────────────────────────────────┐
│  Autonomous AI Agent  │                  │             CTXFW ENGINE               │
│  (Claude / Gemini /   │                  │                                        │
│   Cursor / Antigravity│                  │  ┌──────────────────────────────────┐  │
└───────────┬───────────┘                  │  │   Polyglot AST Topological Engine│  │
            │                              │  │  - Python (ast)                  │  │
            │  Target Context / Brief      │  │  - TypeScript / Go / Java (CST)  │  │
            ▼                              │  │  - Multi-Depth Interface Stubs   │  │
┌───────────────────────┐                  │  └────────────────┬─────────────────┘  │
│ MCP Stdio Interceptor ├─────────────────►│                   │                    │
└───────────────────────┘                  │  ┌────────────────┴─────────────────┐  │
                                           │  │  SQLite WAL High-Concurrency     │  │
                                           │  │  Semantic Cache (<5ms warm hit)  │  │
                                           │  └────────────────┬─────────────────┘  │
                                           │                   ▼                    │
                                           │         [ ACI >= 0.9000? ]             │
                                           │          /              \              │
                                           │       YES                NO            │
                                           │        │                  │            │
                                           │        ▼                  ▼            │
                                           │ ┌──────────────┐   ┌─────────────────┐ │
                                           │ │ VERIFIED     │   │ QUARANTINED     │ │
                                           │ │ SHA-256 Seal │   │ Execution Halt  │ │
                                           │ └──────┬───────┘   └────────┬────────┘ │
                                           └────────┼────────────────────┼──────────┘
                                                    │                    │
                                                    ▼                    ▼
                                           [ Code Generation ]   [ Forensic Report ]
                                           [ & Git Permitted ]   [ Pre-Commit Abort]

核心子系统（v4.1.0 Sovereign Pentad）：

多语言 Tree-Sitter 剪枝器与 $D_3$ 环境制图：
- 为 Python、TypeScript/JavaScript、Go 和 Java 编译拓扑依赖树（$D_0$ 完整、$D_1$ 接口、$D_2$ 名义、$D_3$ 扁平符号目录 $\le 1,000$ 个 token）。
TraceKit 加密账本（ctxfw.audit）：
- 仅追加的 283 字节规范 SHA-256 哈希链审计账本（tracekit.db），可通过 ctxfw trace verify 验证篡改锁存状态。
TokenCast 整数预测器与断路器（ctxfw.budget）：
- 不使用浮点数的整数轨迹预测器和响应式断路器（CLOSED $\to$ TRIPPED / FORCE_D3_PRUNING $\to$ HALTED / EMERGENCY_HALT）。
规范规则编译器与强制执行器（ctxfw.rules）：
- 将 .cursorrules 和 CLAUDE.md 中的禁止性指令编译为确定性的 AST/路径/命令/导入防护规则，并进行 3 轮迭代式路径遍历规范化。
SARA Agent 诱导防火墙（ctxfw.sara）：
- 检查不可信工具观察结果，识别间接提示词注入、角色覆盖（<system>、[INST]）和 Trojan-Source 双向文本转义（ALLOW、STRIP_COMMANDS、QUARANTINE_TOOL）。
SWE-Gate CI 验证器（ctxfw.swegate）与审计账本检索（query_audit_ledger）：
- 通过 evaluate_patch 执行确定性的统一差异和架构回归验证，强制检查圈复杂度增量界限、禁止的模块导入和 # type: ignore 禁令；同时通过 query_audit_ledger 对 SweGateStore（EVL-...）和 TraceKitStore（SES-...）进行只读取证检查。

零接触配置

将边界规则、MCP 服务声明和 pre-commit 哨兵注入你的工作区：

全局 IDE 集成

ctxfw init --global

自动配置 Google Antigravity、Cursor 和 Claude Desktop。

仓库 Pre-Commit 哨兵

ctxfw init --repo .

部署 .git/hooks/pre-commit，防止提交缺少经认证规格说明的未认证代码。

企业治理与 CI/CD 门禁（`v4.1.0`）

适用于需要整合 FinOps 并自动治理 Pull Request 的工程团队：

个人开发者 FinOps 与 LiveBench 2.0 套利（免费 / Apache 2.0）：
```
ctxfw report --share
ctxfw report --export-json ./my-ledger.json
```

团队治理与 SWE-Gate CI（$199 USD/month Flat Squad — 最多 15 名开发者和 5 个 CI/CD 仓库，含 7 天试用）：

export CTXFW_LICENSE_KEY="CTXFW-TEAM-PRO-..."
ctxfw license status
ctxfw gate --diff-file pr.patch --github-summary
ctxfw report --team-merge ./team-ledgers/

官方 GitHub Action（action.yml）：

- name: CTXFW SWE-Gate & FinOps PR Audit
  uses: heuristicolab/ctxfw@v4
  with:
    license-key: ${{ secrets.CTXFW_LICENSE_KEY }}
    diff-range: "origin/main...HEAD"

控制平面、7 天试用与团队授权： https://ctxfw.heuristicolab.com/pricing/

_{由 HEURISTICO LAB 设计}
_{高保障系统组}

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。