@chrischall/office-outlook-mcp 0.0.0

package/skills/outlook-fpx/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: outlook-fpx
+description: Read and act on the user's Outlook / Microsoft 365 mailbox — mail, folders, calendar, contacts, tasks — via the Outlook REST API, using a bearer token lifted from their signed-in browser tab. Use when asked about their Outlook email, calendar or meetings.
+---
+
+# Outlook (Microsoft 365) access
+
+Talks to `https://outlook.office.com/api/v2.0` with a bearer token captured
+from the signed-in Outlook Web tab. **The browser is needed only to mint the
+token** (~25h lifetime) — every actual request is a plain server-side `curl`.
+
+## Setup (once)
+
+```sh
+npm i -g @fetchproxy/cli                      # provides `fpx`
+fpx profile add outlook --domain cloud.microsoft --domain office.com \
+                        --domain microsoft.com --domain office365.com
+fpx profile declare outlook \
+  --capture-header authorization@outlook.cloud.microsoft \
+  --capture-header authorization@outlook.office.com \
+  --allow-download
+```
+
+Declare **all** scopes before the first pairing — widening them later forces the
+user to re-approve. The first `fpx` call prints a 6-digit pair code to approve in
+the Transporter extension popup; the grant then persists.
+
+Requires the **Transporter** Chrome extension, and the extension and CLI must be
+on the **same major version** — a 3.x extension against a 2.x CLI fails by
+binding the port and silently never connecting.
+
+## Use
+
+```sh
+source references/outlook-env.sh
+outlook_token_refresh        # once per ~25h; needs an open, signed-in Outlook tab
+outlook_get '/me' | jq .
+```
+
+- `outlook_get <path> [curl args]` — GET, body on stdout
+- `outlook_get_text <path>` — same plus `Prefer: outlook.body-content-type="text"`; **use this for anything you will read** (measured 9.4× smaller than HTML)
+- `outlook_post <path> <json>` / `outlook_patch <path> <json>`
+- `outlook_token_expiry` — prints time remaining, never the token
+
+Paths are relative to `/api/v2.0`. Exit code **4** means non-2xx; a **401**
+prints `run: outlook_token_refresh`.
+
+Common starting points — full verified set, including calendar, contacts, tasks
+and write payloads, in **`references/api-recipes.md`**:
+
+```sh
+outlook_get '/me/mailfolders/inbox?$select=UnreadItemCount,TotalItemCount'
+outlook_get '/me/mailfolders/inbox/messages?$top=20&$orderby=ReceivedDateTime%20desc&$select=Id,Subject,From,ReceivedDateTime,IsRead'
+outlook_get '/me/calendarview?startDateTime=2026-09-20T00:00:00Z&endDateTime=2026-09-27T00:00:00Z&$select=Subject,Start,End,Location'
+```
+
+## Rules that bite
+
+- **Fields are PascalCase** (`ReceivedDateTime`, `IsRead`). This is the Outlook
+  REST API, *not* Graph — a camelCase Graph snippet silently returns nothing.
+- **Always pass `$select`.** The default projection is ~40 fields per message
+  including the full body.
+- **`$search` and `$filter` cannot be combined.**
+- **`/me/events` does not expand recurring series** — use `/me/calendarview`
+  with a start/end window for "what's on my schedule".
+- **`Prefer: outlook.timezone` takes Windows zone names** (`Eastern Standard
+  Time`), not IANA (`America/New_York`).
+- **`@odata.nextLink` is an absolute URL** — pass it to `curl -K ~/.outlook-fpx/curlrc`
+  directly, not to `outlook_get`, which would prefix the base again.
+- **`/owa/0/service.svc` is not this API** and returns 500. Use `/api/v2.0`.
+- **A 2xx is not proof a write persisted** — re-read the resource to confirm.
+- Never name a shell local `path` or `status`: in zsh `path` is tied to `PATH`
+  (assigning it wipes `PATH` mid-function) and `status` is read-only. Both are
+  harmless in bash, so this only breaks for zsh users.
+
+## Privacy
+
+This reads the user's real mailbox. Surface only what was asked for; do not dump
+message bodies, recipients or attachments into the transcript incidentally. The
+token lives in `~/.outlook-fpx/curlrc` (0600, its own directory — deliberately
+not shared with any MCP's state) and is passed to `curl` via `-K` so it never
+appears in `argv` or `ps` output.

package/skills/outlook-fpx/references/api-recipes.md

@@ -0,0 +1,163 @@
+# Outlook REST v2.0 — verified request shapes
+
+Every endpoint and header below was executed live against a real TransUnion
+M365 mailbox on 2026-09-20 and returned the status shown. Nothing here is
+inferred from documentation.
+
+Base: `https://outlook.office.com/api/v2.0`
+Auth: `Authorization: Bearer <token>` (see SKILL.md for capture)
+
+> **Fields are PascalCase.** This is the Outlook REST API, not Microsoft Graph.
+> `ReceivedDateTime`, `IsRead`, `BodyPreview` — not `receivedDateTime`. Copying a
+> Graph snippet here silently returns nothing useful.
+
+---
+
+## Identity
+
+```sh
+outlook_get '/me' | jq '{EmailAddress, DisplayName, Alias, MailboxGuid}'
+```
+Returns `Id, EmailAddress, DisplayName, Alias, MailboxGuid`. Cheapest liveness check.
+
+---
+
+## Mail
+
+### Folders
+
+```sh
+outlook_get '/me/mailfolders?$top=50' | jq -r '.value[] | "\(.UnreadItemCount)/\(.TotalItemCount)\t\(.DisplayName)"'
+```
+
+Item keys: `Id, DisplayName, ParentFolderId, ChildFolderCount, UnreadItemCount,
+TotalItemCount, SizeInBytes, IsHidden`.
+
+Well-known names usable in place of an id — all verified present:
+`inbox`, `drafts`, `sentitems`, `deleteditems`, `archive`, `junkemail`,
+`outbox`, `clutter`.
+
+```sh
+outlook_get '/me/mailfolders/inbox?$select=UnreadItemCount,TotalItemCount' | jq .
+```
+
+### Listing messages
+
+Always pass `$select` — the default projection returns ~40 fields per message
+including full `Body`, which is enormous on a 13k-message folder.
+
+```sh
+outlook_get '/me/mailfolders/inbox/messages?$top=20&$orderby=ReceivedDateTime%20desc&$select=Id,Subject,From,ReceivedDateTime,IsRead,HasAttachments' \
+  | jq -r '.value[] | "\(.ReceivedDateTime)  \(if .IsRead then " " else "•" end)  \(.From.EmailAddress.Name // "?")\t\(.Subject)"'
+```
+
+Unread only:
+```sh
+outlook_get '/me/mailfolders/inbox/messages?$filter=IsRead%20eq%20false&$top=25&$select=Id,Subject,From,ReceivedDateTime'
+```
+
+Full-text search (`$search` and `$filter` cannot be combined):
+```sh
+outlook_get '/me/messages?$search=%22quarterly%20report%22&$top=10&$select=Id,Subject,From,ReceivedDateTime'
+```
+
+Verified query options: `$top`, `$skip`, `$select`, `$filter`, `$orderby`,
+`$search`, `$count`. Paging: follow `@odata.nextLink` (absolute URL — pass it to
+`curl` directly, not through `outlook_get`, which prefixes the base).
+
+### Reading one message
+
+```sh
+outlook_get_text "/me/messages/$ID" | jq '{Subject, From, ReceivedDateTime, Body: .Body.Content}'
+```
+
+`outlook_get_text` sends `Prefer: outlook.body-content-type="text"`. Measured on
+a real message: **7,299 bytes HTML → 775 bytes text (9.4×)**; across a 5-message
+collection 37,638 → 12,828 bytes. Use it for anything an agent will read.
+
+Without the header the API returns whatever the message was authored in, so a
+collection comes back with a *mix* of `HTML` and `Text` — the `Prefer` header
+normalises all of them to `Text`.
+
+### Attachments
+
+```sh
+outlook_get "/me/messages/$ID/attachments?\$select=Id,Name,Size,ContentType" \
+  | jq -r '.value[] | "\(.Size)\t\(.ContentType)\t\(.Name)"'
+```
+Item keys: `@odata.type, @odata.mediaContentType, Id, Name, ContentType, Size`.
+Content bytes come back base64 in `ContentBytes` when `$select` does not exclude
+it; omit `$select` to get it, and expect the response to be ~1.37× the file size.
+
+---
+
+## Calendar
+
+```sh
+# events in a window — expands recurrences, which /me/events does NOT
+outlook_get '/me/calendarview?startDateTime=2026-09-20T00:00:00Z&endDateTime=2026-09-27T00:00:00Z&$select=Subject,Start,End,Location,Organizer&$orderby=Start/DateTime' \
+  -H 'Prefer: outlook.timezone="Eastern Standard Time"' \
+  | jq -r '.value[] | "\(.Start.DateTime)  \(.Subject)"'
+```
+
+`Prefer: outlook.timezone="<Windows tz name>"` is verified — `Start.TimeZone`
+comes back as the requested zone instead of UTC. Note it takes **Windows**
+zone names (`Eastern Standard Time`), not IANA (`America/New_York`).
+
+`/me/calendars` lists calendars; `/me/events` lists events **without** expanding
+recurring series, so prefer `/me/calendarview` for "what's on my schedule".
+
+---
+
+## Contacts, tasks, people
+
+```sh
+outlook_get '/me/contacts?$top=20&$select=DisplayName,EmailAddresses,CompanyName'
+outlook_get '/me/tasks?$top=20&$select=Subject,Status,DueDateTime'
+outlook_get '/me/people?$top=20&$select=DisplayName,ScoredEmailAddresses'   # relevance-ranked
+outlook_get '/me/MailboxSettings'                                            # tz, working hours, auto-reply
+```
+
+---
+
+## Writes
+
+All four routes were confirmed to exist and be authorised by POSTing a
+deliberately invalid body and receiving **400** (`UnableToDeserializePostBody` /
+`RequestBodyRead`) rather than 401/403/404. **The payloads below are shapes, not
+executed calls** — no mail was sent and nothing was mutated during the build.
+Verify the body of any write by re-reading the resource afterwards; a 2xx is not
+proof it persisted.
+
+```sh
+# send mail
+outlook_post '/me/sendmail' '{
+  "Message": {
+    "Subject": "…",
+    "Body": {"ContentType": "Text", "Content": "…"},
+    "ToRecipients": [{"EmailAddress": {"Address": "someone@example.com"}}]
+  },
+  "SaveToSentItems": true
+}'
+
+# mark read  /  move  /  create draft  /  create event
+outlook_patch "/me/messages/$ID" '{"IsRead": true}'
+outlook_post  "/me/messages/$ID/move" '{"DestinationId": "archive"}'
+outlook_post  '/me/messages' '{"Subject":"…","Body":{"ContentType":"Text","Content":"…"},"ToRecipients":[…]}'
+outlook_post  '/me/events'   '{"Subject":"…","Start":{"DateTime":"2026-09-22T15:00:00","TimeZone":"Eastern Standard Time"},"End":{…}}'
+```
+
+Send only to `@example.com` when testing.
+
+---
+
+## Errors
+
+| Signal | Meaning |
+|---|---|
+| `401`, **empty body**, `WWW-Authenticate: Bearer client_id="00000002-0000-0ff1-ce00-000000000000"` | token expired or revoked → `outlook_token_refresh` |
+| `400` + `error.code` (`UnableToDeserializePostBody`, `RequestBodyRead`) | route exists, payload is wrong |
+| `404` | wrong id or path — *not* an auth problem |
+| `500` on `/owa/0/service.svc` | that is the OWA internal endpoint; it is **not** part of this API. Use `/api/v2.0`. |
+
+`outlook_get` returns rc `4` for any non-2xx and prints the status to stderr.

package/skills/outlook-fpx/references/outlook-env.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# Outlook access helpers — source this file, then use outlook_get / outlook_post.
+#
+#   source references/outlook-env.sh
+#   outlook_token_refresh          # once per ~25h (browser needed only here)
+#   outlook_get '/me/messages?$top=5&$select=Subject,From' | jq .
+#
+# Works under bash and zsh. Data on stdout, diagnostics on stderr.
+# The bearer token never appears in argv (curl reads it from a 0600 config file).
+
+OUTLOOK_FPX_DIR="${OUTLOOK_FPX_DIR:-$HOME/.outlook-fpx}"
+OUTLOOK_FPX_PROFILE="${OUTLOOK_FPX_PROFILE:-outlook}"
+OUTLOOK_API="${OUTLOOK_API:-https://outlook.office.com/api/v2.0}"
+# Host whose outgoing Authorization header we snapshot. New Outlook Web is on
+# outlook.cloud.microsoft; older tenants still serve outlook.office.com.
+OUTLOOK_CAPTURE_HOST="${OUTLOOK_CAPTURE_HOST:-outlook.cloud.microsoft}"
+
+_outlook_curlrc() { printf '%s/curlrc' "$OUTLOOK_FPX_DIR"; }
+
+# Reload an open Outlook tab so the page re-issues API calls while we capture.
+# macOS/Chrome only; a no-op elsewhere (the capture still works if the tab is
+# active on its own, it is just less reliable).
+_outlook_poke_tab() {
+  command -v osascript >/dev/null 2>&1 || return 0
+  osascript - "$OUTLOOK_CAPTURE_HOST" <<'APPLESCRIPT' >/dev/null 2>&1 || true
+on run argv
+	set theHost to item 1 of argv
+	tell application "Google Chrome"
+		repeat with w in windows
+			repeat with t in tabs of w
+				if (URL of t) contains theHost then
+					tell t to reload
+					return "ok"
+				end if
+			end repeat
+		end repeat
+	end tell
+	return "none"
+end run
+APPLESCRIPT
+}
+
+# Capture a fresh bearer token from the signed-in browser tab.
+outlook_token_refresh() {
+  local timeout="${1:-55}" tmp rc token dir
+  dir="$OUTLOOK_FPX_DIR"
+  mkdir -p "$dir" || return 1
+  chmod 700 "$dir" 2>/dev/null
+
+  command -v fpx >/dev/null 2>&1 || {
+    echo "fpx not found — npm i -g @fetchproxy/cli" >&2; return 1; }
+
+  tmp="$(mktemp "${TMPDIR:-/tmp}/outlook-cap.XXXXXX")" || return 1
+
+  echo "capturing token from ${OUTLOOK_CAPTURE_HOST} (reloading your Outlook tab)…" >&2
+  fpx capture "authorization@${OUTLOOK_CAPTURE_HOST}" \
+      --capture-timeout "$timeout" -p "$OUTLOOK_FPX_PROFILE" >"$tmp" 2>"$tmp.err" &
+  local cappid=$!
+  sleep 3
+  _outlook_poke_tab
+  wait "$cappid"; rc=$?
+
+  if [ "$rc" -ne 0 ] || [ ! -s "$tmp" ]; then
+    echo "capture failed (exit $rc). Is an Outlook tab open and signed in?" >&2
+    sed -n '1,3p' "$tmp.err" >&2 2>/dev/null
+    rm -f "$tmp" "$tmp.err"; return 1
+  fi
+
+  token="$(OUTLOOK_CAP_FILE="$tmp" OUTLOOK_CAP_HOST="$OUTLOOK_CAPTURE_HOST" python3 -c '
+import json, os, sys
+d = json.load(open(os.environ["OUTLOOK_CAP_FILE"]))
+v = d.get("authorization@" + os.environ["OUTLOOK_CAP_HOST"])
+if not v:
+    vals = [x for x in d.values() if isinstance(x, str) and x.strip()]
+    v = vals[0] if vals else ""
+sys.stdout.write(v.strip())
+')"
+  rm -f "$tmp" "$tmp.err"
+
+  case "$token" in
+    Bearer\ *) : ;;
+    "") echo "no authorization header captured — reload Outlook and retry" >&2; return 1 ;;
+    *) token="Bearer $token" ;;
+  esac
+
+  local rc_file; rc_file="$(_outlook_curlrc)"
+  umask 077
+  printf 'header = "Authorization: %s"\n' "$token" > "$rc_file" || return 1
+  chmod 600 "$rc_file" 2>/dev/null
+  echo "token stored in $rc_file ($(outlook_token_expiry))" >&2
+}
+
+# Print the token's expiry (non-secret claim) without revealing the token.
+outlook_token_expiry() {
+  local rc_file; rc_file="$(_outlook_curlrc)"
+  [ -f "$rc_file" ] || { echo "no token"; return 1; }
+  OUTLOOK_RC="$rc_file" python3 -c '
+import base64, json, os, re, sys, datetime
+txt = open(os.environ["OUTLOOK_RC"]).read()
+m = re.search(r"Authorization: Bearer ([A-Za-z0-9._-]+)", txt)
+if not m: print("unparseable"); sys.exit(1)
+p = m.group(1).split(".")
+if len(p) < 2: print("not a jwt"); sys.exit(1)
+s = p[1] + "=" * (-len(p[1]) % 4)
+try:
+    exp = json.loads(base64.urlsafe_b64decode(s)).get("exp")
+except Exception:
+    print("undecodable"); sys.exit(1)
+if not exp: print("no exp"); sys.exit(1)
+now = datetime.datetime.now(datetime.timezone.utc).timestamp()
+left = int(exp - now)
+when = datetime.datetime.fromtimestamp(exp, datetime.timezone.utc).strftime("%Y-%m-%d %H:%M:%SZ")
+print(f"expires {when}" + (f", {left//3600}h{(left%3600)//60}m left" if left > 0 else ", EXPIRED"))
+'
+}
+
+# NOTE: never name a local `path` or `status` here. In zsh `path` is tied to the
+# PATH array (assigning it wipes PATH for the rest of the function, so even
+# `mktemp` stops resolving) and `status` is read-only. Both are harmless under
+# bash, so this only shows up when the file is sourced from a zsh shell.
+_outlook_request() {
+  local method="$1" req_path="$2"; shift 2
+  local rc_file; rc_file="$(_outlook_curlrc)"
+  [ -f "$rc_file" ] || { echo "no token — run: outlook_token_refresh" >&2; return 1; }
+
+  local http_status tmp
+  tmp="$(mktemp "${TMPDIR:-/tmp}/outlook-resp.XXXXXX")" || return 1
+  # Args in an array so nothing is re-split; token stays in the -K file.
+  local -a args
+  args=(-s -K "$rc_file" -X "$method" -H 'Accept: application/json'
+        -o "$tmp" -w '%{http_code}' --max-time 60)
+  http_status="$(curl "${args[@]}" "$@" "${OUTLOOK_API}${req_path}")" || {
+    echo "curl failed" >&2; rm -f "$tmp"; return 1; }
+
+  case "$http_status" in
+    2*) cat "$tmp"; rm -f "$tmp"; return 0 ;;
+    401) echo "401 — token expired or revoked. Run: outlook_token_refresh" >&2
+         rm -f "$tmp"; return 4 ;;
+    *)  echo "HTTP $http_status" >&2; sed -n '1,5p' "$tmp" >&2; rm -f "$tmp"; return 4 ;;
+  esac
+}
+
+# outlook_get '<path>' [extra curl args...]
+outlook_get() { local p="$1"; shift; _outlook_request GET "$p" "$@"; }
+
+# outlook_post '<path>' '<json>' [extra curl args...]
+outlook_post() {
+  local p="$1" body="$2"; shift 2
+  _outlook_request POST "$p" -H 'Content-Type: application/json' -d "$body" "$@"
+}
+
+# outlook_patch '<path>' '<json>' [extra curl args...]
+outlook_patch() {
+  local p="$1" body="$2"; shift 2
+  _outlook_request PATCH "$p" -H 'Content-Type: application/json' -d "$body" "$@"
+}
+
+# Plain-text bodies instead of HTML — ~3-9x smaller. Use for anything you read.
+outlook_get_text() { local p="$1"; shift; outlook_get "$p" -H 'Prefer: outlook.body-content-type="text"' "$@"; }