checkbox-mcp-server 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Checkbox MCP Server
+ *
+ * Exposes the Checkbox capability API as MCP tools so AI assistants
+ * (Claude, etc.) can interact with a Checkbox workspace through the
+ * standard Model Context Protocol.
+ *
+ * Environment variables:
+ *   CHECKBOX_API_URL    — Base URL of the Checkbox instance (e.g. https://checkbox.my)
+ *   CHECKBOX_API_TOKEN  — API key (ck_live_...) or Supabase JWT
+ *
+ * Get your API key:
+ *   1. Log in to checkbox.my
+ *   2. Go to Developer Hub (sidebar)
+ *   3. Create an API key — it never expires unless you configure an expiry
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Checkbox MCP Server
+ *
+ * Exposes the Checkbox capability API as MCP tools so AI assistants
+ * (Claude, etc.) can interact with a Checkbox workspace through the
+ * standard Model Context Protocol.
+ *
+ * Environment variables:
+ *   CHECKBOX_API_URL    — Base URL of the Checkbox instance (e.g. https://checkbox.my)
+ *   CHECKBOX_API_TOKEN  — API key (ck_live_...) or Supabase JWT
+ *
+ * Get your API key:
+ *   1. Log in to checkbox.my
+ *   2. Go to Developer Hub (sidebar)
+ *   3. Create an API key — it never expires unless you configure an expiry
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+// ── Config ──────────────────────────────────────────────────────────
+const API_URL = process.env.CHECKBOX_API_URL ?? 'https://checkbox.my';
+const API_TOKEN = process.env.CHECKBOX_API_TOKEN ?? '';
+function getHeaders() {
+    return {
+        'Content-Type': 'application/json',
+        ...(API_TOKEN ? { Authorization: `Bearer ${API_TOKEN}` } : {}),
+    };
+}
+// ── HTTP helpers ────────────────────────────────────────────────────
+async function apiGet(path) {
+    const res = await fetch(`${API_URL}${path}`, {
+        method: 'GET',
+        headers: getHeaders(),
+    });
+    return res.json();
+}
+async function apiPost(path, body) {
+    const res = await fetch(`${API_URL}${path}`, {
+        method: 'POST',
+        headers: getHeaders(),
+        body: JSON.stringify(body),
+    });
+    return res.json();
+}
+function resultText(data) {
+    return JSON.stringify(data, null, 2);
+}
+// ── MCP Server ──────────────────────────────────────────────────────
+const server = new McpServer({
+    name: 'checkbox',
+    version: '1.1.0',
+});
+// 1. List capabilities ───────────────────────────────────────────────
+server.tool('list_capabilities', 'List all available Checkbox commands and queries with their descriptions, required roles, and domains. Call this first to understand what actions are available.', {}, async () => {
+    const data = await apiGet('/api/v2/introspection/capabilities');
+    return { content: [{ type: 'text', text: resultText(data) }] };
+});
+// 2. Execute command ─────────────────────────────────────────────────
+server.tool('execute_command', 'Execute a Checkbox capability command. Use list_capabilities to see available command types and get_schema to understand the payload shape for each entity type.', {
+    type: z.string().describe('The command type (e.g. "create_task", "complete_task", "update_plan")'),
+    organization_id: z.string().optional().describe('Organization ID. Required for org-scoped commands; omit for authenticated-scope commands like create_organization.'),
+    payload: z.record(z.unknown()).describe('Command payload — structure depends on the command type. Use get_schema to discover the expected fields.'),
+}, async ({ type, organization_id, payload }) => {
+    const body = { type, payload };
+    if (organization_id)
+        body.organization_id = organization_id;
+    const data = await apiPost('/api/v2/commands', body);
+    return { content: [{ type: 'text', text: resultText(data) }] };
+});
+// 3. Execute query ───────────────────────────────────────────────────
+server.tool('execute_query', 'Execute a Checkbox capability query. Use list_capabilities to see available query types.', {
+    type: z.string().describe('The query type (e.g. "get_task_states", "workspace_graph", "list_entities", "get_entity")'),
+    organization_id: z.string().describe('Organization ID'),
+    payload: z.record(z.unknown()).describe('Query payload — structure depends on the query type. Use get_schema to discover the expected fields.'),
+}, async ({ type, organization_id, payload }) => {
+    const data = await apiPost('/api/v2/query', {
+        type,
+        organization_id,
+        payload: { ...payload, organization_id },
+    });
+    return { content: [{ type: 'text', text: resultText(data) }] };
+});
+// 4. Get workspace graph ─────────────────────────────────────────────
+server.tool('get_workspace', 'Get the full workspace graph — all entities (tasks, plans, goals, rules, requirements, tables, documents, etc.) and their relationships. Useful for understanding the structure of an organization before taking actions.', {
+    organization_id: z.string().describe('Organization ID'),
+}, async ({ organization_id }) => {
+    const data = await apiPost('/api/v2/introspection/workspace', { organization_id });
+    return { content: [{ type: 'text', text: resultText(data) }] };
+});
+// 5. Find entities ───────────────────────────────────────────────────
+server.tool('find_entities', 'Search for entities in the workspace by type and/or text search. Returns matching entities with their IDs, names, and metadata.', {
+    organization_id: z.string().describe('Organization ID'),
+    entity_type: z.string().optional().describe('Filter by entity type (e.g. "task", "plan", "table", "document")'),
+    search: z.string().optional().describe('Text search across entity names'),
+    limit: z.number().optional().describe('Max results to return (default varies by type)'),
+}, async ({ organization_id, entity_type, search, limit }) => {
+    const data = await apiPost('/api/v2/introspection/entities', {
+        organization_id,
+        entity_type,
+        search,
+        limit,
+    });
+    return { content: [{ type: 'text', text: resultText(data) }] };
+});
+// 6. Get schema ──────────────────────────────────────────────────────
+server.tool('get_schema', 'Get the schema for entity types — describes fields, writable fields, and filterable fields. Use this to understand what parameters to pass when creating or updating entities.', {
+    organization_id: z.string().describe('Organization ID'),
+    entity_type: z.string().optional().describe('Specific entity type to get schema for (e.g. "task", "plan", "table")'),
+    entity_id: z.string().optional().describe('Specific entity ID to get schema for (useful for table records whose schema is defined per-table)'),
+}, async ({ organization_id, entity_type, entity_id }) => {
+    const data = await apiPost('/api/v2/introspection/schema', {
+        organization_id,
+        entity_type,
+        entity_id,
+    });
+    return { content: [{ type: 'text', text: resultText(data) }] };
+});
+// 7. Check permissions ───────────────────────────────────────────────
+server.tool('check_permissions', 'Check which capabilities the current user has in an organization. Returns the user role and a list of all commands/queries with allowed/denied status.', {
+    organization_id: z.string().describe('Organization ID'),
+}, async ({ organization_id }) => {
+    const data = await apiPost('/api/v2/introspection/permissions', { organization_id });
+    return { content: [{ type: 'text', text: resultText(data) }] };
+});
+// 8. List my organizations ──────────────────────────────────────────
+server.tool('list_my_organizations', 'List all organizations the authenticated user belongs to, with their role in each. Call this first to discover which organization_id to use for subsequent commands and queries.', {}, async () => {
+    const data = await apiPost('/api/v2/query', {
+        type: 'list_my_organizations',
+        payload: {},
+    });
+    return { content: [{ type: 'text', text: resultText(data) }] };
+});
+// ── Start ───────────────────────────────────────────────────────────
+async function main() {
+    if (!API_TOKEN) {
+        console.error('Warning: CHECKBOX_API_TOKEN is not set. Authenticated requests will fail.\n' +
+            'Get an API key: log in to checkbox.my → Developer Hub → Create Key');
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "checkbox-mcp-server",
+  "version": "1.1.0",
+  "description": "MCP server for the Checkbox capability API — lets AI assistants (Claude, Cursor, etc.) manage compliance plans, tasks, documents, and more through the Model Context Protocol.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "checkbox-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "checkbox",
+    "compliance",
+    "ai-agent",
+    "claude",
+    "cursor",
+    "automation"
+  ],
+  "author": "Checkbox <hello@checkbox.my>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fadhelcarlos/checkbox.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://checkbox.my",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsx": "^4.19.0",
+    "@types/node": "^22.0.0"
+  }
+}