xlsx-for-ai 2.21.0 → 2.23.0

package/README.md

@@ -194,6 +194,14 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 | Tool | What it does |
 |---|---|
 | `xlsx_post_slack` | Post a workbook to a Slack channel as a file attachment with an optional message. BYOA — the agent supplies the user's Slack bot token (`xoxb-…`); the token is forwarded to Slack and never persisted. Uses Slack's external upload flow. |
+| `xlsx_post_teams` | Post a workbook to a Microsoft Teams channel as a file attachment in a channel message, with an optional message. BYOA — the agent supplies the user's Microsoft Graph access token (JWT); the token is forwarded to Microsoft and never persisted. Uses Graph's filesFolder + upload-session + post-message flow. |
+
+### Integrity verification
+
+| Tool | What it does |
+|---|---|
+| `xlsx_stamp` | Sign a workbook with a cryptographic "integrity verification" stamp — Ed25519-signed claims (named factual checks + their pass/fail/skip status + a content hash) embedded in `docProps/custom.xml`. The stamp travels with the file across saves; a recipient can verify it later to confirm the file hasn't been tampered with since signing. Factual attestations only — never an opinion-shaped seal of approval. |
+| `xlsx_verify_stamp` | Verify a workbook's embedded stamp. Returns (a) whether the Ed25519 signature is valid against the registered public key, (b) whether the workbook bytes match the hash IN the signed claims, and (c) the full check-result content of the stamp. Three distinct trust signals — signature integrity, content integrity, and what was originally attested. |
 
 Tool responses include a citation footer and a `_meta` block (tool name, version, tier, request ID, `powered_by`). Both pass through verbatim; nothing is stripped.
 

package/mcp.js

@@ -849,6 +849,79 @@ const TOOLS = [
       required: ['file_path', 'channel', 'slack_token'],
     },
   },
+
+  {
+    name: 'xlsx_post_teams',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: upload a local .xlsx file to a Microsoft Teams channel as a file attachment in a channel message, with an optional accompanying message. BYOA — the agent must pass the user\'s Microsoft Graph access token (a JWT starting with "eyJ"). The token is forwarded to Microsoft Graph and never stored server-side.\n' +
+      'Uses Microsoft Graph\'s 4-step flow: locate the channel\'s filesFolder driveItem, create an upload session, upload the bytes, then post a chatMessage with the file as an inline attachment.\n\n' +
+      'USE WHEN: the user asks "post this workbook to my Teams channel," "share this with the team in Teams," or any other outbound-file-to-Teams request. The agent has just produced or modified a workbook and wants to deliver it to a Microsoft Teams channel. ' +
+      'Free tier — counts against the 10k/mo cap.\n\n' +
+      'DO NOT USE WHEN: posting to Slack (use xlsx_post_slack). Or when there is no Microsoft Graph token available — the user must have an Entra ID app registration with Group.ReadWrite.All or Files.ReadWrite.All + ChannelMessage.Send scopes, AND a valid access token for that app.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to post.' },
+        team_id: { type: 'string', description: 'Microsoft Teams team ID (GUID). Find via Graph: GET /me/joinedTeams.' },
+        channel_id: { type: 'string', description: 'Microsoft Teams channel ID. Find via Graph: GET /teams/{team-id}/channels.' },
+        graph_token: { type: 'string', description: 'Microsoft Graph access token (JWT). Forwarded to Microsoft; never persisted by us. Must have file-upload + channel-message-send scopes.' },
+        message: { type: 'string', description: 'Optional: message to post alongside the file. Plain text; will be HTML-escaped server-side.' },
+        filename: { type: 'string', description: 'Optional: filename Teams will display. Defaults to the basename of file_path.' },
+      },
+      required: ['file_path', 'team_id', 'channel_id', 'graph_token'],
+    },
+  },
+
+  {
+    name: 'xlsx_stamp',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: sign a workbook with a "workbook integrity verification" stamp — a cryptographic attestation embedded in docProps/custom.xml that says "this file was generated by these tools, passed these N specific checks, signed at this time, and hasn\'t been tampered with since." Factual claims only (never an opinion-shaped seal of approval). Returns the stamped workbook as base64 in _meta.file_b64; pass out_path to write to disk.\n' +
+      'The caller supplies the `checks` array (e.g., from a supervisor review): list of named tests, each with passed/failed/skipped status. Verifiers see the individual check results, not a single good/bad opinion.\n\n' +
+      'USE WHEN: the agent has just produced or reviewed a workbook and wants to attach provable provenance + check results that travel with the file. The recipient can later verify the stamp via xlsx_verify_stamp to confirm the file hasn\'t been modified and to see the original check results.\n\n' +
+      'DO NOT USE WHEN: the user just wants to share a file (use xlsx_post_slack / xlsx_post_teams). Or when there are no real checks to attest to (an empty checks array is allowed and means "we ran zero checks" — but the stamp\'s value is in the checks it records).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to stamp.' },
+        checks: {
+          type: 'array',
+          description: 'Array of named checks, each with passed/failed/skipped status. These are the factual claims the stamp attests to.',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', description: 'Stable check identifier (e.g., "tieouts_consistent").' },
+              name: { type: 'string', description: 'Human-readable check name.' },
+              status: { type: 'string', enum: ['passed', 'failed', 'skipped'] },
+              detail: { type: 'string', description: 'Optional explanation, especially for failed/skipped status.' },
+            },
+            required: ['id', 'name', 'status'],
+          },
+        },
+        out_path: { type: 'string', description: 'Optional: write the stamped workbook to this absolute path. If omitted, the stamped bytes are returned in _meta.file_b64 only.' },
+        exclude_sheets: { type: 'array', items: { type: 'string' }, description: 'Optional: sheet names to exclude from the content hash. Use for scratch tabs that legitimately change without affecting attestation.' },
+        supervisor_version: { type: 'string', description: 'Optional: xlsx-supervisor version string to include in the stamp\'s generated_by claim (e.g., "xlsx-supervisor@1.4.0").' },
+      },
+      required: ['file_path', 'checks'],
+    },
+  },
+
+  {
+    name: 'xlsx_verify_stamp',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: verify a workbook\'s embedded integrity-verification stamp. Returns whether the cryptographic signature is valid, whether the workbook bytes match what was signed (recomputed hash vs hash IN the stamp), and the full check-result content of the stamp.\n' +
+      'A workbook can fail verification three ways: (1) no stamp present (file was never stamped, or the stamp was stripped); (2) signature_valid=false (someone modified the claims after signing, or signed with a different key); (3) hash_matches=false (someone modified the workbook bytes after signing). Each is a distinct trust signal.\n\n' +
+      'USE WHEN: the agent (or a downstream verifier) needs to confirm a workbook hasn\'t been tampered with since it was signed, OR needs to surface the original check results that were attested to. Common scenario: incoming workbook from a counterparty, agent runs verify before trusting any of its values.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to verify.' },
+      },
+      required: ['file_path'],
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -1076,6 +1149,44 @@ async function dispatchTool(name, args) {
     return callTool('xlsx_post_slack', body);
   }
 
+  // xlsx_post_teams: outbound file-to-Teams. Same shape as Slack but with
+  // Microsoft Graph fields (team_id + channel_id + graph_token).
+  if (name === 'xlsx_post_teams') {
+    const body = {
+      file_b64: fileToB64(args.file_path),
+      team_id: args.team_id,
+      channel_id: args.channel_id,
+      graph_token: args.graph_token,
+    };
+    if (args.message !== undefined) body.message = args.message;
+    body.filename = args.filename || path.basename(args.file_path);
+    return callTool('xlsx_post_teams', body);
+  }
+
+  // xlsx_stamp: sign + embed an integrity-verification stamp. Returns the
+  // stamped file as base64 in _meta.file_b64; if out_path is provided we
+  // also write the bytes to disk (same pattern as xlsx_write / xlsx_redact).
+  if (name === 'xlsx_stamp') {
+    const body = {
+      file_b64: fileToB64(args.file_path),
+      checks: args.checks,
+    };
+    if (args.exclude_sheets !== undefined) body.exclude_sheets = args.exclude_sheets;
+    if (args.supervisor_version !== undefined) {
+      body.generated_by = { npm: 'xlsx-for-ai@' + require('./package.json').version, supervisor: args.supervisor_version };
+    }
+    const result = await callTool('xlsx_stamp', body);
+    return applyFileB64(result, args.out_path);
+  }
+
+  // xlsx_verify_stamp: extract + verify the integrity-verification stamp.
+  // Returns structured result in _meta.{valid, signature_valid, hash_matches,
+  // claims, workbook_hash_in_stamp, workbook_hash_recomputed, …}.
+  if (name === 'xlsx_verify_stamp') {
+    const body = { file_b64: fileToB64(args.file_path) };
+    return callTool('xlsx_verify_stamp', body);
+  }
+
   // All other tools (list_sheets, schema, hyperlinks, conditional_formats,
   // styles, etc.) — single-file relay. Forward any common option keys the
   // routes accept so we don't silently drop them. New keys added here as

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xlsx-for-ai",
   "mcpName": "io.github.senoff/xlsx-for-ai",
-  "version": "2.21.0",
+  "version": "2.23.0",
   "description": "The MCP server that makes LLMs reliable on real-world Excel spreadsheets. Thin npm client over a hosted API — read, write, diff, redact, and supervise .xlsx files from any MCP-aware agent.",
   "main": "index.js",
   "bin": {