feat: Documents MCP tools (create-from-template, versions, share, public link, shortcuts, favorites) - EXO-88456 - #2021
Open
Jihed525 wants to merge 1 commit into
Open
Conversation
…lic link, shortcuts, favorites) - EXO-88456 (#2001) * feat: Relocate Document MCP tools into the Documents add-on Move the generic document MCP tools out of the enterprise distribution into the open Documents add-on so they ship in all editions. - Add DocumentMcpTool (@service @Profile("mcp-server")) exposing the 9 document tools (get_root_folder_by_space, attach_document_to_content, update_document_description, get_documents_by_folder_id, get_root_folder_for_user, get_document_by_id, get_document_content_by_id, get_document_transcription_by_id, search_documents) as the current user. - get_document_transcription_by_id is now a plain read of the stored transcription (DocumentFileService.getAudioTranscription) with no ai-agent-service coupling; on-demand AI transcription stays enterprise. - Add documents-services ai-tool-definitions.json with the 9 tool entries. - documents-services: add mcp-server-tools (provided), ecms-core-services (AttachmentService), notes-service (NoteService) and the -parameters javac flag required for MCP argument binding by name. The AI-experience layer (UX bindings, curated prompts, auto-transcription listener) intentionally remains in the enterprise edition. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix: Move Document MCP model records into the Documents add-on The relocated DocumentMcpTool imported DocumentModel / DocumentFileModel / DocumentFolderModel from org.exoplatform.documents.model, but those three records were left behind in the enterprise edition, so documents-services failed to compile ("cannot find symbol"). Bring them into the add-on under org.exoplatform.documents.mcp.model (co-located with the tool, mirroring the poll add-on's io.meeds.poll.mcp.model layout) instead of splitting the org.exoplatform.documents.model package across the api and services jars. Update the imports in DocumentMcpTool accordingly. Add DocumentMcpToolTest (13 cases, JUnit 4 like the rest of the module) so the new tool methods keep the module above its 0.55 coverage gate. No AI (io.meeds.ai / ai-agent-service) dependency is introduced. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat: Add v1 batch of Documents MCP tools (folders, versions, content management) Extend DocumentMcpTool with 15 new MCP tools acting as the current user (ACL enforced by DocumentFileService): Reads: list_folder_children, get_folder_breadcrumb, get_folder_tree, list_document_versions, get_documents_size. Writes (require_approval): create_folder, rename_document, move_document, copy_document, duplicate_document, delete_document (trash only, delay=0), undo_delete_document, restore_document_version, update_version_summary, set_document_visibility. Adds thin model records (BreadcrumbItemModel, DocumentVersionModel, DocumentTreeItemModel, DocumentsSizeModel), matching ai-tool-definitions.json entries, and DocumentMcpToolTest coverage. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix: create_folder under root folder fails in Documents MCP tools The JCR storage createFolder/getBreadcrumb resolve the parent from the node id (folderId) and treat 'folderPath' as a RELATIVE sub-path from that node (node.getNode(folderPath) / getNodeByPath). DocumentMcpTool was passing the parent node's ABSOLUTE JCR path, so creating a folder under the user's ROOT folder failed with ObjectNotFoundException: Folder with path : /Users/.../Private isn't found. Pass null as folderPath in createFolder and getFolderBreadcrumb since the folder id already identifies the JCR node uniquely. move/delete keep passing absolute paths (the storage uses them as absolute JCR paths). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat: Add create_document/upload_document MCP tools using UploadToolUtils - EXO-88354 create_document turns chat-authored text/markdown/HTML into a real DMS file; upload_document imports a binary file from base64 or an SSRF-guarded URL fetch. Both stage the bytes via UploadToolUtils.materialize, wrap them in a one-entry zip (importFiles unzips), import into the target folder as the current user, and poll the folder to return the created document. Pins mcp-server-tools to the ai-contribution build that ships UploadToolUtils. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat: upload_document accepts chat attachments + create_document honors mime_type - EXO-88354 upload_document now declares attachment_object_type/attachment_object_id so EVA forwards a chat-attached file/image; the bytes are resolved server-side as the current user (ACL enforced) via UploadToolUtils.resolveImage's attachment branch (no image-only constraint), keeping the existing base64/url paths. create_document forces the requested mime_type on the stored file via a new DocumentFileService/Storage updateDocumentMimeType (JCR jcr:content/jcr:mimeType), fixing .md files that importFiles left as application/octet-stream. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * revert: drop JCR mime-forcing in create_document; content-type follows file extension - EXO-88354 The prior commit forced the requested mime_type onto the stored file via a new DocumentFileService/Storage updateDocumentMimeType that opened a JCR session and set jcr:content/jcr:mimeType. Revert that JCR plumbing entirely: create_document's stored content type now follows the file extension (resolved by the platform MimeTypeResolver), the pre-fix behavior. The mime_type param is kept but is advisory (extension inference only). The upload_document chat-attachment support is untouched. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor: use renamed UploadToolUtils.FetchedContent - EXO-88354 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat: clear error messages for create_document/upload_document bad input - EXO-88354 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor: drop mime_type from create_document; require a filename with extension - EXO-88354 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat: add version, share, public-link, shortcut and favorite Documents MCP tools Adds six new MCP tools to DocumentMcpTool, each acting as the current user (ACLs enforced) with a matching ai-tool-definitions.json entry and tests: - add_document_version: uploads updated content onto an existing file as a new version via DocumentFileService.createNewVersion (checkout -> set jcr:content -> checkin/VersionHistoryUtils.createVersion), from text/base64/url/chat attachment, with an optional version summary stamped on the new current version. - create_public_link: PublicDocumentAccessService.createPublicDocumentAccess, returning the /portal/download-document/{nodeId} shareable link. - create_document_shortcut: DocumentFileService.createShortcut into a resolved destination folder path. - share_document: DocumentFileService.shareDocument with a user or a space. - favorite_document / unfavorite_document: social FavoriteService with the "document"/"folder" object types. All writes require approval and pre-check edit permission where applicable. Skipped by design: list_trash (admin-only global trash, no per-user scope), share permission levels (service exposes no clean granular API), and create_document_from_template (still no ECMS service method; tracked on #88422). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix: correct integration bugs in Documents MCP tools (conflict values, copy/duplicate return, favorites type, filters, size, share permissions, undo-delete, import conflict) - EXO-88354 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat: add create_document_from_template MCP tool (delegates to ecms DocumentService) - EXO-88354 Adds a Documents MCP tool that creates a new empty office document (Word/Excel/PowerPoint, + ODF when the editor add-on provides it) from the platform's blank template, by delegating to the ecms DocumentService rather than re-implementing template/office logic. - documents-storage-jcr: inject DocumentService, add createDocumentFromTemplate mirroring createFolder (session/parent/ACL), resolve the template by matching NewDocumentTemplate.getExtension against the requested type, then call ecms createDocumentFromTemplate. - documents-api / documents-services: propagate the new storage/service signatures. - DocumentMcpTool.createDocumentFromTemplate + ai-tool-definitions entry (require_approval, document_type enum). ecms does NOT append the extension, so the tool builds a title that ends with '.<type>'. Softened create_document's office-format rejection to point at the new tool. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix: re-verify follow-ups — template extension match, share no-downgrade, undo-delete system session, favorite docs - EXO-88354 Fix 1: create_document_from_template never matched a template because onlyoffice stores extensions with a leading dot (".docx") while the caller's type is dot-stripped ("docx"). Normalize the dot on both sides of the compare in JCRDocumentFileStorage. Trim supported types to docx/xlsx/pptx (the 3 the editor add-on actually ships) in DocumentMcpTool and ai-tool-definitions.json. Fix 2: share_document silently downgraded an existing editor to read because it always appended (recipient,"read") after the preserved (recipient,"edit"), and storage writes permissions in list order. Only add the read grant when the recipient is not already a collaborator. Fix 3: undo_delete_document resolved the trashed node via the user-session overload, but trash lives under a system session, so it false-negatived with a misleading "permanently deleted" error. Use the system-session getDocumentById overload. Fix 4: favorite/unfavorite descriptions and Javadoc advertised "file or folder" though folders are rejected. Correct to files-only wording. Adds regression tests: template dotted-extension match (storage), share edit-preservation, and undo-delete via the system-session overload. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix: resolve created document by name with an ambiguity guard instead of a blind folder-diff (boubaker review, MCP-only) - EXO-88354 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix: adapt DocumentMcpTool to the new UploadToolUtils.ImageSource API mcp-server's develop refactored UploadToolUtils.resolveImage, replacing the four loose imageUrl/imageBase64/attachmentObjectType/attachmentObjectId parameters with a single ImageSource record. Now that feature/ai-contribution tracks that version, the old eight-argument calls no longer compile. Wrap the four values in ImageSource at both call sites. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> (cherry picked from commit b3b3d4a)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Backport of #2001 onto
develop.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(viaDocumentService)Companion PR: exoplatform/onlyoffice#342 (backport
backport/EXO-88456-onlyoffice-mcp-tools), same ticket EXO-88456. Also related: platform-private-distributions#588, which removes the now-duplicated enterprise-only tool once these land.Backport notes
Cherry-picked the squashed source commit
b3b3d4ab(16 commits squashed into the merge tofeature/ai-contribution) ontodevelop, with one manual conflict inpom.xml/module poms:addon.exo.jcr.versionand a newly-addedaddon.exo.ecms.versionto the branch-specific7.3.x-ai-contribution-SNAPSHOTline, andmcp-server-toolsto the same line with a comment noting "the platform-managed 7.3.x-SNAPSHOT does not have it yet" (referring toUploadToolUtils).develop, keptaddon.exo.jcr.versionuntouched (7.3.x-SNAPSHOT) and pinned the newaddon.exo.ecms.version/mcp-server-toolsversion to the regular7.3.x-SNAPSHOTline instead of the ai-contribution fork.mcp-server's currentdevelop(7.3.x-SNAPSHOT) already shipsUploadToolUtils(ImageSource,FetchedContent,resolveImage,materialize) — that comment is stale, the API has since landed on mainlinemcp-serverdevelop via prior backports (EXO-88348).Test
mvn -pl documents-api,documents-storage-jcr,documents-services -am -Dcheckstyle.skip=true -Dlicense.skip=true -DskipTests compile→ BUILD SUCCESS (against the regular7.3.x-SNAPSHOTdependency line, not the ai-contribution fork)mvn -pl documents-services -Dcheckstyle.skip=true -Dlicense.skip=true -Dtest=DocumentMcpToolTest test→ 85 tests, 0 failures/errors🤖 Generated with Claude Code