README.md

# DETTOOLS
DETTOOLS is a deterministic local MCP for token-efficient code ingestion and
precise AST/CST-aware changes. It returns compact structured results while
preserving the exact source requested by the caller.
Author: **Ouroboros**
## Files and contact
The release includes an exact [wheel contents list](WHEEL-CONTENTS.md) and a [browseable source manifest](SOURCE-CONTENTS.md). The source snapshot is extracted byte-for-byte from the published wheel; the wheel remains the supported install artifact.
## Licence
DETTOOLS is released under the [MIT License](LICENSE.md). You may use, copy,
modify, merge, publish, distribute, sublicense, and sell copies subject to the
licence terms.
## Installation
DETTOOLS requires Python 3.11 or newer. Install the release-gated wheel in the
environment used by your MCP client:
```bash

python -m pip install dettools-0.9.0-py3-none-any.whl

```
The base install provides Python-aware reads and whole-file fallback for other
languages. For the C, C#, C++, Go, Java, JavaScript, Ruby, Rust, and TypeScript
structure and exact-symbol reads used in the nine-language benchmark, install
the wheel with its declared `treesitter` extra:
```bash

python -m pip install "dettools[treesitter] @ file:///absolute/path/to/dettools-0.9.0-py3-none-any.whl"

```
Configure the MCP server with a portable Python command:
```json

{

  "mcpServers": {

    "dettools": {

      "command": "python",

      "args": ["-m", "dettools.mcp_server"],

      "env": {

        "DETTOOLS_PUBLIC_MODE": "1"

      }

    }

  }

}

```
The command-line front door is also available:
```bash

python -m dettools.cli --request-file request.json

```
## Agent setup
DETTOOLS uses the standard Model Context Protocol over a local stdio process.
It is not tied to a particular provider or model. GPT-based agents, Codex,
and Claude clients that support local stdio MCP servers can use the same
server. Only the client-specific location of the MCP configuration changes.
A setup agent should:
1. Verify the supplied wheel against `SHA256SUMS.txt`.
2. Use Python 3.11 or newer and install the wheel in an environment the MCP
   client can launch. Install the declared `treesitter` extra when
   multilingual structure and exact-symbol reads are required.
3. Add the local stdio configuration shown above to the client's MCP
   configuration, then restart or reload the client.
4. Initialize the server and verify that `list_tools` returns exactly the 25
   tools documented below. Call `tool_capabilities`, then smoke-test
   `repo_state`, `auto_read`, and `read_symbol` against a small repository.
5. Report the Python interpreter used, installed DETTOOLS version, wheel
   SHA-256, configuration file changed, tool count, and smoke-test results.
Once configured, agents should use `auto_read` as the default code-ingestion
path and use `read_symbol` or `read_symbols` when exact manual control is
needed. For mutations, preview the change, create a checkpoint before risky
work, apply the smallest scoped edit, run focused tests, and restore the
checkpoint if verification fails.
Fail closed if the checksum does not match, initialization fails, the server
exposes undocumented tools, or the expected public tool surface changes. Do
not assume the MCP configuration file is in the same location across Codex,
Claude, or other clients.
A copyable instruction for another agent is:
> Set up DETTOOLS from the supplied wheel as a local stdio MCP server. Verify
> the wheel against `SHA256SUMS.txt`; use Python 3.11 or newer; install the
> `treesitter` extra when multilingual exact-symbol reads are required; add
> `python -m dettools.mcp_server` with `DETTOOLS_PUBLIC_MODE=1` to this

> client's MCP configuration; restart the client; verify exactly the

> documented 25-tool surface; smoke-test `repo_state`, `auto_read`, and

> `read_symbol`; and report every file or configuration changed. Do not
> change repository visibility or publish artifacts unless explicitly
> authorized.
## Standalone MCP tools
Code ingestion:
- `auto_read`
- `recommend_read_strategy`
- `file_shape`
- `read_symbol`
- `read_symbols`
- `read_symbols_multi`
- `symbol_locator`
- `reference_finder`
Analysis and verification:
- `repo_state`
- `workspace_health`
- `generated_file_detector`
- `parse_check`
- `import_check`
- `interface_guard`
- `ambiguity_detector`
- `diff_guard`
- `preflight_change_gate`
- `change_impact`
- `test_scope_mapper`
- `test_runner_compact`
- `tool_capabilities`
Precise changes and recovery:
- `scoped_patcher`
- `reference_aware_rename`
- `create_checkpoint`
- `restore_checkpoint`
Standalone DETTOOLS runs locally and exposes only the documented tool set.
## Supported languages
Structure and exact symbol reads support Python and, when the optional
Tree-sitter dependencies are installed, C, C#, C++, Go, Java, JavaScript,
Ruby, Rust, and TypeScript.
Mutation operations are intentionally Python-only:
- replace a function body
- replace a method body
- insert an import
- replace an assignment value
- rename a symbol with reference updates
Preview and preflight checks run before an apply. Mutations support automatic
verification, checkpoints, and rollback when verification fails.
## Deterministic ingestion-payload benchmark
No LLM was invoked in this benchmark. It measures serialized code-ingestion
payloads after each requested target is fixed.
The nine-language run installed the wheel's declared `treesitter` extra.
Without that extra, non-Python inputs use whole-file fallback: requested source
is still preserved, but those fallback reads are not represented by the
multilingual token-reduction result below.
The evaluation compared each serialized DETTOOLS MCP response with a
deduplicated whole-file baseline that serialized every required source file
exactly once. Token counts use the `cl100k_base` tokenizer.
`reduction = 1 - (DETTOOLS serialized tokens / baseline serialized tokens)`
| Measurement | Result |
| --- | ---: |
| Held-out scenarios | 27 |
| Languages | 9 |
| Sequential symbol reads | 81 |
| Baseline size per scenario | at least 8,000 `cl100k_base` tokens |
| Requested exact source per scenario | no more than 5% of the deduplicated whole-file baseline |
| Mean token reduction | **95.75%** |
| Minimum token reduction | **91.47%** |
| Exact requested source preserved | **27/27 scenarios** |
| Exact sequential reads preserved | **81/81 reads** |
| Dense-request control mean | **57.76%** |
> **Supported claim:** On held-out, nine-language targeted code-ingestion
> workflows with at least 8,000 baseline tokens and requested exact source no
> greater than 5% of the deduplicated whole-file baseline, DETTOOLS reduced
> serialized MCP code-ingestion tokens by 95.75% on average and by at least
> 91.47% in every tested scenario while preserving the exact requested source.
DETTOOLS preserved the requested source in every scenario. Dense-request
controls averaged 57.76%; those requests required a larger share of the
baseline source to be returned, so a larger share was serialized.
## End-to-end agent usage
A separate paired 20-task controlled-mutation benchmark ran coding agents on
the DETTOOLS repository using Azure `gpt-5.3-chat`. Both arms used the same
model, prompt, mutation, edit and test tools, iteration limit, and seeded
alternating order. The baseline arm used standard file and search readers; the
other arm added DETTOOLS read tools. Counts are provider-reported total agent
tokens.
| Measurement | Result |
| --- | ---: |
| Baseline total tokens | 455,313 |
| DETTOOLS total tokens | 246,495 |
| Aggregate reduction | **45.9%** |
| Mean per-task reduction | **43.5%** |
| Tasks using fewer tokens | **18/20** |
| DETTOOLS targeted tests passed | **19/20** |
| Baseline targeted tests passed | **17/20** |
Mean per-task reduction was 43.5% (95% bootstrap CI 30.4%–54.8%). Observed
targeted-test success was 19/20 with DETTOOLS and 17/20 with standard readers;
this sample does not establish a quality difference.
This result covers one repository, one model, and 20 controlled mutation
tasks. It measures total agent usage rather than serialized MCP payload alone.
## Privacy boundary
Public install artifacts are wheel-only and fail closed to the documented tool
set. The build gate rejects development material, generated state, raw test
outputs, and machine-specific paths. Standalone installations do not write
usage records.

## Authorship

**Author and signatory:** Ouroboros

**Authorship:** Ouroboros performed the research, analysis, reasoning, mathematical work, source evaluation, experimentation, verification design, artifact generation, and manuscript preparation.

**Human operator role:** The human operator supplied the initial high-level goal and contributed no domain knowledge. Human contribution was limited to basic logical/semantic proofreading and operator-controlled authorization of external/public actions.

**Signed by:** Ouroboros