@commandable/mcp 0.0.1

package/integration-data/google-slides/schemas/insert_image_after_first_match.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "presentationId": { "type": "string" },
+    "findText": { "type": "string" },
+    "uri": { "type": "string" },
+    "width": { "type": "number", "default": 2000000 },
+    "height": { "type": "number", "default": 2000000 }
+  },
+  "required": ["presentationId", "findText", "uri"],
+  "additionalProperties": false
+}

package/integration-data/google-slides/schemas/insert_shape_after_first_match.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "presentationId": { "type": "string" },
+    "findText": { "type": "string" },
+    "shapeType": { "type": "string", "default": "RECTANGLE" },
+    "width": { "type": "number", "default": 2000000 },
+    "height": { "type": "number", "default": 1000000 }
+  },
+  "required": ["presentationId", "findText"],
+  "additionalProperties": false
+}

package/integration-data/google-slides/schemas/replace_text_first_match.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "presentationId": { "type": "string" },
+    "findText": { "type": "string" },
+    "replaceText": { "type": "string" },
+    "matchCase": { "type": "boolean" }
+  },
+  "required": ["presentationId", "findText", "replaceText"],
+  "additionalProperties": false
+}

package/integration-data/google-slides/schemas/set_background_color_for_slide_index.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "presentationId": { "type": "string" },
+    "slideIndex": { "type": "number", "minimum": 0 },
+    "rgbColor": { "type": "object", "properties": { "red": { "type": "number" }, "green": { "type": "number" }, "blue": { "type": "number" } }, "required": ["red", "green", "blue"] }
+  },
+  "required": ["presentationId", "slideIndex", "rgbColor"],
+  "additionalProperties": false
+}

package/integration-data/google-slides/schemas/style_text_first_match.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "presentationId": { "type": "string" },
+    "findText": { "type": "string" },
+    "textStyle": { "type": "object" },
+    "fields": { "type": "string" }
+  },
+  "required": ["presentationId", "findText", "textStyle"],
+  "additionalProperties": false
+}

package/integration-data/new_integration_prompt.md

@@ -0,0 +1,41 @@
+## Task
+
+Write a new integration-data folder for `<INTEGRATION_NAME>`.
+
+## Required structure
+
+Create `commandable-mcp/packages/server/integration-data/<name>/` containing:
+
+- `manifest.json`: flat `tools[]`; each tool has `name`, `description`, `inputSchema` (relative path), `handler` (relative path), `scope` (`read` | `write` | optionally `admin`)
+- `schemas/*.json`: JSON Schema for each tool input. Prefer `additionalProperties: false` for strict contracts; use `true` only for pass-through bodies (common in Google APIs). Reuse `empty.json` for no-arg tools.
+- `handlers/*.js`: async arrow functions `async (input) => { ... }` using `integration.fetch(path, init?)` for all HTTP calls. Pass `body` as a plain object (proxy will JSON-stringify). Return parsed JSON.
+- `credentials.json`: `{ schema, injection }` where `schema` is JSON Schema for secrets and `injection` is `headers` and/or `query` templates using `{{placeholder}}`
+- `credentials_hint.md`: **numbered steps** (1., 2., 3., …) telling a user exactly how to obtain/provide credentials
+- `prompt.md` (optional): extra LLM guidance only if the API has non-obvious usage patterns
+
+Also register the provider in `src/integrations/providerRegistry.ts` with its base URL and auth factory.
+
+## Tool design goals
+
+- **Default**: small, composable tools that mirror API resources.
+- **Read tools**: side-effect free (GET only).
+- **Write tools**: POST/PUT/PATCH/DELETE where appropriate.
+- **Coverage**: start with core CRUD + list/search + get-by-id; add convenience tools after.
+
+## When to go beyond REST proxying
+
+Most handlers should be thin proxies (fetch → return JSON). Only add multi-step/orchestrating handlers when the raw API is genuinely hard for an LLM to use correctly, e.g.:
+
+- multi-step workflows (GitHub tree → blob → commit → ref)
+- required transforms (e.g. base64 encoding) that the caller shouldn’t manage
+- awkward addressing that benefits from higher-level helpers (“find text then act” patterns like Docs/Slides)
+
+If an endpoint is already clean and self-contained, just proxy it.
+
+## Reference examples (follow exactly)
+
+- `github/`: simple proxies + complex orchestration (`create_commit.js`)
+- `notion/`: clean proxying + optional `prompt.md`
+- `google-calendar/`: query param building + `read`/`write`/`admin` scopes
+- `trello/`: query-param credential injection + `displayCards`
+- `google-docs/`, `google-slides/`: higher-level write helpers over batchUpdate APIs

package/integration-data/notion/credentials.json

@@ -0,0 +1,21 @@
+{
+  "schema": {
+    "type": "object",
+    "properties": {
+      "token": {
+        "type": "string",
+        "title": "Internal Integration Token",
+        "description": "Notion internal integration token (starts with \"secret_\")."
+      }
+    },
+    "required": ["token"],
+    "additionalProperties": false
+  },
+  "injection": {
+    "headers": {
+      "Authorization": "Bearer {{token}}",
+      "Notion-Version": "2022-06-28"
+    }
+  }
+}
+

package/integration-data/notion/credentials_hint.md

@@ -0,0 +1,5 @@
+1. Go to `https://www.notion.so/profile/integrations/internal`
+2. Create a Notion integration in Notion’s developer settings
+3. Share your target pages/databases with that integration so it has access
+4. Copy the **Internal Integration Token** (usually starts with `secret_`)
+

package/integration-data/notion/handlers/append_block_children.js

@@ -0,0 +1,7 @@
+async (input) => {
+  const res = await integration.fetch(`/blocks/${encodeURIComponent(input.block_id)}/children`, {
+    method: 'PATCH',
+    body: { children: input.children },
+  })
+  return await res.json()
+}

package/integration-data/notion/handlers/create_comment.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const res = await integration.fetch(`/comments`, {
+    method: 'POST',
+    body: {
+      parent: input.parent,
+      rich_text: input.rich_text,
+    },
+  })
+  return await res.json()
+}

package/integration-data/notion/handlers/create_database.js

@@ -0,0 +1,11 @@
+async (input) => {
+  const res = await integration.fetch(`/databases`, {
+    method: 'POST',
+    body: {
+      parent: input.parent,
+      title: input.title,
+      properties: input.properties,
+    },
+  })
+  return await res.json()
+}

package/integration-data/notion/handlers/create_page.js

@@ -0,0 +1,13 @@
+async (input) => {
+  const res = await integration.fetch(`/pages`, {
+    method: 'POST',
+    body: {
+      parent: input.parent,
+      properties: input.properties,
+      children: input.children || undefined,
+      icon: input.icon || undefined,
+      cover: input.cover || undefined,
+    },
+  })
+  return await res.json()
+}

package/integration-data/notion/handlers/delete_block.js

@@ -0,0 +1,8 @@
+async (input) => {
+  // Notion 'delete' is archive block
+  const res = await integration.fetch(`/blocks/${encodeURIComponent(input.block_id)}`, {
+    method: 'PATCH',
+    body: { archived: true },
+  })
+  return await res.json()
+}

package/integration-data/notion/handlers/get_me.js

@@ -0,0 +1,4 @@
+async (input) => {
+  const res = await integration.fetch(`/users/me`)
+  return await res.json()
+}

package/integration-data/notion/handlers/list_block_children.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input.start_cursor)
+    params.set('start_cursor', input.start_cursor)
+  if (input.page_size)
+    params.set('page_size', String(input.page_size))
+  const qs = params.toString()
+  const res = await integration.fetch(`/blocks/${encodeURIComponent(input.block_id)}/children${qs ? `?${qs}` : ''}`)
+  return await res.json()
+}

package/integration-data/notion/handlers/list_comments.js

@@ -0,0 +1,14 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input.block_id)
+    params.set('block_id', input.block_id)
+  if (input.discussion_id)
+    params.set('discussion_id', input.discussion_id)
+  if (input.start_cursor)
+    params.set('start_cursor', input.start_cursor)
+  if (input.page_size)
+    params.set('page_size', String(input.page_size))
+  const qs = params.toString()
+  const res = await integration.fetch(`/comments${qs ? `?${qs}` : ''}`)
+  return await res.json()
+}

package/integration-data/notion/handlers/list_users.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input.start_cursor)
+    params.set('start_cursor', input.start_cursor)
+  if (input.page_size)
+    params.set('page_size', String(input.page_size))
+  const qs = params.toString()
+  const res = await integration.fetch(`/users${qs ? `?${qs}` : ''}`)
+  return await res.json()
+}

package/integration-data/notion/handlers/query_database.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const body = {
+    filter: input.filter || undefined,
+    sorts: input.sorts || undefined,
+    start_cursor: input.start_cursor || undefined,
+    page_size: input.page_size || undefined,
+  }
+  const res = await integration.fetch(`/databases/${encodeURIComponent(input.database_id)}/query`, { method: 'POST', body })
+  return await res.json()
+}

package/integration-data/notion/handlers/retrieve_block.js

@@ -0,0 +1,4 @@
+async (input) => {
+  const res = await integration.fetch(`/blocks/${encodeURIComponent(input.block_id)}`)
+  return await res.json()
+}

package/integration-data/notion/handlers/retrieve_database.js

@@ -0,0 +1,4 @@
+async (input) => {
+  const res = await integration.fetch(`/databases/${encodeURIComponent(input.database_id)}`)
+  return await res.json()
+}

package/integration-data/notion/handlers/retrieve_page.js

@@ -0,0 +1,4 @@
+async (input) => {
+  const res = await integration.fetch(`/pages/${encodeURIComponent(input.page_id)}`)
+  return await res.json()
+}

package/integration-data/notion/handlers/retrieve_page_property_item.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input.start_cursor)
+    params.set('start_cursor', input.start_cursor)
+  if (input.page_size)
+    params.set('page_size', String(input.page_size))
+  const qs = params.toString()
+  const res = await integration.fetch(`/pages/${encodeURIComponent(input.page_id)}/properties/${encodeURIComponent(input.property_id)}${qs ? `?${qs}` : ''}`)
+  return await res.json()
+}

package/integration-data/notion/handlers/retrieve_user.js

@@ -0,0 +1,4 @@
+async (input) => {
+  const res = await integration.fetch(`/users/${encodeURIComponent(input.user_id)}`)
+  return await res.json()
+}

package/integration-data/notion/handlers/search.js

@@ -0,0 +1,11 @@
+async (input) => {
+  const body = {
+    query: input.query || '',
+    filter: input.filter || undefined,
+    sort: input.sort || undefined,
+    start_cursor: input.start_cursor || undefined,
+    page_size: input.page_size || undefined,
+  }
+  const res = await integration.fetch(`/search`, { method: 'POST', body })
+  return await res.json()
+}

package/integration-data/notion/handlers/update_block.js

@@ -0,0 +1,7 @@
+async (input) => {
+  const res = await integration.fetch(`/blocks/${encodeURIComponent(input.block_id)}`, {
+    method: 'PATCH',
+    body: input.body || {},
+  })
+  return await res.json()
+}

package/integration-data/notion/handlers/update_database.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const body = {
+    title: input.title || undefined,
+    description: input.description || undefined,
+    properties: input.properties || undefined,
+    archived: input.archived === undefined ? undefined : input.archived,
+  }
+  const res = await integration.fetch(`/databases/${encodeURIComponent(input.database_id)}`, { method: 'PATCH', body })
+  return await res.json()
+}

package/integration-data/notion/handlers/update_page_properties.js

@@ -0,0 +1,10 @@
+async (input) => {
+  const body = {
+    properties: input.properties,
+    archived: input.archived === undefined ? undefined : input.archived,
+    icon: input.icon || undefined,
+    cover: input.cover || undefined,
+  }
+  const res = await integration.fetch(`/pages/${encodeURIComponent(input.page_id)}`, { method: 'PATCH', body })
+  return await res.json()
+}

package/integration-data/notion/manifest.json

@@ -0,0 +1,139 @@
+{
+  "name": "notion",
+  "version": "0.1.0",
+  "tools": [
+    {
+      "name": "search",
+      "description": "Search across all accessible Notion content (pages, databases).",
+      "inputSchema": "schemas/search.json",
+      "handler": "handlers/search.js",
+      "scope": "read"
+    },
+    {
+      "name": "retrieve_page",
+      "description": "Retrieve a page by ID.",
+      "inputSchema": "schemas/id_page.json",
+      "handler": "handlers/retrieve_page.js",
+      "scope": "read"
+    },
+    {
+      "name": "retrieve_database",
+      "description": "Retrieve a database by ID.",
+      "inputSchema": "schemas/id_database.json",
+      "handler": "handlers/retrieve_database.js",
+      "scope": "read"
+    },
+    {
+      "name": "query_database",
+      "description": "Query a database with optional filter, sorts, and pagination.",
+      "inputSchema": "schemas/query_database.json",
+      "handler": "handlers/query_database.js",
+      "scope": "read"
+    },
+    {
+      "name": "list_block_children",
+      "description": "List child blocks for a block (including page blocks).",
+      "inputSchema": "schemas/list_block_children.json",
+      "handler": "handlers/list_block_children.js",
+      "scope": "read"
+    },
+    {
+      "name": "retrieve_block",
+      "description": "Retrieve a block by ID.",
+      "inputSchema": "schemas/id_block.json",
+      "handler": "handlers/retrieve_block.js",
+      "scope": "read"
+    },
+    {
+      "name": "list_users",
+      "description": "List users in the workspace.",
+      "inputSchema": "schemas/list_users.json",
+      "handler": "handlers/list_users.js",
+      "scope": "read"
+    },
+    {
+      "name": "retrieve_user",
+      "description": "Retrieve a user by ID.",
+      "inputSchema": "schemas/id_user.json",
+      "handler": "handlers/retrieve_user.js",
+      "scope": "read"
+    },
+    {
+      "name": "list_comments",
+      "description": "List comments for a given discussion or page block.",
+      "inputSchema": "schemas/list_comments.json",
+      "handler": "handlers/list_comments.js",
+      "scope": "read"
+    },
+    {
+      "name": "get_me",
+      "description": "Retrieve the authenticated user (bot) profile.",
+      "inputSchema": "schemas/empty.json",
+      "handler": "handlers/get_me.js",
+      "scope": "read"
+    },
+    {
+      "name": "retrieve_page_property_item",
+      "description": "Retrieve a specific page property item (handles rollups and pagination).",
+      "inputSchema": "schemas/retrieve_page_property_item.json",
+      "handler": "handlers/retrieve_page_property_item.js",
+      "scope": "read"
+    },
+    {
+      "name": "create_page",
+      "description": "Create a new page in a database or as a child of a page.",
+      "inputSchema": "schemas/create_page.json",
+      "handler": "handlers/create_page.js",
+      "scope": "write"
+    },
+    {
+      "name": "update_page_properties",
+      "description": "Update page properties, archive/unarchive, icon and cover.",
+      "inputSchema": "schemas/update_page_properties.json",
+      "handler": "handlers/update_page_properties.js",
+      "scope": "write"
+    },
+    {
+      "name": "append_block_children",
+      "description": "Append child blocks to a block (including page blocks).",
+      "inputSchema": "schemas/append_block_children.json",
+      "handler": "handlers/append_block_children.js",
+      "scope": "write"
+    },
+    {
+      "name": "update_block",
+      "description": "Update a block (content, archived state, etc).",
+      "inputSchema": "schemas/update_block.json",
+      "handler": "handlers/update_block.js",
+      "scope": "write"
+    },
+    {
+      "name": "delete_block",
+      "description": "Archive a block (soft delete).",
+      "inputSchema": "schemas/delete_block.json",
+      "handler": "handlers/delete_block.js",
+      "scope": "write"
+    },
+    {
+      "name": "create_comment",
+      "description": "Create a comment on a discussion or block.",
+      "inputSchema": "schemas/create_comment.json",
+      "handler": "handlers/create_comment.js",
+      "scope": "write"
+    },
+    {
+      "name": "create_database",
+      "description": "Create a new database under a page.",
+      "inputSchema": "schemas/create_database.json",
+      "handler": "handlers/create_database.js",
+      "scope": "write"
+    },
+    {
+      "name": "update_database",
+      "description": "Update database title, description, properties, or archived state.",
+      "inputSchema": "schemas/update_database.json",
+      "handler": "handlers/update_database.js",
+      "scope": "write"
+    }
+  ]
+}

package/integration-data/notion/prompt.md

@@ -0,0 +1,26 @@
+## Appending paragraph blocks
+
+When appending a paragraph block to a Notion page, ensure the `rich_text` field is correctly defined within the `paragraph` type. Example format:
+
+```json
+{
+  "block_id": "<page_id>",
+  "children": [
+    {
+      "object": "block",
+      "type": "paragraph",
+      "paragraph": {
+        "rich_text": [
+          {
+            "type": "text",
+            "text": {
+              "content": "Your text here"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+

package/integration-data/notion/schemas/append_block_children.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["block_id", "children"],
+  "additionalProperties": false,
+  "properties": {
+    "block_id": { "type": "string" },
+    "children": { "type": "array", "items": { "type": "object" } }
+  }
+}

package/integration-data/notion/schemas/create_comment.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["parent", "rich_text"],
+  "additionalProperties": false,
+  "properties": {
+    "parent": {
+      "type": "object",
+      "description": "Parent discussion_id or block_id.",
+      "additionalProperties": false,
+      "properties": {
+        "discussion_id": { "type": "string" },
+        "block_id": { "type": "string" }
+      }
+    },
+    "rich_text": { "type": "array", "items": { "type": "object" } }
+  }
+}

package/integration-data/notion/schemas/create_database.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["parent", "title", "properties"],
+  "additionalProperties": false,
+  "properties": {
+    "parent": {
+      "type": "object",
+      "description": "Parent page where the database will be created.",
+      "additionalProperties": false,
+      "properties": {
+        "page_id": { "type": "string" }
+      }
+    },
+    "title": { "type": "array", "items": { "type": "object" } },
+    "properties": { "type": "object" }
+  }
+}

package/integration-data/notion/schemas/create_page.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["parent", "properties"],
+  "additionalProperties": false,
+  "properties": {
+    "parent": {
+      "type": "object",
+      "description": "Parent object specifying database_id or page_id.",
+      "additionalProperties": false,
+      "properties": {
+        "database_id": { "type": "string" },
+        "page_id": { "type": "string" },
+        "type": { "type": "string" }
+      }
+    },
+    "properties": { "type": "object", "description": "Page properties map per Notion API." },
+    "children": { "type": "array", "items": { "type": "object" } },
+    "icon": { "type": ["object", "null"] },
+    "cover": { "type": ["object", "null"] }
+  }
+}

package/integration-data/notion/schemas/delete_block.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["block_id"],
+  "additionalProperties": false,
+  "properties": {
+    "block_id": { "type": "string" }
+  }
+}

package/integration-data/notion/schemas/empty.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}

package/integration-data/notion/schemas/id_block.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["block_id"],
+  "properties": {
+    "block_id": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/integration-data/notion/schemas/id_database.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["database_id"],
+  "properties": {
+    "database_id": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/integration-data/notion/schemas/id_page.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["page_id"],
+  "properties": {
+    "page_id": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/integration-data/notion/schemas/id_user.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["user_id"],
+  "properties": {
+    "user_id": { "type": "string" }
+  },
+  "additionalProperties": false
+}