365center-mcp 1.2.1 → 1.2.2

package/dist/index.js

@@ -41,7 +41,7 @@ server.tool("create_site", "Create a new SharePoint site. Template: 'communicati
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
 // ============ DOCUMENTS ============
-server.tool("list_document_libraries", "List all document libraries (drives) in a SharePoint site. Returns driveId for each library — use driveId in list_documents, upload_document, delete_document, and other document tools. Also returns listId for metadata operations.", { siteId: z.string().describe("SharePoint site ID") }, async ({ siteId }) => {
+server.tool("list_document_libraries", "List all document libraries (drives) in a SharePoint site. Returns driveId and listId for each library. Use driveId for file operations (upload, download, delete, list, versions). Use listId for metadata operations (list_columns, get/set_document_metadata, create columns). Call this first when working with documents — you need both IDs.", { siteId: z.string().describe("SharePoint site ID") }, async ({ siteId }) => {
     const libraries = await listDocumentLibraries(siteId);
     return { content: [{ type: "text", text: JSON.stringify(libraries, null, 2) }] };
 });
@@ -53,7 +53,7 @@ server.tool("list_documents", "List documents in a document library folder. Retu
     const docs = await listDocuments(siteId, driveId, folderId || "root");
     return { content: [{ type: "text", text: JSON.stringify(docs, null, 2) }] };
 });
-server.tool("upload_document", "Upload a local file to a SharePoint document library. File is uploaded to the root folder by default, or to a specific folder if folderId is provided. After upload, use set_document_metadata to set metadata fields on the document. Supports files up to 250 GB (automatic session upload for files over 4 MB).", {
+server.tool("upload_document", "Upload a single local file to a SharePoint document library. Root folder by default, or specific folder via folderId. After upload, use set_document_metadata to tag it. Supports up to 250 GB (auto session upload for >4 MB). For multiple files, prefer upload_documents — up to 30 files per call with inline metadata and built-in rate limit protection. NOTE: If using Highlighted Content web parts, filename prefix determines filtering. The 'Title includes the words' filter is SUBSTRING-based — e.g. 'Report' will also match 'ReportQ1' or 'ReportAnnual'. Use non-overlapping prefixes.", {
     siteId: z.string().describe("SharePoint site ID"),
     driveId: z.string().describe("Document library (drive) ID"),
     fileName: z.string().describe("Name for the file in SharePoint"),
@@ -72,7 +72,7 @@ server.tool("download_document", "Download a document from a SharePoint document
     const result = await downloadDocument(siteId, driveId, itemId, localPath);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
-server.tool("upload_documents", "Upload one or more files to SharePoint, optionally setting metadata on each. Max 30 files per call. Files over 4 MB use resumable upload automatically. 500ms delay between files for API rate limits. Returns per-file status for upload and metadata independently.", {
+server.tool("upload_documents", "Batch upload up to 30 files to SharePoint with optional inline metadata per file. Files >4 MB use resumable upload. Built-in 500ms delay between files prevents HTTP 429 from Microsoft. Returns per-file status for upload and metadata independently. When setting metadata, listId is required. Choice values must match predefined choices exactly (case-sensitive). For large batches, split into multiple calls of max 30 files each. Same substring warning as upload_document — if using Highlighted Content web parts, filename prefixes determine which section shows which documents.", {
     siteId: z.string().describe("SharePoint site ID"),
     driveId: z.string().describe("Document library (drive) ID"),
     listId: z.string().optional().describe("List ID — required only if setting metadata via fields"),
@@ -89,7 +89,7 @@ server.tool("upload_documents", "Upload one or more files to SharePoint, optiona
     const results = await uploadDocuments(siteId, driveId, listId, files, folderId || "root");
     return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
 });
-server.tool("search_documents", "Search for documents in a SharePoint site", {
+server.tool("search_documents", "Search for documents across all libraries in a SharePoint site by keyword. Search indexes may take a few minutes to reflect newly uploaded documents.", {
     siteId: z.string().describe("SharePoint site ID"),
     query: z.string().describe("Search query"),
 }, async ({ siteId, query }) => {
@@ -122,7 +122,7 @@ server.tool("get_document_versions", "Get version history of a document (audit t
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
 // ============ METADATA ============
-server.tool("list_columns", "List all custom metadata columns in a SharePoint list/library. The listId can be the list display name (e.g. 'Dokumenty') or the list GUID. Returns column name, type, and choices for choice columns. Use this to discover available metadata fields before calling set_document_metadata.", {
+server.tool("list_columns", "List custom metadata columns in a SharePoint list/library. listId can be display name (e.g. 'Documents') or GUID. Returns internal name, display name, type, and choices. Call this before set_document_metadata — internal column names (used in API) often differ from display names (shown in UI). Using wrong name fails silently.", {
     siteId: z.string().describe("SharePoint site ID"),
     listId: z.string().describe("List or document library list ID"),
 }, async ({ siteId, listId }) => {
@@ -149,7 +149,7 @@ server.tool("create_text_column", "Create a single-line text metadata column in
     const result = await createTextColumn(siteId, listId, name, displayName);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
-server.tool("set_document_metadata", "Set metadata fields on a document. The 'fields' parameter is a JSON string of key-value pairs where keys are column internal names. For choice columns, value must match one of the predefined choices exactly. For multi-select choice columns, value is an array of strings. IMPORTANT: columns must exist before setting values — use list_columns to check, or create_choice_column/create_text_column to create them. Accepts both drive item ID and numeric list item ID — if using drive item ID, provide driveId.", {
+server.tool("set_document_metadata", "Set metadata fields on a document. 'fields' is a JSON string of key-value pairs using column internal names. Choice values must match predefined choices exactly (case-sensitive). Multi-select: use array of strings. Columns must exist first — check with list_columns. Accepts drive item ID (requires driveId) or numeric list item ID. Only change fields the user asked for — leave others untouched. TIP: Changing a Status field (e.g. to 'Pending Approval') can trigger Power Automate flows with 'When item modified' trigger — no HTTP webhooks or extra tools needed.", {
     siteId: z.string().describe("SharePoint site ID"),
     listId: z.string().describe("List or document library list ID"),
     itemId: z.string().describe("Document ID — either numeric list item ID or drive item ID"),
@@ -170,11 +170,11 @@ server.tool("get_document_metadata", "Get all metadata fields of a document incl
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
 // ============ PAGES ============
-server.tool("list_pages", "List all pages in a SharePoint site. Returns page ID, name, title, URL, and publishing state (checkout/published). Use the page ID for publish_page, delete_page, and add_quick_links.", { siteId: z.string().describe("SharePoint site ID") }, async ({ siteId }) => {
+server.tool("list_pages", "List all pages via Graph API. Returns page GUID, name, title, URL, and state. Use page GUID for publish_page, delete_page, add_quick_links. NOTE: Canvas tools (get/set_page_canvas_content) need NUMERIC item IDs from list_site_pages instead — GUIDs from this tool won't work there.", { siteId: z.string().describe("SharePoint site ID") }, async ({ siteId }) => {
     const pages = await listPages(siteId);
     return { content: [{ type: "text", text: JSON.stringify(pages, null, 2) }] };
 });
-server.tool("create_page", "Create a new empty SharePoint page. Page is created in 'checkout' state (draft) — use publish_page to make it visible to users. The 'name' becomes the URL slug (e.g. 'my-page' → my-page.aspx). Use create_page_with_content if you need to add text/sections at creation time.", {
+server.tool("create_page", "Create a new empty page in checkout/draft state. MUST call publish_page after to make it visible. 'name' becomes URL slug (e.g. 'my-page' → my-page.aspx). For pages with text sections, use create_page_with_content. For pages with web parts (Highlighted Content etc.), create empty page first, then set_page_canvas_content, then publish_page.", {
     siteId: z.string().describe("SharePoint site ID"),
     title: z.string().describe("Page title"),
     name: z.string().describe("Page file name (without .aspx)"),
@@ -182,7 +182,7 @@ server.tool("create_page", "Create a new empty SharePoint page. Page is created
     const result = await createPage(siteId, title, name);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
-server.tool("create_page_with_content", "Create a SharePoint page with sections containing HTML content. Page is created in 'checkout' state — use publish_page to make it visible. The 'sections' parameter is a JSON string array. Available layouts: oneColumn (width:12), twoColumns (width:6+6), threeColumns (width:4+4+4), oneThirdLeftColumn (width:4+8), oneThirdRightColumn (width:8+4), fullWidth (width:12). Each column contains HTML text. Example: [{\"layout\":\"twoColumns\",\"columns\":[{\"width\":6,\"html\":\"<h2>Left</h2>\"},{\"width\":6,\"html\":\"<h2>Right</h2>\"}]}]", {
+server.tool("create_page_with_content", "Create a page with HTML text sections. Draft state — MUST call publish_page after. Sections is a JSON string array. Layouts: oneColumn (12), twoColumns (6+6), threeColumns (4+4+4), oneThirdLeftColumn (4+8), oneThirdRightColumn (8+4), fullWidth (12). Example: [{\"layout\":\"twoColumns\",\"columns\":[{\"width\":6,\"html\":\"<h2>Left</h2>\"},{\"width\":6,\"html\":\"<h2>Right</h2>\"}]}]. NOTE: Only supports text/HTML. For web parts like Highlighted Content, use create_page + set_page_canvas_content instead.", {
     siteId: z.string().describe("SharePoint site ID"),
     title: z.string().describe("Page title"),
     name: z.string().describe("Page file name (without .aspx)"),
@@ -203,7 +203,7 @@ server.tool("add_quick_links", "Add a Quick Links web part to a SharePoint page
     const result = await addQuickLinksWebPart(siteId, pageId, links);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
-server.tool("publish_page", "Publish a SharePoint page to make it visible to all site users. Pages are created in 'checkout' (draft) state and must be published to appear on the site. After publishing, the page gets a version number and is accessible via its URL.", {
+server.tool("publish_page", "Publish a page to make it visible. MUST call after: create_page, create_page_with_content, or set_page_canvas_content — without publishing, the page appears EMPTY to users. This is the most commonly forgotten step.", {
     siteId: z.string().describe("SharePoint site ID"),
     pageId: z.string().describe("Page ID"),
 }, async ({ siteId, pageId }) => {
@@ -224,7 +224,7 @@ server.tool("get_navigation", "Get the top navigation menu links of a SharePoint
     const result = await getNavigation(siteUrl);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
-server.tool("add_navigation_link", "Add a link to the top navigation menu of a SharePoint site. Uses SharePoint REST API. The siteUrl must be full URL with https://. The url parameter is the link target (can be internal SharePoint URL or external URL).", {
+server.tool("add_navigation_link", "Add a link to top navigation. REST API, delegated auth. siteUrl must include https://. url = link target (internal or external). Check get_navigation first to avoid duplicates.", {
     siteUrl: z.string().describe("Full SharePoint site URL"),
     title: z.string().describe("Navigation link title"),
     url: z.string().describe("Navigation link URL"),
@@ -268,14 +268,14 @@ server.tool("remove_user_from_group", "Remove a user from a SharePoint group. Us
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
 // ============ REST API — CANVAS CONTENT ============
-server.tool("get_page_canvas_content", "Read the raw CanvasContent1 of a SharePoint page via REST API. Returns the full HTML/JSON content of the page including all web parts. Use this to inspect how existing pages are built (especially Highlighted Content web parts) so you can replicate them. The pageItemId is the numeric list item ID from Site Pages list — use list_site_pages to find it. Uses delegated auth.", {
+server.tool("get_page_canvas_content", "Read raw CanvasContent1 of a page via REST API. Returns full HTML including all web parts. Use to inspect existing page structure before modifying. pageItemId = numeric ID from list_site_pages (NOT GUID from list_pages). Uses delegated auth. ALWAYS read before calling set_page_canvas_content — understand what's there before replacing it.", {
     siteUrl: z.string().describe("Full SharePoint site URL (e.g. https://contoso.sharepoint.com/sites/MySite)"),
     pageItemId: z.number().describe("Numeric item ID from Site Pages list (use list_site_pages to find it)"),
 }, async ({ siteUrl, pageItemId }) => {
     const result = await getPageCanvasContent(siteUrl, pageItemId);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
-server.tool("set_page_canvas_content", "Write raw CanvasContent1 to a SharePoint page via REST API. This replaces the ENTIRE page content. Use get_page_canvas_content first to understand the format. WARNING: this overwrites all existing content on the page. Useful for adding Highlighted Content web parts or any web part not supported by Graph API. Uses delegated auth.", {
+server.tool("set_page_canvas_content", "Replace entire page canvas via REST API. Overwrites ALL existing content. Uses delegated auth. pageItemId = numeric ID from list_site_pages. MUST call publish_page after — page reverts to draft and appears EMPTY without it. Canvas HTML rules: use pre-encoded entities directly (&#123; &#125; &#58; &quot;) — never JSON.stringify then replace (double-escaping on file round-trips). Omit titleHTML property (causes escaping corruption) — titles render from searchablePlainTexts. Read current canvas with get_page_canvas_content first.", {
     siteUrl: z.string().describe("Full SharePoint site URL"),
     pageItemId: z.number().describe("Numeric item ID from Site Pages list"),
     canvasContent: z.string().describe("Raw HTML/JSON canvas content string — get format from get_page_canvas_content on an existing page"),
@@ -291,7 +291,7 @@ server.tool("copy_page", "Copy an existing SharePoint page to create a new one.
     const result = await copyPage(siteUrl, sourceFileName, targetFileName);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
-server.tool("list_site_pages", "List all pages in a SharePoint site via REST API. Returns numeric item IDs needed for get_page_canvas_content and set_page_canvas_content. Also returns title and file name. Uses delegated auth.", {
+server.tool("list_site_pages", "List pages via REST API. Returns NUMERIC item IDs needed for canvas tools (get/set_page_canvas_content). Also returns title and file name. Uses delegated auth. NOTE: This gives numeric IDs for canvas operations. For page GUIDs (needed by publish_page, delete_page), use list_pages instead.", {
     siteUrl: z.string().describe("Full SharePoint site URL"),
 }, async ({ siteUrl }) => {
     const result = await listSitePages(siteUrl);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "365center-mcp",
-  "version": "1.2.1",
-  "description": "MCP server for Microsoft 365 / Office 365 SharePoint — 32 tools for full read-write access to sites, documents, pages, metadata, navigation, and permissions",
+  "version": "1.2.2",
+  "description": "MCP server for Microsoft 365 / Office 365 SharePoint — full read-write access to sites, documents, pages, metadata, navigation, and permissions",
   "type": "module",
   "main": "dist/index.js",
   "bin": {