feat: Documents MCP tools (create-from-template, versions, share, public link, shortcuts, favorites) - EXO-88456

[bmestrallet]

What

Adds Documents MCP tools for the EVA AI agent (delegating to the ecms/documents services), acting as the current user (ACL-enforced):

• create_document_from_template (via DocumentService)
• document version tools, share + public-link tools, shortcut creation, and favorite documents
• create/copy/duplicate/move/rename, filters, size, import — with integration fixes (conflict values, copy/duplicate return, favorites type, share no-downgrade, undo-delete via system session, template extension match)

Dependency / CI

documents-services consumes io.meeds.mcp-server:mcp-server-tools — if pinned to the *-ai-contribution-SNAPSHOT line, CI will be red until mcp-server #13 (UploadToolUtils, EXO-88348) merges and a consuming version is published.

Related

Companion office-side PR exoplatform/onlyoffice#342 (also EXO-88354).

Board: EXO-88354.

🤖 Generated with Claude Code

[boubaker]

Code review

🟡 Medium — resolveAddedChildFile's "last new file" heuristic can return the wrong document under concurrent writes

DocumentMcpTool.java:1382-1395:

return children.stream()
               .filter(FileNode.class::isInstance)
               .map(FileNode.class::cast)
               .filter(file -> !beforeFileIds.contains(file.getId()))
               .reduce((first, second) -> second)   // assumes at most one file was added since the snapshot
               .map(this::toDocumentFileModel)
               .orElse(null);

This backs copyDocument and duplicateDocument (whose underlying storage calls return the destination/parent folder, not the new node — a real limitation the comments call out) and importContent/findImportedDocument behind create_document/upload_document. It snapshots the folder's file ids, calls the storage op, then diffs — but if any other file lands in that same folder between the snapshot and the re-read (a teammate uploading into a shared space folder, another concurrent copy/import, the polling loop's own retries), the diff contains more than one id and this silently returns whichever one the stream produced last — the wrong document, reported to the caller/AI-agent as "the copy you asked for."

Only the single-new-file case is tested (copyDocumentReturnsResolvedCopyNotDestinationFolder, duplicateDocumentReturnsResolvedDuplicateNotParentFolder in DocumentMcpToolTest); nothing exercises "two files added between snapshot and read."

Fix: narrow the diff further (e.g. match on name in addition to "not in before-set"), or — the more durable fix — have the storage layer return the actual created/copied/duplicated node so no snapshot-diff heuristic is needed at all.

---

🟢 Nit — attachDocumentToContent skips the id validation every sibling method applies

DocumentMcpTool.java:216-221:

public void attachDocumentToContent(String documentId, String contentType, long contentId) throws IllegalAccessException {
  // FIXME Why using this content type name ??!!
  contentId = fixNoteContentId(contentType, contentId);
  // FIXME Why using this content type name ??!!
  contentType = fixNoteContentType(contentType);
  attachmentService.linkAttachmentToEntity(getCurrentUserIdentityId(), contentId, contentType, documentId);
}

Every other document-touching method in this class opens with checkDocumentIdParameter/checkCanAccessDocument (or both); this one uses documentId straight from the AI agent with no blank/existence check. Impact looks low — it can only create a dangling attachment link, since any later read of the referenced document still goes through DocumentFileService's own ACL — but it's the one inconsistency in an otherwise very deliberately validated class, and the two carried-forward FIXME Why using this content type name ??!! comments suggest this corner was copied as-is rather than revisited.

---

This is a careful, well-tested PR: each of the "integration fixes" called out in the description has a dedicated regression test that fails without the fix and passes with it — createDocumentFromTemplateMatchesDottedExtension (onlyoffice's dotted extension), createNewVersionAddsVersionableMixinWhenMissing (silent no-op on non-versionable files), shareDocumentDoesNotDowngradeExistingEditor (no-downgrade on re-share), and the copy/duplicate resolution tests above. The undo_delete_document system-session rationale and the share_document no-downgrade logic are both explained in-line with the actual mechanism they work around, not just what changed — makes this easy to trust and to revisit later.

🤖 Generated with Claude Code

[bmestrallet]

@boubaker — fixed MCP-only, no storage/JCR changes (commit 0303f3c):

• 🟡 Medium — replaced the .reduce((first,second) -> second) "last new file" guess. resolveAddedChildFile now narrows the folder-diff to the file matching the expected name — I matched the actual JCR naming (source exo:title + the " (n)" clash counter, plus the duplicate prefix; FileNode.getName() returns the title), so a concurrent different-named upload can no longer be picked. And if more than one candidate still matches, it throws a clear error instead of silently guessing (0 matches for copy/duplicate → an explicit "could not locate" error). Applied to copyDocument, duplicateDocument, and the import/create path.
• Nit — attachDocumentToContent now calls checkCanAccessDocument(documentId) up front (id + ACL), matching every sibling method.
• Tests: copy/duplicate/import each with a concurrent differently-named file added around the op (assert the correct node), the ambiguity guard (two matches → clear throw), and blank-id attach. Each fails against the pre-fix heuristic; 85 green.

I deliberately kept the storage/JCR layer untouched — resolving deterministically-by-name at the MCP layer with an honest error for the rare true same-name collision, rather than changing the shared copyDocument/duplicateDocument return contract that the REST paste() path relies on.