Package org.exoplatform.documents.mcp

Class DocumentMcpTool

java.lang.Object

org.exoplatform.documents.mcp.DocumentMcpTool

All Implemented Interfaces:

io.meeds.mcp.server.plugin.McpToolPlugin

@Service
@Profile("mcp-server")
public class DocumentMcpTool
extends Object
implements io.meeds.mcp.server.plugin.McpToolPlugin

MCP tools exposing the Documents (DMS) add-on to the AI agent (EVA). Every method acts as the current user, so document ACLs are enforced by DocumentFileService. These tools only READ or update document metadata / content; they carry no coupling to the AI service layer (the AI-powered document experiences remain in the enterprise edition).

Field Summary

Fields

Modifier and Type	Field	Description
static final String	FILE_URL_FORMAT
static final String	FOLDER_URL_FORMAT
static final String	PUBLIC_LINK_URL_FORMAT	Path of the anonymous public-download portal page (global page download-document); the document node id is appended as an extra path segment, mirroring how the Documents front-end builds the shareable link ({origin}/{containerName}/download-document/{nodeId}).

Fields inherited from interface io.meeds.mcp.server.plugin.McpToolPlugin

DEFAULT_LIMIT, DEFAULT_OFFSET

Constructor Summary

Constructors

Constructor

Description

DocumentMcpTool(org.exoplatform.documents.service.DocumentFileService documentFileService, org.exoplatform.services.attachments.service.AttachmentService attachmentService, org.exoplatform.social.attachment.AttachmentService socialAttachmentService, org.exoplatform.commons.file.services.FileService fileService, org.exoplatform.social.core.manager.IdentityManager identityManager, org.exoplatform.social.core.space.spi.SpaceService spaceService, io.meeds.social.translation.service.TranslationService translationService, org.exoplatform.social.core.profileproperty.ProfilePropertyService profilePropertyService, org.exoplatform.portal.config.UserACL userAcl, org.exoplatform.portal.config.UserPortalConfigService portalConfigService, org.exoplatform.upload.UploadService uploadService, org.exoplatform.documents.service.PublicDocumentAccessService publicDocumentAccessService, org.exoplatform.social.metadata.favorite.FavoriteService favoriteService)

Method Summary

Modifier and Type	Method	Description
DocumentModel	addDocumentVersion(String documentId, String content, String base64, String url, String attachmentObjectType, String attachmentObjectId, String versionSummary)	Uploads updated content onto an EXISTING file, creating a NEW version of it (the previous content stays retrievable via list_document_versions / restore_document_version).
void	attachDocumentToContent(String documentId, String contentType, long contentId)	Links an existing document to another content entity (an activity, a note, …) as an attachment, acting as the current user.
DocumentModel	copyDocument(String documentId, String destinationFolderId)
DocumentModel	createDocument(String parentFolderId, String name, String content)	Creates a text-based document (markdown, HTML, plain text, CSV, JSON…) from a chat-authored content string.
DocumentModel	createDocumentFromTemplate(String parentFolderId, String name, String documentType)	Creates a NEW EMPTY office document (Word/Excel/PowerPoint, or ODF) from the platform's blank template, by delegating to the ecms DocumentService.
void	createDocumentShortcut(String documentId, String destinationFolderId, String conflictAction)	Creates a shortcut (symlink) to a document inside another folder, so the same file appears in a second location without being copied.
DocumentModel	createFolder(String parentFolderId, String name)
DocumentPublicLinkModel	createPublicLink(String documentId, String password, Long expirationDate)	Creates (or refreshes) an anonymous public share link for a document so it can be downloaded without signing in, optionally protected by a password and/or an expiration date.
void	deleteDocument(String documentId)
DocumentModel	duplicateDocument(String documentId, String prefix)
void	favoriteDocument(String documentId)	Adds a file to the current user's favorites.
DocumentModel	getDocumentById(String documentId)
String	getDocumentContentById(String documentId)	Returns the text of a document the current user can access: from the search index when it holds it, else extracted from the file itself.
List<DocumentModel>	getDocumentsByFolderId(String folderId, Boolean filesOnly, Boolean foldersOnly, Integer offset, Integer limit)
DocumentsSizeModel	getDocumentsSize(Long ownerId)
String	getDocumentTranscriptionById(String documentId)
List<BreadcrumbItemModel>	getFolderBreadcrumb(String folderId)
List<DocumentTreeItemModel>	getFolderTree(String folderId, Boolean withChildren)
DocumentFolderModel	getRootFolderBySpace(long spaceId)
DocumentFolderModel	getRootFolderForUser()
List<DocumentVersionModel>	listDocumentVersions(String documentId)
List<DocumentModel>	listFolderChildren(String folderId, Integer offset, Integer limit)
void	moveDocument(String documentId, String destinationFolderId, String conflictAction)
void	renameDocument(String documentId, String newName)
DocumentVersionModel	restoreDocumentVersion(String versionId)
List<DocumentFileModel>	searchDocuments(String query, Long spaceId, String parentFolderId, Integer offset, Integer limit, Boolean isFavorites)
void	setDocumentVisibility(String documentId, Boolean hidden)
void	shareDocument(String documentId, String username, Long spaceId, Boolean notify)	Shares a document with another user or with a space: the recipient is GRANTED read access to the file and gets it in their "Shared" folder.
void	undoDeleteDocument(String documentId)	Restores a document that was deleted with delete_document: since that tool trashes immediately (delay 0), the delayed-delete cancel path is a no-op, so the node is resolved from trash (it keeps its id/uuid after the move) and restored to its original location.
void	unfavoriteDocument(String documentId)	Removes a file from the current user's favorites.
void	updateDocumentDescription(String documentId, String htmlDescription)
DocumentVersionModel	updateVersionSummary(String documentId, String versionId, String summary)
DocumentModel	uploadDocument(String parentFolderId, String name, String base64, String url, String attachmentObjectType, String attachmentObjectId)	Uploads a real / binary document (PDF, image, office file…) from exactly one of three sources: a file/image the user attached in the chat conversation (resolved server-side as the current user via attachment_object_type / attachment_object_id), a base64 payload, or an http(s) URL (fetched server-side behind an SSRF guard).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.meeds.mcp.server.plugin.McpToolPlugin

getCurrentUserAclIdentity, getCurrentUserLocale, getCurrentUserLocale, getCurrentUserName, getLocale

Field Details

FOLDER_URL_FORMAT

public static final String FOLDER_URL_FORMAT

See Also:

• Constant Field Values

FILE_URL_FORMAT

public static final String FILE_URL_FORMAT

See Also:

• Constant Field Values

PUBLIC_LINK_URL_FORMAT

public static final String PUBLIC_LINK_URL_FORMAT

Path of the anonymous public-download portal page (global page download-document); the document node id is appended as an extra path segment, mirroring how the Documents front-end builds the shareable link ({origin}/{containerName}/download-document/{nodeId}).

See Also:

• Constant Field Values

Constructor Details

DocumentMcpTool

public DocumentMcpTool(org.exoplatform.documents.service.DocumentFileService documentFileService,
 org.exoplatform.services.attachments.service.AttachmentService attachmentService,
 org.exoplatform.social.attachment.AttachmentService socialAttachmentService,
 org.exoplatform.commons.file.services.FileService fileService,
 org.exoplatform.social.core.manager.IdentityManager identityManager,
 org.exoplatform.social.core.space.spi.SpaceService spaceService,
 io.meeds.social.translation.service.TranslationService translationService,
 org.exoplatform.social.core.profileproperty.ProfilePropertyService profilePropertyService,
 org.exoplatform.portal.config.UserACL userAcl,
 org.exoplatform.portal.config.UserPortalConfigService portalConfigService,
 org.exoplatform.upload.UploadService uploadService,
 org.exoplatform.documents.service.PublicDocumentAccessService publicDocumentAccessService,
 org.exoplatform.social.metadata.favorite.FavoriteService favoriteService)

Method Details

getRootFolderBySpace

public DocumentFolderModel getRootFolderBySpace(long spaceId)
                                         throws org.exoplatform.commons.exception.ObjectNotFoundException,
IllegalAccessException

Throws:

org.exoplatform.commons.exception.ObjectNotFoundException

IllegalAccessException

attachDocumentToContent

public void attachDocumentToContent(String documentId,
 String contentType,
 long contentId)
                             throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Links an existing document to another content entity (an activity, a note, …) as an attachment, acting as the current user. Validates the document id and the user's read access on it first — matching every sibling tool method — so a blank or inaccessible id fails cleanly instead of reaching the attachment service with an unchecked reference.

Parameters:

documentId - the id of the document to attach

contentType - the target content type the document is attached to

contentId - the target content id the document is attached to

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

updateDocumentDescription

public void updateDocumentDescription(String documentId,
 String htmlDescription)
                               throws IllegalAccessException,
Exception

Throws:

IllegalAccessException

Exception

getDocumentsByFolderId

public List<DocumentModel> getDocumentsByFolderId(String folderId,
 Boolean filesOnly,
 Boolean foldersOnly,
 Integer offset,
 Integer limit)
                                           throws org.exoplatform.commons.exception.ObjectNotFoundException,
IllegalAccessException

Throws:

org.exoplatform.commons.exception.ObjectNotFoundException

IllegalAccessException

getRootFolderForUser

public DocumentFolderModel getRootFolderForUser()

getDocumentById

public DocumentModel getDocumentById(String documentId)
                              throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

getDocumentContentById

public String getDocumentContentById(String documentId)
                              throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Returns the text of a document the current user can access: from the search index when it holds it, else extracted from the file itself. When neither gives any text, the actual reason is raised rather than an empty answer, so the agent can tell the user why instead of guessing from the file name.

The reason never claims the file is still being indexed: the search index service exposes no way to know whether an indexing operation is pending for a file, and the file itself was just read without success. Only a busy extractor, a fact known for certain, is worded as worth another attempt.

Parameters:

documentId - the document identifier

Returns:

the text of the document

Throws:

IllegalAccessException - when the user cannot access the document

org.exoplatform.commons.exception.ObjectNotFoundException - when the document does not exist

IllegalStateException - when the document has no readable text, with the reason

getDocumentTranscriptionById

public String getDocumentTranscriptionById(String documentId)
                                    throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

searchDocuments

public List<DocumentFileModel> searchDocuments(String query,
 Long spaceId,
 String parentFolderId,
 Integer offset,
 Integer limit,
 Boolean isFavorites)
                                        throws org.exoplatform.commons.exception.ObjectNotFoundException,
IllegalAccessException

Throws:

org.exoplatform.commons.exception.ObjectNotFoundException

IllegalAccessException

listFolderChildren

public List<DocumentModel> listFolderChildren(String folderId,
 Integer offset,
 Integer limit)
                                       throws org.exoplatform.commons.exception.ObjectNotFoundException,
IllegalAccessException

Throws:

org.exoplatform.commons.exception.ObjectNotFoundException

IllegalAccessException

getFolderBreadcrumb

public List<BreadcrumbItemModel> getFolderBreadcrumb(String folderId)
                                              throws org.exoplatform.commons.exception.ObjectNotFoundException,
IllegalAccessException

Throws:

org.exoplatform.commons.exception.ObjectNotFoundException

IllegalAccessException

getFolderTree

public List<DocumentTreeItemModel> getFolderTree(String folderId,
 Boolean withChildren)
                                          throws org.exoplatform.commons.exception.ObjectNotFoundException,
IllegalAccessException

Throws:

org.exoplatform.commons.exception.ObjectNotFoundException

IllegalAccessException

listDocumentVersions

public List<DocumentVersionModel> listDocumentVersions(String documentId)
                                                throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

getDocumentsSize

public DocumentsSizeModel getDocumentsSize(Long ownerId)
                                    throws org.exoplatform.commons.exception.ObjectNotFoundException,
IllegalAccessException

Throws:

org.exoplatform.commons.exception.ObjectNotFoundException

IllegalAccessException

createFolder

public DocumentModel createFolder(String parentFolderId,
 String name)
                           throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

createDocument

public DocumentModel createDocument(String parentFolderId,
 String name,
 String content)
                             throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Creates a text-based document (markdown, HTML, plain text, CSV, JSON…) from a chat-authored content string. This is the chat-native way to turn generated text into a real file in the Documents app. The name must include a file extension: the extension drives the stored content type via the platform MimeTypeResolver, so use a registered text extension (.txt, .html, .csv, .json, .xml…) so the file has the correct type and is readable via get_document_content_by_id.

Parameters:

parentFolderId - the folder where the document is created (get it from get_root_folder_for_user / get_root_folder_by_space / get_documents_by_folder_id)

name - the document file name, including its extension (e.g. 'notes.md', 'report.txt', 'page.html'). The extension determines the file's content type (via the platform MimeTypeResolver); the name is used as-is.

content - the text / markdown / HTML body

Returns:

the created document

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

createDocumentFromTemplate

public DocumentModel createDocumentFromTemplate(String parentFolderId,
 String name,
 String documentType)
                                         throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Creates a NEW EMPTY office document (Word/Excel/PowerPoint, or ODF) from the platform's blank template, by delegating to the ecms DocumentService. Use this when the user wants a blank Word/Excel/PowerPoint document to fill in (e.g. via the online editor): create_document cannot produce office files (they are structured packages, not text) and upload_document needs the real file bytes. The template is created synchronously; the file extension is added automatically from documentType.

Parameters:

parentFolderId - the folder where the document is created (get it from get_root_folder_for_user / get_root_folder_by_space / get_documents_by_folder_id)

name - the document name, WITHOUT extension (e.g. 'Q3 report'); the extension is appended automatically from documentType

documentType - the office document type: one of docx, xlsx, pptx. Availability depends on the installed editor add-on (onlyoffice).

Returns:

the created document

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

uploadDocument

public DocumentModel uploadDocument(String parentFolderId,
 String name,
 String base64,
 String url,
 String attachmentObjectType,
 String attachmentObjectId)
                             throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Uploads a real / binary document (PDF, image, office file…) from exactly one of three sources: a file/image the user attached in the chat conversation (resolved server-side as the current user via attachment_object_type / attachment_object_id), a base64 payload, or an http(s) URL (fetched server-side behind an SSRF guard).

Parameters:

parentFolderId - the destination folder id (get it from get_root_folder_for_user / get_root_folder_by_space / get_documents_by_folder_id)

name - the document file name including its extension (e.g. 'report.pdf'); when uploading from a URL or a chat attachment it may be left blank to reuse the source file name

base64 - the file bytes encoded in base64 (mutually exclusive with url / the chat attachment)

url - an http(s) URL to download the file from (mutually exclusive with base64 / the chat attachment)

attachmentObjectType - the object type of the file the user attached in chat; set automatically by the client — do not fill it from the model

attachmentObjectId - the object id of the file the user attached in chat; set automatically by the client — do not fill it from the model

Returns:

the created document

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

renameDocument

public void renameDocument(String documentId,
 String newName)
                    throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

moveDocument

public void moveDocument(String documentId,
 String destinationFolderId,
 String conflictAction)
                  throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

copyDocument

public DocumentModel copyDocument(String documentId,
 String destinationFolderId)
                           throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

duplicateDocument

public DocumentModel duplicateDocument(String documentId,
 String prefix)
                                throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

deleteDocument

public void deleteDocument(String documentId)
                    throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

undoDeleteDocument

public void undoDeleteDocument(String documentId)
                        throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Restores a document that was deleted with delete_document: since that tool trashes immediately (delay 0), the delayed-delete cancel path is a no-op, so the node is resolved from trash (it keeps its id/uuid after the move) and restored to its original location.

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

restoreDocumentVersion

public DocumentVersionModel restoreDocumentVersion(String versionId)

updateVersionSummary

public DocumentVersionModel updateVersionSummary(String documentId,
 String versionId,
 String summary)

setDocumentVisibility

public void setDocumentVisibility(String documentId,
 Boolean hidden)
                           throws IllegalAccessException

Throws:

IllegalAccessException

addDocumentVersion

public DocumentModel addDocumentVersion(String documentId,
 String content,
 String base64,
 String url,
 String attachmentObjectType,
 String attachmentObjectId,
 String versionSummary)
                                 throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Uploads updated content onto an EXISTING file, creating a NEW version of it (the previous content stays retrievable via list_document_versions / restore_document_version). The new bytes come from exactly one source: a chat-authored text content string, a base64 payload, an http(s) url, or a file the user attached in the conversation. The file's name and type are unchanged; only its content and version history are updated.

Parameters:

documentId - the id of the existing file to add a version to (get it from get_document_by_id / get_documents_by_folder_id / search_documents)

content - plain text / markdown / HTML body to write as the new version (use for text files)

base64 - the new file bytes encoded in base64

url - an http(s) URL to download the new content from (fetched server-side behind an SSRF guard)

attachmentObjectType - the object type of the file the user attached in chat; set automatically by the client — do not fill it from the model

attachmentObjectId - the object id of the file the user attached in chat; set automatically by the client — do not fill it from the model

versionSummary - an optional change note stored on the new version

Returns:

the updated document (with its refreshed size / modification info)

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

createPublicLink

public DocumentPublicLinkModel createPublicLink(String documentId,
 String password,
 Long expirationDate)
                                         throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Creates (or refreshes) an anonymous public share link for a document so it can be downloaded without signing in, optionally protected by a password and/or an expiration date. Requires edit permission on the document.

Parameters:

documentId - the id of the file to share publicly (get it from the read tools)

password - an optional password required to open the link

expirationDate - an optional expiration date, as epoch milliseconds; after it the link stops working. Leave blank for a link that never expires.

Returns:

the shareable link, together with its password and expiration

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

createDocumentShortcut

public void createDocumentShortcut(String documentId,
 String destinationFolderId,
 String conflictAction)
                            throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Creates a shortcut (symlink) to a document inside another folder, so the same file appears in a second location without being copied.

Parameters:

documentId - the id of the file or folder to create a shortcut to

destinationFolderId - the id of the folder where the shortcut is placed (get it from get_root_folder_for_user / get_root_folder_by_space / get_documents_by_folder_id)

conflictAction - behaviour when a node with the same name already exists in the destination; only 'keepBoth' is honoured, defaults to 'keepBoth'

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

shareDocument

public void shareDocument(String documentId,
 String username,
 Long spaceId,
 Boolean notify)
                   throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Shares a document with another user or with a space: the recipient is GRANTED read access to the file and gets it in their "Shared" folder. Provide exactly one of username or spaceId. Requires edit permission on the document.

Parameters:

documentId - the id of the file to share (get it from the read tools)

username - the username to share the document with (mutually exclusive with space_id)

spaceId - the id of the space to share the document with (mutually exclusive with username)

notify - whether to notify the recipient; defaults to true

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

favoriteDocument

public void favoriteDocument(String documentId)
                      throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Adds a file to the current user's favorites. Only files can be favorited; folders have no favorites view in the Documents app.

Parameters:

documentId - the id of the file to mark as favorite

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

unfavoriteDocument

public void unfavoriteDocument(String documentId)
                        throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Removes a file from the current user's favorites. Only files can be favorited; folders have no favorites view in the Documents app.

Parameters:

documentId - the id of the file to remove from favorites

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException