openproject-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cyborgx0x
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# OpenProject MCP Server
+
+Model Context Protocol (MCP) server for OpenProject API integration. Enables AI assistants to interact with OpenProject work packages, projects, and time tracking.
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g openproject-mcp
+```
+
+### Local Installation
+
+```bash
+npm install openproject-mcp
+```
+
+## Configuration
+
+### Get OpenProject API Key
+
+1. Log into your OpenProject instance
+2. Go to **My Account** → **Access tokens**
+3. Create a new API token
+4. Copy the token
+
+### Add to Kiro MCP Config
+
+Add to `.kiro/settings/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "openproject": {
+      "command": "npx",
+      "args": ["-y", "openproject-mcp"],
+      "env": {
+        "OPENPROJECT_URL": "https://your-openproject-instance.com",
+        "OPENPROJECT_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "openproject": {
+      "command": "openproject-mcp",
+      "env": {
+        "OPENPROJECT_URL": "https://your-openproject-instance.com",
+        "OPENPROJECT_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all projects |
+| `get_work_package` | Get work package details by ID |
+| `list_work_packages` | List work packages with filters |
+| `get_children` | Get child work packages of a parent |
+| `list_statuses` | List all available statuses |
+| `list_types` | List all work package types (Feature, Task, Bug, etc.) |
+| `get_user` | Get user information |
+| `create_work_package` | Create a new work package |
+| `update_work_package` | Update an existing work package |
+| `log_time` | Log time entry for a work package |
+| `raw_api_call` | Make a raw API call to any endpoint |
+
+## Usage Examples
+
+### List Children of a Feature
+
+```javascript
+get_children({ parentId: 211 })
+```
+
+### Create a New Task
+
+```javascript
+create_work_package({
+  subject: "Implement token budget management",
+  parentId: 538,
+  assigneeId: 10,
+  startDate: "2026-01-15",
+  dueDate: "2026-01-15"
+})
+```
+
+### List Tasks Assigned to Me
+
+```javascript
+list_work_packages({ assigneeId: "me" })
+```
+
+### Update Work Package Status
+
+```javascript
+update_work_package({
+  id: 123,
+  statusId: 12,  // Status ID from list_statuses
+  estimatedTime: "PT2H"  // 2 hours in ISO 8601 format
+})
+```
+
+### Log Time
+
+```javascript
+log_time({
+  workPackageId: 123,
+  hours: 2.5,
+  comment: "Implemented feature X",
+  spentOn: "2026-01-23"
+})
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENPROJECT_URL` | Yes | Your OpenProject instance URL |
+| `OPENPROJECT_API_KEY` | Yes | API key from OpenProject |
+
+## Requirements
+
+- Node.js >= 18.0.0
+- OpenProject instance with API access
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Links
+
+- [OpenProject API Documentation](https://www.openproject.org/docs/api/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)

package/index.js

@@ -0,0 +1,444 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const BASE_URL = process.env.OPENPROJECT_URL || "https://openproject.cyber.ai.vn";
+const API_KEY = process.env.OPENPROJECT_API_KEY || "";
+
+const server = new Server(
+  { name: "openproject-mcp", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+async function apiRequest(endpoint, method, body) {
+  method = method || "GET";
+  const url = endpoint.startsWith("http") ? endpoint : BASE_URL + endpoint;
+
+  const headers = {
+    "Accept": "application/json",
+    "Content-Type": "application/json",
+  };
+
+  if (API_KEY) {
+    const auth = Buffer.from("apikey:" + API_KEY).toString("base64");
+    headers["Authorization"] = "Basic " + auth;
+  }
+
+  const options = { method: method, headers: headers };
+  if (body && method !== "GET") {
+    options.body = JSON.stringify(body);
+  }
+
+  const response = await fetch(url, options);
+
+  if (!response.ok) {
+    throw new Error("API Error: " + response.status + " " + response.statusText);
+  }
+
+  return response.json();
+}
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "list_projects",
+      description: "List all projects in OpenProject",
+      inputSchema: {
+        type: "object",
+        properties: {
+          pageSize: { type: "number", description: "Number of results per page", default: 20 }
+        }
+      }
+    },
+    {
+      name: "get_work_package",
+      description: "Get a specific work package by ID",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "number", description: "Work package ID" }
+        },
+        required: ["id"]
+      }
+    },
+    {
+      name: "list_work_packages",
+      description: "List work packages with optional filters",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string", description: "Project ID or slug" },
+          parentId: { type: "number", description: "Parent work package ID to list children" },
+          assigneeId: { type: "string", description: "Assignee user ID or 'me'" },
+          status: { type: "string", description: "Status filter" },
+          pageSize: { type: "number", description: "Number of results", default: 100 }
+        }
+      }
+    },
+    {
+      name: "get_children",
+      description: "Get child work packages of a parent",
+      inputSchema: {
+        type: "object",
+        properties: {
+          parentId: { type: "number", description: "Parent work package ID" }
+        },
+        required: ["parentId"]
+      }
+    },
+    {
+      name: "list_statuses",
+      description: "List all available statuses",
+      inputSchema: { type: "object", properties: {} }
+    },
+    {
+      name: "list_types",
+      description: "List all work package types (Feature, Task, Bug, etc.)",
+      inputSchema: { type: "object", properties: {} }
+    },
+    {
+      name: "get_user",
+      description: "Get user information",
+      inputSchema: {
+        type: "object",
+        properties: {
+          userId: { type: "string", description: "User ID or 'me' for current user" }
+        },
+        required: ["userId"]
+      }
+    },
+    {
+      name: "create_work_package",
+      description: "Create a new work package (Task)",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string", description: "Project ID or slug", default: "quan-ly-van-ban-hai-quan" },
+          subject: { type: "string", description: "Work package title/subject" },
+          description: { type: "string", description: "Work package description" },
+          typeId: { type: "number", description: "Type ID (1=Task, 4=Feature, 5=Bug)", default: 1 },
+          parentId: { type: "number", description: "Parent work package ID" },
+          assigneeId: { type: "number", description: "Assignee user ID" },
+          versionId: { type: "number", description: "Sprint/Version ID (22=Sprint 9, 23=Sprint 10)" },
+          startDate: { type: "string", description: "Start date (YYYY-MM-DD)" },
+          dueDate: { type: "string", description: "Due date (YYYY-MM-DD)" }
+        },
+        required: ["subject"]
+      }
+    },
+    {
+      name: "update_work_package",
+      description: "Update an existing work package",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "number", description: "Work package ID" },
+          subject: { type: "string", description: "New subject" },
+          description: { type: "string", description: "New description" },
+          statusId: { type: "number", description: "New status ID" },
+          assigneeId: { type: "number", description: "New assignee ID" },
+          versionId: { type: "number", description: "Sprint/Version ID (22=Sprint 9, 23=Sprint 10)" },
+          estimatedTime: { type: "string", description: "Estimated time in ISO 8601 duration format (e.g., PT2H for 2 hours, PT30M for 30 minutes)" }
+        },
+        required: ["id"]
+      }
+    },
+    {
+      name: "log_time",
+      description: "Log time entry for a work package",
+      inputSchema: {
+        type: "object",
+        properties: {
+          workPackageId: { type: "number", description: "Work package ID" },
+          hours: { type: "number", description: "Hours spent (e.g., 2 for 2 hours, 0.5 for 30 minutes)" },
+          comment: { type: "string", description: "Comment for the time entry" },
+          spentOn: { type: "string", description: "Date spent (YYYY-MM-DD), defaults to today" },
+          activityId: { type: "number", description: "Activity type ID (1=Development)", default: 1 }
+        },
+        required: ["workPackageId", "hours"]
+      }
+    },
+    {
+      name: "raw_api_call",
+      description: "Make a raw API call to any OpenProject endpoint",
+      inputSchema: {
+        type: "object",
+        properties: {
+          endpoint: { type: "string", description: "API endpoint (e.g., /api/v3/work_packages)" },
+          method: { type: "string", description: "HTTP method", default: "GET" },
+          body: { type: "object", description: "Request body for POST/PATCH" }
+        },
+        required: ["endpoint"]
+      }
+    }
+  ]
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    let result;
+
+    switch (name) {
+      case "list_projects": {
+        const pageSize = args.pageSize || 20;
+        result = await apiRequest("/api/v3/projects?pageSize=" + pageSize);
+        if (result._embedded && result._embedded.elements) {
+          result = result._embedded.elements.map(function(p) {
+            return {
+              id: p.id,
+              name: p.name,
+              identifier: p.identifier,
+              status: p.status
+            };
+          });
+        }
+        break;
+      }
+
+      case "get_work_package": {
+        result = await apiRequest("/api/v3/work_packages/" + args.id);
+        var parentHref = result._links && result._links.parent && result._links.parent.href;
+        result = {
+          id: result.id,
+          subject: result.subject,
+          description: result.des,
+          description: result.description?.raw,
+          status: result._links?.status?.title,
+          type: result._links?.type?.title,
+          assignee: result._links?.assignee?.title,
+          parent: result._links?.parent?.title,
+          parentId: result._linksDate,
+          dueDate: result.dueDate,
+          percentageDone: result.percentageDone
+        };
+        break;
+      }
+
+      case "list_work_packages": {
+        var filters = [];
+        if (args.parentId) {
+          filters.push({ parent: { operator: "=", values: [String(args.parentId)] } });
+        }
+        if (args.assigneeId) {
+          filters.push({ assignee: { operator: "=", values: [args.assigneeId] } });
+        }
+        if (args.status) {
+          filters.push({ status: { operator: "=", values: [args.status] } });
+        }
+
+        var endpoint = "/api/v3/work_packages";
+        if (args.projectId) {
+          endpoint = "/api/v3/projects/" + args.projectId + "/work_packages";
+        }
+
+        var params = new URLSearchParams();
+        params.set("pageSize", String(args.pageSize || 100));
+        if (filters.length > 0) {
+          params.set("filters", JSON.stringify(filters));
+        }
+
+        result = await apiRequest(endpoint + "?" + params.toString());
+        if (result._embedded && result._embedded.elements) {
+          result = result._embedded.elements.map(function(wp) {
+            var wpParentHref = wp._links && wp._links.parent && wp._links.parent.href;
+            return {
+              id: wp.id,
+              subject: wp.subject,
+              status: wp._links && wp._links.status ? wp._links.status.title : null,
+              type: wp._links && wp._links.type ? wp._links.type.title : null,
+              assignee: wp._links && wp._links.assignee ? wp._links.assignee.title : null,
+              parentId: wpParentHref ? wpParentHref.split("/").pop() : null
+            };
+          });
+        }
+        break;
+      }
+
+      case "get_children": {
+        var childFilters = [{ parent: { operator: "=", values: [String(args.parentId)] } }];
+        var childParams = new URLSearchParams();
+        childParams.set("pageSize", "100");
+        childParams.set("filters", JSON.stringify(childFilters));
+
+        result = await apiRequest("/api/v3/work_packages?" + childParams.toString());
+        if (result._embedded && result._embedded.elements) {
+          result = result._embedded.elements.map(function(wp) {
+            return {
+              id: wp.id,
+              subject: wp.subject,
+              status: wp._links && wp._links.status ? wp._links.status.title : null,
+              type: wp._links && wp._links.type ? wp._links.type.title : null,
+              assignee: wp._links && wp._links.assignee ? wp._links.assignee.title : null
+            };
+          });
+        }
+        break;
+      }
+
+      case "list_statuses": {
+        result = await apiRequest("/api/v3/statuses");
+        if (result._embedded && result._embedded.elements) {
+          result = result._embedded.elements.map(function(s) {
+            return {
+              id: s.id,
+              name: s.name,
+              isClosed: s.isClosed,
+              isDefault: s.isDefault
+            };
+          });
+        }
+        break;
+      }
+
+      case "list_types": {
+        result = await apiRequest("/api/v3/types");
+        if (result._embedded && result._embedded.elements) {
+          result = result._embedded.elements.map(function(t) {
+            return {
+              id: t.id,
+              name: t.name,
+              color: t.color
+            };
+          });
+        }
+        break;
+      }
+
+      case "get_user": {
+        var userId = args.userId === "me" ? "me" : args.userId;
+        result = await apiRequest("/api/v3/users/" + userId);
+        result = {
+          id: result.id,
+          name: result.name,
+          login: result.login,
+          email: result.email,
+          status: result.status
+        };
+        break;
+      }
+
+      case "create_work_package": {
+        var projectId = args.projectId || "quan-ly-van-ban-hai-quan";
+        var createBody = {
+          subject: args.subject,
+          _links: {
+            type: { href: "/api/v3/types/" + (args.typeId || 1) }
+          }
+        };
+
+        if (args.description) {
+          createBody.description = { format: "markdown", raw: args.description };
+        }
+        if (args.parentId) {
+          createBody._links.parent = { href: "/api/v3/work_packages/" + args.parentId };
+        }
+        if (args.assigneeId) {
+          createBody._links.assignee = { href: "/api/v3/users/" + args.assigneeId };
+        }
+        if (args.versionId) {
+          createBody._links.version = { href: "/api/v3/versions/" + args.versionId };
+        }
+        if (args.startDate) {
+          createBody.startDate = args.startDate;
+        }
+        if (args.dueDate) {
+          createBody.dueDate = args.dueDate;
+        }
+
+        result = await apiRequest("/api/v3/projects/" + projectId + "/work_packages", "POST", createBody);
+        result = {
+          id: result.id,
+          subject: result.subject,
+          status: result._links && result._links.status ? result._links.status.title : null,
+          type: result._links && result._links.type ? result._links.type.title : null,
+          version: result._links && result._links.version ? result._links.version.title : null
+        };
+        break;
+      }
+
+      case "update_work_package": {
+        var current = await apiRequest("/api/v3/work_packages/" + args.id);
+
+        var updateBody = {
+          lockVersion: current.lockVersion
+        };
+
+        if (args.subject) updateBody.subject = args.subject;
+        if (args.description) updateBody.description = { format: "markdown", raw: args.description };
+        if (args.estimatedTime) updateBody.estimatedTime = args.estimatedTime;
+        if (args.statusId || args.assigneeId || args.versionId) {
+          updateBody._links = {};
+          if (args.statusId) {
+            updateBody._links.status = { href: "/api/v3/statuses/" + args.statusId };
+          }
+          if (args.assigneeId) {
+            updateBody._links.assignee = { href: "/api/v3/users/" + args.assigneeId };
+          }
+          if (args.versionId) {
+            updateBody._links.version = { href: "/api/v3/versions/" + args.versionId };
+          }
+        }
+
+        result = await apiRequest("/api/v3/work_packages/" + args.id, "PATCH", updateBody);
+        result = {
+          id: result.id,
+          subject: result.subject,
+          status: result._links && result._links.status ? result._links.status.title : null,
+          version: result._links && result._links.version ? result._links.version.title : null,
+          estimatedTime: result.estimatedTime
+        };
+        break;
+      }
+
+      case "log_time": {
+        var today = new Date().toISOString().split('T')[0];
+        var timeBody = {
+          _links: {
+            workPackage: { href: "/api/v3/work_packages/" + args.workPackageId },
+            activity: { href: "/api/v3/time_entries/activities/" + (args.activityId || 1) }
+          },
+          hours: "PT" + args.hours + "H",
+          spentOn: args.spentOn || today,
+          comment: { format: "plain", raw: args.comment || "" }
+        };
+
+        result = await apiRequest("/api/v3/time_entries", "POST", timeBody);
+        result = {
+          id: result.id,
+          hours: result.hours,
+          spentOn: result.spentOn,
+          workPackageId: args.workPackageId,
+          comment: result.comment?.raw
+        };
+        break;
+      }
+
+      case "raw_api_call": {
+        result = await apiRequest(args.endpoint, args.method || "GET", args.body);
+        break;
+      }
+
+      default:
+        throw new Error("Unknown tool: " + name);
+    }
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: "Error: " + error.message }],
+      isError: true
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "openproject-mcp",
+    "version": "1.0.0",
+    "description": "MCP server for OpenProject API integration",
+    "type": "module",
+    "main": "index.js",
+    "bin": {
+        "openproject-mcp": "index.js"
+    },
+    "scripts": {
+        "start": "node index.js"
+    },
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "openproject",
+        "project-management",
+        "api",
+        "mcp-server"
+    ],
+    "author": "cyborgx0x <leeboykt@gmail.com>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/cyborgx0x/mcp-openproject.git"
+    },
+    "bugs": {
+        "url": "https://github.com/cyborgx0x/mcp-openproject/issues"
+    },
+    "homepage": "https://github.com/cyborgx0x/mcp-openproject#readme",
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.0.0"
+    },
+    "files": [
+        "index.js",
+        "README.md",
+        "LICENSE"
+    ]
+}