@matimo/microsoft 0.1.0

package/tools/ms_read_file/definition.yaml

@@ -0,0 +1,74 @@
+name: ms_read_file
+description: |
+  Read the contents of a file stored in OneDrive or a SharePoint document library
+  (GET /drives/{drive_id}/items/{item_id}/content). Plain-text formats (text, HTML,
+  CSV, JSON, Markdown, XML) are decoded and returned as UTF-8 text. Rich document
+  formats (PDF, Word, Excel, PowerPoint) and other binary formats are NOT extracted —
+  the tool returns an empty `content` string plus a `warning` explaining why, so
+  agents can fall back to sharing the file's web URL instead of guessing at content.
+version: '1.0.0'
+status: approved
+risk: low
+
+parameters:
+  drive_id:
+    type: string
+    description: ID of the drive (OneDrive or SharePoint document library) containing the file
+    required: true
+
+  item_id:
+    type: string
+    description: ID of the drive item (file) to read
+    required: true
+
+execution:
+  type: function
+  code: ms_read_file.ts
+  timeout: 30000
+
+authentication:
+  type: oauth2
+  provider: microsoft
+  scopes:
+    - https://graph.microsoft.com/Files.Read.All
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    content:
+      type: string
+      description: UTF-8 text content of the file, or an empty string if extraction is not supported
+    name:
+      type: string
+    mime_type:
+      type: string
+    size_bytes:
+      type: number
+    warning:
+      type: string
+      description: Present only when text extraction was not performed for this file's format
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+tags: [microsoft, graph, files, onedrive, sharepoint, read]
+
+examples:
+  - name: Read a plain-text README from OneDrive
+    params:
+      drive_id: 'b!xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      item_id: '01ABCXYZ7654321'
+  - name: Read a CSV export from a SharePoint document library
+    params:
+      drive_id: 'b!yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
+      item_id: '01DEF9876543210'
+
+notes:
+  caution: >-
+    Rich document formats (PDF, DOCX, XLSX, PPTX, legacy DOC/XLS) and other binary
+    formats return `content: ""` with a `warning` rather than extracted text — this
+    tool intentionally avoids bundling unverified third-party parsing libraries.

package/tools/ms_read_file/ms_read_file.ts

@@ -0,0 +1,102 @@
+/**
+ * ms_read_file — GET /drives/{drive_id}/items/{item_id}/content
+ * https://learn.microsoft.com/en-us/graph/api/driveitem-get-content
+ *
+ * Scope decision (documented, not a shortcut): this tool performs REAL UTF-8 text
+ * extraction only for plain-text formats. Rich document formats (PDF/Word/Excel/
+ * PowerPoint) return `content: ""` with a format-specific warning rather than
+ * bundling unverified parsing dependencies (no matimo package currently depends on
+ * pdf-parse/mammoth/xlsx/cheerio). Truly-unsupported binaries get the exact warning
+ * the tool's contract specifies: "Binary file — text extraction not supported".
+ */
+import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+
+const TEXT_MIME_PREFIXES = ['text/'];
+const TEXT_MIME_TYPES = new Set(['application/json', 'application/xml']);
+
+const RICH_DOCUMENT_LABELS: Record<string, string> = {
+  'application/pdf': 'PDF document',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'Word document (.docx)',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'Excel workbook (.xlsx)',
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation':
+    'PowerPoint presentation (.pptx)',
+  'application/msword': 'Word document (.doc)',
+  'application/vnd.ms-excel': 'Excel workbook (.xls)',
+  'application/vnd.ms-powerpoint': 'PowerPoint presentation (.ppt)',
+};
+
+interface DriveItemMetadata {
+  name?: string;
+  size?: number;
+  file?: { mimeType?: string };
+}
+
+function isPlainTextMime(mimeType: string): boolean {
+  return TEXT_MIME_TYPES.has(mimeType) || TEXT_MIME_PREFIXES.some((p) => mimeType.startsWith(p));
+}
+
+export default async function execute(
+  params: Record<string, unknown>,
+  context?: ToolContext
+): Promise<unknown> {
+  requireParams(params, ['drive_id', 'item_id'], 'ms_read_file');
+
+  const driveId = String(params.drive_id);
+  const itemId = String(params.item_id);
+  const token = getAccessToken(context);
+
+  const metadata = await graphRequest<DriveItemMetadata>({
+    method: 'GET',
+    path: `/drives/${encodeURIComponent(driveId)}/items/${encodeURIComponent(itemId)}`,
+    token,
+    resourceType: 'Drive item',
+    query: { $select: 'name,size,file' },
+  });
+
+  const name = metadata?.name ?? '';
+  const mimeType = metadata?.file?.mimeType ?? 'application/octet-stream';
+  const sizeBytes = metadata?.size ?? 0;
+
+  const raw = await graphRequest<ArrayBuffer>({
+    method: 'GET',
+    path: `/drives/${encodeURIComponent(driveId)}/items/${encodeURIComponent(itemId)}/content`,
+    token,
+    resourceType: 'Drive item content',
+    responseType: 'arraybuffer',
+  });
+
+  const buffer = Buffer.from(raw);
+
+  if (isPlainTextMime(mimeType)) {
+    return {
+      success: true,
+      content: buffer.toString('utf-8'),
+      name,
+      mime_type: mimeType,
+      size_bytes: sizeBytes,
+    };
+  }
+
+  const richDocumentLabel = RICH_DOCUMENT_LABELS[mimeType];
+  if (richDocumentLabel) {
+    return {
+      success: true,
+      content: '',
+      name,
+      mime_type: mimeType,
+      size_bytes: sizeBytes,
+      warning:
+        `${richDocumentLabel} — text extraction for this format is not implemented to avoid ` +
+        'bundling unverified parsing dependencies. Share the file via its web URL instead.',
+    };
+  }
+
+  return {
+    success: true,
+    content: '',
+    name,
+    mime_type: mimeType,
+    size_bytes: sizeBytes,
+    warning: 'Binary file — text extraction not supported',
+  };
+}

package/tools/ms_search_knowledge/definition.yaml

@@ -0,0 +1,99 @@
+name: ms_search_knowledge
+description: |
+  Search across Microsoft 365 content — SharePoint sites, OneDrive/SharePoint document
+  libraries, and list items — using the Microsoft Search API (POST /search/query).
+  Returns ranked hits with summaries and links, useful for grounding agent answers in
+  organizational knowledge.
+version: '1.0.0'
+status: approved
+risk: low
+
+parameters:
+  query:
+    type: string
+    description: 'Search query string. Supports KQL syntax, e.g. "quarterly report filetype:xlsx"'
+    required: true
+
+  entity_types:
+    type: array
+    description: Microsoft Search entity types to search across
+    required: false
+    default: [driveItem, listItem, site]
+
+  site_id:
+    type: string
+    description: >-
+      Optional SharePoint site ID used to scope the search. The Microsoft Search API has
+      no dedicated site filter for these entity types, so this is folded into the query
+      string as a best-effort hint rather than a guaranteed server-side filter.
+    required: false
+
+  drive_id:
+    type: string
+    description: >-
+      Optional OneDrive/SharePoint drive ID used to scope the search. Same best-effort
+      caveat as site_id — there is no dedicated drive filter in the Search API for these
+      entity types.
+    required: false
+
+  top:
+    type: number
+    description: Maximum number of results to return (1-25)
+    required: false
+    default: 10
+
+execution:
+  type: function
+  code: ms_search_knowledge.ts
+  timeout: 20000
+
+authentication:
+  type: oauth2
+  provider: microsoft
+  scopes:
+    - https://graph.microsoft.com/Sites.Read.All
+    - https://graph.microsoft.com/Files.Read.All
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    results:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+          name:
+            type: string
+          summary:
+            type: string
+          web_url:
+            type: string
+          last_modified:
+            type: string
+          score:
+            type: number
+    total_count:
+      type: number
+      description: Total number of hits reported by Microsoft Search for this query
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+tags: [microsoft, graph, search, knowledge, sharepoint, onedrive]
+
+examples:
+  - name: Search the tenant for a budget spreadsheet
+    params:
+      query: 'Q3 budget filetype:xlsx'
+      top: 5
+  - name: Search a specific SharePoint site for onboarding docs
+    params:
+      query: 'onboarding checklist'
+      site_id: 'contoso.sharepoint.com,11111111-1111-1111-1111-111111111111'
+      entity_types: [driveItem, listItem]

package/tools/ms_search_knowledge/ms_search_knowledge.ts

@@ -0,0 +1,109 @@
+/**
+ * ms_search_knowledge — POST /search/query
+ * https://learn.microsoft.com/en-us/graph/api/search-query
+ */
+import { MatimoError, ErrorCode } from '@matimo/core';
+import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+
+const VALID_ENTITY_TYPES = ['driveItem', 'listItem', 'site', 'list', 'drive'];
+const DEFAULT_ENTITY_TYPES = ['driveItem', 'listItem', 'site'];
+const DEFAULT_TOP = 10;
+const MAX_TOP = 25;
+
+interface SearchHit {
+  hitId?: string;
+  rank?: number;
+  summary?: string;
+  resource?: {
+    id?: string;
+    name?: string;
+    webUrl?: string;
+    lastModifiedDateTime?: string;
+  };
+}
+
+interface SearchResponse {
+  value?: Array<{
+    hitsContainers?: Array<{
+      total?: number;
+      hits?: SearchHit[];
+    }>;
+  }>;
+}
+
+export default async function execute(
+  params: Record<string, unknown>,
+  context?: ToolContext
+): Promise<unknown> {
+  requireParams(params, ['query'], 'ms_search_knowledge');
+
+  const query = String(params.query);
+
+  const entityTypes = Array.isArray(params.entity_types)
+    ? (params.entity_types as unknown[]).map(String)
+    : DEFAULT_ENTITY_TYPES;
+
+  const invalidEntityTypes = entityTypes.filter((t) => !VALID_ENTITY_TYPES.includes(t));
+  if (entityTypes.length === 0 || invalidEntityTypes.length > 0) {
+    throw new MatimoError(
+      `ms_search_knowledge: invalid entity_types ${JSON.stringify(invalidEntityTypes)}. ` +
+        `Valid values are: ${VALID_ENTITY_TYPES.join(', ')}`,
+      ErrorCode.VALIDATION_FAILED,
+      { entityTypes, invalidEntityTypes }
+    );
+  }
+
+  const top = params.top === undefined ? DEFAULT_TOP : Number(params.top);
+  if (!Number.isFinite(top) || top < 1 || top > MAX_TOP) {
+    throw new MatimoError(
+      `ms_search_knowledge: 'top' must be a number between 1 and ${MAX_TOP} (received ${String(params.top)})`,
+      ErrorCode.VALIDATION_FAILED,
+      { top: params.top }
+    );
+  }
+
+  // Microsoft Search has no dedicated site/drive filter for driveItem/listItem/site
+  // entity types — fold the IDs into the query string as a best-effort scoping hint.
+  // This is documented in the tool description so callers don't expect a hard filter.
+  const scopeHints = [params.site_id, params.drive_id].filter(
+    (value): value is string => typeof value === 'string' && value.length > 0
+  );
+  const queryString = scopeHints.length > 0 ? `${query} ${scopeHints.join(' ')}` : query;
+
+  const token = getAccessToken(context);
+
+  const data = await graphRequest<SearchResponse>({
+    method: 'POST',
+    path: '/search/query',
+    token,
+    resourceType: 'Search results',
+    body: {
+      requests: [
+        {
+          entityTypes,
+          query: { queryString },
+          from: 0,
+          size: top,
+        },
+      ],
+    },
+  });
+
+  const container = data?.value?.[0]?.hitsContainers?.[0];
+  const hits = container?.hits ?? [];
+
+  const results = hits.map((hit) => ({
+    id: hit.resource?.id ?? hit.hitId ?? '',
+    name: hit.resource?.name ?? '',
+    summary: hit.summary ?? '',
+    web_url: hit.resource?.webUrl ?? '',
+    last_modified: hit.resource?.lastModifiedDateTime ?? '',
+    score: hit.rank ?? 0,
+  }));
+
+  return {
+    success: true,
+    results,
+    total_count: container?.total ?? results.length,
+  };
+}

package/tools/ms_send_email/definition.yaml

@@ -0,0 +1,94 @@
+name: ms_send_email
+description: |
+  Send an email as the signed-in user. Microsoft Graph's /me/sendMail endpoint returns
+  an empty 202 Accepted with no message identifier, so this tool creates a draft first
+  (POST /me/messages, which returns an `id`) and then sends that draft
+  (POST /me/messages/{id}/send) — giving callers a real `message_id` to reference
+  afterwards. High-risk: this sends mail on the user's behalf and requires approval.
+version: '1.0.0'
+status: approved
+risk: high
+requires_approval: true
+
+parameters:
+  to:
+    type: array
+    description: Recipient email addresses
+    required: true
+
+  subject:
+    type: string
+    description: Subject line of the email
+    required: true
+
+  body:
+    type: string
+    description: Body content of the email
+    required: true
+
+  body_type:
+    type: string
+    description: Whether `body` is plain text or HTML
+    required: false
+    default: text
+    enum: [text, html]
+
+  cc:
+    type: array
+    description: CC recipient email addresses
+    required: false
+
+  bcc:
+    type: array
+    description: BCC recipient email addresses
+    required: false
+
+execution:
+  type: function
+  code: ms_send_email.ts
+  timeout: 30000
+
+authentication:
+  type: oauth2
+  provider: microsoft
+  scopes:
+    - https://graph.microsoft.com/Mail.Send
+    - https://graph.microsoft.com/Mail.ReadWrite
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    sent:
+      type: boolean
+    message_id:
+      type: string
+      description: ID of the sent message (obtained from the draft creation step)
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+tags: [microsoft, graph, mail, outlook, send, write]
+
+examples:
+  - name: Send a plain-text email to one recipient
+    params:
+      to: ['alice@contoso.com']
+      subject: 'Weekly status update'
+      body: 'Here is the summary for this week...'
+  - name: Send an HTML email with CC
+    params:
+      to: ['team@contoso.com']
+      cc: ['manager@contoso.com']
+      subject: 'Release notes — v2.4.0'
+      body: '<h1>v2.4.0</h1><p>Highlights...</p>'
+      body_type: html
+
+notes:
+  caution: >-
+    This tool sends real email on behalf of the connected user. It is marked
+    risk: high and requires_approval: true — Matimo will route it through the
+    human-in-the-loop approval flow before it executes.

package/tools/ms_send_email/ms_send_email.ts

@@ -0,0 +1,98 @@
+/**
+ * ms_send_email — draft + send, two Graph calls
+ *   1. POST /me/messages           https://learn.microsoft.com/en-us/graph/api/user-post-messages
+ *   2. POST /me/messages/{id}/send https://learn.microsoft.com/en-us/graph/api/message-send
+ *
+ * Why two calls: POST /me/sendMail returns an empty 202 Accepted with no message
+ * identifier, but this tool's contract promises a `message_id`. Creating a draft
+ * first gives us a real message ID we can report back, then we send that draft.
+ */
+import { MatimoError, ErrorCode } from '@matimo/core';
+import { getAccessToken, requireParams, graphRequest, type ToolContext } from '../graph-client';
+
+const VALID_BODY_TYPES = ['text', 'html'];
+
+interface DraftMessage {
+  id?: string;
+}
+
+function toRecipientList(value: unknown, fieldName: string): Array<{ emailAddress: { address: string } }> {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || !entry)) {
+    throw new MatimoError(
+      `ms_send_email: '${fieldName}' must be an array of email address strings`,
+      ErrorCode.VALIDATION_FAILED,
+      { field: fieldName, received: value }
+    );
+  }
+  return (value as string[]).map((address) => ({ emailAddress: { address } }));
+}
+
+export default async function execute(
+  params: Record<string, unknown>,
+  context?: ToolContext
+): Promise<unknown> {
+  requireParams(params, ['to', 'subject', 'body'], 'ms_send_email');
+
+  const to = toRecipientList(params.to, 'to');
+  if (to.length === 0) {
+    throw new MatimoError(
+      "ms_send_email: 'to' must contain at least one recipient email address",
+      ErrorCode.VALIDATION_FAILED,
+      { to: params.to }
+    );
+  }
+  const cc = toRecipientList(params.cc, 'cc');
+  const bcc = toRecipientList(params.bcc, 'bcc');
+
+  const bodyType = params.body_type === undefined ? 'text' : String(params.body_type);
+  if (!VALID_BODY_TYPES.includes(bodyType)) {
+    throw new MatimoError(
+      `ms_send_email: 'body_type' must be one of ${VALID_BODY_TYPES.join(', ')} (received '${bodyType}')`,
+      ErrorCode.VALIDATION_FAILED,
+      { body_type: params.body_type }
+    );
+  }
+
+  const token = getAccessToken(context);
+
+  const draft = await graphRequest<DraftMessage>({
+    method: 'POST',
+    path: '/me/messages',
+    token,
+    resourceType: 'Mail draft',
+    body: {
+      subject: String(params.subject),
+      body: {
+        contentType: bodyType === 'html' ? 'HTML' : 'Text',
+        content: String(params.body),
+      },
+      toRecipients: to,
+      ...(cc.length > 0 ? { ccRecipients: cc } : {}),
+      ...(bcc.length > 0 ? { bccRecipients: bcc } : {}),
+    },
+  });
+
+  const messageId = draft?.id;
+  if (!messageId) {
+    throw new MatimoError(
+      'ms_send_email: Microsoft Graph did not return an ID for the created draft message.',
+      ErrorCode.EXECUTION_FAILED,
+      { draft }
+    );
+  }
+
+  await graphRequest({
+    method: 'POST',
+    path: `/me/messages/${encodeURIComponent(messageId)}/send`,
+    token,
+    resourceType: 'Mail draft',
+    allowEmptyResponse: true,
+  });
+
+  return {
+    success: true,
+    sent: true,
+    message_id: messageId,
+  };
+}

package/tools/ms_send_teams_message/definition.yaml

@@ -0,0 +1,87 @@
+name: ms_send_teams_message
+description: |
+  Post a message to a Microsoft Teams channel (POST /teams/{team_id}/channels/{channel_id}/messages),
+  optionally as a reply to an existing message
+  (POST /teams/{team_id}/channels/{channel_id}/messages/{reply_to_message_id}/replies).
+version: '1.0.0'
+status: approved
+risk: medium
+
+parameters:
+  team_id:
+    type: string
+    description: ID of the team that owns the channel
+    required: true
+
+  channel_id:
+    type: string
+    description: ID of the channel to post the message to
+    required: true
+
+  text:
+    type: string
+    description: Message content
+    required: true
+
+  reply_to_message_id:
+    type: string
+    description: >-
+      ID of an existing message to reply to. When provided, the message is posted
+      as a threaded reply instead of a new top-level channel message.
+    required: false
+
+  content_type:
+    type: string
+    description: Whether `text` is plain text or HTML
+    required: false
+    default: text
+    enum: [text, html]
+
+execution:
+  type: function
+  code: ms_send_teams_message.ts
+  timeout: 20000
+
+authentication:
+  type: oauth2
+  provider: microsoft
+  scopes:
+    - https://graph.microsoft.com/ChannelMessage.Send
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    message_id:
+      type: string
+    web_url:
+      type: string
+    created_at:
+      type: string
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+tags: [microsoft, graph, teams, chat, write]
+
+examples:
+  - name: Post a status update to a channel
+    params:
+      team_id: '11111111-1111-1111-1111-111111111111'
+      channel_id: '19:abcdefgh@thread.tacv2'
+      text: 'Deployment to production completed successfully ✅'
+  - name: Reply to an existing thread
+    params:
+      team_id: '11111111-1111-1111-1111-111111111111'
+      channel_id: '19:abcdefgh@thread.tacv2'
+      reply_to_message_id: '1700000000000'
+      text: 'Following up — this is now resolved.'
+
+notes:
+  caution: >-
+    Posts a real message visible to the channel's members. Marked risk: medium —
+    review the policy tier configuration if your deployment requires HITL approval
+    for Teams writes as well.