@mondaydotcomorg/monday-api-mcp 1.11.3 → 1.12.2

package/README.md

@@ -8,7 +8,7 @@ A server implementation for the [Model Context Protocol (MCP)](https://modelcont
 
 ## 💻 Claude Desktop Demo
 
-https://github.com/user-attachments/assets/ed8d24e1-256b-4f6b-9d84-38e54a8703fd
+<https://github.com/user-attachments/assets/ed8d24e1-256b-4f6b-9d84-38e54a8703fd>
 
 ## Prerequisites
 
@@ -33,9 +33,55 @@ The monday.com API token can also be provided via the `monday_token` environment
 | monday.com API Token | `--token`, `-t` | monday.com API token (can also be provided via `monday_token` environment variable) | Yes | - |
 | API Version | `--version`, `-v` | monday.com API version | No | `current` |
 | Read Only Mode | `--read-only`, `-ro` | Enable read-only mode | No | `false` |
-| Monday apps Tools | `--mode`, `-m` | Set the mode for tool selection: "api" - API tools only, "apps" - (Beta) Monday Apps tools only | No | `api` |
+| Mode | `--mode`, `-m` | Set the mode for tool selection: "api" - API tools only, "apps" - (Beta) Monday Apps tools only, "atp" - (Alpha) ATP server mode | No | `api` |
 | Dynamic API Tools | `--enable-dynamic-api-tools`, `-edat` | (Beta) Enable dynamic API tools (Mode that includes the whole API schema, not supported when using read-only mode) | No | `false` |
 
+## 🧪 ATP Mode (Alpha)
+
+ATP (Agent Tool Protocol) mode provides an alternative integration that enables GraphQL API exploration and code execution capabilities. This mode exposes two powerful tools:
+
+- **explore_api**: Navigate and discover the monday.com GraphQL API structure
+- **execute_code**: Execute JavaScript code to call monday.com APIs dynamically
+
+> ⚠️ **Alpha Feature**: ATP mode is currently in alpha. APIs and behavior may change.
+
+### Usage
+
+```bash
+npx @mondaydotcomorg/monday-api-mcp@latest -t abcd123 -m atp
+```
+
+### Configuration
+
+| Environment Variable | Description | Required |
+|---------------------|-------------|----------|
+| `MONDAY_ATP_PORT` | Specify a fixed port for the ATP server (1-65535). If not set, a random available port will be used. | No |
+| `NODE_OPTIONS` | Node.js runtime options. Set to `--no-node-snapshot` for compatibility. | Yes |
+| `ATP_JWT_SECRET` | JWT secret for ATP authentication. Must be set but currently not used (e.g., `ignore`). | Yes |
+
+### Cursor Integration (ATP Mode)
+
+```json
+{
+  "mcpServers": {
+    "monday-api-mcp": {
+      "command": "npx",
+      "args": [
+        "@mondaydotcomorg/monday-api-mcp@latest",
+        "-t",
+        "abcd123",
+        "-m",
+        "atp"
+      ],
+      "env": {
+        "NODE_OPTIONS": "--no-node-snapshot",
+        "ATP_JWT_SECRET": "ignore"
+      }
+    }
+  }
+}
+```
+
 ## 💻 Claude Desktop Integration
 
 ```json

package/dist/domains/atp/atp.consts.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_DESCRIPTIONS = exports.getMondaySchemaUrl = exports.QUERY_DEPTH_LIMIT = exports.DEFAULT_API_VERSION = exports.MONDAY_API_NAME = exports.MONDAY_API_BASE_URL = exports.ATP_SERVER_VERSION = exports.ATP_SERVER_NAME = void 0;
+exports.ATP_SERVER_NAME = 'monday.com';
+exports.ATP_SERVER_VERSION = '1.0.0';
+exports.MONDAY_API_BASE_URL = 'https://api.monday.com/v2';
+exports.MONDAY_API_NAME = 'monday';
+exports.DEFAULT_API_VERSION = '2025-10';
+exports.QUERY_DEPTH_LIMIT = 2;
+const getMondaySchemaUrl = (version = exports.DEFAULT_API_VERSION) => `https://api.monday.com/v2/get_schema?version=${version}&format=sdl`;
+exports.getMondaySchemaUrl = getMondaySchemaUrl;
+exports.TOOL_DESCRIPTIONS = {
+    execute_code: `Execute Javascript code to call Monday.com APIs. MUST use 'return' to see results.
+
+**API Pattern:** api.monday.query_xxx() for reads, api.monday.mutation_xxx() for writes.
+
+**Critical Rules:**
+- Use _fields parameter for nested data: 'id,name,columns{id,title,type},items_page{cursor}'
+- ColumnValue has: id, type, text, value (NOT "title")
+- items_page returns ~25 items - use pagination for more
+- When searching/filtering, use the FULL value provided by the user (e.g., full name, not partial)
+
+**When Unsure - ASK THE USER:**
+- If you're not 100% sure about the user's intent, ASK before executing
+- If multiple results match a search, ASK which one they mean
+- If you're missing required information - ASK, don't guess
+
+**Multi-line Example:**
+\`\`\`typescript
+// 1. Get board with columns and cursor
+const boards = await api.monday.query_boards({ 
+  ids: ['BOARD_ID'],
+  _fields: 'id,columns{id,title,type},items_page{cursor}'
+});
+const board = boards[0];
+
+// 2. Find column by title
+const statusCol = board.columns.find(c => c.title === 'Status')?.id;
+
+// 3. Paginate items
+let cursor = board.items_page.cursor;
+const allItems = [];
+for (let page = 0; page < 20; page++) {
+  if (!cursor) break;
+  const result = await api.monday.query_next_items_page({ 
+    cursor, limit: 100,
+    _fields: 'cursor,items{id,name,group{title},column_values{id,text}}'
+  });
+  allItems.push(...result.items);
+  cursor = result.cursor;
+}
+
+// 4. Analyze and return
+return { total: allItems.length, items: allItems.slice(0, 5) };
+\`\`\`
+
+Use AFTER exploring the API to understand available operations.`,
+    explore_api: `Explore Monday.com API structure using filesystem-like navigation. ALWAYS use this BEFORE writing code to discover available operations and parameters.
+
+**Navigation Paths:**
+- "/monday/query" - List all query operations (read data)
+- "/monday/mutation" - List all mutation operations (write data)  
+- "/monday/query/boards" - See parameters for boards query
+- "/monday/query/items" - See parameters for items query
+
+**Valid Exploration Pattern:**
+2. Then: path="/monday/query" to see query operations
+3. Then: path="/monday/query/<operation_name>" to see parameters
+
+**DO NOT explore nested paths like:**
+- /monday/query/boards/items_page (doesn't exist)
+- /monday/query/boards/fields (doesn't exist)
+
+Only explore: /monday/query, /monday/mutation, or /monday/query/<operation_name>
+
+**Example Workflow:**
+1. explore_api path="/monday/query" → discover "boards", "items", "users" operations  
+2. explore_api path="/monday/query/boards" → see ids, _fields parameters
+3. YOU MUST USE THE EXPLORE_API TOOL TO DISCOVER THE OPERATIONS AND PARAMETERS BEFORE USING THE EXECUTE_CODE TOOL
+4. NOW write code using execute_code with discovered operations
+5. TRY TO MAKE ALL CODE EXECUTION IN ONE SCRIPT INSTEAD OF MULTIPLE ONES (IF POSSIBLE)
+
+**IMPORTANT - When Unsure, ASK:**
+- If you don't understand what the user wants - ASK
+- If you're missing required information - ASK
+- Don't guess or assume - it's better to ask than to make mistakes`,
+};

package/dist/domains/atp/atp.service.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAtpMcpServer = runAtpMcpServer;
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const net_1 = require("net");
+const atp_consts_js_1 = require("./atp.consts.js");
+// Dynamic imports required: ATP packages are ESM, this package is CJS
+async function loadAtpDependencies() {
+    const { createServer } = await import('@mondaydotcomorg/atp-server');
+    const { AgentToolProtocolClient, ToolNames } = await import('@mondaydotcomorg/atp-client');
+    const { registerToolsWithMCP } = await import('@mondaydotcomorg/atp-mcp-adapter');
+    return { createServer, AgentToolProtocolClient, ToolNames, registerToolsWithMCP };
+}
+function getToolDescriptions(ToolNames) {
+    return {
+        [String(ToolNames.EXECUTE_CODE)]: atp_consts_js_1.TOOL_DESCRIPTIONS.execute_code,
+        [String(ToolNames.EXPLORE_API)]: atp_consts_js_1.TOOL_DESCRIPTIONS.explore_api,
+    };
+}
+function filterAndEnhanceTools(tools, toolDescriptions) {
+    return tools
+        .filter((tool) => tool.name in toolDescriptions)
+        .map((tool) => ({
+        ...tool,
+        description: toolDescriptions[tool.name],
+    }));
+}
+/**
+ * Gets the ATP port from environment variable, or returns undefined to use dynamic port allocation.
+ * Set MONDAY_ATP_PORT environment variable to use a specific port.
+ */
+function getAtpPort() {
+    const envPort = process.env.MONDAY_ATP_PORT;
+    if (envPort) {
+        const port = parseInt(envPort, 10);
+        if (!isNaN(port) && port > 0 && port <= 65535) {
+            return port;
+        }
+    }
+    return undefined; // Will use dynamic port allocation
+}
+/**
+ * Finds an available port by binding to port 0 and letting the OS assign one.
+ */
+async function findAvailablePort() {
+    return new Promise((resolve, reject) => {
+        const server = (0, net_1.createServer)();
+        server.listen(0, () => {
+            const address = server.address();
+            if (address && typeof address === 'object') {
+                const port = address.port;
+                server.close(() => resolve(port));
+            }
+            else {
+                server.close(() => reject(new Error('Failed to get port from server address')));
+            }
+        });
+        server.on('error', reject);
+    });
+}
+async function initAtpServer(createServer) {
+    const server = createServer({ logger: 'none' });
+    // Use configured port or find an available one
+    const configuredPort = getAtpPort();
+    const port = configuredPort ?? (await findAvailablePort());
+    await server.listen(port);
+    return { server, port };
+}
+async function loadMondaySchema(server, token, version) {
+    const apiVersion = version ?? atp_consts_js_1.DEFAULT_API_VERSION;
+    await server.loadGraphQL((0, atp_consts_js_1.getMondaySchemaUrl)(apiVersion), {
+        name: atp_consts_js_1.MONDAY_API_NAME,
+        url: atp_consts_js_1.MONDAY_API_BASE_URL,
+        headers: {
+            Authorization: token,
+            'API-Version': apiVersion,
+        },
+        queryDepthLimit: atp_consts_js_1.QUERY_DEPTH_LIMIT,
+    });
+}
+async function initAtpClient(AgentToolProtocolClient, port) {
+    const client = new AgentToolProtocolClient({
+        baseUrl: `http://localhost:${port}`,
+    });
+    await client.init({ name: 'monday-api-mcp', version: '1.0.0' });
+    await client.connect();
+    return client;
+}
+function createMcpServer() {
+    return new mcp_js_1.McpServer({
+        name: atp_consts_js_1.ATP_SERVER_NAME,
+        version: atp_consts_js_1.ATP_SERVER_VERSION,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+}
+async function runAtpMcpServer(config) {
+    const { token, version } = config;
+    const { createServer, AgentToolProtocolClient, ToolNames, registerToolsWithMCP } = await loadAtpDependencies();
+    const { server, port } = await initAtpServer(createServer);
+    await loadMondaySchema(server, token, version);
+    const client = await initAtpClient(AgentToolProtocolClient, port);
+    const mcpServer = createMcpServer();
+    const toolDescriptions = getToolDescriptions(ToolNames);
+    const atpTools = filterAndEnhanceTools(client.getATPTools(), toolDescriptions);
+    registerToolsWithMCP(atpTools, mcpServer);
+    const transport = new stdio_js_1.StdioServerTransport();
+    await mcpServer.connect(transport);
+}

package/dist/domains/atp/atp.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domains/atp/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAtpMcpServer = void 0;
+var atp_service_js_1 = require("./atp.service.js");
+Object.defineProperty(exports, "runAtpMcpServer", { enumerable: true, get: function () { return atp_service_js_1.runAtpMcpServer; } });
+__exportStar(require("./atp.consts.js"), exports);
+__exportStar(require("./atp.types.js"), exports);

package/dist/index.js

@@ -6,17 +6,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const mcp_1 = require("@mondaydotcomorg/agent-toolkit/mcp");
+const core_1 = require("@mondaydotcomorg/agent-toolkit/core");
 const args_service_js_1 = require("./utils/args/args.service.js");
+const index_js_1 = require("./domains/atp/index.js");
 const dotenv_1 = __importDefault(require("dotenv"));
 dotenv_1.default.config();
-/**
- * Initializes and starts the MCP server with the Monday Agent Toolkit
- * Uses stdio for transport
- */
-async function runServer() {
-    const args = process.argv.slice(2);
-    const parsedArgs = (0, args_service_js_1.parseArgs)(args);
-    const validatedArgs = (0, args_service_js_1.validateArgs)(parsedArgs);
+async function runMcpServer(validatedArgs) {
     const toolkit = new mcp_1.MondayAgentToolkit({
         mondayApiToken: validatedArgs.token,
         mondayApiVersion: validatedArgs.version,
@@ -31,6 +26,20 @@ async function runServer() {
     const transport = new stdio_js_1.StdioServerTransport();
     await toolkit.connect(transport);
 }
+async function runServer() {
+    const args = process.argv.slice(2);
+    const parsedArgs = (0, args_service_js_1.parseArgs)(args);
+    const validatedArgs = (0, args_service_js_1.validateArgs)(parsedArgs);
+    if (validatedArgs.mode === core_1.ToolMode.ATP) {
+        await (0, index_js_1.runAtpMcpServer)({
+            token: validatedArgs.token,
+            version: validatedArgs.version,
+        });
+    }
+    else {
+        await runMcpServer(validatedArgs);
+    }
+}
 runServer().catch((error) => {
     console.error('Fatal error in main():', error);
     process.exit(1);

package/dist/utils/args/args.config.js

@@ -25,7 +25,7 @@ exports.ARG_CONFIGS = [
     {
         name: 'mode',
         flags: ['--mode', '-m'],
-        description: 'Set the mode for tool selection: "api" - API tools only, "apps" - (Beta) Monday Apps tools only',
+        description: 'Set the mode for tool selection: "api" - API tools only, "apps" - (Beta) Monday Apps tools only, "atp" - ATP server mode with GraphQL exploration',
         required: false,
         defaultValue: 'api',
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/monday-api-mcp",
-  "version": "1.11.3",
+  "version": "1.12.2",
   "description": "MCP server for using the monday.com API",
   "mcpName": "com.monday/monday.com",
   "license": "MIT",
@@ -25,7 +25,11 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.2",
     "@mondaydotcomorg/agent-toolkit": "*",
-    "dotenv": "^16.4.7"
+    "@mondaydotcomorg/atp-client": "^0.19.6",
+    "@mondaydotcomorg/atp-mcp-adapter": "^0.19.7",
+    "@mondaydotcomorg/atp-server": "^0.19.7",
+    "dotenv": "^16.4.7",
+    "zod": "^3.25.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",