mise

Content fetching for Google Drive and Gmail — via the mise-en-space MCP.

First Run (no token yet)

If the MCP server returns an auth error, the user needs to authenticate with Google. Do this for them — don't ask them to type CLI commands.

mise.do(operation="setup_oauth")

This opens a browser at Google's consent screen on the user's Mac, runs a localhost listener, exchanges the auth code, and stashes the token in macOS Keychain. The MCP call returns immediately with the consent URL inline as a fallback (in case the browser didn't auto-open). Once the user sees "Authorization Successful" in the browser, retry the original mise call.

If setup_oauth itself fails (e.g. port 3000 in use), the error message will name the remediation. The CLI fallback (uv run python -m auth --auto from the mise-en-space repo) exists for users running mise outside Cowork/Desktop, but setup_oauth is the path to default to.

Identity & multi-account

When multiple Workspace connectors are loaded in the same session — Cowork's native Drive/Calendar bound to one Google account, mise bound to another — the connector names alone don't say which is which. Mise responses self-disclose: `cues._identity.email` shows the authenticated email on every response. Read it, especially when the user has both a personal and a work Workspace identity active.

When in doubt about which account a question targets, prefer mcp__plugin_mise_mise__* (or whatever name your runtime gives mise's tools) over generic Drive/Gmail tools — mise's binding is explicit. If you've fetched data and the user reacts with "that's not the account I meant", check cues._identity in the response, then re-route or have them re-auth with the right account.

Iron Law: Files are artifacts. Emails are meaning.

A document tells you what was decided. The email thread tells you why, who pushed back, and what concerns remain.

Always: Pass base_path

MCP servers run as separate processes. Without base_path, deposits land in the server's directory — not yours.

# ALWAYS include base_path
search("Q4 planning", base_path="/Users/modha/Repos/my-project")
fetch("1abc...", base_path="/Users/modha/Repos/my-project")

Deposit accumulation: mise/ grows without bound during a session. Be aware during heavy research — 15+ deposits add up.

The Three Tools

fetch auto-detects input: Drive file ID, Drive URL, or Gmail thread ID.

After Every Fetch

This checklist applies to all workflows — quick fetch, research, everything.

The fetch response includes a cues block with decision-tree signals — check it BEFORE reading files:

"cues": {
  "files": ["content.md", "comments.md", "manifest.json"],
  "open_comment_count": 3,
  "warnings": [],
  "content_length": 4280,
  "email_context": null,
  "participants": ["Rupa Jones", "Ella Collis"]  // Gmail only
}

1. Read `cues` first — it tells you what's in the deposit and what to act on
2. If open_comment_count > 0 → read comments.md (the real discussion lives here)
3. If email_context is populated → the file was shared via email; consider fetching that thread
4. If warnings is non-empty → note extraction issues
5. Read content.md
6. For Gmail: check cues.files for *.pdf.md (extracted attachment text)

manifest.json is still on disk for scripts/jq, but cues surfaces the actionable signals so you don't need to read it separately.

See references/deposit-structure.md for folder layout and attachment patterns.

Workflow 1: Quick Fetch

When: "Get me this doc" / "Fetch this URL" / "Read that email thread"

fetch("1abc...", base_path="...")                          # Drive file
fetch("https://docs.google.com/...", base_path="...")      # Drive URL
fetch("18f3a4b...", base_path="...")                       # Gmail thread
fetch("thread_id", attachment="budget.xlsx", base_path="...")  # Single attachment
fetch("folder_id", base_path="...", recursive=True)        # Full folder tree (depth 5, 1000 items max)

Gmail URL gotcha: Browser URLs contain web-format IDs (FMfcgz...), not API IDs. The MCP converts automatically, but conversion fails for self-sent emails (~2018+). If fetch errors on a Gmail URL, ask the user for the thread ID.

What fetch can't take: Only Workspace content is fetchable — mail.google.com/#search/... URLs and non-Google URLs (GitHub, docs sites) will 404. Run the query through search instead. And the 12-char ID fragment in a deposit folder name (doc--title--1jinlqdtqLpw) is a prefix, not a fetchable ID — the full ID is in that folder's manifest.json.

Then follow the After Every Fetch checklist above.

Workflow 2: Research

When: "Help me prepare for the Lantern meeting" / "What do we know about X?"

This is where the skill earns its keep. Don't just search→fetch→read. Follow the exploration loop:

1. Search Drive for topic → find files
2. Fetch most relevant → read content + comments
3. Check email_context in results → find the sending thread
4. Search Gmail filename:X or from:sender → get the email
5. Read email → discover new terms, people, context
6. Search again with new terms → expand understanding

When to stop: 2-3 iterations usually suffice. Stop when you understand the key decision-makers and their positions, or when new searches return familiar results. Don't exhaust every thread — the goal is understanding, not completeness.

The loop discovers meaning (in communications) behind artifacts (files).

See references/exploration-loop.md for a worked example.

Workflow 3: Precision Search

When: "Find emails from Elizabeth about contracts" / "Search for the budget spreadsheet"

Gmail: Use Operators, Not Keyword Soup

# BAD — keyword soup returns noise
search("Elizabeth Smith Project Alpha data privacy contracts")

# GOOD — operators target precisely
search("from:[email protected] after:2025/12/01", sources=["gmail"])
search("filename:strawman from:[email protected]", sources=["gmail"])
search("has:attachment subject:lantern after:2025/12/01", sources=["gmail"])

Key operators: from:, to:, filename:, has:attachment, after:, before:, subject:, in:sent

Two asymmetries that waste sessions:

• "What did X send/share?" needs `(from:X OR to:X OR cc:X)` — the thing X "shared" often arrives in a thread someone else started, with X on To: or Cc:. from:X alone structurally misses it.
• Short free-text tokens (`PR`, `AI`, `KPI`) are brittle through the API — the Gmail UI fuzzy-matches them; the API doesn't. If a short-token query returns suspiciously little, drop the token and narrow by participants + date instead, then open each of the 5–20 hits. Before reporting an email "not findable", confirm in the Gmail UI.

See references/gmail-operators.md for the full set and the search-asymmetry detail.

Drive: Keywords Only (Different Syntax!)

Drive search uses plain keywords — not Gmail operators. from:, is:starred, subject: will return 400 errors on Drive.

search("Q4 budget", sources=["drive"], base_path="...")     # Drive only
search("budget 2026", base_path="...")                       # Both sources

# Type filter — narrows Drive results by file type (query optional)
search(type="spreadsheet", base_path="...")                  # All spreadsheets
search("budget", type="spreadsheet", base_path="...")        # Budget spreadsheets only
search(type="folder", sources=["drive"], base_path="...")    # List folders

Type values: folder, doc, spreadsheet / sheet, slides / presentation, pdf, image, video, form. Type filter applies to Drive only — ignored for Gmail.

Triage Large Results

When search returns 20+ results, don't read the full JSON. Filter first:

jq '.drive_results[:5] | .[] | {name, id}' mise/search--*.json
jq '.drive_results[] | select(.name | test("framework"; "i"))' mise/search--*.json

Rule of thumb: <10 results → just read. >15 → filter with jq first.

See references/filtering-results.md for patterns.

Search Sources

Default sources are ['drive', 'gmail']. Two additional sources are available:

# Recent comment activity
search("project update", sources=["activity"], base_path="...")

# Calendar enrichment (adds meeting_context to Drive results)
search("Q4 report", sources=["drive", "calendar"], base_path="...")

`activity` returns comment events — who commented, on what, when. Actors show as "Unknown" (people/ID limitation); the content and file are accurate.

`calendar` is NOT in default sources (adds an API call with ±7 day window). When included alongside drive, matching calendar event attachments add meeting_context to Drive results — connecting a file to the meeting where it was discussed.

Workflow 4: Do (Act on Workspace)

When: "Make a Google Doc from this" / "Move this file" / "Update that doc" / "Add a note to the meeting minutes"

The Operations

Choosing the Right Edit Operation

All edit operations work on both Google Docs and plain files (markdown, JSON, SVG, YAML, etc. stored in Drive). The tool auto-detects the file type and uses the right API — Docs API for Google Docs, Drive Files API for everything else. No extra flags needed.

Overwrite destroys everything — images, tables, formatting, all gone. It's a full replacement from markdown. Use it when you're publishing a complete new version of a document.

Surgical edits preserve existing content. Use prepend, append, or replace_text when the document has content worth keeping:

Binary files (images, PDFs, etc.) reject text operations (prepend/append/replace_text) with a clear error. overwrite works on binary files (full byte replacement).

Create and Move

# Create doc
do(operation="create", content="# Meeting Notes\n\n- Item 1", title="Team Sync")
do(operation="create", content=content, title="Report", doc_type="doc", folder_id="1xyz...")

# Create sheet (see Sheet Creation below for details)
do(operation="create", content="Name,Score\nAlice,95\nBob,87", title="Results", doc_type="sheet")

# Create plain file (no Google conversion — stays as-is in Drive)
do(operation="create", content="<svg>...</svg>", title="diagram.svg", doc_type="file")
do(operation="create", content="# Notes\n\nContent here", title="notes.md", doc_type="file")
do(operation="create", content='{"key": "value"}', title="config.json", doc_type="file")

# Move single file
do(operation="move", file_id="1abc...", folder_id="1xyz...")

# Batch move — validates destination once, returns per-file summary
do(operation="move", file_id=["1abc...", "1def...", "1ghi..."], folder_id="1xyz...")
# Returns: {batch: true, total: 3, succeeded: 2, failed: 1, results: [...]}

Create: Without folder_id, the doc lands in Drive root. Response includes cues.folder showing where it landed. Use doc_type="file" for plain files (markdown, SVG, JSON, YAML, etc.) — MIME type is inferred from the title extension. The file stays as-is in Drive, no conversion to Google format. Response includes cues.plain_file and cues.mime_type.

Move: Enforces single parent — removes all existing parents, adds destination. Response includes cues.destination_folder (name) and cues.previous_parents.

Rename and Share

# Rename
do(operation="rename", file_id="1abc...", title="Final Q4 Report")

# Share — TWO-STEP confirm gate
# Step 1: Preview (returns what would happen, does NOT share)
do(operation="share", file_id="1abc...", to="[email protected]")
# → {"preview": true, "message": "Would share 'Report' with [email protected] as reader", ...}

# Step 2: Execute after user approves
do(operation="share", file_id="1abc...", to="[email protected]", confirm=True)

# Share with role and multiple people
do(operation="share", file_id="1abc...", to="[email protected], [email protected]", role="writer", confirm=True)

Share requires user approval. The first call without confirm=True always returns a preview. Show it to the user and only call again with confirm=True after they approve. Roles: reader (default), writer, commenter.

Non-Google accounts (iCloud, Outlook, etc.): Google requires a notification email. The tool handles this automatically — check cues.notified to see which recipients got an invite email.

Overwrite

# Full replacement from inline markdown
do(operation="overwrite", file_id="1abc...", content="# Q4 Report\n\nRevised findings...", base_path="...")

# From a deposit folder (fetch → edit locally → publish back)
do(operation="overwrite", file_id="1abc...", source="mise/doc--q4-report--1abc/", base_path="...")

For Google Docs: uses Drive's import engine — all markdown formatting (headings, bold, tables, lists) renders automatically. Response includes cues.char_count.

For plain files: content is uploaded as-is. Response includes cues.plain_file: true and cues.mime_type.

Surgical Edits

# Add to end of document
do(operation="append", file_id="1abc...", content="\n\n## 18 Feb Update\n\nNew findings...", base_path="...")

# Add to start of document
do(operation="prepend", file_id="1abc...", content="DRAFT — Do not circulate\n\n", base_path="...")

# Find and replace (case-sensitive, all occurrences)
do(operation="replace_text", file_id="1abc...", find="Q3", content="Q4", base_path="...")

# Delete matched text (replace with empty string)
do(operation="replace_text", file_id="1abc...", find="DRAFT — ", content="", base_path="...")

replace_text response includes cues.occurrences_changed — check it to confirm the replacement happened.

Sheet Creation

Pass CSV as content with doc_type="sheet". Google's Drive import handles type detection — it gets numbers, dates, currencies, booleans, and formulae right ~94% of the time. Trust it. Don't pre-format.

# Simple data
do(operation="create", doc_type="sheet", title="Team Scores", base_path="...",
   content="Name,Score,Pass\nAlice,95,TRUE\nBob,87,TRUE\nCarol,62,FALSE")

# With formulae — cells starting with = are preserved
do(operation="create", doc_type="sheet", title="Budget", base_path="...",
   content="Item,Cost\nLicences,12000\nHosting,8500\nTotal,=SUM(B2:B3)")

# Values with commas need CSV quoting
do(operation="create", doc_type="sheet", title="Staff", base_path="...",
   content='Name,Department,Salary\nAlice,"Sales, Marketing","£65,000"\nBob,Engineering,"£52,000"')

# From a deposit folder (saves tokens — don't inline large CSVs)
do(operation="create", doc_type="sheet", source="mise/sheet--budget--abc123/", base_path="...")

CSV quoting rule: If a value contains a comma, wrap it in double quotes ("Sales, Marketing"). This is standard CSV — applies to currency with thousands separators ("£65,000") and multi-word categories.

Deposit-then-publish is the preferred pattern for large data. Write CSV to a deposit folder, then pass source= instead of content=. The tool reads content.csv from the folder and uses the manifest title. Multi-tab deposits (with tabs in manifest) are auto-detected and create multi-tab sheets.

#### What Google auto-detects well

#### What needs help

The tick prefix (') tells Google Sheets "treat this as text, not a number." Write it directly in the CSV value — Google strips the tick from display but preserves the text type.

#### Anti-patterns

Gmail Attachments

PDFs and images are extracted eagerly. Office files (DOCX/XLSX/PPTX) are skipped during thread fetch (5-10s each). Extract on demand:

fetch("thread_id", attachment="budget.xlsx", base_path="...")

See references/deposit-structure.md for the full attachment layout.

Workflow 5: Folder Triage

When: "Organise this Drive folder" / "What's in this folder?" / "Move all the spreadsheets into one place"

Three-step loop: explore → understand → batch-move.

Step 1: Find subfolders

# Find subfolders inside a parent (query optional — type alone is enough)
search(type="folder", folder_id="<parent_id>", base_path="...")

# Or search by name if you don't have the parent ID
search("Q4 reports", type="folder", base_path="...")

Step 2: Explore the tree

# Recursive fetch — builds full indented tree, capped at depth 5 / 1000 items
fetch("<folder_id>", recursive=True, base_path="...")

The deposited content.md shows the full hierarchy with file IDs. Read it to understand what's where.

If the tree is truncated (cues["truncated"] is True): the cap was hit. Fetch individual subfolders separately to explore those branches:

fetch("<subfolder_id>", recursive=True, base_path="...")  # repeat per branch

Step 3: Batch move

# Move multiple files in one call — validates destination once, per-file summary
do(
    operation="move",
    file_id=["<id1>", "<id2>", "<id3>"],
    folder_id="<dest_id>",
    base_path="..."
)
# Returns: {batch: true, total: 3, succeeded: 2, failed: 1, results: [...]}

Check results in the response — each entry has its own ok/error. A failed move on one file doesn't block the others.

Anti-patterns

Workflow 6: Inbox Triage

When: "Help me triage my inbox" / "Archive everything from that newsletter" / "Star the important threads"

The triage workflow combines search, review, and batch actions. Pagination and batch ops work together — search surfaces the full picture, batch operations let you act on it efficiently.

Step 1: Search with Gmail operators

Target what matters using operators rather than keywords:

# Unread in inbox
search("is:unread in:inbox", sources=["gmail"], base_path="...")

# Recent unread from a person
search("is:unread from:[email protected] newer_than:7d", sources=["gmail"], base_path="...")

# Newsletters and promotions (good candidates for bulk archive)
search("category:promotions newer_than:30d", sources=["gmail"], base_path="...")

# Custom label
search("label:project-alpha is:unread", sources=["gmail"], base_path="...")

Search follows nextPageToken automatically, so results aren't capped at the first page. If results are truncated (very large result set), cues.truncated will be true.

Step 2: Review and decide

Read the search results. Each thread shows subject, participants, date, and snippet. Decide which threads to act on — fetch individual threads if you need more context before deciding:

fetch("thread_id", base_path="...")  # Read the full conversation

Step 3: Act in batch

Pass a list of thread IDs to process multiple threads in one call:

# Archive threads you've reviewed
do(operation="archive", file_id=["thread1", "thread2", "thread3"], base_path="...")

# Star threads that need follow-up
do(operation="star", file_id=["thread4", "thread5"], base_path="...")

# Label threads for a project
do(operation="label", file_id=["thread6", "thread7"], label="follow-up", base_path="...")

Each batch call returns a summary with succeeded/failed counts and per-thread results — a failed operation on one thread doesn't block the others.

The label operation covers more than labels

label works with system labels, which means it handles several triage actions through one operation:

Label names are resolved automatically — use human-readable names like "follow-up", not Gmail's internal IDs.

Drafting emails

Compose drafts for the user to review and send from Gmail:

# New email
do(operation="draft", to="[email protected]", subject="Q4 update", content="...", base_path="...")

# Reply in a thread
do(operation="reply_draft", file_id="thread_id", content="Thanks for the update...", base_path="...")

# Include Drive files as formatted links in the body
do(operation="draft", to="[email protected]", subject="Report ready",
   content="Here's the report", include=["drive_file_id"], base_path="...")

Draft-only — Claude composes, the user reviews and sends from Gmail. This is a safety boundary, not a limitation.

Common mistakes

Error Handling

Anti-Patterns

Integration

Composes with:

• todoist-gtd — @Claude inbox items may request research; results inform outcomes

When to Use

• Research tasks involving multiple Drive/Gmail sources
• Finding context around a document (who sent it, what was discussed)
• Creating or editing Google Docs/Sheets/Slides
• Inbox triage — searching, reviewing, and batch-acting on Gmail threads
• Composing email drafts (new or reply)
• Any task needing cross-source exploration

Boundaries

• Task doesn't involve Google Workspace (no Drive or Gmail)
• Pure filesystem operations

Success Criteria

This skill works when:

• Gmail searches use operators, not keyword soup
• Drive searches use keywords, not Gmail operators
• comments.md is checked after every doc/sheet/slides fetch
• email_context hints are followed to source emails
• Large results are filtered before reading
• Research tasks follow the exploration loop, not single-search-and-stop
• Triage uses batch operations, not one-thread-at-a-time
• label is used for mark_read/unread/unstar rather than seeking separate operations
• Errors are reported with actionable guidance, not just "it failed"