veqtor-mcp

Veqtor MCP

Website · Demo · Documentation · PyPI · GitHub 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 and the next-round prompt.

Veqtor is not legal advice, a generic Word editor, a hosted service, or a tamper-evident audit system. Review the known limitations before using it on a real matter.

This source tree defines package version 0.6.0.dev1 and the twenty-three-tool development MCP contract veqtor.mcp.v0.6.0. The drafting tools support paragraph insertion and replacement, comment replies and thread status, a selected author for each batch, and backup-backed saves to the working file. This is a development version; the public release remains 0.5.0. See author drafting. All current tools report the new contract-wide marker. Legacy calls remain compatible with the historical 0.4.0 release; the additive paragraph target and the two deal-position tools require 0.4.2. Live producer.version identifies this package version and producer.build fingerprints the imported Python sources.

Public installations must use an independently verified released version. Source presence does not establish publication or exact-package 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 and the GitHub Releases list, then select one exact version for every command below:

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

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

Author drafting

The tools introduced in 0.5.0—read_document_comments, preflight_document_edits and apply_document_edits—support editing one's own pending insertions and saving the same working DOCX with a mandatory backup. Development version 0.6.0.dev1 adds paragraph insertion/replacement and comment threads. Configure VEQTOR_TRACKED_CHANGE_AUTHOR and VEQTOR_COMMENT_INITIALS for the default, and configure any additional own profiles through VEQTOR_OWN_AUTHOR_PROFILES. A batch's optional author_profile: {name, initials} must match a configured profile; a request cannot introduce another author's identity. Paragraph edits track only changed words by default; whole-text replacement is an explicit mode. Close Word before a save and refresh document references afterwards. The complete operation and recovery contract is in AUTHOR_DRAFTING.md. The agent protocol requires authorization for the concrete plan and explicit instructions for thread status changes; it is also delivered through MCP initialization instructions. The public installation commands below continue to select the published release.

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. Use the first verified version in the table above and never guess a release-asset URL.

Opening an official MCPB requests installation approval and the tracked-change author name; version 0.5.0 also asks for comment initials. 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 connects the exact version selected above to local Codex over stdio. The next-round workflow reuses saved positions, presents a selected-issue brief and prepares a separate tracked Word counterproposal after your decisions. That workflow requires 0.4.2 or later and its eleven document/position tools; 0.5.0 adds three author-drafting tools. The fallback 0.4.0 supports the historical nine-tool document workflow only.

After installing uv, find its executable with command -v uvx. Replace the path and author below with your own values:

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. Registration alone does not establish a working document workflow. The guide separates the historical public-package observations from pending acceptance of the exact 0.5.0 package. Select a version only after both public verifiers pass.

Install a verified published version for Claude Code

Install uv once, replace X.Y.Z using the table above, then register that exact Veqtor version for your user account:

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

Open a new Claude Code session and verify the registration:

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:

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:

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:

uvx veqtor-mcp@X.Y.Z doctor

For a persistent isolated installation:

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.

Five-minute demo

Create a disposable four-round synthetic negotiation:

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:

{
  "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 development package 0.6.0.dev1 and its twenty-three-tool development MCP contract veqtor.mcp.v0.6.0. 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.
• compare_incoming_version: read-only comparison of two explicitly selected, hash-bound versions, with complete paragraph membership and separate markup, table topology and package-part observations. See incoming comparison.
• read_document_tables: complete bounded, snapshot-bound table/cell/paragraph inventory and a read-only report of textual reference candidates and raw field nodes.
• check_bilingual_conditions: Decimal/date/unit checks for explicitly selected single-value condition pairs in selected language cells, with unsupported and unpaired value coverage. Numeric agreement does not verify translation or obligation equivalence. See bilingual columns.
• 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.
• read_deal_positions: bounded reads of saved negotiation positions and their explicit confirmation state.
• mutate_deal_positions: expected-revision position updates, confirmation and withdrawal, independently of document edits.
• read_document_revisions (unreleased 0.6.0.dev1): exact main-document revision inventory and accept/reject previews. Explicit decide_revision operations cover supported text and all six property domains through the existing preflight and same-file backup workflow. See the decision contract.
• read_document_comments: paginated comment text, authors, replies, thread status, paragraph locations and source hash.
• preflight_document_edits: dry-run text and paragraph changes, comments, replies and thread status, bound to the selected author and the working document.
• apply_document_edits: apply that unchanged proof and save in place with an exact backup, or create a separate copy. A durable prepared operation precedes publication; file verification and journal completion are separate outcomes.
• recover_document_operation: observe an existing operation and complete a lost journal result without applying edits again. See the operation journal.

The complete request, response and error contract is in the versioned MCP Tool API. 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.

Optional provenance is disabled for a workspace inside .veqtor or .veqtor-backups (case-insensitive path components after resolving aliases). Reading immutable round snapshots or retained backups therefore does not add a nested sidecar: successful reads return record_id: null, record_status: disabled. An existing legacy journal there can be exported without appending an access event; an uninitialized folder remains refused. Nothing is redirected to a guessed parent matter or automatically repaired. Ordinary matter journals and the required drafting operation journal keep their existing behavior.

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); this is not acceptance of 0.5.0
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 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.

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:

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.

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. The exact-SHA immutable publication contract is documented in the release guide.

Maintainer

Veqtor MCP is an independent open-source project created and maintained by Ilya Shilov (@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 and API. Exact-candidate native acceptance remains a separate gate; the published 0.4.0 installation does not contain these tools.