plane-mcp-oss 0.1.0__tar.gz

plane_mcp_oss-0.1.0/.env.example

@@ -0,0 +1,27 @@
+# Copy to `.env` (loaded automatically) or export these in your shell / MCP
+# client config. CLI flags override all of these.
+
+# --- Credentials -------------------------------------------------------------
+# Personal access token from Plane: Profile settings -> Personal access tokens.
+# Sent as the `X-API-Key` header. Alias: PLANE_TOKEN.
+PLANE_API_KEY=plane_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Alternative to the API key: an OAuth access token, sent as `Authorization: Bearer ...`.
+# PLANE_OAUTH_TOKEN=
+
+# --- Instance ----------------------------------------------------------------
+# Workspace slug from your Plane URL: https://app.plane.so/<workspace-slug>/projects/
+# Alias: PLANE_WORKSPACE.
+PLANE_WORKSPACE_SLUG=my-team
+
+# Plane instance URL. Alias: PLANE_URL.
+# Leave as the default for Plane Cloud, or point it at your self-hosted instance.
+# All of these are accepted:
+#   https://api.plane.so                 (Plane Cloud)
+#   https://plane.example.com            (self-hosted)
+#   https://example.com/plane            (self-hosted behind a subpath)
+#   https://plane.example.com/api/v1     (version suffix included)
+PLANE_BASE_URL=https://api.plane.so
+
+# Request timeout in seconds.
+PLANE_TIMEOUT=30

plane_mcp_oss-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,79 @@
+name: Bug report
+description: Report something that is broken or behaves unexpectedly
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug! Please fill in as much as you
+        can — it makes fixing much faster.
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Preflight
+      options:
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+        - label: I am running the latest commit on `main`.
+          required: false
+  - type: input
+    id: version
+    attributes:
+      label: Version / commit
+      description: Output of `uv run plane-mcp --show-config`, or the commit SHA.
+    validations:
+      required: true
+  - type: dropdown
+    id: plane-edition
+    attributes:
+      label: Plane edition
+      description: "`GET /api/instances/` reports this under `instance.edition`."
+      options:
+        - Plane Cloud
+        - Community Edition (self-hosted)
+        - Enterprise (self-hosted)
+        - Not sure
+    validations:
+      required: true
+  - type: input
+    id: plane-version
+    attributes:
+      label: Plane version
+      description: "`instance.current_version` from `GET /api/instances/`."
+    validations:
+      required: false
+  - type: input
+    id: transport
+    attributes:
+      label: Transport & client
+      placeholder: "stdio via Claude Desktop / http via Cursor"
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Include the tool name, arguments, and the full error message.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      description: Redact tokens before pasting.
+      render: shell
+    validations:
+      required: false

plane_mcp_oss-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or usage help
+    url: https://github.com/abelsr/plane-mcp-oss/discussions
+    about: Ask how to configure or use the server.
+  - name: Security report
+    url: https://github.com/abelsr/plane-mcp-oss/security/advisories/new
+    about: Please report vulnerabilities privately, not as a public issue.
+  - name: Plane API reference
+    url: https://developers.plane.so/api-reference/introduction
+    about: Documentation for the underlying Plane REST API.

plane_mcp_oss-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,40 @@
+name: Feature request
+description: Suggest a new tool, capability, or improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Preflight
+      options:
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do that the server does not support yet?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: |
+        If you know the Plane endpoint, include its method and path
+        (see https://developers.plane.so/api-reference/introduction).
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+    validations:
+      required: false

plane_mcp_oss-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

plane_mcp_oss-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,28 @@
+## What does this PR do?
+
+<!-- A short description of the change and the motivation behind it. -->
+
+## Related issue
+
+<!-- e.g. Closes #12 -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New tool / feature
+- [ ] Documentation
+- [ ] Refactor / chore
+- [ ] Breaking change
+
+## Plane endpoint(s) used
+
+<!-- If adding a tool: METHOD /api/v1/path -->
+
+## Checklist
+
+- [ ] `uv run pytest` passes locally
+- [ ] New tools are added to `EXPECTED_TOOLS` in `tests/test_server.py`
+- [ ] New client methods have an offline test asserting method/path/body
+- [ ] `README.md` tool table updated (if a tool changed)
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+- [ ] No credentials, `.env` files, or real workspace data included

plane_mcp_oss-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.2.0
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} pytest -q
+
+      - name: Build the distribution
+        run: uv build

plane_mcp_oss-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+# Publishes the built distribution to PyPI using Trusted Publishing (OIDC):
+# no API token is stored in the repository.
+#
+# One-time setup on PyPI (Account -> Publishing -> Add a pending publisher):
+#   PyPI project name : plane-mcp-oss
+#   Owner             : abelsr
+#   Repository name   : plane-mcp-oss
+#   Workflow name     : publish.yml
+#   Environment name  : pypi
+#
+# After that, publishing a GitHub Release triggers this workflow. It can also
+# be run manually from the Actions tab.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/plane-mcp-oss
+    permissions:
+      id-token: write # required for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.2.0
+
+      - name: Run tests
+        run: |
+          uv sync --extra dev
+          uv run pytest -q
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

plane_mcp_oss-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Secrets — never commit real credentials
+.env
+.env.local
+
+# Virtualenv / uv
+.venv/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Build
+dist/
+build/

plane_mcp_oss-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

plane_mcp_oss-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-25
+
+### Added
+
+- FastMCP server exposing the Plane REST API over stdio, HTTP, and SSE.
+- Configuration from environment variables, a `.env` file, or CLI flags, with
+  precedence and aliases (`PLANE_URL`, `PLANE_WORKSPACE`, `PLANE_TOKEN`); self-hosted
+  URL normalization (subpaths, trailing slashes, versioned URLs).
+- `--show-config` to print the resolved configuration with secrets redacted.
+- Tools for projects, work items, states, labels, cycles, modules, workspace
+  members, the current user, and work item comments (create/list/update/delete).
+- Tools for pages — workspace wiki and project pages — with the full
+  create/update/archive/restore/delete lifecycle.
+- `search_work_items` (public search endpoint) and
+  `advanced_search_work_items` (permission-gated).
+- MCP resources `plane://me`, `plane://projects`,
+  `plane://projects/{project_id}/states` and the `triage_work_items` prompt.
+- 32 offline tests using `httpx.MockTransport` and an in-memory FastMCP client.
+
+### Notes
+
+- The public Pages REST API is **Plane Cloud only**; it is absent from the
+  open-source Community Edition, so the page tools return an explanatory error
+  there.
+- `advanced_search_work_items` may return 403 depending on workspace permissions.
+
+[Unreleased]: https://github.com/abelsr/plane-mcp-oss/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/abelsr/plane-mcp-oss/releases/tag/v0.1.0

plane_mcp_oss-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+abelsantillanrdz@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

plane_mcp_oss-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,109 @@
+# Contributing
+
+Thanks for your interest in improving the Plane MCP server! This project is
+small and friendly — issues and pull requests are welcome.
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Ways to contribute
+
+- **Report a bug** — open an issue; include your Plane edition/version
+  (`GET /api/instances/` reports it) and the exact tool call.
+- **Request an operation** — the server covers a subset of the Plane API. If a
+  tool is missing, say which endpoint you need.
+- **Add a tool** — see [Adding a tool](#adding-a-tool) below.
+- **Improve docs** — corrections to the README, examples, and error messages.
+
+## Development setup
+
+Requirements: Python 3.10+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/abelsr/plane-mcp-oss.git
+cd plane-mcp-oss
+uv sync --extra dev
+```
+
+Run the tests (they are fully offline — no Plane account required):
+
+```bash
+uv run pytest
+```
+
+Try the server against a workspace:
+
+```bash
+cp .env.example .env        # then fill in PLANE_API_KEY / PLANE_WORKSPACE_SLUG
+uv run plane-mcp --show-config
+uv run plane-mcp            # stdio; Ctrl-C to stop
+```
+
+> **Never commit real credentials.** `.env` is git-ignored; keep it that way.
+> Tests use dummy tokens and `httpx.MockTransport`, so they never touch the
+> network.
+
+## Project layout
+
+```
+src/plane_mcp/
+├── config.py    # env/.env/CLI settings + validation
+├── client.py    # async httpx wrapper: auth, URLs, errors, pagination (no FastMCP)
+├── server.py    # FastMCP tools/resources/prompts + CLI
+└── __main__.py
+tests/           # offline: httpx.MockTransport + in-memory FastMCP client
+```
+
+The split matters: `client.py` must not import FastMCP, so it stays reusable
+and unit-testable. Keep API concerns there and tool wiring in `server.py`.
+
+## Adding a tool
+
+1. Add a method to `PlaneClient` in `client.py` using the helper that builds
+   workspace paths, and raise-through `PlaneAPIError` (do not import FastMCP).
+
+   ```python
+   async def list_pages(self, *, project_id: str | None = None) -> dict[str, Any]:
+       return await self.request("GET", self._pages_root(project_id))
+   ```
+
+2. Register the tool in `server.py`, wrapping the call with `_call` so failures
+   become clean `ToolError`s, and write a docstring with an `Args:` section —
+   MCP clients surface it directly to the model.
+
+   ```python
+   @mcp.tool
+   async def list_pages(project_id: str | None = None) -> dict[str, Any]:
+       """List pages.
+
+       Args:
+           project_id: Project UUID, or omit for workspace wiki pages.
+       """
+       client = get_client()
+       data = await _call(client.list_pages(project_id=project_id))
+       return summarize_paginated(data)
+   ```
+
+3. Add the tool name to `EXPECTED_TOOLS` in `tests/test_server.py`.
+4. Add an offline test in `tests/test_client.py` that stubs the HTTP call and
+   asserts the method, path, and body — see existing tests for the pattern.
+5. Update the tool table in `README.md` and add a `CHANGELOG.md` entry.
+
+## Style
+
+- Keep the `ruff` defaults in mind (line length ~100, imports sorted); no
+  formatter is enforced yet, so match the surrounding code.
+- Prefer stdlib and the two runtime dependencies (`fastmcp`, `httpx`) over new
+  packages. Discuss in an issue before adding a dependency.
+- Public functions and tools get type hints and a docstring.
+
+## Commit and PR guidelines
+
+- Branch from `main`; keep pull requests focused on one change.
+- Write imperative, descriptive commits (e.g. `Add cycle work item tools`).
+- Ensure `uv run pytest` passes and CI is green.
+- Describe **what** and **why** in the PR; reference the Plane endpoint you used.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+[MIT License](LICENSE).

plane_mcp_oss-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abel Santillan Rodriguez
+
+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.