@matimo/microsoft 0.1.0

package/tools/ms_create_document/ms_create_document.ts

@@ -0,0 +1,96 @@
+/**
+ * ms_create_document — PUT /drives/{drive-id}/items/{parent-item-id}:/{filename}:/content
+ * https://learn.microsoft.com/en-us/graph/api/driveitem-put-content
+ *
+ * Uses the "simple upload" by-path addressing syntax. Graph caps this endpoint at
+ * 4 MB; larger files require a resumable upload session, which is out of scope here
+ * and is rejected with a clear validation error rather than silently truncating.
+ */
+import { MatimoError, ErrorCode } from '@matimo/core';
+import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+
+const VALID_ENCODINGS = ['text', 'base64'];
+const VALID_CONFLICT_BEHAVIOURS = ['replace', 'rename', 'fail'];
+const DEFAULT_PARENT_ITEM_ID = 'root';
+const MAX_UPLOAD_BYTES = 4 * 1024 * 1024;
+
+interface UploadedItem {
+  id?: string;
+  name?: string;
+  webUrl?: string;
+  size?: number;
+}
+
+export default async function execute(
+  params: Record<string, unknown>,
+  context?: ToolContext
+): Promise<unknown> {
+  requireParams(params, ['drive_id', 'filename', 'content'], 'ms_create_document');
+
+  const driveId = String(params.drive_id);
+  const parentItemId =
+    typeof params.parent_item_id === 'string' && params.parent_item_id
+      ? params.parent_item_id
+      : DEFAULT_PARENT_ITEM_ID;
+  const filename = String(params.filename);
+
+  const encoding = params.content_encoding === undefined ? 'text' : String(params.content_encoding);
+  if (!VALID_ENCODINGS.includes(encoding)) {
+    throw new MatimoError(
+      `ms_create_document: 'content_encoding' must be one of ${VALID_ENCODINGS.join(', ')} (received '${encoding}')`,
+      ErrorCode.VALIDATION_FAILED,
+      { content_encoding: params.content_encoding }
+    );
+  }
+
+  const conflictBehaviour =
+    params.conflict_behaviour === undefined ? 'replace' : String(params.conflict_behaviour);
+  if (!VALID_CONFLICT_BEHAVIOURS.includes(conflictBehaviour)) {
+    throw new MatimoError(
+      `ms_create_document: 'conflict_behaviour' must be one of ${VALID_CONFLICT_BEHAVIOURS.join(', ')} (received '${conflictBehaviour}')`,
+      ErrorCode.VALIDATION_FAILED,
+      { conflict_behaviour: params.conflict_behaviour }
+    );
+  }
+
+  const buffer =
+    encoding === 'base64'
+      ? Buffer.from(String(params.content), 'base64')
+      : Buffer.from(String(params.content), 'utf-8');
+
+  if (buffer.byteLength > MAX_UPLOAD_BYTES) {
+    throw new MatimoError(
+      `ms_create_document: content is ${buffer.byteLength} bytes, exceeding the ` +
+        `${MAX_UPLOAD_BYTES}-byte limit of the simple-upload endpoint. Files this large ` +
+        'require a resumable upload session, which this tool does not implement.',
+      ErrorCode.VALIDATION_FAILED,
+      { sizeBytes: buffer.byteLength, maxBytes: MAX_UPLOAD_BYTES }
+    );
+  }
+
+  const token = getAccessToken(context);
+
+  // By-path addressing uses literal colons as delimiters — only the path SEGMENTS
+  // (drive id, parent item id, filename) are percent-encoded, not the colons.
+  const path =
+    `/drives/${encodeURIComponent(driveId)}/items/${encodeURIComponent(parentItemId)}` +
+    `:/${encodeURIComponent(filename)}:/content`;
+
+  const item = await graphRequest<UploadedItem>({
+    method: 'PUT',
+    path,
+    token,
+    resourceType: 'Drive folder',
+    query: { '@microsoft.graph.conflictBehavior': conflictBehaviour },
+    body: buffer,
+    headers: { 'Content-Type': 'application/octet-stream' },
+  });
+
+  return {
+    success: true,
+    item_id: item?.id ?? '',
+    name: item?.name ?? filename,
+    web_url: item?.webUrl ?? '',
+    size_bytes: item?.size ?? buffer.byteLength,
+  };
+}

package/tools/ms_get_email/definition.yaml

@@ -0,0 +1,88 @@
+name: ms_get_email
+description: |
+  List messages in the signed-in user's mailbox (GET /me/messages), with optional
+  OData filtering, free-text search, and folder scoping. Returns a clean, agent-friendly
+  summary of each message rather than the full raw Graph payload.
+version: '1.0.0'
+status: approved
+risk: low
+
+parameters:
+  top:
+    type: number
+    description: Maximum number of messages to return (1-50)
+    required: false
+    default: 10
+
+  filter:
+    type: string
+    description: >-
+      Raw OData $filter expression, e.g. "isRead eq false" or
+      "from/emailAddress/address eq 'alerts@contoso.com'"
+    required: false
+
+  search:
+    type: string
+    description: Free-text $search expression, e.g. '"quarterly report"'
+    required: false
+
+  folder_id:
+    type: string
+    description: >-
+      ID (or well-known name such as "inbox", "sentitems", "drafts") of the mail
+      folder to list messages from. Defaults to the entire mailbox when omitted.
+    required: false
+
+execution:
+  type: function
+  code: ms_get_email.ts
+  timeout: 20000
+
+authentication:
+  type: oauth2
+  provider: microsoft
+  scopes:
+    - https://graph.microsoft.com/Mail.Read
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    messages:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+          subject:
+            type: string
+          from:
+            type: string
+            description: Display name and/or email address of the sender
+          received_at:
+            type: string
+          is_read:
+            type: boolean
+          body_preview:
+            type: string
+          has_attachments:
+            type: boolean
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+tags: [microsoft, graph, mail, outlook, read]
+
+examples:
+  - name: List the 5 most recent unread messages
+    params:
+      top: 5
+      filter: 'isRead eq false'
+  - name: Search the inbox for messages mentioning "invoice"
+    params:
+      folder_id: inbox
+      search: '"invoice"'

package/tools/ms_get_email/ms_get_email.ts

@@ -0,0 +1,94 @@
+/**
+ * ms_get_email — GET /me/messages
+ * https://learn.microsoft.com/en-us/graph/api/user-list-messages
+ */
+import { MatimoError, ErrorCode } from '@matimo/core';
+import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+
+const DEFAULT_TOP = 10;
+const MAX_TOP = 50;
+
+interface EmailAddress {
+  name?: string;
+  address?: string;
+}
+
+interface MessageRecipient {
+  emailAddress?: EmailAddress;
+}
+
+interface GraphMessage {
+  id?: string;
+  subject?: string;
+  from?: MessageRecipient;
+  receivedDateTime?: string;
+  isRead?: boolean;
+  bodyPreview?: string;
+  hasAttachments?: boolean;
+}
+
+interface MessagesResponse {
+  value?: GraphMessage[];
+}
+
+function formatSender(message: GraphMessage): string {
+  const address = message.from?.emailAddress;
+  if (!address) return '';
+  if (address.name && address.address) return `${address.name} <${address.address}>`;
+  return address.name ?? address.address ?? '';
+}
+
+export default async function execute(
+  params: Record<string, unknown>,
+  context?: ToolContext
+): Promise<unknown> {
+  requireParams(params, [], 'ms_get_email');
+
+  const top = params.top === undefined ? DEFAULT_TOP : Number(params.top);
+  if (!Number.isFinite(top) || top < 1 || top > MAX_TOP) {
+    throw new MatimoError(
+      `ms_get_email: 'top' must be a number between 1 and ${MAX_TOP} (received ${String(params.top)})`,
+      ErrorCode.VALIDATION_FAILED,
+      { top: params.top }
+    );
+  }
+
+  const folderId = typeof params.folder_id === 'string' && params.folder_id ? params.folder_id : undefined;
+  const filter = typeof params.filter === 'string' && params.filter ? params.filter : undefined;
+  const search = typeof params.search === 'string' && params.search ? params.search : undefined;
+
+  const token = getAccessToken(context);
+
+  const path = folderId
+    ? `/me/mailFolders/${encodeURIComponent(folderId)}/messages`
+    : '/me/messages';
+
+  const data = await graphRequest<MessagesResponse>({
+    method: 'GET',
+    path,
+    token,
+    resourceType: 'Mail folder',
+    headers: search ? { 'ConsistencyLevel': 'eventual' } : undefined,
+    query: {
+      $top: top,
+      $select: 'id,subject,from,receivedDateTime,isRead,bodyPreview,hasAttachments',
+      ...(filter ? { $filter: filter } : {}),
+      ...(search ? { $search: search } : {}),
+    },
+  });
+
+  const messages = (data?.value ?? []).map((message) => ({
+    id: message.id ?? '',
+    subject: message.subject ?? '',
+    from: formatSender(message),
+    received_at: message.receivedDateTime ?? '',
+    is_read: message.isRead ?? false,
+    body_preview: message.bodyPreview ?? '',
+    has_attachments: message.hasAttachments ?? false,
+  }));
+
+  return {
+    success: true,
+    messages,
+  };
+}

package/tools/ms_list_files/definition.yaml

@@ -0,0 +1,81 @@
+name: ms_list_files
+description: |
+  List the children of a folder in OneDrive or a SharePoint document library
+  (GET /drives/{drive_id}/items/{item_id}/children). Defaults to listing the root
+  folder of the drive. Returns a flat list of files and subfolders with basic metadata.
+version: '1.0.0'
+status: approved
+risk: low
+
+parameters:
+  drive_id:
+    type: string
+    description: ID of the drive (OneDrive or SharePoint document library) to list
+    required: true
+
+  item_id:
+    type: string
+    description: ID of the folder item whose children should be listed
+    required: false
+    default: root
+
+  top:
+    type: number
+    description: Maximum number of items to return (1-100)
+    required: false
+    default: 20
+
+execution:
+  type: function
+  code: ms_list_files.ts
+  timeout: 20000
+
+authentication:
+  type: oauth2
+  provider: microsoft
+  scopes:
+    - https://graph.microsoft.com/Files.Read.All
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    items:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+          name:
+            type: string
+          type:
+            type: string
+            description: "'file' or 'folder'"
+          size_bytes:
+            type: number
+          last_modified:
+            type: string
+          mime_type:
+            type: string
+            description: Present only for files (folders have no MIME type)
+          web_url:
+            type: string
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+tags: [microsoft, graph, files, onedrive, sharepoint, list]
+
+examples:
+  - name: List the root of a OneDrive
+    params:
+      drive_id: 'b!xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+  - name: List a specific folder, capped at 50 items
+    params:
+      drive_id: 'b!xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      item_id: '01ABCXYZ7654321'
+      top: 50

package/tools/ms_list_files/ms_list_files.ts

@@ -0,0 +1,71 @@
+/**
+ * ms_list_files — GET /drives/{drive_id}/items/{item_id}/children
+ * https://learn.microsoft.com/en-us/graph/api/driveitem-list-children
+ */
+import { MatimoError, ErrorCode } from '@matimo/core';
+import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+
+const DEFAULT_ITEM_ID = 'root';
+const DEFAULT_TOP = 20;
+const MAX_TOP = 100;
+
+interface DriveItem {
+  id?: string;
+  name?: string;
+  size?: number;
+  lastModifiedDateTime?: string;
+  webUrl?: string;
+  file?: { mimeType?: string };
+  folder?: unknown;
+}
+
+interface ChildrenResponse {
+  value?: DriveItem[];
+}
+
+export default async function execute(
+  params: Record<string, unknown>,
+  context?: ToolContext
+): Promise<unknown> {
+  requireParams(params, ['drive_id'], 'ms_list_files');
+
+  const driveId = String(params.drive_id);
+  const itemId = typeof params.item_id === 'string' && params.item_id ? params.item_id : DEFAULT_ITEM_ID;
+
+  const top = params.top === undefined ? DEFAULT_TOP : Number(params.top);
+  if (!Number.isFinite(top) || top < 1 || top > MAX_TOP) {
+    throw new MatimoError(
+      `ms_list_files: 'top' must be a number between 1 and ${MAX_TOP} (received ${String(params.top)})`,
+      ErrorCode.VALIDATION_FAILED,
+      { top: params.top }
+    );
+  }
+
+  const token = getAccessToken(context);
+
+  const data = await graphRequest<ChildrenResponse>({
+    method: 'GET',
+    path: `/drives/${encodeURIComponent(driveId)}/items/${encodeURIComponent(itemId)}/children`,
+    token,
+    resourceType: 'Drive folder',
+    query: {
+      $top: top,
+      $select: 'id,name,size,lastModifiedDateTime,webUrl,file,folder',
+    },
+  });
+
+  const items = (data?.value ?? []).map((item) => ({
+    id: item.id ?? '',
+    name: item.name ?? '',
+    type: item.folder ? 'folder' : 'file',
+    size_bytes: item.size ?? 0,
+    last_modified: item.lastModifiedDateTime ?? '',
+    ...(item.file?.mimeType ? { mime_type: item.file.mimeType } : {}),
+    web_url: item.webUrl ?? '',
+  }));
+
+  return {
+    success: true,
+    items,
+  };
+}

package/tools/ms_publish_to_sharepoint/definition.yaml

@@ -0,0 +1,92 @@
+name: ms_publish_to_sharepoint
+description: |
+  Create a SharePoint site page (POST /sites/{site_id}/pages) with a single text web
+  part containing the supplied content, then optionally publish it
+  (POST /sites/{site_id}/pages/{page_id}/microsoft.graph.sitePage/publish). Publishing
+  makes the page visible to everyone with site access — high-risk, requires approval.
+version: '1.0.0'
+status: approved
+risk: high
+requires_approval: true
+
+parameters:
+  site_id:
+    type: string
+    description: ID of the SharePoint site to publish the page to
+    required: true
+
+  title:
+    type: string
+    description: Title of the page. Also used to derive the page's file name.
+    required: true
+
+  content:
+    type: string
+    description: Body content for the page's single text web part
+    required: true
+
+  content_type:
+    type: string
+    description: >-
+      Whether `content` is HTML or plain text. Plain text is escaped and wrapped in
+      a paragraph before being placed in the web part's HTML container, since
+      SharePoint site pages always store web part content as HTML.
+    required: false
+    default: html
+    enum: [html, text]
+
+  publish:
+    type: boolean
+    description: When true (the default), publish the page immediately after creating it
+    required: false
+    default: true
+
+execution:
+  type: function
+  code: ms_publish_to_sharepoint.ts
+  timeout: 30000
+
+authentication:
+  type: oauth2
+  provider: microsoft
+  scopes:
+    - https://graph.microsoft.com/Sites.Manage.All
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    page_id:
+      type: string
+    web_url:
+      type: string
+    published:
+      type: boolean
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+tags: [microsoft, graph, sharepoint, publish, write]
+
+examples:
+  - name: Publish an HTML announcement page
+    params:
+      site_id: 'contoso.sharepoint.com,11111111-1111-1111-1111-111111111111'
+      title: 'Q3 results are in'
+      content: '<h2>We hit our targets</h2><p>Thanks to everyone who contributed.</p>'
+  - name: Create a plain-text draft without publishing
+    params:
+      site_id: 'contoso.sharepoint.com,11111111-1111-1111-1111-111111111111'
+      title: 'Draft: Office relocation FAQ'
+      content: 'This page is still being reviewed by Facilities.'
+      content_type: text
+      publish: false
+
+notes:
+  caution: >-
+    Publishing makes the page visible to everyone with access to the site. Marked
+    risk: high and requires_approval: true so Matimo routes it through the
+    human-in-the-loop approval flow before it executes.

package/tools/ms_publish_to_sharepoint/ms_publish_to_sharepoint.ts

@@ -0,0 +1,126 @@
+/**
+ * ms_publish_to_sharepoint
+ *   Create:  POST /sites/{site-id}/pages
+ *            https://learn.microsoft.com/en-us/graph/api/sitepage-create
+ *   Publish: POST /sites/{site-id}/pages/{page-id}/microsoft.graph.sitePage/publish
+ *            https://learn.microsoft.com/en-us/graph/api/sitepage-publish
+ *
+ * Site pages always store web part bodies as HTML, so plain-text content is
+ * HTML-escaped and wrapped in a single <p> before being placed in a textWebPart.
+ */
+import { MatimoError, ErrorCode } from '@matimo/core';
+import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+
+const VALID_CONTENT_TYPES = ['html', 'text'];
+
+interface SitePage {
+  id?: string;
+  webUrl?: string;
+}
+
+const HTML_ESCAPES: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+};
+
+function escapeHtml(text: string): string {
+  return text.replace(/[&<>"']/g, (ch) => HTML_ESCAPES[ch]);
+}
+
+function deriveFileName(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return `${slug || 'page'}.aspx`;
+}
+
+export default async function execute(
+  params: Record<string, unknown>,
+  context?: ToolContext
+): Promise<unknown> {
+  requireParams(params, ['site_id', 'title', 'content'], 'ms_publish_to_sharepoint');
+
+  const siteId = String(params.site_id);
+  const title = String(params.title);
+
+  const contentType = params.content_type === undefined ? 'html' : String(params.content_type);
+  if (!VALID_CONTENT_TYPES.includes(contentType)) {
+    throw new MatimoError(
+      `ms_publish_to_sharepoint: 'content_type' must be one of ${VALID_CONTENT_TYPES.join(', ')} (received '${contentType}')`,
+      ErrorCode.VALIDATION_FAILED,
+      { content_type: params.content_type }
+    );
+  }
+
+  const rawContent = String(params.content);
+  const innerHtml = contentType === 'text' ? `<p>${escapeHtml(rawContent)}</p>` : rawContent;
+
+  const shouldPublish = params.publish === undefined ? true : params.publish === true;
+
+  const token = getAccessToken(context);
+
+  const page = await graphRequest<SitePage>({
+    method: 'POST',
+    path: `/sites/${encodeURIComponent(siteId)}/pages`,
+    token,
+    resourceType: 'SharePoint site',
+    body: {
+      '@odata.type': '#microsoft.graph.sitePage',
+      name: deriveFileName(title),
+      title,
+      pageLayout: 'article',
+      canvasLayout: {
+        horizontalSections: [
+          {
+            layout: 'oneColumn',
+            id: '1',
+            emphasis: 'none',
+            columns: [
+              {
+                id: '1',
+                width: 12,
+                webparts: [
+                  {
+                    '@odata.type': '#microsoft.graph.textWebPart',
+                    innerHtml,
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    },
+  });
+
+  const pageId = page?.id;
+  if (!pageId) {
+    throw new MatimoError(
+      'ms_publish_to_sharepoint: Microsoft Graph did not return an ID for the created page.',
+      ErrorCode.EXECUTION_FAILED,
+      { page }
+    );
+  }
+
+  if (shouldPublish) {
+    await graphRequest({
+      method: 'POST',
+      path: `/sites/${encodeURIComponent(siteId)}/pages/${encodeURIComponent(pageId)}/microsoft.graph.sitePage/publish`,
+      token,
+      resourceType: 'SharePoint page',
+      allowEmptyResponse: true,
+    });
+  }
+
+  return {
+    success: true,
+    page_id: pageId,
+    web_url: page?.webUrl ?? '',
+    published: shouldPublish,
+  };
+}