@commandable/integration-data 0.0.4 → 0.0.6

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/insert_inline_image_after_first_match.json

@@ -5,7 +5,6 @@
     "documentId": { "type": "string" },
     "findText": { "type": "string" },
     "uri": { "type": "string" },
-    "altText": { "type": "string" },
     "position": { "type": "string", "enum": ["after", "before"], "default": "after" }
   },
   "required": ["documentId", "findText", "uri"],

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/__tests__/handlers.test.ts

@@ -0,0 +1,145 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { createCredentialStore, createIntegrationNode, createProxy, createToolbox, safeCleanup } from '../../__tests__/liveHarness.js'
+
+// LIVE Google Drive tests -- runs once per available credential variant.
+// Required env vars (at least one):
+// - GOOGLE_SERVICE_ACCOUNT_JSON  (service_account variant)
+// - GOOGLE_TOKEN                 (oauth_token variant)
+
+const env = process.env as Record<string, string | undefined>
+
+interface VariantConfig {
+  key: string
+  credentials: () => Record<string, string>
+}
+
+const variants: VariantConfig[] = [
+  {
+    key: 'service_account',
+    credentials: () => ({ serviceAccountJson: env.GOOGLE_SERVICE_ACCOUNT_JSON || '', subject: env.GOOGLE_IMPERSONATE_SUBJECT || '' }),
+  },
+  {
+    key: 'oauth_token',
+    credentials: () => ({ token: env.GOOGLE_TOKEN || '' }),
+  },
+].filter(v => Object.values(v.credentials()).some(val => val.trim().length > 0))
+
+const suiteOrSkip = variants.length > 0 ? describe : describe.skip
+
+suiteOrSkip('google-drive handlers (live)', () => {
+  for (const variant of variants) {
+    describe(`variant: ${variant.key}`, () => {
+      const ctx: { folderId?: string, fileId?: string, destFolderId?: string } = {}
+      let drive: ReturnType<typeof createToolbox>
+
+      beforeAll(async () => {
+        const credentialStore = createCredentialStore(async () => variant.credentials())
+        const proxy = createProxy(credentialStore)
+        drive = createToolbox(
+          'google-drive',
+          proxy,
+          createIntegrationNode('google-drive', { label: 'Google Drive', credentialId: 'google-drive-creds', credentialVariant: variant.key }),
+          variant.key,
+        )
+
+        const folder = await drive.write('create_folder')({ name: `CmdTest Drive ${Date.now()}` })
+        ctx.folderId = folder?.id
+        expect(ctx.folderId).toBeTruthy()
+
+        const destFolder = await drive.write('create_folder')({ name: `CmdTest Drive Dest ${Date.now()}` })
+        ctx.destFolderId = destFolder?.id
+        expect(ctx.destFolderId).toBeTruthy()
+
+        const file = await drive.write('create_file')({
+          name: `CmdTest File ${Date.now()}`,
+          mimeType: 'application/vnd.google-apps.document',
+          parentId: ctx.folderId,
+        })
+        ctx.fileId = file?.id
+        expect(ctx.fileId).toBeTruthy()
+      }, 60000)
+
+      afterAll(async () => {
+        await safeCleanup(async () => ctx.fileId ? drive.write('delete_file')({ fileId: ctx.fileId }) : Promise.resolve())
+        await safeCleanup(async () => ctx.folderId ? drive.write('delete_file')({ fileId: ctx.folderId }) : Promise.resolve())
+        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)
+        const result = await drive.read('get_file')({ fileId: ctx.fileId })
+        expect(result?.id).toBe(ctx.fileId)
+        expect(typeof result?.name).toBe('string')
+        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)
+        const result = await drive.write('move_file')({
+          fileId: ctx.fileId,
+          addParents: ctx.destFolderId,
+          removeParents: ctx.folderId,
+        })
+        expect(result?.id).toBe(ctx.fileId)
+        const meta = await drive.read('get_file')({ fileId: ctx.fileId })
+        expect(meta?.parents).toContain(ctx.destFolderId)
+      }, 30000)
+
+      it('delete_file deletes a file permanently', async () => {
+        const tempFile = await drive.write('create_file')({
+          name: `CmdTest Temp ${Date.now()}`,
+          mimeType: 'application/vnd.google-apps.document',
+        })
+        const tempId = tempFile?.id
+        expect(tempId).toBeTruthy()
+        await drive.write('delete_file')({ fileId: tempId })
+        await expect(drive.read('get_file')({ fileId: tempId })).rejects.toThrow()
+      }, 30000)
+    })
+  }
+})

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"
     }
   ]
 }
-

package/integrations/google-drive/prompt.md

@@ -0,0 +1,59 @@
+## File and folder IDs
+
+Drive file and folder IDs appear in the URL:
+- Files: `https://drive.google.com/file/d/{fileId}/view`
+- Folders: `https://drive.google.com/drive/folders/{folderId}`
+- Google Docs: `https://docs.google.com/document/d/{documentId}/edit`
+
+Use `search_files` or `list_files` to find IDs programmatically.
+
+## MIME types for Google Workspace files
+
+When creating files with `create_file`, use these MIME types:
+
+| File type | MIME type |
+|---|---|
+| Google Doc | `application/vnd.google-apps.document` |
+| Google Sheet | `application/vnd.google-apps.spreadsheet` |
+| Google Slides | `application/vnd.google-apps.presentation` |
+| Google Forms | `application/vnd.google-apps.form` |
+| Google Folder | `application/vnd.google-apps.folder` |
+
+## Drive search query syntax
+
+The `query` parameter in `search_files` uses the Drive search syntax:
+
+- `name contains 'budget'` — file name contains string
+- `name = 'exact name'` — exact file name match
+- `mimeType = 'application/pdf'` — filter by MIME type
+- `mimeType != 'application/vnd.google-apps.folder'` — exclude folders
+- `'folderId' in parents` — files in a specific folder
+- `modifiedTime > '2024-01-01T00:00:00'` — modified after date (RFC3339)
+- `trashed = true` — only trashed files
+- `starred = true` — only starred files
+- `sharedWithMe = true` — files shared with the user
+
+Combine with `and`, `or`, `not`: `name contains 'report' and mimeType = 'application/pdf' and modifiedTime > '2024-01-01T00:00:00'`
+
+## Reading file contents
+
+1. Use `search_files` or `list_files` to find the file (note its `id` and `mimeType`)
+2. Call `get_file_content` with `fileId` and `mimeType`
+   - For Google Workspace files, the `mimeType` triggers automatic export
+   - For text/CSV/JSON files, content is returned directly
+
+## Export formats
+
+Google Workspace files must be exported (they have no binary content):
+
+| Source | Default export | Alternative exports |
+|---|---|---|
+| Google Docs | `text/plain` | `text/html`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/pdf` |
+| Google Sheets | `text/csv` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `application/pdf` |
+| Google Slides | `text/plain` | `application/vnd.openxmlformats-officedocument.presentationml.presentation`, `application/pdf` |
+
+## Sharing files
+
+- Individual user: `share_file` with `type='user'`, `role='writer'`, `emailAddress='user@example.com'`
+- Anyone with link: `share_file` with `type='anyone'`, `role='reader'`
+- Whole domain: `share_file` with `type='domain'`, `role='reader'`, `domain='example.com'`

package/integrations/google-drive/schemas/get_file.json

@@ -4,7 +4,7 @@
   "required": ["fileId"],
   "additionalProperties": false,
   "properties": {
-    "fileId": { "type": "string" }
+    "fileId": { "type": "string", "description": "Drive file or folder ID. Use search_files or list_files to find file IDs." },
+    "fields": { "type": "string", "description": "Comma-separated list of fields to return. Defaults to 'id,name,mimeType,modifiedTime,createdTime,size,parents,trashed,webViewLink'. See the Drive API fields reference for all available fields." }
   }
 }
-

package/integrations/google-drive/schemas/get_file_content.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["fileId"],
+  "properties": {
+    "fileId": { "type": "string", "description": "Drive file ID. Use search_files or list_files to find file IDs." },
+    "mimeType": { "type": "string", "description": "The file's MIME type, obtained from get_file or search_files. Required for Google Workspace files (Docs, Sheets, Slides) to trigger automatic text export. Google Docs files start with 'application/vnd.google-apps.'." },
+    "exportMimeType": { "type": "string", "description": "Override the export format. For Google Docs: 'text/plain', 'text/html', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'. For Sheets: 'text/csv', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'. For Slides: 'text/plain', 'application/vnd.openxmlformats-officedocument.presentationml.presentation'. For any: 'application/pdf'." }
+  },
+  "additionalProperties": false
+}

package/integrations/google-drive/schemas/list_files.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "folderId": { "type": "string", "description": "Parent folder ID to list contents of. Omit to list files across all of Drive (not scoped to a folder). Use search_files with query=\"'root' in parents\" to list only root-level files." },
+    "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Maximum results per page. Defaults to 50. Use pageToken from the response for the next page." },
+    "pageToken": { "type": "string", "description": "Page token from a previous list_files response to retrieve the next page of results." },
+    "orderBy": { "type": "string", "description": "Sort order. Examples: 'modifiedTime desc', 'name', 'createdTime desc'. Default is unspecified." },
+    "fields": { "type": "string", "description": "Override the fields returned in each file. Defaults to 'nextPageToken,files(id,name,mimeType,modifiedTime,size,parents)'." }
+  },
+  "additionalProperties": false
+}