checkbox-mcp-server 1.1.1 → 2.0.1

package/dist/index.d.ts

@@ -8,7 +8,8 @@
  *
  * 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
+ *   CHECKBOX_API_KEY    — API key (ck_live_...) — preferred
+ *   CHECKBOX_API_TOKEN  — Alias for CHECKBOX_API_KEY (backward compat)
  *
  * Get your API key:
  *   1. Log in to checkbox.my

package/dist/index.js

@@ -8,7 +8,8 @@
  *
  * 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
+ *   CHECKBOX_API_KEY    — API key (ck_live_...) — preferred
+ *   CHECKBOX_API_TOKEN  — Alias for CHECKBOX_API_KEY (backward compat)
  *
  * Get your API key:
  *   1. Log in to checkbox.my
@@ -20,7 +21,7 @@ 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 ?? '';
+const API_TOKEN = process.env.CHECKBOX_API_KEY || process.env.CHECKBOX_API_TOKEN || '';
 function getHeaders() {
     return {
         'Content-Type': 'application/json',
@@ -33,7 +34,11 @@ async function apiGet(path) {
         method: 'GET',
         headers: getHeaders(),
     });
-    return res.json();
+    const json = await res.json().catch(() => null);
+    if (!res.ok) {
+        throw new Error(extractError(json) || `Request failed (${res.status})`);
+    }
+    return json;
 }
 async function apiPost(path, body) {
     const res = await fetch(`${API_URL}${path}`, {
@@ -41,7 +46,28 @@ async function apiPost(path, body) {
         headers: getHeaders(),
         body: JSON.stringify(body),
     });
-    return res.json();
+    const json = await res.json().catch(() => null);
+    if (!res.ok) {
+        const msg = extractError(json) || `Request failed (${res.status})`;
+        throw new Error(msg);
+    }
+    if (json && json.success === false) {
+        throw new Error(extractError(json) || 'Request failed');
+    }
+    return json;
+}
+function extractError(obj) {
+    if (!obj)
+        return '';
+    if (typeof obj === 'string')
+        return obj;
+    if (typeof obj.error === 'string')
+        return obj.error;
+    if (obj.error?.message)
+        return obj.error.message;
+    if (obj.message)
+        return obj.message;
+    return JSON.stringify(obj);
 }
 function resultText(data) {
     return JSON.stringify(data, null, 2);
@@ -49,12 +75,17 @@ function resultText(data) {
 // ── MCP Server ──────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'checkbox',
-    version: '1.1.0',
+    version: '2.0.1',
 });
 // 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) }] };
+    try {
+        const data = await apiGet('/api/v2/introspection/capabilities');
+        return { content: [{ type: 'text', text: resultText(data) }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+    }
 });
 // 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.', {
@@ -62,11 +93,16 @@ server.tool('execute_command', 'Execute a Checkbox capability command. Use list_
     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) }] };
+    try {
+        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) }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+    }
 });
 // 3. Execute query ───────────────────────────────────────────────────
 server.tool('execute_query', 'Execute a Checkbox capability query. Use list_capabilities to see available query types.', {
@@ -74,19 +110,29 @@ server.tool('execute_query', 'Execute a Checkbox capability query. Use list_capa
     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) }] };
+    try {
+        const data = await apiPost('/api/v2/query', {
+            type,
+            organization_id,
+            payload: { ...payload, organization_id },
+        });
+        return { content: [{ type: 'text', text: resultText(data) }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+    }
 });
 // 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) }] };
+    try {
+        const data = await apiPost('/api/v2/introspection/workspace', { organization_id });
+        return { content: [{ type: 'text', text: resultText(data) }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+    }
 });
 // 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.', {
@@ -95,13 +141,18 @@ server.tool('find_entities', 'Search for entities in the workspace by type and/o
     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) }] };
+    try {
+        const data = await apiPost('/api/v2/introspection/entities', {
+            organization_id,
+            entity_type,
+            search,
+            limit,
+        });
+        return { content: [{ type: 'text', text: resultText(data) }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+    }
 });
 // 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.', {
@@ -109,27 +160,42 @@ server.tool('get_schema', 'Get the schema for entity types — describes fields,
     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) }] };
+    try {
+        const data = await apiPost('/api/v2/introspection/schema', {
+            organization_id,
+            entity_type,
+            entity_id,
+        });
+        return { content: [{ type: 'text', text: resultText(data) }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+    }
 });
 // 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) }] };
+    try {
+        const data = await apiPost('/api/v2/introspection/permissions', { organization_id });
+        return { content: [{ type: 'text', text: resultText(data) }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+    }
 });
 // 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) }] };
+    try {
+        const data = await apiPost('/api/v2/query', {
+            type: 'list_my_organizations',
+            payload: {},
+        });
+        return { content: [{ type: 'text', text: resultText(data) }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+    }
 });
 // ── Start ───────────────────────────────────────────────────────────
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "checkbox-mcp-server",
-  "version": "1.1.1",
+  "version": "2.0.1",
   "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",