@commandable/integration-data 0.0.5 → 0.0.7

package/integrations/google-docs/handlers/read_document.js

@@ -0,0 +1,189 @@
+async (input) => {
+  const MONO_FONTS = new Set([
+    'Courier',
+    'Courier New',
+    'Consolas',
+    'Menlo',
+    'Monaco',
+    'Roboto Mono',
+    'Source Code Pro',
+  ])
+
+  const HEADING_MAP = {
+    TITLE: '#',
+    SUBTITLE: '##',
+    HEADING_1: '#',
+    HEADING_2: '##',
+    HEADING_3: '###',
+    HEADING_4: '####',
+    HEADING_5: '#####',
+    HEADING_6: '######',
+  }
+
+  const BULLET_GLYPHS = new Set([
+    'BULLET_DISC_CIRCLE_SQUARE',
+    'BULLET_DIAMONDX_ARROW3D_SQUARE',
+    'BULLET_CHECKBOX',
+    'BULLET_ARROW_DIAMOND_DISC',
+    'BULLET_STAR_CIRCLE_SQUARE',
+  ])
+
+  const LIST_NUMBER_GLYPHS = new Set([
+    'DECIMAL',
+    'ZERO_DECIMAL',
+    'UPPER_ALPHA',
+    'ALPHA',
+    'UPPER_ROMAN',
+    'ROMAN',
+  ])
+
+  const trimEndWhitespace = (value) => (value || '').replace(/[ \t]+$/g, '')
+
+  const escapeCell = (value) =>
+    String(value ?? '')
+      .replace(/\|/g, '\\|')
+      .replace(/\r?\n/g, '<br>')
+
+  const extractPlainTextFromParagraph = (paragraph) => {
+    let text = ''
+    for (const element of paragraph?.elements || []) {
+      text += element?.textRun?.content || ''
+    }
+    return trimEndWhitespace(text)
+  }
+
+  const applyTextStyle = (text, textStyle = {}) => {
+    const raw = (text || '').replace(/\n/g, '')
+    if (!raw) return ''
+
+    let out = raw
+    if (textStyle.link?.url) out = `[${out}](${textStyle.link.url})`
+
+    const fontFamily = textStyle.weightedFontFamily?.fontFamily || ''
+    const isMono = textStyle.smallCaps || MONO_FONTS.has(fontFamily)
+
+    if (isMono) out = `\`${out}\``
+    if (textStyle.bold) out = `**${out}**`
+    if (textStyle.italic) out = `*${out}*`
+    if (textStyle.strikethrough) out = `~~${out}~~`
+
+    return out
+  }
+
+  const paragraphToMarkdown = (paragraph, docLists) => {
+    const styleType = paragraph?.paragraphStyle?.namedStyleType
+    const headingPrefix = HEADING_MAP[styleType] || ''
+
+    let line = ''
+    for (const element of paragraph?.elements || []) {
+      line += applyTextStyle(element?.textRun?.content || '', element?.textRun?.textStyle || {})
+    }
+    line = trimEndWhitespace(line)
+
+    if (!line) return ''
+
+    const bullet = paragraph?.bullet
+    if (bullet) {
+      const nestingLevel = bullet.nestingLevel || 0
+      const listMeta = docLists?.[bullet.listId]
+      const nesting = listMeta?.listProperties?.nestingLevels?.[nestingLevel]
+      const glyphType = nesting?.glyphType || ''
+      const isNumbered = LIST_NUMBER_GLYPHS.has(glyphType) && !BULLET_GLYPHS.has(glyphType)
+      const indent = '  '.repeat(Math.max(0, nestingLevel))
+      return `${indent}${isNumbered ? '1.' : '-'} ${line}`
+    }
+
+    if (headingPrefix) return `${headingPrefix} ${line}`
+    return line
+  }
+
+  const tableToMarkdown = (table, docLists) => {
+    const rows = table?.tableRows || []
+    if (!rows.length) return ''
+
+    const normalized = rows.map((row) =>
+      (row?.tableCells || []).map((cell) => {
+        const parts = []
+        for (const c of cell?.content || []) {
+          if (c?.paragraph) {
+            const p = paragraphToMarkdown(c.paragraph, docLists)
+            if (p) parts.push(p)
+          }
+        }
+        return escapeCell(parts.join('<br>'))
+      }),
+    )
+
+    const width = Math.max(...normalized.map((r) => r.length), 1)
+    const padded = normalized.map((r) => [...r, ...Array(width - r.length).fill('')])
+    const header = padded[0] || Array(width).fill('')
+    const separator = Array(width).fill('---')
+    const body = padded.slice(1)
+
+    const lines = [
+      `| ${header.join(' | ')} |`,
+      `| ${separator.join(' | ')} |`,
+      ...body.map((r) => `| ${r.join(' | ')} |`),
+    ]
+    return lines.join('\n')
+  }
+
+  const docToPlainText = (docBodyContent) => {
+    const lines = []
+    for (const item of docBodyContent || []) {
+      if (item?.paragraph) {
+        const text = extractPlainTextFromParagraph(item.paragraph)
+        if (text) lines.push(text)
+      } else if (item?.table) {
+        for (const row of item.table.tableRows || []) {
+          const cells = (row.tableCells || []).map((cell) => {
+            const pieces = []
+            for (const contentItem of cell.content || []) {
+              if (contentItem?.paragraph) {
+                const text = extractPlainTextFromParagraph(contentItem.paragraph)
+                if (text) pieces.push(text)
+              }
+            }
+            return pieces.join(' ')
+          })
+          if (cells.some(Boolean)) lines.push(cells.join(' | '))
+        }
+      }
+    }
+    return lines.join('\n\n').trim()
+  }
+
+  const { documentId } = input
+  const res = await integration.fetch(`/documents/${encodeURIComponent(documentId)}`)
+  const doc = await res.json()
+
+  const content = doc?.body?.content || []
+  const lists = doc?.lists || {}
+
+  const blocks = []
+  for (const item of content) {
+    if (item?.paragraph) {
+      const line = paragraphToMarkdown(item.paragraph, lists)
+      if (line) blocks.push(line)
+    } else if (item?.table) {
+      const table = tableToMarkdown(item.table, lists)
+      if (table) blocks.push(table)
+    }
+  }
+
+  const markdown = blocks.join('\n\n').trim()
+  if (markdown) {
+    return {
+      documentId: doc?.documentId || documentId,
+      title: doc?.title || '',
+      markdown,
+    }
+  }
+
+  // Escape hatch: return plain text if markdown conversion produced nothing.
+  return {
+    documentId: doc?.documentId || documentId,
+    title: doc?.title || '',
+    markdown: docToPlainText(content),
+  }
+}

package/integrations/google-docs/manifest.json

@@ -3,53 +3,38 @@
   "version": "0.1.0",
   "tools": [
     {
-      "name": "get_document",
-      "description": "Retrieve Google Doc content and metadata.",
-      "inputSchema": "schemas/get_document.json",
-      "handler": "handlers/get_document.js",
-      "scope": "read"
-    },
-    {
-      "name": "get_document_text",
-      "description": "Retrieve the document's plain text content.",
-      "inputSchema": "schemas/get_document_text.json",
-      "handler": "handlers/get_document_text.js",
-      "scope": "read"
-    },
-    {
-      "name": "get_document_structured",
-      "description": "Retrieve the structured body JSON (body.content).",
-      "inputSchema": "schemas/get_document_structured.json",
-      "handler": "handlers/get_document_structured.js",
+      "name": "read_document",
+      "description": "Read a Google Doc and return its content as clean Markdown. Preserves headings, bold, italic, strikethrough, links, code spans, ordered/unordered lists with nesting, and tables. This is the standard way to read document content. For editing, use append_text, replace_all_text, first-match tools, or batch_update.",
+      "inputSchema": "schemas/read_document.json",
+      "handler": "handlers/read_document.js",
       "scope": "read"
     },
     {
       "name": "create_document",
-      "description": "Create a new Google Doc.",
+      "description": "Create a new empty Google Doc with the given title. Returns the created document's metadata including its documentId, which is needed for all subsequent operations on the document.",
       "inputSchema": "schemas/create_document.json",
       "handler": "handlers/create_document.js",
       "scope": "write"
     },
     {
       "name": "batch_update",
-      "description": "Send a documents.batchUpdate request to modify a Doc (insertText, replaceAllText, structural updates, etc).",
+      "description": "Send a documents.batchUpdate request to modify a document with one or more structured requests. Supports insertText, deleteContentRange, replaceAllText, createNamedRange, updateTextStyle, updateParagraphStyle, insertTable, insertInlineImage, and more. For common operations, prefer the higher-level tools: append_text, replace_all_text, and the first-match tools. Use batch_update for operations not covered by those helpers.",
       "inputSchema": "schemas/batch_update.json",
       "handler": "handlers/batch_update.js",
       "scope": "write"
     },
-    { "name": "append_text", "description": "Append plain text to the end of the document.", "inputSchema": "schemas/append_text.json", "handler": "handlers/append_text.js", "scope": "write" },
-    { "name": "replace_all_text", "description": "Replace all occurrences of text matching a query.", "inputSchema": "schemas/replace_all_text.json", "handler": "handlers/replace_all_text.js", "scope": "write" },
-
-    { "name": "style_first_match", "description": "Find the first occurrence of text and apply a TextStyle to it.", "inputSchema": "schemas/style_first_match.json", "handler": "handlers/style_first_match.js", "scope": "write" },
-    { "name": "insert_text_after_first_match", "description": "Find the first occurrence of text and insert new text after or before it.", "inputSchema": "schemas/insert_text_after_first_match.json", "handler": "handlers/insert_text_after_first_match.js", "scope": "write" },
-    { "name": "insert_table_after_first_match", "description": "Find the first occurrence of text and insert a table nearby.", "inputSchema": "schemas/insert_table_after_first_match.json", "handler": "handlers/insert_table_after_first_match.js", "scope": "write" },
-    { "name": "insert_page_break_after_first_match", "description": "Find the first occurrence of text and insert a page break nearby.", "inputSchema": "schemas/insert_page_break_after_first_match.json", "handler": "handlers/insert_page_break_after_first_match.js", "scope": "write" },
-    { "name": "insert_inline_image_after_first_match", "description": "Find the first occurrence of text and insert an inline image nearby.", "inputSchema": "schemas/insert_inline_image_after_first_match.json", "handler": "handlers/insert_inline_image_after_first_match.js", "scope": "write" },
-    { "name": "delete_first_match", "description": "Find the first occurrence of text and delete it.", "inputSchema": "schemas/delete_first_match.json", "handler": "handlers/delete_first_match.js", "scope": "write" },
-    { "name": "update_paragraph_style_for_first_match", "description": "Find the first occurrence of text and update the paragraph style for that paragraph.", "inputSchema": "schemas/update_paragraph_style_for_first_match.json", "handler": "handlers/update_paragraph_style_for_first_match.js", "scope": "write" },
+    { "name": "append_text", "description": "Append plain text to the end of a Google Doc. Automatically fetches the document to find the correct end index and inserts the text there. Use this for adding content to the end of a document without needing to know the document structure.", "inputSchema": "schemas/append_text.json", "handler": "handlers/append_text.js", "scope": "write" },
+    { "name": "replace_all_text", "description": "Replace all occurrences of a text string in a Google Doc with new text. Case-sensitive by default. More efficient than the first-match tools when you need to replace every occurrence. Returns the number of occurrences replaced.", "inputSchema": "schemas/replace_all_text.json", "handler": "handlers/replace_all_text.js", "scope": "write" },
+    { "name": "style_first_match", "description": "Find the first occurrence of text in a document and apply a TextStyle to it (bold, italic, fontSize, foregroundColor, etc.). Uses a marker-based approach: replaces the text with a unique marker, locates the marker's position, applies the style, then restores the original text. Returns {applied: true/false}.", "inputSchema": "schemas/style_first_match.json", "handler": "handlers/style_first_match.js", "scope": "write" },
+    { "name": "insert_text_after_first_match", "description": "Find the first occurrence of text and insert new text immediately before or after it. Useful for inserting content at a specific anchor point in the document without knowing exact character indices. Returns {applied: true/false}.", "inputSchema": "schemas/insert_text_after_first_match.json", "handler": "handlers/insert_text_after_first_match.js", "scope": "write" },
+    { "name": "insert_table_after_first_match", "description": "Find the first occurrence of text and insert a table with the specified number of rows and columns nearby. Returns {applied: true/false}.", "inputSchema": "schemas/insert_table_after_first_match.json", "handler": "handlers/insert_table_after_first_match.js", "scope": "write" },
+    { "name": "insert_page_break_after_first_match", "description": "Find the first occurrence of text and insert a page break nearby. Useful for structuring long documents. Returns {applied: true/false}.", "inputSchema": "schemas/insert_page_break_after_first_match.json", "handler": "handlers/insert_page_break_after_first_match.js", "scope": "write" },
+    { "name": "insert_inline_image_after_first_match", "description": "Find the first occurrence of text and insert an inline image nearby, referenced by URL. Returns {applied: true/false}.", "inputSchema": "schemas/insert_inline_image_after_first_match.json", "handler": "handlers/insert_inline_image_after_first_match.js", "scope": "write" },
+    { "name": "delete_first_match", "description": "Find the first occurrence of text in the document and delete it. Only the first match is removed. Use replace_all_text with an empty string to remove all occurrences. Returns {applied: true/false}.", "inputSchema": "schemas/delete_first_match.json", "handler": "handlers/delete_first_match.js", "scope": "write" },
+    { "name": "update_paragraph_style_for_first_match", "description": "Find the first occurrence of text and update the paragraph style for the paragraph containing it. Use to apply heading levels (HEADING_1 through HEADING_6), NORMAL_TEXT, or adjust spacing, alignment, and indentation. Returns {applied: true/false}.", "inputSchema": "schemas/update_paragraph_style_for_first_match.json", "handler": "handlers/update_paragraph_style_for_first_match.js", "scope": "write" },
     {
       "name": "update_document_style",
-      "description": "Update the document style (e.g., page size, margins).",
+      "description": "Update document-level style properties such as page size (pageSize.width, pageSize.height in pt), margins (marginTop, marginBottom, marginLeft, marginRight in pt), and page orientation. Does not affect individual paragraph or text styles.",
       "inputSchema": "schemas/update_document_style.json",
       "handler": "handlers/update_document_style.js",
       "scope": "write"

package/integrations/google-docs/prompt.md

@@ -0,0 +1,49 @@
+## Reading documents
+
+Use `read_document` as the standard read tool. It returns clean markdown with headings, lists, links, inline code, and tables preserved as much as possible.
+
+`read_document` includes an escape hatch: if markdown conversion fails to produce useful content, it falls back to plain-text extraction so you still get readable output.
+
+For editing workflows, read with `read_document` first, then use `append_text`, `replace_all_text`, first-match tools, or `batch_update`.
+
+## Editing documents
+
+The Google Docs API uses character-index-based editing, but the high-level tools handle index resolution automatically:
+
+- **`append_text`** — adds text to the end of the document (no index needed)
+- **`replace_all_text`** — replaces every occurrence of a string (no index needed)
+- **First-match tools** (`style_first_match`, `insert_text_after_first_match`, etc.) — locate text by content, then act on the first match
+
+Only use `batch_update` with raw index operations when the higher-level tools don't cover your use case.
+
+## First-match pattern
+
+The `*_first_match` tools use a 3-step marker approach:
+1. Replace all occurrences of `findText` with a unique marker (`__CMD_MARK_...`)
+2. Fetch the document to find the marker's exact character indices
+3. Apply the operation at those indices, then restore the original text
+
+This means each first-match operation makes 3 API calls. They return `{applied: true}` on success or `{applied: false}` if the text was not found.
+
+## Common batch_update operations
+
+```json
+{ "requests": [
+  { "insertText": { "text": "Hello", "location": { "index": 1 } } },
+  { "deleteContentRange": { "range": { "startIndex": 5, "endIndex": 10 } } },
+  { "updateTextStyle": {
+      "range": { "startIndex": 1, "endIndex": 6 },
+      "textStyle": { "bold": true },
+      "fields": "bold"
+  }},
+  { "updateParagraphStyle": {
+      "range": { "startIndex": 1, "endIndex": 2 },
+      "paragraphStyle": { "namedStyleType": "HEADING_1" },
+      "fields": "namedStyleType"
+  }}
+]}
+```
+
+## Document IDs
+
+The documentId appears in the Google Docs URL: `https://docs.google.com/document/d/{documentId}/edit`

package/integrations/google-docs/schemas/{get_document_text.json → read_document.json}

@@ -1,9 +1,12 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "type": "object",
+  "required": ["documentId"],
   "properties": {
-    "documentId": { "type": "string" }
+    "documentId": {
+      "type": "string",
+      "description": "Google Doc documentId from URL: https://docs.google.com/document/d/{documentId}/edit"
+    }
   },
-  "required": ["documentId"],
   "additionalProperties": false
 }

package/integrations/google-docs/todo.md

@@ -0,0 +1,18 @@
+## Future: Native markdown export via Drive API
+
+Google Drive `files.export` now supports `text/markdown` as an export MIME type for Google Docs (added July 2024). This could replace the custom Docs API -> markdown conversion in `read_document` with a single API call:
+
+```
+GET https://www.googleapis.com/drive/v3/files/{fileId}/export?mimeType=text/markdown
+```
+
+### Why we're not using it yet
+
+- The `google-docs` integration's base URL points to `docs.googleapis.com/v1`, not the Drive API. Calling Drive export would require either a proxy enhancement to allow cross-API calls or hardcoding the Drive URL in the handler.
+- The custom conversion (ported from taylorwilsdon's approach) keeps the integration self-contained within the Docs API.
+
+### When to revisit
+
+- If we add cross-provider fetch support to the proxy/handler runtime.
+- If the custom markdown conversion proves unreliable or hard to maintain.
+- The Drive export requires `drive.readonly` scope (already included in the docs credential config).

package/integrations/google-drive/README.md

@@ -0,0 +1,26 @@
+# Google Drive
+
+**9 tools**
+
+![Google Drive tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/theomccabe/771bd329f303087690c522afa1baa6f3/raw/test-google-drive.json)
+
+## Credential variants
+
+| Variant | Label |
+|---|---|
+| `service_account` | Service Account (recommended) _(default)_ |
+| `oauth_token` | OAuth Access Token (short-lived) |
+
+## Tools
+
+| Tool | Scope | Description |
+|---|---|---|
+| `list_files` | read | List files in a Google Drive folder or across all of Drive. Returns id, name, mimeType, m… |
+| `search_files` | read | Search Google Drive for files by name, MIME type, or raw Drive query syntax. Use the 'nam… |
+| `get_file` | read | Get metadata for a Drive file or folder by ID. Returns id, name, mimeType, modifiedTime, … |
+| `get_file_content` | read | Read the text content of a Drive file. For Google Workspace files (Docs, Sheets, Slides),… |
+| `create_folder` | write | Create a new folder in Google Drive. Optionally nest it inside a parent folder using pare… |
+| `create_file` | write | Create a new Drive file (metadata only -- no content upload). To create a Google Workspac… |
+| `move_file` | write | Move a file or folder to a different parent folder by updating its parents. Provide the d… |
+| `share_file` | write | Share a Drive file or folder with a specific user, group, domain, or make it publicly acc… |
+| `delete_file` | write | Permanently and immediately delete a Drive file or folder by ID. This bypasses Trash and … |

package/integrations/google-drive/__tests__/handlers.test.ts

@@ -65,6 +65,25 @@ suiteOrSkip('google-drive handlers (live)', () => {
         await safeCleanup(async () => ctx.destFolderId ? drive.write('delete_file')({ fileId: ctx.destFolderId }) : Promise.resolve())
       }, 60000)
 
+      it('list_files returns files in folder', async () => {
+        if (!ctx.folderId)
+          return expect(true).toBe(true)
+        const result = await drive.read('list_files')({ folderId: ctx.folderId })
+        expect(Array.isArray(result?.files)).toBe(true)
+        expect(result?.files.some((f: any) => f?.id === ctx.fileId)).toBe(true)
+      }, 30000)
+
+      it('search_files finds file by name', async () => {
+        if (!ctx.fileId)
+          return expect(true).toBe(true)
+        const meta = await drive.read('get_file')({ fileId: ctx.fileId })
+        const name = meta?.name
+        if (!name)
+          return expect(true).toBe(true)
+        const result = await drive.read('search_files')({ name: name.slice(0, 10) })
+        expect(Array.isArray(result?.files)).toBe(true)
+      }, 30000)
+
       it('get_file returns file metadata', async () => {
         if (!ctx.fileId)
           return expect(true).toBe(true)
@@ -74,6 +93,30 @@ suiteOrSkip('google-drive handlers (live)', () => {
         expect(typeof result?.mimeType).toBe('string')
       }, 30000)
 
+      it('get_file_content exports a Google Doc as text', async () => {
+        if (!ctx.fileId)
+          return expect(true).toBe(true)
+        const result = await drive.read('get_file_content')({
+          fileId: ctx.fileId,
+          mimeType: 'application/vnd.google-apps.document',
+        })
+        expect(result?.fileId).toBe(ctx.fileId)
+        // A newly created empty doc may have empty content -- just verify the shape
+        expect(result?.content !== undefined || result?.message !== undefined).toBe(true)
+      }, 30000)
+
+      it('share_file shares a file with anyone reader', async () => {
+        if (!ctx.fileId)
+          return expect(true).toBe(true)
+        const result = await drive.write('share_file')({
+          fileId: ctx.fileId,
+          role: 'reader',
+          type: 'anyone',
+          sendNotificationEmail: false,
+        })
+        expect(result?.id || result?.role).toBeTruthy()
+      }, 30000)
+
       it('move_file moves the file to a different folder', async () => {
         if (!ctx.fileId || !ctx.destFolderId || !ctx.folderId)
           return expect(true).toBe(true)

package/integrations/google-drive/__tests__/usage_parity.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest'
+import { getMissingToolUsages } from '../../__tests__/usageParity.js'
+
+describe('google-drive static usage parity', () => {
+  it('every manifest tool is referenced in tests', () => {
+    const missing = getMissingToolUsages({ integrationName: 'google-drive', importMetaUrl: import.meta.url })
+    expect(missing, `Missing handler usages in tests: ${missing.join(', ')}`).toEqual([])
+  })
+})

package/integrations/google-drive/handlers/get_file.js

@@ -1,7 +1,5 @@
 async (input) => {
-  const res = await integration.fetch(`/files/${encodeURIComponent(input.fileId)}?fields=id,name,mimeType,parents,trashed`, {
-    method: 'GET',
-  })
+  const fields = input.fields || 'id,name,mimeType,modifiedTime,createdTime,size,parents,trashed,webViewLink'
+  const res = await integration.fetch(`/files/${encodeURIComponent(input.fileId)}?fields=${encodeURIComponent(fields)}`)
   return await res.json()
 }
-

package/integrations/google-drive/handlers/get_file_content.js

@@ -0,0 +1,41 @@
+async (input) => {
+  const fileId = encodeURIComponent(input.fileId)
+  const googleExportMap = {
+    'application/vnd.google-apps.document': 'text/plain',
+    'application/vnd.google-apps.spreadsheet': 'text/csv',
+    'application/vnd.google-apps.presentation': 'text/plain',
+    'application/vnd.google-apps.drawing': 'image/svg+xml',
+    'application/vnd.google-apps.script': 'application/vnd.google-apps.script+json',
+  }
+  const exportMimeType = input.exportMimeType
+    || (input.mimeType ? googleExportMap[input.mimeType] : null)
+    || null
+
+  let res
+  if (exportMimeType) {
+    res = await integration.fetch(`/files/${fileId}/export?mimeType=${encodeURIComponent(exportMimeType)}`)
+  }
+  else {
+    res = await integration.fetch(`/files/${fileId}?alt=media`)
+  }
+
+  const contentType = res.headers?.get?.('content-type') || ''
+  const isText = contentType.startsWith('text/')
+    || contentType.includes('json')
+    || contentType.includes('csv')
+    || contentType.includes('xml')
+    || contentType.includes('javascript')
+
+  if (isText) {
+    const content = await res.text()
+    return { fileId: input.fileId, mimeType: contentType, content }
+  }
+
+  // Binary content: inform the agent it needs a text export
+  return {
+    fileId: input.fileId,
+    mimeType: contentType,
+    content: null,
+    message: `Binary content (${contentType}). To get readable text, provide exportMimeType='text/plain' for documents, 'text/csv' for spreadsheets, or 'text/html'. For PDFs and images this is not possible via export.`,
+  }
+}

package/integrations/google-drive/handlers/list_files.js

@@ -0,0 +1,15 @@
+async (input) => {
+  const params = new URLSearchParams()
+  const qParts = ['trashed = false']
+  if (input.folderId)
+    qParts.push(`'${input.folderId}' in parents`)
+  params.set('q', qParts.join(' and '))
+  params.set('fields', input.fields || 'nextPageToken,files(id,name,mimeType,modifiedTime,size,parents)')
+  params.set('pageSize', String(input.pageSize || 50))
+  if (input.pageToken)
+    params.set('pageToken', input.pageToken)
+  if (input.orderBy)
+    params.set('orderBy', input.orderBy)
+  const res = await integration.fetch(`/files?${params.toString()}`)
+  return await res.json()
+}

package/integrations/google-drive/handlers/search_files.js

@@ -0,0 +1,20 @@
+async (input) => {
+  const params = new URLSearchParams()
+  const qParts = []
+  if (input.query)
+    qParts.push(input.query)
+  if (input.name)
+    qParts.push(`name contains '${input.name.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`)
+  if (input.mimeType)
+    qParts.push(`mimeType = '${input.mimeType}'`)
+  if (!input.includeTrashed)
+    qParts.push('trashed = false')
+  if (qParts.length > 0)
+    params.set('q', qParts.join(' and '))
+  params.set('fields', input.fields || 'nextPageToken,files(id,name,mimeType,modifiedTime,size,parents)')
+  params.set('pageSize', String(input.pageSize || 20))
+  if (input.pageToken)
+    params.set('pageToken', input.pageToken)
+  const res = await integration.fetch(`/files?${params.toString()}`)
+  return await res.json()
+}

package/integrations/google-drive/handlers/share_file.js

@@ -0,0 +1,20 @@
+async (input) => {
+  const fileId = encodeURIComponent(input.fileId)
+  const params = new URLSearchParams()
+  if (input.sendNotificationEmail !== undefined)
+    params.set('sendNotificationEmail', String(input.sendNotificationEmail))
+  if (input.emailMessage)
+    params.set('emailMessage', input.emailMessage)
+  const body = {
+    role: input.role,
+    type: input.type,
+  }
+  if (input.emailAddress) body.emailAddress = input.emailAddress
+  if (input.domain) body.domain = input.domain
+  const qs = params.toString()
+  const res = await integration.fetch(`/files/${fileId}/permissions${qs ? `?${qs}` : ''}`, {
+    method: 'POST',
+    body,
+  })
+  return await res.json()
+}

package/integrations/google-drive/manifest.json

@@ -2,41 +2,68 @@
   "name": "google-drive",
   "version": "0.1.0",
   "tools": [
+    {
+      "name": "list_files",
+      "description": "List files in a Google Drive folder or across all of Drive. Returns id, name, mimeType, modifiedTime, size, and parents for each file. Excludes trashed files by default. Use folderId to scope to a specific folder. For name- or type-based search, use search_files instead. Defaults to 50 results per page; use pageToken from the response for the next page.",
+      "inputSchema": "schemas/list_files.json",
+      "handler": "handlers/list_files.js",
+      "scope": "read"
+    },
+    {
+      "name": "search_files",
+      "description": "Search Google Drive for files by name, MIME type, or raw Drive query syntax. Use the 'name' shorthand for simple name searches (e.g. name='quarterly report'). Use 'mimeType' to filter by type. Use 'query' for advanced Drive search expressions (e.g. \"modifiedTime > '2024-01-01'\" or \"'folderId' in parents and mimeType='application/pdf'\"). All provided filters are combined with AND. Defaults to 20 results per page.",
+      "inputSchema": "schemas/search_files.json",
+      "handler": "handlers/search_files.js",
+      "scope": "read"
+    },
+    {
+      "name": "get_file",
+      "description": "Get metadata for a Drive file or folder by ID. Returns id, name, mimeType, modifiedTime, createdTime, size, parents, trashed status, and webViewLink by default. To read the actual file contents, use get_file_content. To find a file by name, use search_files.",
+      "inputSchema": "schemas/get_file.json",
+      "handler": "handlers/get_file.js",
+      "scope": "read"
+    },
+    {
+      "name": "get_file_content",
+      "description": "Read the text content of a Drive file. For Google Workspace files (Docs, Sheets, Slides), automatically exports to text/plain or text/csv. Pass the 'mimeType' from get_file or search_files results to enable automatic export format detection. Use 'exportMimeType' to override the format (e.g. 'text/html' for formatted HTML, 'text/csv' for Sheets data). Returns {fileId, mimeType, content} for text files. Binary files (PDFs, images) return a message suggesting an export format.",
+      "inputSchema": "schemas/get_file_content.json",
+      "handler": "handlers/get_file_content.js",
+      "scope": "read"
+    },
     {
       "name": "create_folder",
-      "description": "Create a folder in Google Drive.",
+      "description": "Create a new folder in Google Drive. Optionally nest it inside a parent folder using parentId. Returns the created folder's metadata including its ID, which can be used as a parentId for subsequent file creation.",
       "inputSchema": "schemas/create_folder.json",
       "handler": "handlers/create_folder.js",
       "scope": "write"
     },
     {
       "name": "create_file",
-      "description": "Create a Drive file (including Google Docs/Sheets/Slides) optionally inside a parent folder.",
+      "description": "Create a new Drive file (metadata only -- no content upload). To create a Google Workspace file, use the appropriate mimeType: 'application/vnd.google-apps.document' for Docs, 'application/vnd.google-apps.spreadsheet' for Sheets, 'application/vnd.google-apps.presentation' for Slides. Optionally place it in a folder with parentId. Returns the created file's metadata including its ID.",
       "inputSchema": "schemas/create_file.json",
       "handler": "handlers/create_file.js",
       "scope": "write"
     },
     {
       "name": "move_file",
-      "description": "Move a file to a different parent folder (add/remove parents).",
+      "description": "Move a file or folder to a different parent folder by updating its parents. Provide the destination folder ID as addParents and optionally the current parent ID as removeParents (to remove it from the old location). Get the current parents from get_file.",
       "inputSchema": "schemas/move_file.json",
       "handler": "handlers/move_file.js",
       "scope": "write"
     },
     {
-      "name": "get_file",
-      "description": "Get a Drive file’s metadata by fileId.",
-      "inputSchema": "schemas/get_file.json",
-      "handler": "handlers/get_file.js",
-      "scope": "read"
+      "name": "share_file",
+      "description": "Share a Drive file or folder with a specific user, group, domain, or make it publicly accessible. Use type='user' with emailAddress for individual sharing. Use type='anyone' with role='reader' to create a public view link. Use type='domain' with domain for organization-wide sharing. Returns the created permission resource.",
+      "inputSchema": "schemas/share_file.json",
+      "handler": "handlers/share_file.js",
+      "scope": "write"
     },
     {
       "name": "delete_file",
-      "description": "Permanently delete a Drive file or folder by fileId.",
+      "description": "Permanently and immediately delete a Drive file or folder by ID. This bypasses Trash and cannot be undone. To move to Trash instead, use the Google Drive UI or modify file properties. Use search_files or list_files to find file IDs.",
       "inputSchema": "schemas/delete_file.json",
       "handler": "handlers/delete_file.js",
       "scope": "write"
     }
   ]
 }
-