MCP Merge & Combine Tools

Fold several revisions into one Word document with tracked changes labeled by where they came from.

Two related operations, and picking the right one matters.

Merge is for revisions of a shared original: three people each edited contract.docx and you want one document holding all their edits. Each revision is diffed against that common base, which produces a clean result.

Combine is for documents with no shared original: three people each drafted from scratch. There is no base to diff against, so the engine constructs one by folding the documents into each other. Prefer merge whenever a shared base exists.

Both produce a single Word document in which every edit is a tracked change labeled by the version it came from, so each can be accepted or rejected in Word. Both are order-independent: where revisions conflict, every edit appears as a tracked change attributed to its source.

create_merge

Parameter	Type	Default	Meaning
`base_file_path`	string	—	Path to the base document every revision was edited from
`base_file_name`	string	—	Display name for the base
`next_version_file_paths`	string[]	—	Paths to the revised versions — at least two
`next_version_file_names`	string[]	—	Display names, in the same order
`next_version_authors`	string[]	—	Author label per revision, in the same order. Defaults to the account's author label
`merged_file_name`	string	`Merged <base name>`	Name for the result
`version_story_name`	string	—	Name for a new project
`version_story_id`	string	—	Add to an existing project

Every revision must be an independent edit of the same base. Two or more revisions are required — with a single revision the base-to-revision redline already is the combined document, so use compare instead.

next_version_authors, when given, must have exactly as many entries as there are revisions. It is what makes the result readable: without it every change carries the same author label and you lose the ability to tell whose edit is whose.

Response

{
  "status": "awaiting_uploads",
  "version_story_id": "uuid",
  "version_story_name": "Acme MSA",
  "version_story_url": "https://app.versionstory.com/version-story/<id>",
  "upload_manifest_url": "https://... (signed, 1 hour)",
  "uploads": [{ "role": "base", "file_name": "msa.docx", "upload_url": "...", "authorization": "..." }],
  "staged_file_names": ["msa.docx", "msa_legal.docx", "msa_finance.docx"],
  "merge": {
    "merge_version_id": "uuid",
    "merge_mapping_id": "uuid",
    "merged_file_name": "Merged msa.docx",
    "merged_document_url": "https://app.versionstory.com/..."
  }
}

Transfer each source file with a PUT as described in Transferring files. Merge generation begins once the uploads land and the underlying comparisons finish.

get_merged_document

Parameter	Type	Required	Meaning
`version_story_id`	string	Yes	The project holding the merge
`merge_version_id`	string	Yes	From the create response's `merge.merge_version_id`

Merging generates a comparison of each revision against the base and then folds those redlines together, so processing may come back several times — several minutes is normal. Call again with identical arguments to keep waiting.

A processing response carries comparison_statuses, listing each underlying comparison's file name and generation status, so you can see how far along it is.

Response — ready

{
  "status": "ready",
  "version_story_id": "uuid",
  "merge": { "merge_version_id": "uuid", "merged_file_name": "Merged msa.docx" },
  "downloads": [{ "option": "merged_docx", "file_name": "Merged msa.docx" }],
  "text_url": "https://... (signed, 1 hour)",
  "text_file_name": "Merged msa.md",
  "download_manifest_url": "https://... (signed, 1 hour)"
}

merged_docx is the only output format — there is no PDF rendering of a merge. Fetch download_manifest_url for the actual download URL, and save it as binary.

text_url is a markdown rendering of the merged document's tracked changes, useful for analysis. In a merged document, adjacent changes from different revisions competing over the same text are wrapped in <conflict id="1"> elements — see Reading the changes.

A failed status is terminal and lists causes in errors; waiting again does not regenerate the merge. awaiting_uploads lists the untransferred sources in missing_uploads.

create_combine

Same shape, no base.

Parameter	Type	Default	Meaning
`document_file_paths`	string[]	—	Paths to the documents — at least two
`document_file_names`	string[]	—	Display names, in the same order
`document_authors`	string[]	—	Author label per document, in the same order
`combined_file_name`	string	`Combined document`	Name for the result
`version_story_name`	string	—	Name for a new project
`version_story_id`	string	—	Add to an existing project

The response mirrors merge's, with a combine descriptor carrying combine_version_id and combined_document_url.

get_combined_document

Parameter	Type	Required	Meaning
`version_story_id`	string	Yes	The project holding the combine
`combine_version_id`	string	Yes	From the create response's `combine.combine_version_id`

Identical semantics to get_merged_document. The download option is combined_docx.