diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index dec1d58..d80b06a 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -1,12 +1,9 @@ -name: NPM Package Release +name: NPM + Github Release on: - workflow_dispatch: - inputs: - version: - description: "Version number (e.g., 0.1.0)" - required: true - type: string + push: + branches: + - main permissions: contents: write @@ -43,11 +40,15 @@ jobs: env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + - name: get-npm-version + id: package-version + uses: martinbeentjes/npm-get-version-action@v1.3.1 + - name: Create GitHub Release uses: softprops/action-gh-release@v1 with: - tag_name: v${{ github.event.inputs.version }} - name: v${{ github.event.inputs.version }} + tag_name: v${{ steps.package-version.outputs.current-version }} + name: v${{ steps.package-version.outputs.current-version }} draft: false prerelease: false generate_release_notes: true diff --git a/README.md b/README.md index b8ccb59..d179613 100644 --- a/README.md +++ b/README.md @@ -1,280 +1,343 @@ # Plane MCP Server -The Plane MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with Plane APIs, enabling projects, work items, and automations capabilities for develops and AI interfaces. +The Plane MCP Server brings the power of Model Context Protocol (MCP) to Plane, allowing AI agents and developer tools to interact programmatically with your Plane workspace. -## Use Cases +Whether you're building intelligent assistants, automation scripts, or workflow-driven tools, this server provides a seamless bridge to Plane’s API—so you can create projects, manage issues, assign tasks, and keep your work in sync with AI-powered tools. -- Create, update Projects and Work items -- Assign People, Properties, and Write Comments to progress on the Work -- Move and observe with various Work items in States -- Add Labels to the Work items -- Extracting and analyzing data from Projects and Members inside Plane -- Building AI powered tools and applications that interact with Plane's ecosystem +## What can you do with it? +This server unlocks all sorts of useful capabilities for anyone working with Plane: -## Configuration Parameters +- Spin up projects and work items directly from your AI or app interface. + +- Update progress, assign team members, set properties, or add comments—all programmatically. + +- Move issues through workflows and update their states on the fly. + +- Organize work with labels, modules, and cycles. + +- Analyze data about your team’s work across projects. + +- Build smart apps that interact naturally with Plane—whether it’s an AI agent logging work, or a bot keeping projects tidy. -1. `PLANE_API_KEY` - The user's API token. This can be obtained from the `/settings/api-tokens/` page in the UI. -2. `PLANE_WORKSPACE_SLUG` - The workspace slug for your Plane instance. -3. `PLANE_API_HOST_URL` (optional) - The host URL of the Plane API Server. Defaults to https://api.plane.so/ ## Tools ### Users -- `get_user` - Get the current user's information +- `get_user` + - Get the current user's information - No parameters required ### Projects -- `get_projects` - Get all projects for the current user - +- `get_projects` + - Get all projects for the current user - No parameters required -- `create_project` - Create a new project - - `name`: Project name (string, required) +- `create_project` + - Create a new project + - Parameters: + - `name` (string, required): Project name ### Issue Types -- `list_issue_types` - Get all issue types for a specific project - - - `project_id`: UUID of the project (string, required) - -- `get_issue_type` - Get details of a specific issue type - - - `project_id`: UUID of the project (string, required) - - `type_id`: UUID of the issue type (string, required) - -- `create_issue_type` - Create a new issue type in a project - - - `project_id`: UUID of the project (string, required) - - `issue_type_data`: Object containing: - - `name`: Name of the issue type (string, required) - - `description`: Description of the issue type (string, required) - -- `update_issue_type` - Update an existing issue type - - - `project_id`: UUID of the project (string, required) - - `type_id`: UUID of the issue type (string, required) - - `issue_type_data`: Fields to update on the issue type (object) - -- `delete_issue_type` - Delete an issue type - - `project_id`: UUID of the project (string, required) - - `type_id`: UUID of the issue type (string, required) +- `list_issue_types` + - Get all issue types for a specific project + - Parameters: + - `project_id` (string, required): UUID of the project + +- `get_issue_type` + - Get details of a specific issue type + - Parameters: + - `project_id` (string, required): UUID of the project + - `type_id` (string, required): UUID of the issue type + +- `create_issue_type` + - Create a new issue type in a project + - Parameters: + - `project_id` (string, required): UUID of the project + - `issue_type_data`: Object containing: + - `name` (string, required): Name of the issue type + - `description` (string, required): Description of the issue type + +- `update_issue_type` + - Update an existing issue type + - Parameters: + - `project_id` (string, required): UUID of the project + - `type_id` (string, required): UUID of the issue type + - `issue_type_data` (object): Fields to update on the issue type + +- `delete_issue_type` + - Delete an issue type + - Parameters: + - `project_id` (string, required): UUID of the project + - `type_id` (string, required): UUID of the issue type ### States -- `list_states` - Get all states for a specific project - - - `project_id`: UUID of the project (string, required) - -- `get_state` - Get details of a specific state - - - `project_id`: UUID of the project (string, required) - - `state_id`: UUID of the state (string, required) - -- `create_state` - Create a new state in a project - - - `project_id`: UUID of the project (string, required) - - `state_data`: Object containing: - - `name`: Name of the state (string, required) - - `color`: Color code for the state (string, required) - -- `update_state` - Update an existing state - - - `project_id`: UUID of the project (string, required) - - `state_id`: UUID of the state (string, required) - - `state_data`: Fields to update on the state (object) - -- `delete_state` - Delete a state - - `project_id`: UUID of the project (string, required) - - `state_id`: UUID of the state (string, required) +- `list_states` + - Get all states for a specific project + - Parameters: + - `project_id` (string, required): UUID of the project + +- `get_state` + - Get details of a specific state + - Parameters: + - `project_id` (string, required): UUID of the project + - `state_id` (string, required): UUID of the state + +- `create_state` + - Create a new state in a project + - Parameters: + - `project_id` (string, required): UUID of the project + - `state_data`: Object containing: + - `name` (string, required): Name of the state + - `color` (string, required): Color code for the state + +- `update_state` + - Update an existing state + - Parameters: + - `project_id` (string, required): UUID of the project + - `state_id` (string, required): UUID of the state + - `state_data` (object): Fields to update on the state + +- `delete_state` + - Delete a state + - Parameters: + - `project_id` (string, required): UUID of the project + - `state_id` (string, required): UUID of the state ### Labels -- `list_labels` - Get all labels for a specific project - - - `project_id`: UUID of the project (string, required) - -- `get_label` - Get details of a specific label - - - `project_id`: UUID of the project (string, required) - - `label_id`: UUID of the label (string, required) - -- `create_label` - Create a new label in a project - - - `project_id`: UUID of the project (string, required) - - `label_data`: Object containing: - - `name`: Name of the label (string, required) - - `color`: Color code for the label (string, required) - -- `update_label` - Update an existing label - - - `project_id`: UUID of the project (string, required) - - `label_id`: UUID of the label (string, required) - - `label_data`: Fields to update on the label (object) - -- `delete_label` - Delete a label - - `project_id`: UUID of the project (string, required) - - `label_id`: UUID of the label (string, required) +- `list_labels` + - Get all labels for a specific project + - Parameters: + - `project_id` (string, required): UUID of the project + +- `get_label` + - Get details of a specific label + - Parameters: + - `project_id` (string, required): UUID of the project + - `label_id` (string, required): UUID of the label + +- `create_label` + - Create a new label in a project + - Parameters: + - `project_id` (string, required): UUID of the project + - `label_data`: Object containing: + - `name` (string, required): Name of the label + - `color` (string, required): Color code for the label + +- `update_label` + - Update an existing label + - Parameters: + - `project_id` (string, required): UUID of the project + - `label_id` (string, required): UUID of the label + - `label_data` (object): Fields to update on the label + +- `delete_label` + - Delete a label + - Parameters: + - `project_id` (string, required): UUID of the project + - `label_id` (string, required): UUID of the label ### Issues -- `get_issue_using_readable_identifier` - Get issue details using readable identifier (e.g., PROJ-123) - - - `project_identifier`: Project identifier (e.g., "PROJ") (string, required) - - `issue_identifier`: Issue number (e.g., "123") (string, required) - -- `get_issue_comments` - Get all comments for a specific issue - - - `project_id`: UUID of the project (string, required) - - `issue_id`: UUID of the issue (string, required) - -- `add_issue_comment` - Add a comment to an issue - - - `project_id`: UUID of the project (string, required) - - `issue_id`: UUID of the issue (string, required) - - `comment_html`: HTML content of the comment (string, required) - -- `create_issue` - Create a new issue - - - `project_id`: UUID of the project (string, required) - - `issue_data`: Object containing: - - `name`: Title of the issue (string, required) - - `description_html`: HTML description of the issue (string, required) - -- `update_issue` - Update an existing issue - - `project_id`: UUID of the project (string, required) - - `issue_id`: UUID of the issue (string, required) - - `issue_data`: Fields to update on the issue (object) +- `get_issue_using_readable_identifier` + - Get issue details using readable identifier (e.g., PROJ-123) + - Parameters: + - `project_identifier` (string, required) + - `issue_identifier` (string, required): Issue numbe: Project identifier (e.g., "PROJ") r (e.g., "123") + +- `get_issue_comments` + - Get all comments for a specific issue + - Parameters: + - `project_id` (string, required): UUID of the project + - `issue_id` (string, required): UUID of the issue + +- `add_issue_comment` + - Add a comment to an issue + - Parameters: + - `project_id` (string, required): UUID of the project + - `issue_id` (string, required): UUID of the issue + - `comment_html` (string, required): HTML content of the comment + +- `create_issue` + - Create a new issue + - Parameters: + - `project_id` (string, required): UUID of the project + - `issue_data`: Object containing: + - `name` (string, required): Title of the issue + - `description_html` (string, required): HTML description of the issue + +- `update_issue` + - Update an existing issue + - Parameters: + - `project_id` (string, required): UUID of the project + - `issue_id` (string, required): UUID of the issue + - `issue_data` (object): Fields to update on the issue ### Modules -- `list_modules` - Get all modules for a specific project - - - `project_id`: UUID of the project (string, required) - -- `get_module` - Get details of a specific module - - - `project_id`: UUID of the project (string, required) - - `module_id`: UUID of the module (string, required) - -- `create_module` - Create a new module in a project - - - `project_id`: UUID of the project (string, required) - - `module_data`: Object containing: - - `name`: Name of the module (string, required) - -- `update_module` - Update an existing module - - - `project_id`: UUID of the project (string, required) - - `module_id`: UUID of the module (string, required) - - `module_data`: Fields to update on the module (object) - -- `delete_module` - Delete a module - - `project_id`: UUID of the project (string, required) - - `module_id`: UUID of the module (string, required) +- `list_modules` + - Get all modules for a specific project + - Parameters: + - `project_id` (string, required): UUID of the project + +- `get_module` + - Get details of a specific module + - Parameters: + - `project_id` (string, required): UUID of the project + - `module_id` (string, required): UUID of the module + +- `create_module` + - Create a new module in a project + - Parameters: + - `project_id` (string, required): UUID of the project + - `module_data`: Object containing: + - `name` (string, required): Name of the module + +- `update_module` + - Update an existing module + - Parameters: + - `project_id` (string, required): UUID of the project + - `module_id` (string, required): UUID of the module + - `module_data` (object): Fields to update on the module + +- `delete_module` + - Delete a module + - Parameters: + - `project_id` (string, required): UUID of the project + - `module_id` (string, required): UUID of the module ### Module Issues -- `list_module_issues` - Get all issues for a specific module - - - `project_id`: UUID of the project (string, required) - - `module_id`: UUID of the module (string, required) - -- `add_module_issues` - Add issues to a module - - - `project_id`: UUID of the project (string, required) - - `module_id`: UUID of the module (string, required) - - `issues`: Array of issue UUIDs to add (string[], required) - -- `delete_module_issue` - Remove an issue from a module - - `project_id`: UUID of the project (string, required) - - `module_id`: UUID of the module (string, required) - - `issue_id`: UUID of the issue to remove (string, required) +- `list_module_issues` + - Get all issues for a specific module + - Parameters: + - `project_id` (string, required): UUID of the project + - `module_id` (string, required): UUID of the module + +- `add_module_issues` + - Add issues to a module + - Parameters: + - `project_id` (string, required): UUID of the project + - `module_id` (string, required): UUID of the module + - `issues` (string[], required): Array of issue UUIDs to add + +- `delete_module_issue` + - Remove an issue from a module + - Parameters: + - `project_id` (string, required): UUID of the project + - `module_id` (string, required): UUID of the module + - `issue_id` (string, required): UUID of the issue to remove ### Cycles -- `list_cycles` - Get all cycles for a specific project - - - `project_id`: UUID of the project (string, required) - -- `get_cycle` - Get details of a specific cycle - - - `project_id`: UUID of the project (string, required) - - `cycle_id`: UUID of the cycle (string, required) - -- `create_cycle` - Create a new cycle in a project - - - `project_id`: UUID of the project (string, required) - - `cycle_data`: Object containing: - - `name`: Name of the cycle (string, required) - - `start_date`: Start date (YYYY-MM-DD) (string, required) - - `end_date`: End date (YYYY-MM-DD) (string, required) - -- `update_cycle` - Update an existing cycle - - - `project_id`: UUID of the project (string, required) - - `cycle_id`: UUID of the cycle (string, required) - - `cycle_data`: Fields to update on the cycle (object) - -- `delete_cycle` - Delete a cycle - - `project_id`: UUID of the project (string, required) - - `cycle_id`: UUID of the cycle (string, required) +- `list_cycles` + - Get all cycles for a specific project + - Parameters: + - `project_id` (string, required): UUID of the project + +- `get_cycle` + - Get details of a specific cycle + - Parameters: + - `project_id` (string, required): UUID of the project + - `cycle_id` (string, required): UUID of the cycle + +- `create_cycle` + - Create a new cycle in a project + - Parameters: + - `project_id` (string, required): UUID of the project + - `cycle_data`: Object containing: + - `name` (string, required): Name of the cycle + - `start_date` (string, required): Start date (YYYY-MM-DD) + - `end_date` (string, required) +: End date (YYYY-MM-DD) +- `update_cycle` + - Update an existing cycle + - Parameters: + - `project_id` (string, required): UUID of the project + - `cycle_id` (string, required): UUID of the cycle + - `cycle_data` (object): Fields to update on the cycle + +- `delete_cycle` + - Delete a cycle + - Parameters: + - `project_id` (string, required): UUID of the project + - `cycle_id` (string, required): UUID of the cycle ### Cycle Issues -- `list_cycle_issues` - Get all issues for a specific cycle - - - `project_id`: UUID of the project (string, required) - - `cycle_id`: UUID of the cycle (string, required) - -- `add_cycle_issues` - Add issues to a cycle - - - `project_id`: UUID of the project (string, required) - - `cycle_id`: UUID of the cycle (string, required) - - `issues`: Array of issue UUIDs to add (string[], required) - -- `delete_cycle_issue` - Remove an issue from a cycle - - `project_id`: UUID of the project (string, required) - - `cycle_id`: UUID of the cycle (string, required) - - `issue_id`: UUID of the issue to remove (string, required) +- `list_cycle_issues` + - Get all issues for a specific cycle + - Parameters: + - `project_id` (string, required): UUID of the project + - `cycle_id` (string, required): UUID of the cycle + +- `add_cycle_issues` + - Add issues to a cycle + - Parameters: + - `project_id` (string, required): UUID of the project + - `cycle_id` (string, required): UUID of the cycle + - `issues` (string[], required): Array of issue UUIDs to add + +- `delete_cycle_issue` + - Remove an issue from a cycle + - Parameters: + - `project_id` (string, required): UUID of the project + - `cycle_id` (string, required): UUID of the cycle + - `issue_id` (string, required): UUID of the issue to remove ### Work Logs -- `get_issue_worklogs` - Get all worklogs for a specific issue - - - `project_id`: UUID of the project (string, required) - - `issue_id`: UUID of the issue (string, required) - -- `get_total_worklogs` - Get total logged time for a project +- `get_issue_worklogs` + - Get all worklogs for a specific issue + - Parameters: + - `project_id` (string, required): UUID of the project + - `issue_id` (string, required): UUID of the issue + +- `get_total_worklogs` + - Get total logged time for a project + - Parameters: + - `project_id` (string, required): UUID of the project + +- `create_worklog` + - Create a new worklog for an issue + - Parameters: + - `project_id` (string, required): UUID of the project + - `issue_id` (string, required): UUID of the issue + - `worklog_data`: Object containing: + - `description` (string, required): Description of the work done + - `duration` (integer, required): Duration in minutes + +- `update_worklog` + - Update an existing worklog + - Parameters: + - `project_id` (string, required): UUID of the project + - `issue_id` (string, required): UUID of the issue + - `worklog_id` (string, required): UUID of the worklog + - `worklog_data` (object): Fields to update on the worklog + +- `delete_worklog` + - Delete a worklog + - Parameters: + - `project_id` (string, required): UUID of the project + - `issue_id` (string, required): UUID of the issue + - `worklog_id` (string, required): UUID of the worklog - - `project_id`: UUID of the project (string, required) -- `create_worklog` - Create a new worklog for an issue - - - `project_id`: UUID of the project (string, required) - - `issue_id`: UUID of the issue (string, required) - - `worklog_data`: Object containing: - - `description`: Description of the work done (string, required) - - `duration`: Duration in minutes (integer, required) - -- `update_worklog` - Update an existing worklog - - - `project_id`: UUID of the project (string, required) - - `issue_id`: UUID of the issue (string, required) - - `worklog_id`: UUID of the worklog (string, required) - - `worklog_data`: Fields to update on the worklog (object) +## Configuration Parameters -- `delete_worklog` - Delete a worklog - - `project_id`: UUID of the project (string, required) - - `issue_id`: UUID of the issue (string, required) - - `worklog_id`: UUID of the worklog (string, required) +- `PLANE_API_KEY` - Your Plane API token. You can generate one from the Workspace Settings > API Tokens page (`/settings/api-tokens/`) in the Plane app. +- `PLANE_WORKSPACE_SLUG` - The workspace slug for your Plane instance. The workspace-slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. +- `PLANE_API_HOST_URL` (optional) - The host URL of the Plane API Server. Defaults to https://api.plane.so/ ## Usage ### Claude Desktop -Add Plane to [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) by editing your `claude_desktop_config.json`. +You can add Plane to [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) by updating your `claude_desktop_config.json`: ```json { @@ -287,7 +350,7 @@ Add Plane to [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) b ], "env": { "PLANE_API_KEY": "", - "PLANE_API_HOST_URL": "", "PLANE_WORKSPACE_SLUG": "" } } @@ -297,7 +360,7 @@ Add Plane to [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) b ### VSCode -Add Plane to [VSCode](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) by editing your `.vscode.json/mcp.json`. +You can also connect Plane to [VSCode](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) by editing your `.vscode.json` or `mcp.json` file: ```json { @@ -310,7 +373,7 @@ Add Plane to [VSCode](https://code.visualstudio.com/docs/copilot/chat/mcp-server ], "env": { "PLANE_API_KEY": "", - "PLANE_API_HOST_URL": "", "PLANE_WORKSPACE_SLUG": "" } } @@ -321,4 +384,4 @@ Add Plane to [VSCode](https://code.visualstudio.com/docs/copilot/chat/mcp-server ## License -This project is licensed under the terms of the MIT open source license. +This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository. \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index cce999b..387777c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,17 +1,17 @@ { "name": "@makeplane/plane-mcp-server", - "version": "0.1.4", + "version": "0.1.5", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@makeplane/plane-mcp-server", - "version": "0.1.4", + "version": "0.1.5", "license": "MIT", "dependencies": { "@modelcontextprotocol/sdk": "^1.9.0", "@scarf/scarf": "^1.4.0", - "axios": "^1.8.4", + "axios": "1.12.0", "zod-to-json-schema": "^3.24.5" }, "bin": { @@ -870,13 +870,13 @@ "license": "MIT" }, "node_modules/axios": { - "version": "1.8.4", - "resolved": "https://registry.npmjs.org/axios/-/axios-1.8.4.tgz", - "integrity": "sha512-eBSYY4Y68NNlHbHBMdeDmKNtDgXWhQsJcGqzO3iLUM0GraQFSS9cVgPX5I9b3lbdFKyYoAEGAZF1DwhTaljNAw==", + "version": "1.12.0", + "resolved": "https://registry.npmjs.org/axios/-/axios-1.12.0.tgz", + "integrity": "sha512-oXTDccv8PcfjZmPGlWsPSwtOJCZ/b6W5jAMCNcfwJbCzDckwG0jrYJFaWH1yvivfCXjVzV/SPDEhMB3Q+DSurg==", "license": "MIT", "dependencies": { "follow-redirects": "^1.15.6", - "form-data": "^4.0.0", + "form-data": "^4.0.4", "proxy-from-env": "^1.1.0" } }, @@ -1702,14 +1702,15 @@ } }, "node_modules/form-data": { - "version": "4.0.2", - "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.2.tgz", - "integrity": "sha512-hGfm/slu0ZabnNt4oaRZ6uREyfCj6P4fT/n6A1rGV+Z0VdGXjfOhVUpkn6qVQONHGIFwmveGXyDs75+nr6FM8w==", + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.4.tgz", + "integrity": "sha512-KrGhL9Q4zjj0kiUt5OO4Mr/A/jlI2jDYs5eHBpYHPcBEVSiipAvn2Ko2HnPe20rmcuuvMHNdZFp+4IlGTMF0Ow==", "license": "MIT", "dependencies": { "asynckit": "^0.4.0", "combined-stream": "^1.0.8", "es-set-tostringtag": "^2.1.0", + "hasown": "^2.0.2", "mime-types": "^2.1.12" }, "engines": { diff --git a/package.json b/package.json index 9d71bd9..b826731 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@makeplane/plane-mcp-server", - "version": "0.1.4", + "version": "0.1.5", "description": "The Plane MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with Plane APIs, enabling projects, work items, and automations capabilities for develops and AI interfaces.", "bin": { "plane-mcp-server": "./build/index.js" @@ -33,7 +33,7 @@ "dependencies": { "@modelcontextprotocol/sdk": "^1.9.0", "@scarf/scarf": "^1.4.0", - "axios": "^1.8.4", + "axios": "1.12.0", "zod-to-json-schema": "^3.24.5" }, "devDependencies": { diff --git a/src/common/request-helper.ts b/src/common/request-helper.ts index b6ddc21..3e2f488 100644 --- a/src/common/request-helper.ts +++ b/src/common/request-helper.ts @@ -9,7 +9,7 @@ export async function makePlaneRequest(method: string, path: string, body: an }; // Only add Content-Type for non-GET requests - if (method.toUpperCase() !== 'GET') { + if (method.toUpperCase() !== "GET") { headers["Content-Type"] = "application/json"; } @@ -21,7 +21,7 @@ export async function makePlaneRequest(method: string, path: string, body: an }; // Only include body for non-GET requests - if (method.toUpperCase() !== 'GET' && body !== null) { + if (method.toUpperCase() !== "GET" && body !== null) { config.data = body; } diff --git a/src/tools/issues.ts b/src/tools/issues.ts index 6c413a0..c5d4f21 100644 --- a/src/tools/issues.ts +++ b/src/tools/issues.ts @@ -2,15 +2,109 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { z } from "zod"; import { makePlaneRequest } from "../common/request-helper.js"; -import { Issue as IssueSchema } from "../schemas.js"; +import { type Issue, Issue as IssueSchema } from "../schemas.js"; + +type IssueStateSummary = { + id: string; + name?: string; + color?: string; + group?: string; +}; + +type IssuePrioritySummary = { + id?: string; + label?: string; + name?: string; + key?: string; +}; + +type IssueWithDetails = Issue & { + state_detail?: IssueStateSummary | null; + priority_detail?: IssuePrioritySummary | null; +}; + +type IssuesResponse = { + grouped_by: null; + sub_grouped_by: null; + total_count: number; + next_cursor: string; + prev_cursor: string; + next_page_results: boolean; + prev_page_results: boolean; + count: number; + total_pages: number; + total_results: number; + extra_stats: null; + results: IssueWithDetails[]; +}; + +export const registerIssueTools = (server: McpServer): void => { + server.tool( + "list_project_issues", + "Get all issues for a specific project. This requests project_id as uuid parameter. If you have a readable identifier for project, you can use the get_projects tool to get the project_id from it", + { + project_id: z.string().describe("The uuid identifier of the project to get issues for"), + }, + async ({ project_id }) => { + const issuesResponse: IssuesResponse = await makePlaneRequest( + "GET", + `workspaces/${process.env.PLANE_WORKSPACE_SLUG}/projects/${project_id}/issues/` + ); + + // Return only essential fields to reduce token usage and improve LLM processing + const simplifiedIssues = issuesResponse.results.map((issue) => { + const stateDetail = issue.state_detail ?? null; + const priorityDetail = + issue.priority_detail ?? + (typeof issue.priority === "object" && issue.priority !== null + ? (issue.priority as IssuePrioritySummary) + : null); + + return { + id: issue.id, + name: issue.name, + sequence_id: issue.sequence_id, + state: { + id: issue.state ?? stateDetail?.id ?? null, + name: stateDetail?.name ?? null, + color: stateDetail?.color ?? null, + group: stateDetail?.group ?? null, + }, + priority: { + id: typeof issue.priority === "string" ? issue.priority : (priorityDetail?.id ?? null), + label: priorityDetail?.label ?? priorityDetail?.name ?? null, + key: priorityDetail?.key ?? null, + }, + created_at: issue.created_at, + updated_at: issue.updated_at, + }; + }); + + return { + content: [ + { + type: "text", + text: JSON.stringify( + { + total_count: issuesResponse.total_count, + count: issuesResponse.count, + results: simplifiedIssues, + }, + null, + 2 + ), + }, + ], + }; + } + ); -export const registerIssueTools = (server: McpServer) => { server.tool( "get_issue_using_readable_identifier", - "Get all issues for a specific project. When issue identifier is provided something like FIRST-123, ABC-123, etc. For FIRST-123, project_identifier is FIRST and issue_identifier is 123", + "Get a specific issue using its readable identifier. When issue identifier is provided something like FIRST-123, ABC-123, etc. For FIRST-123, project_identifier is FIRST and issue_identifier is 123", { - project_identifier: z.string().describe("The readable identifier of the project to get issues for"), - issue_identifier: z.string().describe("The identifier of the issue to get"), + project_identifier: z.string().describe("The readable identifier of the project (e.g., 'FIRST' for FIRST-123)"), + issue_identifier: z.string().describe("The issue number (e.g., '123' for FIRST-123)"), }, async ({ project_identifier, issue_identifier }) => { const issue = await makePlaneRequest( diff --git a/src/tools/modules.ts b/src/tools/modules.ts index 7436be3..53ea228 100644 --- a/src/tools/modules.ts +++ b/src/tools/modules.ts @@ -4,7 +4,7 @@ import { z } from "zod"; import { makePlaneRequest } from "../common/request-helper.js"; import { Module as ModuleSchema } from "../schemas.js"; -export const registerModuleTools = (server: McpServer) => { +export const registerModuleTools = (server: McpServer): void => { server.tool( "list_modules", "Get all modules for a specific project",