@matimo/microsoft 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# @matimo/microsoft
+
+Microsoft Graph tools for Matimo — search, OneDrive/SharePoint files, Outlook mail,
+Microsoft Teams, calendar, and SharePoint publishing through YAML-defined tools that
+work with any AI framework.
+
+## 📦 Installation
+
+```bash
+npm install @matimo/microsoft
+# or
+pnpm add @matimo/microsoft
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { MatimoInstance } from '@matimo/core';
+
+const matimo = await MatimoInstance.init('./packages/microsoft/tools');
+
+// Search across SharePoint and OneDrive
+const search = await matimo.execute('ms_search_knowledge', {
+  query: 'Q3 budget filetype:xlsx',
+  top: 5,
+});
+
+// List files in a OneDrive folder
+const files = await matimo.execute('ms_list_files', {
+  drive_id: 'b!xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+});
+
+// Read a plain-text file's contents
+const file = await matimo.execute('ms_read_file', {
+  drive_id: 'b!xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+  item_id: '01ABCXYZ7654321',
+});
+
+// Send an email (requires_approval: true — routed through HITL)
+await matimo.execute('ms_send_email', {
+  to: ['alice@contoso.com'],
+  subject: 'Weekly status update',
+  body: 'Here is the summary for this week...',
+});
+```
+
+## 🛠️ Available Tools
+
+| Tool | Description | Risk | Graph endpoint |
+|------|-------------|------|----------------|
+| `ms_search_knowledge` | Search SharePoint sites, OneDrive/SharePoint files, and list items | low | `POST /search/query` |
+| `ms_read_file` | Read a OneDrive/SharePoint file's contents (plain-text formats only) | low | `GET /drives/{id}/items/{id}/content` |
+| `ms_list_files` | List the children of a OneDrive/SharePoint folder | low | `GET /drives/{id}/items/{id}/children` |
+| `ms_get_email` | List messages in the signed-in user's mailbox | low | `GET /me/messages` |
+| `ms_send_email` | Send an email as the signed-in user | **high** (approval) | `POST /me/messages` + `/send` |
+| `ms_send_teams_message` | Post (or reply to) a message in a Teams channel | medium | `POST /teams/{id}/channels/{id}/messages` |
+| `ms_create_document` | Upload a small file to OneDrive/SharePoint (≤4 MB) | medium | `PUT /drives/{id}/items/{id}:/{name}:/content` |
+| `ms_create_calendar_event` | Create a calendar event, optionally as a Teams meeting | medium | `POST /me/events` |
+| `ms_publish_to_sharepoint` | Create and publish a SharePoint site page | **high** (approval) | `POST /sites/{id}/pages` + `/publish` |
+
+## 🔐 Authentication
+
+Microsoft Graph tools use delegated OAuth2 access tokens. Matimo never performs the
+OAuth code exchange itself — connect Microsoft through your Matimo deployment (Nova),
+then provide the resulting token at execution time:
+
+```bash
+export MICROSOFT_GRAPH_ACCESS_TOKEN="eyJ0eXAiOiJKV1Qi..."
+```
+
+or pass it through per-call credentials:
+
+```typescript
+await matimo.execute(
+  'ms_get_email',
+  { top: 5 },
+  { credentials: { MICROSOFT_GRAPH_ACCESS_TOKEN: token } }
+);
+```
+
+See [`definition.yaml`](./definition.yaml) for the full OAuth2 provider configuration
+(authorization/token endpoints, default scopes, and app registration setup steps).
+
+## ⚠️ Risk & Approval
+
+`ms_send_email` and `ms_publish_to_sharepoint` are marked `risk: high` and
+`requires_approval: true` — Matimo routes them through the human-in-the-loop approval
+flow before they execute, since they send mail and publish content visible to others
+on the user's behalf. `ms_send_teams_message`, `ms_create_document`, and
+`ms_create_calendar_event` are `risk: medium` (external writes, narrower blast radius).
+The remaining read-only tools are `risk: low`.
+
+## 📚 Integration Examples
+
+See [`examples/tools/microsoft/`](../../examples/tools/microsoft/) for runnable
+factory, decorator, LangChain agent, and policy-approval examples.
+
+## Additional Resources
+
+- [Microsoft Graph API overview](https://learn.microsoft.com/en-us/graph/overview)
+- [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference)
+- [Microsoft Entra admin center](https://entra.microsoft.com) (app registration)
+- [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer) (try API calls interactively)
+- [Matimo Documentation](../../README.md)

package/definition.yaml

@@ -0,0 +1,61 @@
+# Microsoft Identity Platform OAuth2 Provider Definition
+#
+# This file defines the OAuth2 configuration for Microsoft (Entra ID / Azure AD v2.0).
+# All Microsoft Graph tools reference this provider definition.
+#
+# Users can override these endpoints via:
+# 1. Runtime config (highest priority)
+# 2. Environment variables: OAUTH_MICROSOFT_AUTH_URL, OAUTH_MICROSOFT_TOKEN_URL, etc.
+# 3. This YAML definition (lowest priority)
+#
+# Pattern: Define once, use everywhere
+
+name: microsoft-provider
+type: provider
+version: '1.0.0'
+
+description: |
+  Microsoft Identity Platform OAuth2 Provider Configuration
+
+  All Microsoft Graph tools use these endpoints to obtain delegated
+  access tokens for the Graph API (https://graph.microsoft.com).
+
+  Setup:
+  1. Register an application in the Microsoft Entra admin center (https://entra.microsoft.com)
+  2. Add a Web/SPA redirect URI for your OAuth callback
+  3. Create a client secret (or configure a certificate) under "Certificates & secrets"
+  4. Grant the delegated Graph scopes your tools need under "API permissions"
+  5. Set MICROSOFT_CLIENT_ID and MICROSOFT_CLIENT_SECRET environment variables
+  6. Set MICROSOFT_REDIRECT_URI to your callback URL
+
+  Note: Matimo never performs the OAuth code exchange itself — it expects a
+  valid delegated access token to be supplied at execution time (e.g. via
+  MICROSOFT_GRAPH_ACCESS_TOKEN), exactly like the Slack/Gmail providers.
+
+provider:
+  name: microsoft
+  displayName: Microsoft
+
+  # OAuth2 Endpoints (Microsoft identity platform v2.0, multi-tenant "common" tenant)
+  # See: https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oauth-code
+  endpoints:
+    authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
+    tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
+    revokeUrl: https://login.microsoftonline.com/common/oauth2/v2.0/logout
+
+  # Standard delegated scopes for the tools in this package.
+  # Tools can request a narrower set with their own `authentication.scopes`.
+  defaultScopes:
+    - offline_access
+    - https://graph.microsoft.com/Sites.Read.All
+    - https://graph.microsoft.com/Files.Read.All
+    - https://graph.microsoft.com/Mail.Read
+    - https://graph.microsoft.com/Mail.Send
+    - https://graph.microsoft.com/ChannelMessage.Send
+    - https://graph.microsoft.com/Files.ReadWrite
+    - https://graph.microsoft.com/Calendars.ReadWrite
+    - https://graph.microsoft.com/Sites.Manage.All
+
+  # Additional metadata
+  documentation: https://learn.microsoft.com/en-us/graph/overview
+  learnMore: https://developer.microsoft.com/en-us/graph/graph-explorer

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@matimo/microsoft",
+  "version": "0.1.0",
+  "description": "Microsoft Graph tools for Matimo (search, files, mail, Teams, calendar, SharePoint)",
+  "type": "module",
+  "files": [
+    "tools",
+    "README.md",
+    "definition.yaml"
+  ],
+  "peerDependencies": {
+    "matimo": "0.1.3"
+  },
+  "devDependencies": {
+    "axios": "^1.15.2",
+    "@matimo/core": "0.1.3"
+  }
+}

package/tools/graph-client.ts

@@ -0,0 +1,233 @@
+/**
+ * Shared Microsoft Graph helpers for all `type: function` tools in this package.
+ *
+ * Conventions (mirrors @matimo/slack and @matimo/gmail):
+ * - Tools NEVER perform OAuth token exchange. A delegated Graph access token is
+ *   injected at execution time via `context.credentials.MICROSOFT_GRAPH_ACCESS_TOKEN`
+ *   (or the MICROSOFT_GRAPH_ACCESS_TOKEN environment variable as a fallback).
+ * - Every Graph error is normalized into a MatimoError with the closest matching
+ *   ErrorCode (Matimo has no per-provider error classes — see errors/matimo-error.ts).
+ */
+import axios from 'axios';
+import { MatimoError, ErrorCode } from '@matimo/core';
+
+export const GRAPH_BASE_URL = 'https://graph.microsoft.com/v1.0';
+
+export interface ToolContext {
+  credentials?: Record<string, string>;
+}
+
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 503]);
+const MAX_RETRIES = 3;
+const INITIAL_BACKOFF_MS = 500;
+
+/**
+ * Resolve the delegated Graph access token. Matimo never exchanges OAuth codes —
+ * the token must already be present in per-call credentials or the environment.
+ */
+export function getAccessToken(context?: ToolContext): string {
+  const token =
+    context?.credentials?.MICROSOFT_GRAPH_ACCESS_TOKEN ?? process.env.MICROSOFT_GRAPH_ACCESS_TOKEN;
+
+  if (!token) {
+    throw new MatimoError(
+      'Microsoft Graph access token is missing. Provide it via credentials.MICROSOFT_GRAPH_ACCESS_TOKEN ' +
+        'or the MICROSOFT_GRAPH_ACCESS_TOKEN environment variable. Matimo never performs the OAuth ' +
+        'exchange itself — connect Microsoft in Nova first.',
+      ErrorCode.AUTH_FAILED,
+      { provider: 'microsoft', placeholder: 'MICROSOFT_GRAPH_ACCESS_TOKEN' }
+    );
+  }
+
+  return token;
+}
+
+/**
+ * Validate required parameters BEFORE any network call, mirroring the
+ * "ValidationError before any API call" requirement. Throws VALIDATION_FAILED.
+ */
+export function requireParams(
+  params: Record<string, unknown>,
+  required: string[],
+  toolName: string
+): void {
+  const missing = required.filter((name) => {
+    const value = params[name];
+    return value === undefined || value === null || value === '';
+  });
+
+  if (missing.length > 0) {
+    throw new MatimoError(
+      `${toolName}: missing required parameter(s): ${missing.join(', ')}`,
+      ErrorCode.VALIDATION_FAILED,
+      { toolName, missingParams: missing }
+    );
+  }
+}
+
+interface GraphErrorBody {
+  error?: { code?: string; message?: string };
+}
+
+/**
+ * Map a Microsoft Graph HTTP error response onto a MatimoError using the closest
+ * matching ErrorCode (Matimo has no CredentialError/NotFoundError/ProviderError
+ * classes — see typescript/packages/core/src/errors/matimo-error.ts):
+ *   401/403 -> AUTH_FAILED      ("Microsoft Graph access denied. Check connection status in Nova.")
+ *   404     -> FILE_NOT_FOUND   (details.resourceType identifies what was missing)
+ *   429     -> RATE_LIMIT_EXCEEDED (details.retryAfterSeconds carries Retry-After)
+ *   500/503 -> EXECUTION_FAILED (retryable)
+ *   other   -> EXECUTION_FAILED
+ */
+export function mapGraphError(
+  status: number,
+  data: unknown,
+  headers: Record<string, unknown> | undefined,
+  resourceType: string
+): MatimoError {
+  const graphError = (data as GraphErrorBody | undefined)?.error;
+  const details: Record<string, unknown> = { statusCode: status, graphError, resourceType };
+
+  if (status === 401 || status === 403) {
+    return new MatimoError(
+      'Microsoft Graph access denied. Check connection status in Nova.',
+      ErrorCode.AUTH_FAILED,
+      details
+    );
+  }
+
+  if (status === 404) {
+    return new MatimoError(`${resourceType} not found.`, ErrorCode.FILE_NOT_FOUND, details);
+  }
+
+  if (status === 429) {
+    const retryAfterHeader = headers?.['retry-after'] ?? headers?.['Retry-After'];
+    const retryAfterSeconds =
+      retryAfterHeader !== undefined ? Number(retryAfterHeader) : undefined;
+    return new MatimoError(
+      'Microsoft Graph rate limit exceeded. Respect Retry-After before retrying.',
+      ErrorCode.RATE_LIMIT_EXCEEDED,
+      { ...details, retryAfterSeconds }
+    );
+  }
+
+  if (status === 500 || status === 503) {
+    return new MatimoError(
+      'Microsoft Graph service is temporarily unavailable. Please retry shortly.',
+      ErrorCode.EXECUTION_FAILED,
+      details
+    );
+  }
+
+  return new MatimoError(
+    `Microsoft Graph request failed with status ${status}.`,
+    ErrorCode.EXECUTION_FAILED,
+    details
+  );
+}
+
+function buildQueryString(query?: Record<string, string | number | undefined>): string {
+  if (!query) return '';
+  const parts = Object.entries(query)
+    .filter(([, value]) => value !== undefined && value !== null && value !== '')
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+  return parts.length > 0 ? `?${parts.join('&')}` : '';
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export interface GraphRequestOptions {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  /** Path relative to https://graph.microsoft.com/v1.0, e.g. '/me/messages' */
+  path: string;
+  token: string;
+  query?: Record<string, string | number | undefined>;
+  body?: unknown;
+  headers?: Record<string, string>;
+  /** Human-readable resource name used to build a clear 404 message, e.g. 'Drive item' */
+  resourceType?: string;
+  /** Set to 'arraybuffer' for binary downloads (e.g. file content) */
+  responseType?: 'json' | 'arraybuffer';
+  /** Treat a 204/empty body as success and return null (e.g. publish, sendMail) */
+  allowEmptyResponse?: boolean;
+}
+
+/**
+ * Perform an authenticated Microsoft Graph request with retry-on-429/5xx
+ * (respecting Retry-After, exponential backoff, max 3 retries) and normalized
+ * MatimoError mapping for every other failure.
+ */
+export async function graphRequest<T = unknown>(options: GraphRequestOptions): Promise<T> {
+  const {
+    method,
+    path,
+    token,
+    query,
+    body,
+    headers,
+    resourceType = 'Resource',
+    responseType = 'json',
+    allowEmptyResponse = false,
+  } = options;
+
+  const url = `${GRAPH_BASE_URL}${path}${buildQueryString(query)}`;
+
+  let attempt = 0;
+  for (;;) {
+    let response;
+    try {
+      response = await axios.request({
+        method,
+        url,
+        data: body,
+        responseType,
+        validateStatus: () => true,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          ...(responseType === 'json' ? { Accept: 'application/json' } : {}),
+          ...(body !== undefined && !(body instanceof Buffer)
+            ? { 'Content-Type': 'application/json' }
+            : {}),
+          ...headers,
+        },
+      });
+    } catch (error) {
+      throw new MatimoError(
+        'Microsoft Graph request failed before a response was received (network error).',
+        ErrorCode.NETWORK_ERROR,
+        { path, originalError: error instanceof Error ? error.message : String(error) },
+        error
+      );
+    }
+
+    if (response.status >= 200 && response.status < 300) {
+      if (allowEmptyResponse && (response.status === 204 || !response.data)) {
+        return null as T;
+      }
+      return response.data as T;
+    }
+
+    const error = mapGraphError(
+      response.status,
+      response.data,
+      response.headers as Record<string, unknown>,
+      resourceType
+    );
+
+    const isRetryable = RETRYABLE_STATUS_CODES.has(response.status) && attempt < MAX_RETRIES;
+    if (!isRetryable) {
+      throw error;
+    }
+
+    const retryAfterSeconds = error.details?.retryAfterSeconds as number | undefined;
+    const delayMs =
+      retryAfterSeconds !== undefined && !Number.isNaN(retryAfterSeconds)
+        ? retryAfterSeconds * 1000
+        : INITIAL_BACKOFF_MS * 2 ** attempt;
+
+    attempt += 1;
+    await sleep(delayMs);
+  }
+}

package/tools/ms_create_calendar_event/definition.yaml

@@ -0,0 +1,100 @@
+name: ms_create_calendar_event
+description: |
+  Create an event on the signed-in user's default calendar (POST /me/events).
+  Supports attendees, location, a single IANA/Windows time zone for both start and
+  end, and Microsoft Teams online meetings (isOnlineMeeting), returning the meeting's
+  join URL when one is created.
+version: '1.0.0'
+status: approved
+risk: medium
+
+parameters:
+  subject:
+    type: string
+    description: Title of the event
+    required: true
+
+  body:
+    type: string
+    description: Description / agenda for the event (plain text)
+    required: false
+
+  start:
+    type: string
+    description: 'Start date and time, e.g. "2026-06-15T09:00:00"'
+    required: true
+
+  end:
+    type: string
+    description: 'End date and time, e.g. "2026-06-15T09:30:00"'
+    required: true
+
+  timezone:
+    type: string
+    description: 'IANA or Windows time zone applied to both `start` and `end`, e.g. "America/Los_Angeles"'
+    required: false
+    default: UTC
+
+  attendees:
+    type: array
+    description: Email addresses of attendees to invite
+    required: false
+
+  location:
+    type: string
+    description: Free-text location / room name for the event
+    required: false
+
+  is_online_meeting:
+    type: boolean
+    description: When true, Microsoft Teams creates an online meeting for this event
+    required: false
+    default: false
+
+execution:
+  type: function
+  code: ms_create_calendar_event.ts
+  timeout: 25000
+
+authentication:
+  type: oauth2
+  provider: microsoft
+  scopes:
+    - https://graph.microsoft.com/Calendars.ReadWrite
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    event_id:
+      type: string
+    web_link:
+      type: string
+    join_url:
+      type: string
+      description: Microsoft Teams meeting join URL — present only when is_online_meeting is true
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+tags: [microsoft, graph, calendar, outlook, teams, write]
+
+examples:
+  - name: Schedule a 30-minute internal sync
+    params:
+      subject: 'Sprint planning'
+      start: '2026-06-15T09:00:00'
+      end: '2026-06-15T09:30:00'
+      timezone: 'America/Los_Angeles'
+      attendees: ['alice@contoso.com', 'bob@contoso.com']
+  - name: Schedule an online Teams meeting with a location fallback
+    params:
+      subject: 'All-hands'
+      start: '2026-06-20T17:00:00'
+      end: '2026-06-20T18:00:00'
+      timezone: UTC
+      location: 'Building 4, Room 200'
+      is_online_meeting: true

package/tools/ms_create_calendar_event/ms_create_calendar_event.ts

@@ -0,0 +1,79 @@
+/**
+ * ms_create_calendar_event — POST /me/events
+ * https://learn.microsoft.com/en-us/graph/api/user-post-events
+ */
+import { MatimoError, ErrorCode } from '@matimo/core';
+import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+
+const DEFAULT_TIMEZONE = 'UTC';
+
+interface OnlineMeeting {
+  joinUrl?: string;
+}
+
+interface CalendarEvent {
+  id?: string;
+  webLink?: string;
+  onlineMeeting?: OnlineMeeting;
+}
+
+function toAttendeeList(value: unknown): Array<{ emailAddress: { address: string }; type: 'required' }> {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || !entry)) {
+    throw new MatimoError(
+      "ms_create_calendar_event: 'attendees' must be an array of email address strings",
+      ErrorCode.VALIDATION_FAILED,
+      { attendees: value }
+    );
+  }
+  return (value as string[]).map((address) => ({
+    emailAddress: { address },
+    type: 'required' as const,
+  }));
+}
+
+export default async function execute(
+  params: Record<string, unknown>,
+  context?: ToolContext
+): Promise<unknown> {
+  requireParams(params, ['subject', 'start', 'end'], 'ms_create_calendar_event');
+
+  const subject = String(params.subject);
+  const start = String(params.start);
+  const end = String(params.end);
+  const timezone =
+    typeof params.timezone === 'string' && params.timezone ? params.timezone : DEFAULT_TIMEZONE;
+
+  const attendees = toAttendeeList(params.attendees);
+  const isOnlineMeeting = params.is_online_meeting === true;
+
+  const token = getAccessToken(context);
+
+  const event = await graphRequest<CalendarEvent>({
+    method: 'POST',
+    path: '/me/events',
+    token,
+    resourceType: 'Calendar',
+    body: {
+      subject,
+      ...(typeof params.body === 'string' && params.body
+        ? { body: { contentType: 'Text', content: params.body } }
+        : {}),
+      start: { dateTime: start, timeZone: timezone },
+      end: { dateTime: end, timeZone: timezone },
+      ...(attendees.length > 0 ? { attendees } : {}),
+      ...(typeof params.location === 'string' && params.location
+        ? { location: { displayName: params.location } }
+        : {}),
+      isOnlineMeeting,
+      ...(isOnlineMeeting ? { onlineMeetingProvider: 'teamsForBusiness' } : {}),
+    },
+  });
+
+  return {
+    success: true,
+    event_id: event?.id ?? '',
+    web_link: event?.webLink ?? '',
+    ...(event?.onlineMeeting?.joinUrl ? { join_url: event.onlineMeeting.joinUrl } : {}),
+  };
+}

package/tools/ms_create_document/definition.yaml

@@ -0,0 +1,103 @@
+name: ms_create_document
+description: |
+  Create (or overwrite) a small file in OneDrive or a SharePoint document library by
+  uploading content directly
+  (PUT /drives/{drive_id}/items/{parent_item_id}:/{filename}:/content). Intended for
+  small text-based documents — Microsoft Graph requires resumable upload sessions for
+  files larger than 4 MB, which this tool does not implement.
+version: '1.0.0'
+status: approved
+risk: medium
+
+parameters:
+  drive_id:
+    type: string
+    description: ID of the destination drive (OneDrive or SharePoint document library)
+    required: true
+
+  parent_item_id:
+    type: string
+    description: ID of the destination folder item. Defaults to the drive's root folder.
+    required: false
+    default: root
+
+  filename:
+    type: string
+    description: 'Name to give the new file, including extension, e.g. "report.md"'
+    required: true
+
+  content:
+    type: string
+    description: File content. Provide as plain text, or as base64 when content_encoding is "base64"
+    required: true
+
+  content_encoding:
+    type: string
+    description: How `content` is encoded
+    required: false
+    default: text
+    enum: [text, base64]
+
+  conflict_behaviour:
+    type: string
+    description: >-
+      How to handle a name collision with an existing item. Passed as the
+      @microsoft.graph.conflictBehavior query hint on a best-effort basis — Graph's
+      simple-upload (PUT .../content) endpoint documents this parameter primarily for
+      resumable upload sessions, so behaviour may vary by tenant/library configuration.
+    required: false
+    default: replace
+    enum: [replace, rename, fail]
+
+execution:
+  type: function
+  code: ms_create_document.ts
+  timeout: 30000
+
+authentication:
+  type: oauth2
+  provider: microsoft
+  scopes:
+    - https://graph.microsoft.com/Files.ReadWrite
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    item_id:
+      type: string
+    name:
+      type: string
+    web_url:
+      type: string
+    size_bytes:
+      type: number
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+tags: [microsoft, graph, files, onedrive, sharepoint, write]
+
+examples:
+  - name: Create a Markdown summary document at the drive root
+    params:
+      drive_id: 'b!xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      filename: 'meeting-notes-2026-06-07.md'
+      content: '# Meeting notes\n\n- Decided to ship v2.4.0 next week'
+  - name: Upload a base64-encoded file into a specific folder
+    params:
+      drive_id: 'b!xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      parent_item_id: '01ABCXYZ7654321'
+      filename: 'export.csv'
+      content: 'bmFtZSxlbWFpbAphbGljZSxhbGljZUBjb250b3NvLmNvbQ=='
+      content_encoding: base64
+      conflict_behaviour: rename
+
+notes:
+  caution: >-
+    Uses the simple-upload endpoint, which Microsoft Graph limits to files up to
+    4 MB. Larger files require a resumable upload session
+    (createUploadSession), which this tool does not implement.