{"id":28175587,"url":"https://github.com/creodot/plane-mcp-server","last_synced_at":"2025-05-15T23:15:49.298Z","repository":{"id":287477859,"uuid":"958701592","full_name":"Creodot/plane-mcp-server","owner":"Creodot","description":"✈ MCP For Plane.so","archived":false,"fork":false,"pushed_at":"2025-04-12T14:25:09.000Z","size":191,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-12T14:40:07.602Z","etag":null,"topics":["biomejs","mcp","modelcontextprotocol","open-source","plane","typescript"],"latest_commit_sha":null,"homepage":"https://plane.so","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Creodot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-01T16:13:48.000Z","updated_at":"2025-04-12T14:25:04.000Z","dependencies_parsed_at":"2025-04-12T14:40:10.073Z","dependency_job_id":null,"html_url":"https://github.com/Creodot/plane-mcp-server","commit_stats":null,"previous_names":["creodot/plane-mcp","creodot/plane-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Creodot%2Fplane-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Creodot%2Fplane-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Creodot%2Fplane-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Creodot%2Fplane-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Creodot","download_url":"https://codeload.github.com/Creodot/plane-mcp-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436903,"owners_count":22070949,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["biomejs","mcp","modelcontextprotocol","open-source","plane","typescript"],"created_at":"2025-05-15T23:14:51.814Z","updated_at":"2025-05-15T23:15:49.279Z","avatar_url":"https://github.com/Creodot.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ✨ Plane.so MCP Server ✨\n\n[![CI](https://github.com/Creodot/plane-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Creodot/plane-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![npm version](https://img.shields.io/npm/v/YOUR_PACKAGE_NAME?label=npm%20package)](https://www.npmjs.com/package/YOUR_PACKAGE_NAME) \u003c!-- Replace YOUR_PACKAGE_NAME if published --\u003e\n[![Node.js Version](https://img.shields.io/node/v/YOUR_PACKAGE_NAME.svg)](https://nodejs.org/) \u003c!-- Replace YOUR_PACKAGE_NAME if published --\u003e\n[![TypeScript](https://img.shields.io/badge/Built%20with-TypeScript-blue.svg)](https://www.typescriptlang.org/)\n[![BiomeJS](https://img.shields.io/badge/Code%20Style-Biome-ffb043.svg)](https://biomejs.dev/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n\u003e A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server acting as a bridge to the [Plane.so API](https://developers.plane.so/api-reference/introduction). 🚀\n\nThis server allows MCP clients (like AI assistants or other tools) to interact with Plane.so resources (initially Issues) through defined tools.\n\n## 📚 Table of Contents\n\n*   [For Users](#-for-users)\n    *   [Available Tools](#-available-tools)\n    *   [Prerequisites](#-prerequisites)\n    *   [Installation](#-installation)\n    *   [Configuration](#-configuration)\n    *   [Usage](#-usage)\n    *   [Examples](#-examples)\n    *   [Security Considerations](#-security-considerations)\n*   [For Developers](#-for-developers)\n    *   [Development](#development-%EF%B8%8F)\n    *   [Project Structure](#-project-structure)\n    *   [Validation and Error Handling](#-validation-and-error-handling)\n    *   [Adding New Tools](#-adding-new-tools)\n    *   [Testing](#-testing)\n    *   [Linting and Formatting](#-linting-and-formatting)\n    *   [Contributing](#-contributing)\n    *   [Code of Conduct](#%EF%B8%8F-code-of-conduct)\n*   [License](#-license)\n\n## 👤 For Users\n\nThis section provides information for users who want to install and run the Plane.so MCP server to connect it with their MCP client (e.g., Cursor, Claude App).\n\n### ⭐ Available Tools\n\nThe server exposes the following tools to interact with the Plane.so API. Tool names use underscores (e.g., `plane_get_issue`).\n\n#### `plane_get_issue`\n\nRetrieves details of a specific issue.\n\n**Parameters:**\n\n*   `project_id` (string, required): ID of the project containing the issue.\n*   `issue_id` (string, required): ID of the issue to retrieve.\n\n**Example:**\n\n```json\n{\n  \"project_id\": \"your_project_id_here\",\n  \"issue_id\": \"your_issue_id_here\"\n}\n```\n\n#### `plane_create_issue`\n\nCreates a new issue in a specified project.\n\n**Parameters:**\n\n*   `project_id` (string, required): ID of the project where the issue should be created.\n*   `name` (string, required): Title of the issue.\n*   `description_html` (string, optional): HTML description of the issue (Plane API often requires this format).\n*   `priority` (string, optional): Priority of the issue (\"urgent\", \"high\", \"medium\", \"low\", \"none\").\n*   `state_id` (string, optional): ID of the state for this issue.\n*   `assignees` (array\u003cstring\u003e, optional): Array of user IDs to assign to this issue.\n\n**Example:**\n\n```json\n{\n  \"project_id\": \"your_project_id_here\",\n  \"name\": \"New Feature Request\",\n  \"description_html\": \"\u003cp\u003eDetails about the new feature.\u003c/p\u003e\",\n  \"priority\": \"medium\"\n}\n```\n\n#### `plane_update_issue`\n\nUpdates an existing issue in a project.\n\n**Parameters:**\n\n*   `project_id` (string, required): ID of the project containing the issue.\n*   `issue_id` (string, required): ID of the issue to update.\n*   `name` (string, optional): Updated title of the issue.\n*   `description_html` (string, optional): Updated HTML description of the issue.\n*   `priority` (string, optional): Updated priority of the issue.\n*   `state_id` (string, optional): Updated state ID of the issue.\n*   `assignees` (array\u003cstring\u003e, optional): Updated array of user IDs assigned to this issue.\n\n**Example:**\n\n```json\n{\n  \"project_id\": \"your_project_id_here\",\n  \"issue_id\": \"your_issue_id_here\",\n  \"priority\": \"high\",\n  \"assignees\": [\"user_id_1\"]\n}\n```\n\n### ✅ Prerequisites\n\n*   [Node.js](https://nodejs.org/) (v20 or higher recommended)\n*   [npm](https://www.npmjs.com/)\n*   A Plane.so account and an API Key -\u003e Workspace Icon (top left) -\u003e Settings -\u003e API Tokens -\u003e Add API Token\n*   Plane.so Workspace slug -\u003e `https://app.plane.so/{workspace_slug}/` (Replace `{workspace_slug}` with your actual workspace slug)\n\n### 🛠️ Installation\n\n```bash\nnpm install\n```\n\n### 🚀 Usage\n\nThe server will start and listen for requests on its standard input (stdin) and send responses to its standard output (stdout). You need to configure your MCP client (like Cursor, Claude App, etc.) to launch this server process when needed.\n\nFor more details on the Model Context Protocol, visit [modelcontextprotocol.io](https://modelcontextprotocol.io/).\n\n### ✨ Examples\n\nHere are some example prompts you could give your AI assistant (once the server is configured in it):\n\n*   \"Get the details for issue `BUG-123` in the `WebApp` project.\"\n*   \"Create a new high-priority issue in the `API` project titled 'Refactor authentication module' with the description 'Need to update the auth library.'\"\n*   \"Update issue `FEAT-45` in the `Design` project and assign it to `user_abc`.\"\n\nYour assistant will use the appropriate tools (`plane_get_issue`, `plane_create_issue`, `plane_update_issue`) and likely ask for your confirmation before making changes.\n\n### 🛡️ Security Considerations\n\n*   **API Key Security:** Your `PLANE_API_KEY` stored in the `.env` file grants access to your Plane.so workspace. Keep this file secure and never commit it to version control.\n*   **Permissions:** Ensure the API key used has the necessary permissions within Plane.so to perform the actions required by the tools (e.g., read issues, create issues, update issues).\n*   **User Approval:** Most MCP clients will require your explicit approval before executing actions that modify data (like creating or updating issues), providing a safety layer.\n\n---\n\n## 🧑‍💻 For Developers\n\nThis section is for developers who want to contribute to the project, run tests, or use the development environment.\n\n### Development 🧑‍💻\n\n```bash\nnpm run dev\n```\n\n### Project Structure 📂\n\nThe project follows a domain-driven organization:\n\n```\nsrc/\n├── configs/         # Environment and configuration\n├── plane-client.js  # API client wrapper\n├── schemas/         # Zod validation schemas\n│   ├── tools.schema.ts    # Common tool schemas and utilities\n│   ├── project.schema.ts  # Project-specific schemas \n│   └── issue.schema.ts    # Issue-specific schemas\n├── services/        # Service layer for API interactions\n│   ├── project.service.ts\n│   └── issue.service.ts\n├── tools/           # MCP tool definitions and handlers\n│   ├── index.ts           # Tool registration\n│   ├── project.tools.ts   # Project tool definitions\n│   └── issue.tools.ts     # Issue tool definitions\n└── types/           # TypeScript type definitions\n```\n\n### Validation and Error Handling ✅\n\nThe project uses Zod for comprehensive validation:\n\n1. **Schema Definition**: Domain-specific schemas are defined in `src/schemas/`\n2. **Schema Validation**: The `validateWithSchema` utility ensures consistent validation\n3. **Error Handling**: Custom `ValidationError` class for structured error reporting\n\nExample of using validation:\n\n```typescript\n// In a service method\nconst validData = validateWithSchema(MySchema, inputData);\n// validData is now correctly typed and validated\n```\n\n### Adding New Tools 🔧\n\nTo add a new tool:\n\n1. Define the tool interface in the appropriate domain file (e.g., `src/tools/issue.tools.ts`)\n2. Add validation schemas in the domain schema file (e.g., `src/schemas/issue.schema.ts`)\n3. Implement the service method in the service file (e.g., `src/services/issue.service.ts`)\n4. Register the tool in `src/tools/index.ts`\n\n### Testing 🧪\n\nThe project includes multiple types of tests:\n\n#### Unit Tests\n\nRun unit tests (fast, no API calls):\n\n```bash\nnpm run test:unit\n```\n\n#### Integration Tests\n\nThese tests make real API calls, so they need API credentials:\n\n1. Create a `.env.test` file with:\n```\nAPI_KEY=your_plane_api_key\nWORKSPACE_SLUG=your_workspace_slug\n```\n\n2. Run integration tests:\n```bash\nnpm run test:local\n```\n\n3. Quick endpoint check:\n```bash\nnpm run check:local\n```\n\n#### Pre-commit Hooks\n\nThe pre-commit hooks only run linting and formatting, not tests. This ensures:\n- Faster commits\n- No API call requirements during development\n- No need for API credentials during regular development\n\nWhen you want to run tests manually:\n```bash\n# Unit tests only\nnpm run test:unit\n\n# All tests including integration (needs API credentials)\nnpm test\n```\n\n### Linting and Formatting ✨\n\nCheck for linting and formatting errors using Biome:\n\n```bash\nnpm run lint\nnpm run format:check\n```\n\nApply formatting and lint fixes automatically:\n\n```bash\nnpm run format\n```\n\n(Note: Formatting is also automatically applied on commit via Husky and lint-staged!)\n\n### 🙌 Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to contribute, report bugs, or suggest features.\n\n### 🤝 Code of Conduct\n\nWe are committed to providing a welcoming and inclusive environment. Please review our [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).\n\n---\n\n## 📜 License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcreodot%2Fplane-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcreodot%2Fplane-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcreodot%2Fplane-mcp-server/lists"}