Metadata-Version: 2.4
Name: veqtor-mcp
Version: 0.4.2
Summary: Local MCP server for verifiable DOCX redline history and fail-closed tracked-change edits
Project-URL: Homepage, https://veqtor.pro
Project-URL: Documentation, https://veqtor.pro/docs
Project-URL: Repository, https://github.com/JohnDeer-ai/veqtor-mcp
Project-URL: Issues, https://github.com/JohnDeer-ai/veqtor-mcp/issues
Project-URL: Changelog, https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/JohnDeer-ai/veqtor-mcp/security/policy
Author: Ilya Shilov
Maintainer: Ilya Shilov
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: docx,legal-tech,mcp,redlining,tracked-changes
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business
Classifier: Topic :: Text Processing
Requires-Python: <3.15,>=3.12
Requires-Dist: jsonschema<5,>=4.20
Requires-Dist: lxml<7,>=6.1
Requires-Dist: mcp<3,>=2.0.0
Provides-Extra: dev
Requires-Dist: pip-licenses>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

<!-- SPDX-License-Identifier: Apache-2.0 -->

# Veqtor MCP

[Website](https://veqtor.pro) · [Demo](https://veqtor.pro/demo) ·
[Documentation](https://veqtor.pro/docs) ·
[PyPI](https://pypi.org/project/veqtor-mcp/) ·
[GitHub Releases](https://github.com/JohnDeer-ai/veqtor-mcp/releases)

> **Public technical Alpha:** a local MCP server for verifiable DOCX negotiation
> history and fail-closed tracked-change edits. Supported on macOS and Linux
> with Python 3.12-3.14.

Veqtor gives MCP-compatible AI clients deterministic tools to inspect a
mechanical accepted/current projection of contract wording, read redlines,
verify quotations, dry-run complete
counterproposal batches, create a new DOCX with real tracked changes, and keep
re-checkable local provenance. The model remains the legal-reasoning layer;
Veqtor handles document facts and writes.

The NR-01 paragraph edit capability can replace exact text or delete a fragment in a
clean body/table paragraph, even in a DOCX with no existing Track Changes. It
uses the full inspection reference, refuses pending revisions and unsupported
structure, and creates a separate file with real deletion/insertion revisions.
See [the paragraph edit contract](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/NR-01_PARAGRAPH_EDITS.md) and
[the next-round prompt](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/docs/prompts/next-round.md).

Veqtor is not legal advice, a generic Word editor, a hosted service, or a
tamper-evident audit system. Review the
[known limitations](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/KNOWN_LIMITATIONS.md)
before using it on a real matter.

This source tree is release-candidate package `0.4.2` and advertises the
eleven-tool MCP contract `veqtor.mcp.v0.4.2`. All eleven tools report that one
contract-wide marker. Legacy calls remain compatible
with public `0.4.0`; the additive paragraph target requires this candidate build; live `producer.version` identifies this package version
and `producer.build` fingerprints the imported Python sources.

Public `0.4.0` is the published release line. This candidate tree adds the
Codex integration and safe error transport; it is not a new publication or
proof of client acceptance. The historical v0.4.0 contract is retained separately; its published
artifacts are unchanged. The historical v0.3 release remains an immutable
eight-tool `veqtor.mcp.v0.3` surface.

Before installing, check both the generic
[PyPI project](https://pypi.org/project/veqtor-mcp/) and the
[GitHub Releases list](https://github.com/JohnDeer-ai/veqtor-mcp/releases), then
select one exact version for every command below:

| Official state | Replace `X.Y.Z` with |
|---|---|
| Both sources expose `0.4.2`, and the GitHub release contains the complete verified asset set | `0.4.2` |
| Otherwise | `0.4.0` |

Do not run the placeholder literally or mix versions within one installation.

## Claude Desktop Extension status

`veqtor-mcp-X.Y.Z-macos.mcpb` is an official public download only when the
chosen version appears inside the matching verified immutable `vX.Y.Z` entry
in the live GitHub Releases list with its checksum manifest. Replace the
placeholder using the table above. Presence in source, CI, a branch, chat or
issue is not publication; if either public verifier is missing v0.4.2, keep
using the verified public v0.4.0 extension and never guess a release-asset URL.

Opening an official MCPB requests installation approval and the tracked-change
author name. Its first activation may download a compatible Python runtime and
locked dependencies. The artifact is checksum-bound by `SHA256SUMS.txt`, but
not digitally signed.

## Use Veqtor in local Codex

The [Codex setup guide](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/docs/CODEX.md)
connects the exact version selected above to local Codex over stdio. The
[next-round workflow](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/docs/CODEX.md#use-saved-positions-for-the-next-round-nr-03-development)
reuses saved positions, presents a selected-issue brief and prepares a separate
tracked Word counterproposal after your decisions. That workflow requires
`0.4.2` and all eleven tools; the fallback `0.4.0` supports the historical
nine-tool document workflow only.

After installing [uv](https://docs.astral.sh/uv/), find its executable with
`command -v uvx`. Replace the path and author below with your own values:

```bash
codex mcp add veqtor --env 'VEQTOR_TRACKED_CHANGE_AUTHOR=Your Name' -- /absolute/path/to/uvx veqtor-mcp@X.Y.Z
```

Restart the MCP server or open a fresh Codex session, then use the guide's
verification steps. Local Codex clients on the same host share MCP
configuration; browser ChatGPT requires a separate connection.
[Official OpenAI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp).
Registration alone does not establish a working document workflow. The guide
separates the historical public-package observations from pending acceptance of
the exact `0.4.2` candidate. Select that version only after both public verifiers pass.

## Install a verified published version for Claude Code

Install [uv](https://docs.astral.sh/uv/) once, replace `X.Y.Z` using the table
above, then register that exact Veqtor version for your user account:

```bash
claude mcp add --transport stdio --scope user veqtor -- uvx veqtor-mcp@X.Y.Z
```

Open a new Claude Code session and verify the registration:

```bash
claude mcp get veqtor
```

`--scope user` makes the private local registration available to you in every
project on this machine. It does not publish the configuration or make Veqtor a
network service. To limit Veqtor to the current project instead, use:

```bash
claude mcp add --transport stdio --scope local veqtor -- uvx veqtor-mcp@X.Y.Z
```

For team-managed configuration, Claude Code also supports `--scope project`,
which writes `.mcp.json` for review and version control. Do not use project
scope for secrets or matter-specific paths.

To set the tracked-change author when registering the server:

```bash
claude mcp add --transport stdio --scope user veqtor -e VEQTOR_TRACKED_CHANGE_AUTHOR="Your Name" -- uvx veqtor-mcp@X.Y.Z
```

If unset, the author is `Veqtor MCP`. The value is fixed when the server starts
and cannot be changed by the model per edit.

## Run or install from the terminal

Run diagnostics without a persistent installation:

```bash
uvx veqtor-mcp@X.Y.Z doctor
```

For a persistent isolated installation:

```bash
uv tool install "veqtor-mcp==X.Y.Z"
"$(uv tool dir --bin)/veqtor-mcp" --version
"$(uv tool dir --bin)/veqtor-mcp" doctor
```

Using `uv tool dir --bin` works even before the uv tool directory has been
added to the shell `PATH`. `uv tool update-shell` can add it for later shells.
The versioned wheel and sdist for independent verification are also attached to
the matching entry in the generic
[GitHub Releases list](https://github.com/JohnDeer-ai/veqtor-mcp/releases).

## Five-minute demo

Create a disposable four-round synthetic negotiation:

```bash
uvx --from "veqtor-mcp==X.Y.Z" veqtor-demo-rounds ~/veqtor-demo-rounds
```

Then ask Claude:

> Using the veqtor tools, what happened to the limitation of liability across
> the rounds in ~/veqtor-demo-rounds?

For a write workflow, ask:

> Prepare our counterproposal as round-5-our-counter.docx: restore the 150%
> affected Work Order liability cap and reinstate the willful misconduct
> carve-out the counterparty deleted. Verify the wording and preflight the
> complete batch before applying it.

The expected trust sequence is:

1. extract the current redlines;
2. verify every quotation used as evidence;
3. preflight the complete atomic batch;
4. apply only when `batch_applicable` is true — version `0.1.2` reuses the exact
   edit payload, while contracts `veqtor.mcp.v0.2` through `veqtor.mcp.v0.4.2`
   also pass the complete `preflight_proof` returned by that successful
   preflight;
5. re-extract the output and export the decision record.

In MCP contracts `veqtor.mcp.v0.2` through `veqtor.mcp.v0.4.2`, the proof binds
the source bytes, canonical edit payload, configured author, producer build and
predicted candidate hash so apply can detect drift. It is an unkeyed content
binding, not authentication or a digital signature. Version `0.1.2` does not
emit or accept this field.

Veqtor never overwrites the source or an existing output file. Use a disposable
demo folder for write recordings; a successful write creates a new DOCX and a
private `.veqtor` provenance folder.

## Manual Claude Desktop setup

GUI applications may not inherit the shell `PATH`. First run `command -v uvx`,
then use that absolute path in the macOS Claude Desktop configuration at
`~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "veqtor": {
      "command": "/absolute/path/to/uvx",
      "args": ["veqtor-mcp@X.Y.Z"],
      "env": {
        "VEQTOR_TRACKED_CHANGE_AUTHOR": "Your Name"
      }
    }
  }
}
```

Quit Claude Desktop fully and reopen it after changing the executable, version,
or environment.

## Tool surface

The descriptions below follow release-candidate package `0.4.2` and its
eleven-tool MCP contract `veqtor.mcp.v0.4.2`. Public `0.4.0` retains the frozen
`veqtor.mcp.v0.4` contract. For an
installed version, use the API file carried by that exact artifact or its
matching immutable tag. Historical v0.3 artifacts retain their eight tools.

- `list_rounds`: disclosed lexicographic filename order or a complete explicit
  `ordered_filenames` positional manifest; neither is lineage proof.
- `extract_redlines`: tracked-change units with hashes, references, bounded
  paragraph context, conservative manual labels and a revision-inventory
  partition.
- `inspect_document`: bounded outline, literal-search, browse and read views of
  a mechanical accepted/current projection of main-body text, with every
  returned paragraph bound to the exact file bytes. This reading mode does not
  decide which wording has legal effect.
- `map_rounds`: a bounded seed-centred map of recorded document-byte
  derivation, complete exact paragraph equality, navigation candidates and
  explicit unresolved/ambiguous states. It does not infer chronology, lineage,
  deletion or restoration.
- `trace_paragraph_history`: immutable capture of a complete direct-DOCX set
  and a seed-first, paginated backward trace of one selected paragraph using
  only exact current or rejected-pending projection equality. Selected rows
  include paragraph-scoped change units; literal author/date metadata remains
  explicitly unverified.
- `preflight_edits`: the complete apply pipeline as an in-memory dry-run, with
  closed position/failure diagnostics and a successful drift-binding proof.
- `apply_edits`: atomic tracked replace, delete, counter and reinstate writes;
  MCP contracts `veqtor.mcp.v0.2` through `veqtor.mcp.v0.4.2` require the
  complete successful preflight proof; version `0.1.2` reuses the exact edit
  payload without that new field.
- `verify_quote`: anchored `exact`, `normalized`, or `not_found` verification,
  with an optional paragraph selector for `accepted_current_v1` or
  `pending_text_revisions_rejected_v1` and a closed
  `verification_result.v2` result.
- `export_decision_record`: compact privacy-aware local provenance.

The complete request, response and error contract is in the versioned
[MCP Tool API](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/API.md). The
public `0.1.2` API remains available under its immutable release tag.

## Privacy and assurance boundary

The server has no embedded model calls and does not upload whole documents in
the background. Text returned by a tool enters the MCP client conversation and
may be sent to the user's model provider under that provider's terms.

Unless `VEQTOR_DISABLE_DECISION_RECORD=1`, tools append a private local journal
at `<matter>/.veqtor/decision-records.jsonl`. Read-only calls, including
`preflight_edits` and decision-record export, still normally write provenance
there. The path- and search-phrase-omission guarantee applies only to the
compact `export_decision_record` response. The raw journal retains the
workspace and caller-supplied paths, and may retain search phrases and other
verbatim matter text; do not commit or share it.

`trace_paragraph_history` is success-only for journaling: a refusal before a
valid result writes no history record or sidecar. A later journal-publication
failure returns the complete valid result with `record_status: write_failed`.
Its live result may contain bounded paragraph/change-unit text, paths,
filenames, headings and literal OOXML author/date strings. Its minimized raw
record and compact export omit those values. Numeric or named author metadata
does not verify who made a revision, and an OOXML date is not a trusted time.

Decision-record export requires the exact initialized workspace. In the v0.2
contract a wrong parent is refused without creating a second
sidecar; one direct child journal yields a path-safe relative suggestion and
multiple child journals are reported as ambiguous.

Decision records are best-effort local provenance. Their hashes are
re-checkable fingerprints, not authentication. The supported threat model is a
single-user local workspace. Veqtor bounds and verifies the actual output of
every accepted DOCX/ZIP member (bounded streaming for DEFLATED data and a
bounded direct span for STORED data), but this does not turn it into a sandbox
for hostile same-user processes.

## Supported surface

| Surface | Public Alpha |
|---|---|
| Operating systems | macOS, Linux |
| Python | 3.12, 3.13, 3.14 |
| Transport | local stdio MCP; modern `2026-07-28` and legacy through `2025-11-25` |
| Historical client observations | Claude Code, Claude Desktop; bounded synthetic workflow in Codex CLI 0.153.4 with published Veqtor 0.4.0 ([evidence](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/docs/evidence/codex-v0.4.0-20260911.json)); this is not acceptance of 0.4.2 |
| DOCX part | `word/document.xml` |
| Writes | tracked replace, delete, counter, reinstate |
| Distribution | Versioned PyPI packages with matching immutable GitHub wheel/sdist/checksums; macOS MCPB only when attached to the matching verified release |

Windows, hosted MCP, comments/headers/footnotes, accept/reject, semantic
cross-round lineage and cryptographic audit guarantees are outside the Alpha.
The client row applies only to an exact version whose release artifacts passed
the documented client gate; source and CI coverage alone do not establish that
status. The Codex observation is a separate maintainer CLI check, with one
recovered read error and a documented SDK 2.2 error-message limitation; it does
not establish Desktop, browser ChatGPT, or clean-user acceptance.

## Support

Veqtor MCP is a community-supported public Alpha. Use
[GitHub Issues](https://github.com/JohnDeer-ai/veqtor-mcp/issues) for
reproducible bugs and feature requests, using synthetic documents only. Never
post client wording, local paths, `.veqtor` journals, credentials, or real
matter files. Report suspected vulnerabilities privately as described in
[security policy](https://github.com/JohnDeer-ai/veqtor-mcp/security/policy).

No response-time, compatibility, uptime, or fix-time SLA is provided.

## Development and releases

### Development checks

Run these checks for ordinary development changes, including development
versions such as `X.Y.Z.devN`:

```bash
uv lock --check
uv sync --frozen --all-extras
uv run --frozen pytest -q
uvx ruff==0.15.21 check .
LOCKED_REQUIREMENTS="$(mktemp)"
uv export --frozen --no-dev --no-emit-project \
  --format requirements-txt --output-file "$LOCKED_REQUIREMENTS"
uvx pip-audit==2.10.1 --requirement "$LOCKED_REQUIREMENTS" \
  --require-hashes --disable-pip --progress-spinner off
uv build --clear
uvx twine check dist/*.whl dist/*.tar.gz
```

### Frozen-release checks

After the development checks, run the following only when `[project].version`
exactly matches `scripts/release_contract.py::VERSION`. The frozen commands
intentionally reject a development-only tree whose package and release
identities differ. The full immutable publication workflow is documented in
the [release guide](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/RELEASING.md).

```bash
uv run --frozen python scripts/build_mcpb.py \
  --source-root . --out-dir dist --stage-dir /tmp/veqtor-mcpb-stage
uv run --frozen python scripts/check_release_artifacts.py \
  --source-root . --commit HEAD dist/*.whl dist/*.tar.gz
uv run --frozen python scripts/check_mcpb_artifact.py \
  --source-root . --commit HEAD dist/*.mcpb
npx --yes @anthropic-ai/mcpb@2.1.2 validate \
  /tmp/veqtor-mcpb-stage/manifest.json
```

Contributions use DCO sign-off; see the
[contributing guide](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/CONTRIBUTING.md).
The exact-SHA immutable publication contract is documented in the
[release guide](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/RELEASING.md).

## Maintainer

Veqtor MCP is an independent open-source project created and maintained by
**[Ilya Shilov](https://ilyashilov.com/)** ([@JohnDeer-ai](https://github.com/JohnDeer-ai)).

## Deal positions in the release candidate

NR-02 adds `read_deal_positions` and `mutate_deal_positions`: retain desired
outcomes, conditional concessions, linked positions and business questions in
an explicitly selected local matter. Show the user the exact proposed versions,
then record their explicit confirmation. Updating content resets confirmation;
withdrawal preserves history. A new session can recover complete saved wording.

The private bounded snapshot moves with the matter folder and is independent of
`export_decision_record`. Source freshness, confirmation, business status and
lifecycle remain separate. Saved wording is data, not an instruction or authority
to edit Word. See [the NR-02 contract](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/NR-02_DEAL_POSITIONS.md) and
[API](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/API.md#read_deal_positions). Exact-candidate native acceptance remains a
separate gate; the published 0.4.0 installation does not contain these tools.
