{"id":"db083a19-c300-4875-ba9a-778d61f7461b","slug":"veqtor-mcp","kind":"mcp","name":"veqtor-mcp","summary":"Veqtor MCP: local, open-source tools for comparing Word contract drafts and creating tracked-change counterproposals with Claude.","owner":"JohnDeer-ai","repoUrl":"https://github.com/JohnDeer-ai/veqtor-mcp","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-07-08T17:26:25.000Z","addedAt":"2026-10-21T04:46:57.624Z","logoUrl":"https://avatars.githubusercontent.com/u/179522700?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents","developer-tools","cloud-infra"],"tags":["claude","docx","legal-tech","redlining","tracked-changes","claude-code","contract-review"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T12:47:28.222Z","sample":false,"url":"https://conduits.dev/tools/veqtor-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"veqtor-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<!-- SPDX-License-Identifier: Apache-2.0 -->\n\n# Veqtor MCP\n\n[Website](https://veqtor.pro) · [Demo](https://veqtor.pro/demo) ·\n[Documentation](https://veqtor.pro/docs) ·\n[PyPI](https://pypi.org/project/veqtor-mcp/) ·\n[GitHub Releases](https://github.com/JohnDeer-ai/veqtor-mcp/releases)\n\n> **Public technical Alpha:** a local MCP server for verifiable DOCX negotiation\n> history and fail-closed tracked-change edits. Supported on macOS and Linux\n> with Python 3.12-3.14.\n\nVeqtor gives MCP-compatible AI clients deterministic tools to inspect a\nmechanical accepted/current projection of contract wording, read redlines,\nverify quotations, dry-run complete\ncounterproposal batches, create a new DOCX with real tracked changes, and keep\nre-checkable local provenance. The model remains the legal-reasoning layer;\nVeqtor handles document facts and writes.\n\nThe NR-01 paragraph edit capability can replace exact text or delete a fragment in a\nclean body/table paragraph, even in a DOCX with no existing Track Changes. It\nuses the full inspection reference, refuses pending revisions and unsupported\nstructure, and creates a separate file with real deletion/insertion revisions.\nSee [the paragraph edit contract](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/NR-01_PARAGRAPH_EDITS.md) and\n[the next-round prompt](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/docs/prompts/next-round.md).\n\nVeqtor is not legal advice, a generic Word editor, a hosted service, or a\ntamper-evident audit system. Review the\n[known limitations](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/KNOWN_LIMITATIONS.md)\nbefore using it on a real matter.\n\nThis source tree defines package version `0.6.0.dev1` and the\ntwenty-three-tool development MCP contract `veqtor.mcp.v0.6.0`. The drafting tools\nsupport paragraph insertion and replacement, comment replies and thread status,\na selected author for each batch, and backup-backed saves to the working file.\nThis is a development version; the public release remains 0.5.0. See [author drafting](#author-drafting).\nAll current tools report the new contract-wide marker. Legacy calls remain\ncompatible with the historical `0.4.0` release; the additive paragraph target\nand the two deal-position tools require `0.4.2`. Live `producer.version`\nidentifies this package version and `producer.build` fingerprints the imported\nPython sources.\n\nPublic installations must use an independently verified released version.\nSource presence does not establish publication or exact-package client acceptance. The historical v0.4.0 contract is retained separately; its published\nartifacts are unchanged. The historical v0.3 release remains an immutable\neight-tool `veqtor.mcp.v0.3` surface.\n\nBefore installing, check both the generic\n[PyPI project](https://pypi.org/project/veqtor-mcp/) and the\n[GitHub Releases list](https://github.com/JohnDeer-ai/veqtor-mcp/releases), then\nselect one exact version for every command below:\n\n| Official state | Replace `X.Y.Z` with |\n|---|---|\n| Both sources expose `0.5.0`, and the GitHub release contains the complete verified asset set | `0.5.0` |\n| Otherwise, both sources expose verified `0.4.2` | `0.4.2` |\n| Otherwise | `0.4.0` |\n\nDo not run the placeholder literally or mix versions within one installation.\n\n## Author drafting\n\nThe tools introduced in `0.5.0`—`read_document_comments`, `preflight_document_edits`\nand `apply_document_edits`—support editing one's own pending insertions and\nsaving the same working DOCX with a mandatory backup. Development version\n`0.6.0.dev1` adds paragraph insertion/replacement and comment threads.\nConfigure `VEQTOR_TRACKED_CHANGE_AUTHOR` and `VEQTOR_COMMENT_INITIALS` for the default,\nand configure any additional own profiles through `VEQTOR_OWN_AUTHOR_PROFILES`.\nA batch's optional `author_profile: {name, initials}` must match a configured\nprofile; a request cannot introduce another author's identity. Paragraph edits\ntrack only changed words by default; whole-text replacement is an explicit mode.\nClose Word before a save and refresh document references afterwards. The complete\noperation and recovery contract is in [AUTHOR_DRAFTING.md](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/docs/AUTHOR_DRAFTING.md).\nThe [agent protocol](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/docs/AUTHOR_DRAFTING_WORKFLOW.md) requires authorization for\nthe concrete plan and explicit instructions for thread status changes; it is\nalso delivered through MCP initialization instructions.\nThe public installation commands below continue to select the published release.\n\n## Claude Desktop Extension status\n\n`veqtor-mcp-X.Y.Z-macos.mcpb` is an official public download only when the\nchosen version appears inside the matching verified immutable `vX.Y.Z` entry\nin the live GitHub Releases list with its checksum manifest. Replace the\nplaceholder using the table above. Presence in source, CI, a branch, chat or\nissue is not publication. Use the first verified version in the table above\nand never guess a release-asset URL.\n\nOpening an official MCPB requests installation approval and the tracked-change\nauthor name; version 0.5.0 also asks for comment initials. Its first activation\nmay download a compatible Python runtime and\nlocked dependencies. The artifact is checksum-bound by `SHA256SUMS.txt`, but\nnot digitally signed.\n\n## Use Veqtor in local Codex\n\nThe [Codex setup guide](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/docs/CODEX.md)\nconnects the exact version selected above to local Codex over stdio. The\n[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)\nreuses saved positions, presents a selected-issue brief and prepares a separate\ntracked Word counterproposal after your decisions. That workflow requires\n`0.4.2` or later and its eleven document/position tools; `0.5.0` adds three\nauthor-drafting tools. The fallback `0.4.0` supports the historical\nnine-tool document workflow only.\n\nAfter installing [uv](https://docs.astral.sh/uv/), find its executable with\n`command -v uvx`. Replace the path and author below with your own values:\n\n```bash\ncodex mcp add veqtor --env 'VEQTOR_TRACKED_CHANGE_AUTHOR=Your Name' -- /absolute/path/to/uvx veqtor-mcp@X.Y.Z\n```\n\nRestart the MCP server or open a fresh Codex session, then use the guide's\nverification steps. Local Codex clients on the same host share MCP\nconfiguration; browser ChatGPT requires a separate connection.\n[Official OpenAI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp).\nRegistration alone does not establish a working document workflow. The guide\nseparates the historical public-package observations from pending acceptance of\nthe exact `0.5.0` package. Select a version only after both public verifiers pass.\n\n## Install a verified published version for Claude Code\n\nInstall [uv](https://docs.astral.sh/uv/) once, replace `X.Y.Z` using the table\nabove, then register that exact Veqtor version for your user account:\n\n```bash\nclaude mcp add --transport stdio --scope user veqtor -- uvx veqtor-mcp@X.Y.Z\n```\n\nOpen a new Claude Code session and verify the registration:\n\n```bash\nclaude mcp get veqtor\n```\n\n`--scope user` makes the private local registration available to you in every\nproject on this machine. It does not publish the configuration or make Veqtor a\nnetwork service. To limit Veqtor to the current project instead, use:\n\n```bash\nclaude mcp add --transport stdio --scope local veqtor -- uvx veqtor-mcp@X.Y.Z\n```\n\nFor team-managed configuration, Claude Code also supports `--scope project`,\nwhich writes `.mcp.json` for review and version control. Do not use project\nscope for secrets or matter-specific paths.\n\nTo set the tracked-change author when registering the server:\n\n```bash\nclaude mcp add --transport stdio --scope user veqtor -e VEQTOR_TRACKED_CHANGE_AUTHOR=\"Your Name\" -- uvx veqtor-mcp@X.Y.Z\n```\n\nIf unset, the author is `Veqtor MCP`. The value is fixed when the server starts\nand cannot be changed by the model per edit.\n\n## Run or install from the terminal\n\nRun diagnostics without a persistent installation:\n\n```bash\nuvx veqtor-mcp@X.Y.Z doctor\n```\n\nFor a persistent isolated installation:\n\n```bash\nuv tool install \"veqtor-mcp==X.Y.Z\"\n\"$(uv tool dir --bin)/veqtor-mcp\" --version\n\"$(uv tool dir --bin)/veqtor-mcp\" doctor\n```\n\nUsing `uv tool dir --bin` works even before the uv tool directory has been\nadded to the shell `PATH`. `uv tool update-shell` can add it for later shells.\nThe versioned wheel and sdist for independent verification are also attached to\nthe matching entry in the generic\n[GitHub Releases list](https://github.com/JohnDeer-ai/veqtor-mcp/releases).\n\n## Five-minute demo\n\nCreate a disposable four-round synthetic negotiation:\n\n```bash\nuvx --from \"veqtor-mcp==X.Y.Z\" veqtor-demo-rounds ~/veqtor-demo-rounds\n```\n\nThen ask Claude:\n\n> Using the veqtor tools, what happened to the limitation of liability across\n> the rounds in ~/veqtor-demo-rounds?\n\nFor a write workflow, ask:\n\n> Prepare our counterproposal as round-5-our-counter.docx: restore the 150%\n> affected Work Order liability cap and reinstate the willful misconduct\n> carve-out the counterparty deleted. Verify the wording and preflight the\n> complete batch before applying it.\n\nThe expected trust sequence is:\n\n1. extract the current redlines;\n2. verify every quotation used as evidence;\n3. preflight the complete atomic batch;\n4. apply only when `batch_applicable` is true — version `0.1.2` reuses the exact\n   edit payload, while contracts `veqtor.mcp.v0.2` through `veqtor.mcp.v0.4.2`\n   also pass the complete `preflight_proof` returned by that successful\n   preflight;\n5. re-extract the output and export the decision record.\n\nIn MCP contracts `veqtor.mcp.v0.2` through `veqtor.mcp.v0.4.2`, the proof binds\nthe source bytes, canonical edit payload, configured author, producer build and\npredicted candidate hash so apply can detect drift. It is an unkeyed content\nbinding, not authentication or a digital signature. Version `0.1.2` does not\nemit or accept this field.\n\nVeqtor never overwrites the source or an existing output file. Use a disposable\ndemo folder for write recordings; a successful write creates a new DOCX and a\nprivate `.veqtor` provenance folder.\n\n## Manual Claude Desktop setup\n\nGUI applications may not inherit the shell `PATH`. First run `command -v uvx`,\nthen use that absolute path in the macOS Claude Desktop configuration at\n`~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"veqtor\": {\n      \"command\": \"/absolute/path/to/uvx\",\n      \"args\": [\"veqtor-mcp@X.Y.Z\"],\n      \"env\": {\n        \"VEQTOR_TRACKED_CHANGE_AUTHOR\": \"Your Name\"\n      }\n    }\n  }\n}\n```\n\nQuit Claude Desktop fully and reopen it after changing the executable, version,\nor environment.\n\n## Tool surface\n\nThe descriptions below follow development package `0.6.0.dev1` and its\ntwenty-three-tool development MCP contract `veqtor.mcp.v0.6.0`. Public `0.4.0` retains the frozen\n`veqtor.mcp.v0.4` contract. For an\ninstalled version, use the API file carried by that exact artifact or its\nmatching immutable tag. Historical v0.3 artifacts retain their eight tools.\n\n- `list_rounds`: disclosed lexicographic filename order or a complete explicit\n  `ordered_filenames` positional manifest; neither is lineage proof.\n- `extract_redlines`: tracked-change units with hashes, references, bounded\n  paragraph context, conservative manual labels and a revision-inventory\n  partition.\n- `compare_incoming_version`: read-only comparison of two explicitly selected, hash-bound\n  versions, with complete paragraph membership and separate markup, table topology and\n  package-part observations. See [incoming comparison](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/docs/INCOMING_COMPARISON.md).\n- `read_document_tables`: complete bounded, snapshot-bound table/cell/paragraph\n  inventory and a read-only report of textual reference candidates and raw field nodes.\n- `check_bilingual_conditions`: Decimal/date/unit checks for explicitly selected\n  single-value condition pairs in selected language cells, with unsupported and\n  unpaired value coverage. Numeric agreement does not verify translation or\n  obligation equivalence. See [bilingual columns](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/docs/BILINGUAL_COLUMNS.md).\n- `inspect_document`: bounded outline, literal-search, browse and read views of\n  a mechanical accepted/current projection of main-body text, with every\n  returned paragraph bound to the exact file bytes. This reading mode does not\n  decide which wording has legal effect.\n- `map_rounds`: a bounded seed-centred map of recorded document-byte\n  derivation, complete exact paragraph equality, navigation candidates and\n  explicit unresolved/ambiguous states. It does not infer chronology, lineage,\n  deletion or restoration.\n- `trace_paragraph_history`: immutable capture of a complete direct-DOCX set\n  and a seed-first, paginated backward trace of one selected paragraph using\n  only exact current or rejected-pending projection equality. Selected rows\n  include paragraph-scoped change units; literal author/date metadata remains\n  explicitly unverified.\n- `preflight_edits`: the complete apply pipeline as an in-memory dry-run, with\n  closed position/failure diagnostics and a successful drift-binding proof.\n- `apply_edits`: atomic tracked replace, delete, counter and reinstate writes;\n  MCP contracts `veqtor.mcp.v0.2` through `veqtor.mcp.v0.4.2` require the\n  complete successful preflight proof; version `0.1.2` reuses the exact edit\n  payload without that new field.\n- `verify_quote`: anchored `exact`, `normalized`, or `not_found` verification,\n  with an optional paragraph selector for `accepted_current_v1` or\n  `pending_text_revisions_rejected_v1` and a closed\n  `verification_result.v2` result.\n- `export_decision_record`: compact privacy-aware local provenance.\n- `read_deal_positions`: bounded reads of saved negotiation positions and their\n  explicit confirmation state.\n- `mutate_deal_positions`: expected-revision position updates, confirmation and\n  withdrawal, independently of document edits.\n- `read_document_revisions` (unreleased `0.6.0.dev1`): exact main-document\n  revision inventory and accept/reject previews. Explicit `decide_revision`\n  operations cover supported text and all six property domains through the\n  existing preflight and same-file backup workflow. See the\n  [decision contract](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/docs/REVISION_DECISIONS.md).\n- `read_document_comments`: paginated comment text, authors, replies, thread status,\n  paragraph locations and source hash.\n- `preflight_document_edits`: dry-run text and paragraph changes, comments, replies\n  and thread status, bound to the selected author and the working document.\n- `apply_document_edits`: apply that unchanged proof and save in place with an\n  exact backup, or create a separate copy. A durable prepared operation precedes\n  publication; file verification and journal completion are separate outcomes.\n- `recover_document_operation`: observe an existing operation and complete a lost\n  journal result without applying edits again. See the\n  [operation journal](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/docs/OPERATION_JOURNAL.md).\n\nThe complete request, response and error contract is in the versioned\n[MCP Tool API](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/API.md). The\npublic `0.1.2` API remains available under its immutable release tag.\n\n## Privacy and assurance boundary\n\nThe server has no embedded model calls and does not upload whole documents in\nthe background. Text returned by a tool enters the MCP client conversation and\nmay be sent to the user's model provider under that provider's terms.\n\nUnless `VEQTOR_DISABLE_DECISION_RECORD=1`, tools append a private local journal\nat `<matter>/.veqtor/decision-records.jsonl`. Read-only calls, including\n`preflight_edits` and decision-record export, still normally write provenance\nthere. The path- and search-phrase-omission guarantee applies only to the\ncompact `export_decision_record` response. The raw journal retains the\nworkspace and caller-supplied paths, and may retain search phrases and other\nverbatim matter text; do not commit or share it.\n\nOptional provenance is disabled for a workspace inside `.veqtor` or\n`.veqtor-backups` (case-insensitive path components after resolving aliases).\nReading immutable round snapshots or retained backups therefore does not add a\nnested sidecar: successful reads return `record_id: null`, `record_status:\ndisabled`. An existing legacy journal there can be exported without appending\nan access event; an uninitialized folder remains refused. Nothing is redirected\nto a guessed parent matter or automatically repaired. Ordinary matter journals\nand the required drafting operation journal keep their existing behavior.\n\n`trace_paragraph_history` is success-only for journaling: a refusal before a\nvalid result writes no history record or sidecar. A later journal-publication\nfailure returns the complete valid result with `record_status: write_failed`.\nIts live result may contain bounded paragraph/change-unit text, paths,\nfilenames, headings and literal OOXML author/date strings. Its minimized raw\nrecord and compact export omit those values. Numeric or named author metadata\ndoes not verify who made a revision, and an OOXML date is not a trusted time.\n\nDecision-record export requires the exact initialized workspace. In the v0.2\ncontract a wrong parent is refused without creating a second\nsidecar; one direct child journal yields a path-safe relative suggestion and\nmultiple child journals are reported as ambiguous.\n\nDecision records are best-effort local provenance. Their hashes are\nre-checkable fingerprints, not authentication. The supported threat model is a\nsingle-user local workspace. Veqtor bounds and verifies the actual output of\nevery accepted DOCX/ZIP member (bounded streaming for DEFLATED data and a\nbounded direct span for STORED data), but this does not turn it into a sandbox\nfor hostile same-user processes.\n\n## Supported surface\n\n| Surface | Public Alpha |\n|---|---|\n| Operating systems | macOS, Linux |\n| Python | 3.12, 3.13, 3.14 |\n| Transport | local stdio MCP; modern `2026-07-28` and legacy through `2025-11-25` |\n| 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.5.0 |\n| DOCX part | `word/document.xml` |\n| Writes | tracked replace, delete, counter, reinstate |\n| Distribution | Versioned PyPI packages with matching immutable GitHub wheel/sdist/checksums; macOS MCPB only when attached to the matching verified release |\n\nWindows, hosted MCP, comments/headers/footnotes, accept/reject, semantic\ncross-round lineage and cryptographic audit guarantees are outside the Alpha.\nThe client row applies only to an exact version whose release artifacts passed\nthe documented client gate; source and CI coverage alone do not establish that\nstatus. The Codex observation is a separate maintainer CLI check, with one\nrecovered read error and a documented SDK 2.2 error-message limitation; it does\nnot establish Desktop, browser ChatGPT, or clean-user acceptance.\n\n## Support\n\nVeqtor MCP is a community-supported public Alpha. Use\n[GitHub Issues](https://github.com/JohnDeer-ai/veqtor-mcp/issues) for\nreproducible bugs and feature requests, using synthetic documents only. Never\npost client wording, local paths, `.veqtor` journals, credentials, or real\nmatter files. Report suspected vulnerabilities privately as described in\n[security policy](https://github.com/JohnDeer-ai/veqtor-mcp/security/policy).\n\nNo response-time, compatibility, uptime, or fix-time SLA is provided.\n\n## Development and releases\n\n### Development checks\n\nRun these checks for ordinary development changes, including development\nversions such as `X.Y.Z.devN`:\n\n```bash\nuv lock --check\nuv sync --frozen --all-extras\nuv run --frozen pytest -q\nuvx ruff==0.15.21 check .\nLOCKED_REQUIREMENTS=\"$(mktemp)\"\nuv export --frozen --no-dev --no-emit-project \\\n  --format requirements-txt --output-file \"$LOCKED_REQUIREMENTS\"\nuvx pip-audit==2.10.1 --requirement \"$LOCKED_REQUIREMENTS\" \\\n  --require-hashes --disable-pip --progress-spinner off\nuv build --clear\nuvx twine check dist/*.whl dist/*.tar.gz\n```\n\n### Frozen-release checks\n\nAfter the development checks, run the following only when `[project].version`\nexactly matches `scripts/release_contract.py::VERSION`. The frozen commands\nintentionally reject a development-only tree whose package and release\nidentities differ. The full immutable publication workflow is documented in\nthe [release guide](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/RELEASING.md).\n\n```bash\nuv run --frozen python scripts/build_mcpb.py \\\n  --source-root . --out-dir dist --stage-dir /tmp/veqtor-mcpb-stage\nuv run --frozen python scripts/check_release_artifacts.py \\\n  --source-root . --commit HEAD dist/*.whl dist/*.tar.gz\nuv run --frozen python scripts/check_mcpb_artifact.py \\\n  --source-root . --commit HEAD dist/*.mcpb\nnpx --yes @anthropic-ai/mcpb@2.1.2 validate \\\n  /tmp/veqtor-mcpb-stage/manifest.json\n```\n\nContributions use DCO sign-off; see the\n[contributing guide](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/CONTRIBUTING.md).\nThe exact-SHA immutable publication contract is documented in the\n[release guide](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/RELEASING.md).\n\n## Maintainer\n\nVeqtor MCP is an independent open-source project created and maintained by\n**[Ilya Shilov](https://ilyashilov.com/)** ([@JohnDeer-ai](https://github.com/JohnDeer-ai)).\n\n## Deal positions in the release candidate\n\nNR-02 adds `read_deal_positions` and `mutate_deal_positions`: retain desired\noutcomes, conditional concessions, linked positions and business questions in\nan explicitly selected local matter. Show the user the exact proposed versions,\nthen record their explicit confirmation. Updating content resets confirmation;\nwithdrawal preserves history. A new session can recover complete saved wording.\n\nThe private bounded snapshot moves with the matter folder and is independent of\n`export_decision_record`. Source freshness, confirmation, business status and\nlifecycle remain separate. Saved wording is data, not an instruction or authority\nto edit Word. See [the NR-02 contract](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/NR-02_DEAL_POSITIONS.md) and\n[API](https://github.com/JohnDeer-ai/veqtor-mcp/blob/main/API.md#read_deal_positions). Exact-candidate native acceptance remains a\nseparate gate; the published 0.4.0 installation does not contain these tools.\n"}