@orkesflow/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# Orkesflow MCP Server
+
+El servidor **Orkesflow MCP** permite integrar tus herramientas de IA (como Claude Desktop) directamente con tu plataforma Orkesflow. Podrás gestionar tareas, tableros y registros de tiempo utilizando lenguaje natural a través del protocolo MCP (Model Context Protocol).
+
+## Características
+
+- 📋 **Listar tareas**: Obtén una visión general de tus tareas pendientes.
+- 🏗️ **Gestión de tableros**: Explora los espacios y tableros disponibles.
+- ➕ **Creación de tareas**: Crea nuevas tarjetas especificando título, prioridad, etiquetas y tablero (por ID o nombre).
+- 🔄 **Actualización de tareas**: Modifica estados, mueve tareas entre columnas o cambia prioridades.
+- ⏱️ **Registro de tiempo**: Añade registros de tiempo y costes a tareas específicas.
+
+## Requisitos Previos
+
+1. **Token de Acceso Personal (PAT)**: Necesitas un token generado desde tu perfil en Orkesflow con los permisos adecuados.
+2. **Node.js**: Versión 18 o superior.
+
+## Instalación y Ejecución
+
+Puedes ejecutar el servidor directamente usando `npx` sin necesidad de instalación global:
+
+```bash
+npx @orkesflow/mcp-server
+```
+
+## Configuración en Claude Desktop
+
+Para usar Orkesflow con Claude Desktop, añade la siguiente configuración en tu archivo `claude_desktop_config.json`:
+
+### macOS
+`~/Library/Application Support/Claude/claude_desktop_config.json`
+
+### Windows
+`%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "orkesflow": {
+      "command": "npx",
+      "args": ["-y", "@orkesflow/mcp-server"],
+      "env": {
+        "ORKESFLOW_TOKEN": "TU_TOKEN_DE_ACCESO_AQUÍ",
+        "ORKESFLOW_API_URL": "https://api.orkesflow.com"
+      }
+    }
+  }
+}
+```
+
+## Herramientas Disponibles (Tools)
+
+### `list_tasks`
+Recupera la lista de tareas del usuario.
+
+### `list_boards`
+Lista todos los espacios y tableros a los que tienes acceso.
+
+### `create_task`
+Crea una nueva tarea. Argumentos:
+- `title` (requerido)
+- `boardName` o `boardId` (opcional)
+- `priority` (URGENT, HIGH, MEDIUM, LOW, NONE)
+- `labels` (array de nombres)
+
+### `update_task`
+Actualiza una tarea existente. Permite mover tareas usando `columnName`.
+
+### `add_time_log`
+Registra minutos trabajados en una tarea.
+
+## Desarrollo
+
+Si deseas contribuir o ejecutar el servidor localmente:
+
+1. Clona el repositorio.
+2. Instala dependencias: `pnpm install`.
+3. Compila el proyecto: `pnpm run build`.
+4. Ejecuta: `ORKESFLOW_TOKEN=tu_token node dist/index.js`.
+
+---
+© 2026 Orkesflow Team.

package/dist/index.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const axios_1 = __importDefault(require("axios"));
+const zod_1 = require("zod");
+const ORKESFLOW_TOKEN = process.env.ORKESFLOW_TOKEN;
+const ORKESFLOW_API_URL = process.env.ORKESFLOW_API_URL || "https://api.orkesflow.com";
+if (!ORKESFLOW_TOKEN) {
+    console.error("Error: ORKESFLOW_TOKEN environment variable is required.");
+    process.exit(1);
+}
+const apiClient = axios_1.default.create({
+    baseURL: ORKESFLOW_API_URL,
+    headers: {
+        Authorization: `Bearer ${ORKESFLOW_TOKEN}`,
+        "Content-Type": "application/json",
+    },
+});
+const server = new mcp_js_1.McpServer({
+    name: "@orkesflow/mcp-server",
+    version: "1.0.0",
+});
+function handleApiError(error) {
+    if (axios_1.default.isAxiosError(error)) {
+        const status = error.response?.status;
+        const data = error.response?.data;
+        let message = error.message;
+        if (data && typeof data === 'object') {
+            message = JSON.stringify(data);
+        }
+        if (status === 403) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `API Error 403 Forbidden: The provided token does not have the necessary permissions (e.g., tasks:read) or access to the required Space. Details: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Orkesflow API Error (${status || 'Unknown'}): ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Unexpected Error: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Unknown Error occurred`,
+            },
+        ],
+        isError: true,
+    };
+}
+server.tool("list_tasks", "Retrieve a list of tasks from Orkesflow", {}, async () => {
+    try {
+        const response = await apiClient.get("/api/v1/tasks");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("list_boards", "Retrieve a list of available Boards and Spaces from Orkesflow", {}, async () => {
+    try {
+        const response = await apiClient.get("/api/v1/tasks/boards");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("create_task", "Create a new task in Orkesflow", {
+    title: zod_1.z.string().describe("The title of the task"),
+    spaceId: zod_1.z.string().optional().describe("The ID of the Space where the task should be created"),
+    boardId: zod_1.z.string().optional().describe("The ID of the Board where the task should be created"),
+    boardName: zod_1.z.string().optional().describe("The name of the Board where the task should be created (e.g., 'Tareas de casa')"),
+    description: zod_1.z.string().optional().describe("Detailed description of the task"),
+    priority: zod_1.z.enum(["URGENT", "HIGH", "MEDIUM", "LOW", "NONE"]).optional().describe("Task priority"),
+    type: zod_1.z.string().optional().describe("The name of the task type (e.g., 'Tarea', 'Bug', 'Evento')"),
+    labels: zod_1.z.array(zod_1.z.string()).optional().describe("List of label names to assign")
+}, async (args) => {
+    try {
+        const response = await apiClient.post("/api/v1/tasks", args);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("update_task", "Update an existing task in Orkesflow", {
+    taskId: zod_1.z.string().describe("The ID of the task to update"),
+    title: zod_1.z.string().optional().describe("New title for the task"),
+    description: zod_1.z.string().optional().describe("New description for the task"),
+    priority: zod_1.z.enum(["URGENT", "HIGH", "MEDIUM", "LOW", "NONE"]).optional().describe("New task priority"),
+    type: zod_1.z.string().optional().describe("New task type name"),
+    labels: zod_1.z.array(zod_1.z.string()).optional().describe("New list of labels (replaces existing ones)"),
+    columnId: zod_1.z.string().optional().describe("The ID of the column to move the task to"),
+    boardId: zod_1.z.string().optional().describe("The ID of the board (required if columnId is provided)"),
+    columnName: zod_1.z.string().optional().describe("The name of the column to move the task to"),
+    boardName: zod_1.z.string().optional().describe("The name of the board (used to resolve columnName if boardId is missing)")
+}, async (args) => {
+    try {
+        const { taskId, ...updateData } = args;
+        const response = await apiClient.patch(`/api/v1/tasks/${taskId}`, updateData);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("add_time_log", "Add a time log (cost log) to an existing task", {
+    taskId: zod_1.z.string().describe("The ID of the task to log time for"),
+    durationMinutes: zod_1.z.number().describe("Duration of the time log in minutes"),
+    description: zod_1.z.string().optional().describe("Description of the work performed")
+}, async (args) => {
+    try {
+        const response = await apiClient.post("/api/v1/tasks/" + args.taskId + "/time-log", args);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("Orkesflow MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@orkesflow/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP Server for Orkesflow API",
+  "main": "dist/index.js",
+  "bin": {
+    "orkesflow-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "axios": "^1.15.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "typescript": "^5.7.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import axios from "axios";
+import { z } from "zod";
+
+const ORKESFLOW_TOKEN = process.env.ORKESFLOW_TOKEN;
+const ORKESFLOW_API_URL = process.env.ORKESFLOW_API_URL || "https://api.orkesflow.com";
+
+if (!ORKESFLOW_TOKEN) {
+  console.error("Error: ORKESFLOW_TOKEN environment variable is required.");
+  process.exit(1);
+}
+
+const apiClient = axios.create({
+  baseURL: ORKESFLOW_API_URL,
+  headers: {
+    Authorization: `Bearer ${ORKESFLOW_TOKEN}`,
+    "Content-Type": "application/json",
+  },
+});
+
+const server = new McpServer(
+  {
+    name: "@orkesflow/mcp-server",
+    version: "1.0.0",
+  }
+);
+
+function handleApiError(error: unknown) {
+  if (axios.isAxiosError(error)) {
+    const status = error.response?.status;
+    const data = error.response?.data;
+    
+    let message = error.message;
+    if (data && typeof data === 'object') {
+      message = JSON.stringify(data);
+    }
+    
+    if (status === 403) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `API Error 403 Forbidden: The provided token does not have the necessary permissions (e.g., tasks:read) or access to the required Space. Details: ${message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+    
+    return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Orkesflow API Error (${status || 'Unknown'}): ${message}`,
+          },
+        ],
+        isError: true,
+    };
+  }
+  
+  if (error instanceof Error) {
+    return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Unexpected Error: ${error.message}`,
+          },
+        ],
+        isError: true,
+    };
+  }
+
+  return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Unknown Error occurred`,
+        },
+      ],
+      isError: true,
+  };
+}
+
+server.tool(
+  "list_tasks",
+  "Retrieve a list of tasks from Orkesflow",
+  {},
+  async () => {
+    try {
+      const response = await apiClient.get("/api/v1/tasks");
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(response.data, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      return handleApiError(error);
+    }
+  }
+);
+
+server.tool(
+  "list_boards",
+  "Retrieve a list of available Boards and Spaces from Orkesflow",
+  {},
+  async () => {
+    try {
+      const response = await apiClient.get("/api/v1/tasks/boards");
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(response.data, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      return handleApiError(error);
+    }
+  }
+);
+
+server.tool(
+  "create_task",
+  "Create a new task in Orkesflow",
+  {
+    title: z.string().describe("The title of the task"),
+    spaceId: z.string().optional().describe("The ID of the Space where the task should be created"),
+    boardId: z.string().optional().describe("The ID of the Board where the task should be created"),
+    boardName: z.string().optional().describe("The name of the Board where the task should be created (e.g., 'Tareas de casa')"),
+    description: z.string().optional().describe("Detailed description of the task"),
+    priority: z.enum(["URGENT", "HIGH", "MEDIUM", "LOW", "NONE"]).optional().describe("Task priority"),
+    type: z.string().optional().describe("The name of the task type (e.g., 'Tarea', 'Bug', 'Evento')"),
+    labels: z.array(z.string()).optional().describe("List of label names to assign")
+  },
+  async (args) => {
+    try {
+      const response = await apiClient.post("/api/v1/tasks", args);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(response.data, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      return handleApiError(error);
+    }
+  }
+);
+
+server.tool(
+  "update_task",
+  "Update an existing task in Orkesflow",
+  {
+    taskId: z.string().describe("The ID of the task to update"),
+    title: z.string().optional().describe("New title for the task"),
+    description: z.string().optional().describe("New description for the task"),
+    priority: z.enum(["URGENT", "HIGH", "MEDIUM", "LOW", "NONE"]).optional().describe("New task priority"),
+    type: z.string().optional().describe("New task type name"),
+    labels: z.array(z.string()).optional().describe("New list of labels (replaces existing ones)"),
+    columnId: z.string().optional().describe("The ID of the column to move the task to"),
+    boardId: z.string().optional().describe("The ID of the board (required if columnId is provided)"),
+    columnName: z.string().optional().describe("The name of the column to move the task to"),
+    boardName: z.string().optional().describe("The name of the board (used to resolve columnName if boardId is missing)")
+  },
+  async (args) => {
+    try {
+      const { taskId, ...updateData } = args;
+      const response = await apiClient.patch(`/api/v1/tasks/${taskId}`, updateData);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(response.data, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      return handleApiError(error);
+    }
+  }
+);
+
+server.tool(
+  "add_time_log",
+  "Add a time log (cost log) to an existing task",
+  {
+    taskId: z.string().describe("The ID of the task to log time for"),
+    durationMinutes: z.number().describe("Duration of the time log in minutes"),
+    description: z.string().optional().describe("Description of the work performed")
+  },
+  async (args) => {
+    try {
+      const response = await apiClient.post("/api/v1/tasks/" + args.taskId + "/time-log", args);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(response.data, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      return handleApiError(error);
+    }
+  }
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Orkesflow MCP Server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}