Metadata-Version: 2.4
Name: contextweave-mcp
Version: 0.4.0
Summary: Unified code-context MCP server: structural, lexical and semantic retrieval
Keywords: mcp,tree-sitter,code-search,retrieval,embeddings,claude,codex,llm
Author: artemOP
Author-email: artemOP <matthew.brough123890@gmail.com>
License-Expression: MPL-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Indexing
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=2.3.0
Requires-Dist: msgpack>=1.2.3
Requires-Dist: pathspec>=1.1.1
Requires-Dist: pydantic>=2.14.0
Requires-Dist: sqlite-vec>=0.1.9
Requires-Dist: tokenizers>=0.23.2
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: tree-sitter==0.26.*
Requires-Dist: tree-sitter-language-pack>=1.21.0
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/matthew-brough/ContextWeave
Project-URL: Repository, https://github.com/matthew-brough/ContextWeave
Project-URL: Issues, https://github.com/matthew-brough/ContextWeave/issues
Description-Content-Type: text/markdown

# ContextWeave

Code-context MCP server for coding agents. It gives an agent structural, lexical
and semantic retrieval over a repository, so it can pull the definition it
needs instead of reading whole files.

- **Structural**: tree-sitter symbols, key paths and headings for 27 languages
  and data/doc formats (`cw languages`).
- **Lexical + semantic**: a SQLite index with full-text search and
  [sqlite-vec](https://github.com/asg017/sqlite-vec) embeddings, fused and
  packed into a token budget.
- **Graph**: callers, callees, imports, inheritance, tests and config edges.

Published on PyPI as **`contextweave-mcp`**. The import package is
`contextweave` and the commands are `cw` and `contextweave`.

## Install

Requires Python 3.14+.

```sh
uv tool install contextweave-mcp
cw --version
```

## Quickstart

From the root of a project:

```sh
cw init                 # index + wire up Claude Code (default agent)
cw status               # counts, freshness, daemon and model health
cw search "where are retries handled"
```

`cw init` indexes the project and installs the agent integration: MCP server
registration, hooks, and a routing block that tells the agent when to use which
tool. Remove it again with `cw uninstall` (the index is kept; `cw forget` drops
it).

| `--agent`     | Integration                                  |
| ------------- | -------------------------------------------- |
| `claude_code` | `.mcp.json`, `.claude/settings.json` hooks and a `CLAUDE.md` block (default) |
| `codex`       | One global entry in Codex's `config.toml` and an `AGENTS.md` block |
| `agents_md`   | `.mcp.json` and an `AGENTS.md` block, no hooks |
| `none`        | Index only                                   |

`cw init --plugin` writes a Claude Code plugin directory instead of editing
project files. `--dry-run` shows what would change.

To run the server by hand for any MCP client:

```sh
cw serve   # MCP over stdio
```

## MCP tools

| Tool             | Use it to                                                      |
| ---------------- | -------------------------------------------------------------- |
| `context_search` | Describe behaviour in words; get a budgeted pack of relevant code |
| `get_symbol`     | Fetch one definition, key path or heading by name             |
| `file_outline`   | See one file's shape: symbols, schema key paths or headings   |
| `search_symbols` | Find names across the project                                  |
| `ast_query`      | Run a raw tree-sitter query on one file                        |
| `expand`         | Resolve a `cw://` ref to its current bytes                     |
| `related`        | Graph neighbours of a symbol or file                           |

Every tool is read-only. Results are terse text; summarised or omitted items
carry `cw://` refs that `expand` resolves later, and report when the code moved
or was deleted.

## Models

Semantic search, chunk annotation and query gating use local models served by
[llama.cpp](https://github.com/ggml-org/llama.cpp) `llama-server` (embed,
annotate) and a classifier endpoint. **No model weights are bundled or
downloaded by ContextWeave**; you run the servers and point the config at them.
Each model has its own licence: the default embed model,
jina-code-embeddings, is CC-BY-NC (non-commercial). Swap `models.embed`
for a permissively licensed model if that does not fit your use.

| Slot       | Default model                                 | Endpoints (gpu / cpu) |
| ---------- | --------------------------------------------- | --------------------- |
| `embed`    | `jinaai/jina-code-embeddings-1.5b-GGUF:Q8_0`  | `:8770` / `:8771`     |
| `annotate` | `unsloth/Qwen3.5-4B-GGUF:Q4_K_M`              | `:8772` / `:8773`     |
| `classify` | Kev-0.8B (`kev-latest`)                       | `:8765` (gpu only)    |

Example servers:

```sh
llama-server -hf jinaai/jina-code-embeddings-1.5b-GGUF:Q8_0 --embeddings --pooling last --port 8770
llama-server -hf unsloth/Qwen3.5-4B-GGUF:Q4_K_M --port 8772
```

Models are optional. Without them the structural and lexical paths still work;
indexing reports the skipped stages as degraded and `cw index` fills them in
once the servers are up. `cw models probe` times each slot on your hardware.

## Configuration

Settings are layered: built-in defaults, then
`~/.config/contextweave/config.toml` (honours `XDG_CONFIG_HOME`), then
`.contextweave.toml` in the project root. `cw config show` prints the effective
values.

```toml
[index]
include = ["src", "tests"]
ignore = ["vendor/**"]

[models.embed.gpu]
endpoint = "http://127.0.0.1:8770"
# Set launch to have the daemon start and supervise the server itself.
launch = ""
```

## CLI

| Command                         | Purpose                                    |
| ------------------------------- | ------------------------------------------ |
| `cw init` / `cw uninstall`      | Install or remove agent integration        |
| `cw index`                      | Build or refresh the index                 |
| `cw status`                     | Counts, freshness, daemon and model health |
| `cw search <query>`             | Run the retrieval pipeline and print the pack |
| `cw projects` / `cw forget`     | List or remove registered projects         |
| `cw daemon start\|stop\|status` | Per-user daemon (Linux / WSL2)             |
| `cw savings`                    | Token savings ledger                       |
| `cw config show`                | Effective configuration                    |
| `cw languages`                  | Supported languages and their profiles     |
| `cw cache`, `cw tune`, `cw eval`| Maintenance, score tuning, evaluation suites |

## Platforms

Linux and WSL2 are the primary targets and run the shared per-user daemon. On
Windows the server runs in-process; the daemon needs Unix sockets.

## Development

```sh
uv sync
uv run ruff check . && uv run ruff format --check .
uv run pyright
uv run pytest            # add -m "not daemon" off Linux
```

## Licence

[Mozilla Public License 2.0](LICENSE). Model weights used at runtime are not
part of this project and are covered by their own licences.
