contextweaver
MCP gateway: bounded tool shortlists + artifact-backed result firewall. Deterministic, no model.
Open source Open in the app JSON README (API)
About
MCP gateway: bounded tool shortlists + artifact-backed result firewall. Deterministic, no model.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- dgenio
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.18.2
- Stars
- 9
- Forks
- 15
- Open pull requests
- 1
- Last push
- 2026-09-07T12:10:44Z
- Repository state
- ativo
- Language
- Python
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:42
- Updated
- 2026-08-29 08:00:05
- Origin id
io.github.dgenio/contextweaver
README
# contextweaver <!-- mcp-name: io.github.dgenio/contextweaver --> [](https://github.com/dgenio/contextweaver/actions/workflows/ci.yml) [](https://pypi.org/project/contextweaver/) [](https://pypi.org/project/contextweaver/) [](LICENSE) [](https://scorecard.dev/viewer/?uri=github.com/dgenio/contextweaver) [](https://dgenio.github.io/contextweaver) [](https://github.com/dgenio/contextweaver/discussions) > **Capture an agent's effective capability surface, commit it, and see semantically meaningful changes before deployment.** ContextWeaver is currently testing a deliberately narrow product hypothesis: **capability snapshot + semantic drift**. Given an OpenAPI document, a captured MCP `tools/list` response, or a native ContextWeaver catalog, the D1 experiment produces a deterministic normalized snapshot that you can inspect, verify, and compare with a later candidate. It does not require a model account, a gateway, a tool executor, or the Weaver Stack. **Status:** alpha, and specifically a **product experiment**. The implementation works and is tested; the user-value hypothesis is not yet proven. The project is actively measuring whether independent users keep this workflow after trying it on real projects. ## Try the capability-drift experiment Clone the repository and install that checkout so the maintained example fixtures and the code under evaluation are guaranteed to match: Commands below use `python3`, matching the repository's documented default (`docs/agent-context/workflows.md`). On Windows installations that expose Python through the launcher, replace `python3` with `py -3`; if your environment already exposes the intended interpreter as `python`, use that consistently. ```bash git clone --depth 1 https://github.com/dgenio/contextweaver.git cd contextweaver python3 -m pip install . ``` Run the maintained OpenAPI example: ```bash python3 -m contextweaver.d1 snapshot examples/d1/openapi_before.json --source-type openapi --output ./cw-before.json python3 -m contextweaver.d1 snapshot examples/d1/openapi_after.json --source-type openapi --output ./cw-after.json python3 -m contextweaver.d1 inspect ./cw-after.json python3 -m contextweaver.d1 verify ./cw-after.json python3 -m contextweaver.d1 diff ./cw-before.json ./cw-after.json ``` The candidate fixture intentionally: - makes `customer_id` required on the existing `listInvoices` capability; - changes its description; - adds a new `getInvoice` capability. The diff separates capability additions/removals from changes to an existing logical capability and reports the structured paths that changed. Contract changes are separated from documentation-only changes. Changes involving fields such as `required`, `type`, or `enum` are flagged as **potentially breaking** for review. That flag is intentionally conservative: ContextWeaver does **not** claim to be a complete JSON-Schema compatibility checker. Full walkthrough: [Capability drift experiment](docs/d1_capability_drift.md). ## Use it on your own source ### OpenAPI ```bash python3 -m contextweaver.d1 snapshot ./openapi.yaml --source-type openapi --output ./capabilities.json python3 -m contextweaver.d1 verify ./capabilities.json ``` After the API changes: ```bash python3 -m contextweaver.d1 snapshot ./openapi.yaml --source-type openapi --output ./capabilities-candidate.json python3 -m contextweaver.d1 diff ./capabilities.json ./capabilities-candidate.json ``` ### Captured MCP tools If you already have an MCP `tools/list` response saved as JSON: ```bash python3 -m contextweaver.d1 snapshot ./tools-list.json \ --source-type mcp \ --output ./capabilities.json ``` For MCP, D1 compares tools by their upstream logical name so an input-schema edit appears as a change to the same capability rather than an unexplained remove/add pair. The historical schema-sensitive routing ID is retained separately as `normalized_id` for inspection. Capturing a live MCP server is a separate operation. `snapshot`, `inspect`, `diff`, and `verify` do not execute discovered capabilities. ### Native ContextWeaver catalog ```bash python3 -m contextweaver.d1 snapshot ./catalog.json \ --source-type native \ --output ./capabilities.json ``` ## What `verify` means `verify` checks the D1 snapshot contract: structure, deterministic ordering, logical-ID uniqueness, and the canonical capability digest. It is **not**: - deployment approval; - security certification; - authentication or authorization; - a guarantee that a tool implementation is correct; - routing-quality evaluation; - production runtime attestation. ## When not to use ContextWeaver D1 A negative answer is useful evidence for this project. Do **not** add ContextWeaver just because capability snapshots sound tidy. Use something simpler when: - **ordinary Git diff, config review, and tests already make your capability changes obvious;** - your tool/API surface is tiny and rarely changes; - provider-native tool search is the only problem you are trying to solve; - you need an agent loop, tool executor, IAM layer, or production orchestrator; - maintaining another committed artifact costs more than the review/debugging problem it removes. If you try D1 and conclude that Git/tests are cheaper, that is a valid product result — please say so. ## What is being tested The current survival experiment asks a stronger question than whether the code works: > Do capability snapshots and semantic drift reports improve a real > review/manual/risk process enough that independent users keep them? The project distinguishes: ```text qualified exposure -> understood the problem -> chose to evaluate -> attempted setup -> reached first useful output -> used on a real project -> retained independently / removed ``` Stars, forks, downloads, a successful demo, and maintainer-created integrations are not treated as retained adoption. The controlling product decision is tracked in [#758](https://github.com/dgenio/contextweaver/issues/758), and the distribution quality gate is [#855](https://github.com/dgenio/contextweaver/issues/855). Unassisted first success and retention are tracked in [#658](https://github.com/dgenio/contextweaver/issues/658) and genuine adoption in [#551](https://github.com/dgenio/contextweaver/issues/551). ## What about routing, context compilation, and the MCP gateway? ContextWeaver already contains substantial historical runtime functionality. That code still exists and currently shipped behavior should remain truthful and safe, but **existing implementation is not evidence that the project should keep expanding it**. Two broader hypotheses are explicitly evidence-first: - **D2 — bounded / phase-aware context compilation:** conditional. It must show consequential value beyond contemporary provider/runtime-native mechanisms. - **D3 — custom deterministic tool selection:** a falsification track. It must beat modern provider-native tool search/deferred loading or a simple retrieval baseline on something target users actually care about. During the D1 experiment, the project is not expanding routing sophistication, runtime bundle machinery, memory/session surfaces, framework breadth, gateway scope, vector stores, or model-assisted enrichment without a concrete external blocker or approved falsification experiment. If you are maintaining an existing integration that uses those historical surfaces, the relevant documentation remains available: - [Which historical pattern fits?](docs/which_pattern.md) - [Context firewall](docs/context_firewall.md) - [MCP Context Gateway architecture](docs/architectures/mcp_context_gateway.md) - [MCP gateway security model](docs/security_model.md) - [Comparison / alternatives](docs/comparison.md) - [Ecosystem map](docs/ecosystem.md) ## Evidence and claims The D1 implementation supports scoped engineering claims such as deterministic snapshot construction under the documented source/adapter contract and structured semantic-diff output. It does **not** yet support the stronger claim that users need or retain the product. The historical token-reduction headline is intentionally not used to sell D1. The current evidence-integrity work for those older benchmark claims is tracked in [#841](https://github.com/dgenio/contextweaver/issues/841). See [Claims & evidence](docs/claims.md) for the claim registry and [Capability drift experiment](docs/d1_capability_drift.md) for the exact D1 contract and limitations. ## Python API stability D1 is intentionally exposed through: ```bash python3 -m contextweaver.d1 ... ``` rather than being promoted immediately into the historical top-level CLI or a large new public Python API. That is deliberate. The experiment should earn a permanent surface through real retained use before the project takes on another compatibility obligation. ## Part of the Weaver Stack — optionally ContextWeaver can be used standalone. It has no hard dependency on the sibling Weaver projects. The wider Weaver Stack contains adjacent experiments/components for planning, execution boundaries, guardrails, lessons, and evaluation. That ecosystem is **not required** to evaluate D1, and Stack coherence is not a reason to preserve a ContextWeaver feature that does not justify itself independently. See the [Ecosystem map](docs/ecosystem.md) only if you actually need those adjacent responsibilities. ## Install and compatibility ```bash pip install contextweaver ``` Python 3.10–3.14 are covered by the repository CI matrix. Current package version: **0.18.2** | Project | Release | |---|---| | ContextWeaver (this repo, [v0.18.2](https://github.com/dgenio/contextweaver/releases/tag/v0.18.2)) | current package release | The repository is pre-1.0. Prefer the latest supported patch release for bug and security fixes, and check the changelog before relying on historical runtime APIs. ## Current roadmap The roadmap is intentionally a product-decision sequence, not a feature queue. | Milestone | Status | Meaning | |---|---|---| | **v0.18.1 — D1 survival experiment baseline** | ✅ complete | Offline snapshot/inspect/diff/verify exists; user value remains unverified. | | **v0.18.2** | ✅ current (v0.18.2) | D1 survival experiment and release-path recovery | | **D1 distribution gate** | 🔬 evidence first | Make the front door understandable, recruit qualified evaluators, measure first success and retention. | | **D1 decision** | ⏸ next decision | Continue, shrink further, or kill based on retained value after competent distribution. | | **D2 / D3** | 🧪 conditional | Run only if D1 evidence or independent problem discovery justifies bounded falsification experiments. | A green CI run does not advance this roadmap by itself. ## Contributing The most valuable contributions during the survival experiment are narrow and evidence-linked: - a real D1 evaluator blocker; - a semantic-diff case that is currently misleading or silently lost; - deterministic normalization correctness; - security/release maintenance for behavior the package still ships; - negative evidence showing a simpler alternative wins. Please do not add a framework adapter, routing policy, storage backend, runtime phase, or ecosystem integration solely for completeness. See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) for repository engineering conventions. ## Security See [SECURITY.md](SECURITY.md) for supported-version and vulnerability-reporting guidance. Do not include credentials, customer data, proprietary schemas, or private prompts in public adoption/evaluation reports. ## Documentation - [Documentation site](https://dgenio.github.io/contextweaver) - [Capability drift experiment](docs/d1_capability_drift.md) - [Claims & evidence](docs/claims.md) - [Daily Driver guide](docs/daily_driver.md) — historical/runtime users - [Cookbook](docs/cookbook.md) — broader shipped surfaces - [FAQ](docs/faq.md) - [Changelog](CHANGELOG.md) ## License Apache-2.0. See [LICENSE](LICENSE).