Release v0.3.1

CLAUDE.md

@@ -57,6 +57,16 @@ Ordered as registered; the earlier one wraps the later:
 | `CoerceArguments` | repairs arguments a client encoded as strings, before validation (`coercion.py`) |
 | `ValidateActionArguments` | refuses arguments the chosen action does not accept, from the `ACTIONS` declaration |
 
+A dispatch tool's name is not its operation, so `PlaneLoggingMiddleware` adds `resource` and `action` to every `tools/call` record — start, success and error alike, where previously only success and error carried anything. For a retired name both are resolved through the alias table, since it carries no `action` of its own.
+
+| field | means |
+|---|---|
+| `tool` | the name the caller used — **unchanged**, so existing dashboards keep counting the same thing |
+| `resource` | the resource tool that ran (`workitem`); equals `tool` for a current call |
+| `action` | the operation (`count`), absent only for a tool that has no actions |
+
+`resource` + `action` names one operation however it was reached, and `tool != resource` is exactly the set of calls still arriving on a retired name. `legacy.py` also keeps its per-resolution log line, which predates these fields.
+
 Coercion runs before validation so an argument is judged by the value it repairs to. `ValidateActionArguments` closes a gap a per-tool schema cannot: every action's parameters share one schema, so an argument meant for another action validated cleanly and was then dropped, and the call answered a different question than the one asked. Only arguments carrying a value are judged, and retired names are exempt — they arrive with no `action` and under their own parameter spelling.
 
 ### Client Context (`client.py`)
@@ -70,7 +80,7 @@ Coercion runs before validation so an argument is judged by the value it repairs
 
 ### Tools (`tools/`)
 
-One action-dispatch tool per Plane resource: **28 tools, 183 actions, ~57k chars advertised**. `tools/__init__.py` re-exports `register_tools`, so `server.py` and `__main__.py` see a single entry point.
+One action-dispatch tool per Plane resource: **30 tools, 204 actions, ~67k chars advertised**. `tools/__init__.py` re-exports `register_tools`, so `server.py` and `__main__.py` see a single entry point.
 
 One module per resource, each exporting `NAME`, `ACTIONS`, `LEGACY` and `register(mcp)`. `ACTIONS` is the single source of truth: the tool description and its `ToolAnnotations` are generated from it, and the conformance suite asserts they agree with the function signature. See `tools/README.md` for the full convention.
 
@@ -96,7 +106,7 @@ Shared building blocks for the tool surface, split by *when* they act:
 | `governance.py` | policy | `workspace_owns_resource`, `GOVERNED_BY`, `workspace_owns`, `migration_in_progress`, `plan_gated` |
 | `transforms.py` | listing | `StripOutputSchemas` |
 
-Governance has two questions, and both matter. `workspace_owns_resource` reads the workspace flag that governs a resource — used *before* a write, to pick the scope. `workspace_owns` reads the refusal — used *after*, because the flag is cached and the lockout outlives it being toggled off. There is no single flag: work item types carry their own (`is_work_item_types_enabled`, public `work_item_types`), while states, labels, workflows, templates and automations share `workspace_governance_status` (public `states_owned_by_workspace`). `GOVERNED_BY` maps resource to flag so a newly governed resource is one row.
+Governance, plan gates and the rest of the toolkit conventions are documented in `plane_mcp/toolkit/README.md`, including what adding a newly governed resource takes.
 
 Names are re-exported from `plane_mcp/toolkit/__init__.py`, so a resource module needs one import: `from plane_mcp.toolkit import Action, build_description, missing, opt`.
 
@@ -122,3 +132,4 @@ Integration tests in `tests/test_integration.py` use `FastMCP.Client` with `Stre
 | `PLANE_OAUTH_PROVIDER_*` | http/sse OAuth | OAuth client credentials and base URL |
 | `PLANE_OAUTH_ALLOWED_REDIRECT_URIS` | http/sse OAuth (optional) | Comma-separated redirect URI patterns appended to the built-in allowlist (onboard clients without a release) |
 | `LOG_USER_INFO` | all (optional, default: false) | When `true`, include user info (PII such as display name) in logs alongside the opaque user id |
+| `LOG_PAYLOADS` | all (optional, default: true) | Log request payloads.|

README.md

@@ -7,7 +7,7 @@ work items, cycles, modules, releases, customers and more.
 Built on [FastMCP](https://github.com/jlowin/fastmcp) and the official
 [`plane-sdk`](https://pypi.org/project/plane-sdk/).
 
-- **28 tools**, one per Plane resource, covering 183 operations
+- **30 tools**, one per Plane resource, covering 204 operations
 - **Local or remote** — stdio, streamable HTTP, SSE
 - **OAuth or API key** authentication
 
@@ -98,7 +98,7 @@ HTTP transport instead.
 
 ## Tools
 
-The server advertises 28 tools, one per resource. Each takes an `action`
+The server advertises 30 tools, one per resource. Each takes an `action`
 parameter that selects the operation:
 
 ```python
@@ -179,7 +179,8 @@ Structured JSON. Each tool call logs its name, duration, status and — when
 available — an opaque user id and the workspace slug.
 
 ```bash
-export LOG_USER_INFO=true    # also log the display name (PII); default false
+export LOG_USER_INFO=false    # also log the display name (PII);
+export LOG_PAYLOADS=false    # keep request payloads out of logs; default true
 ```
 
 Only the OAuth and PAT transports carry a display name; stdio is unaffected.

plane_mcp/middleware.py

@@ -3,14 +3,15 @@
 from __future__ import annotations
 
 from collections.abc import Collection
+from typing import Any
 
 from fastmcp.server.middleware import Middleware, MiddlewareContext
 from fastmcp.server.middleware.logging import StructuredLoggingMiddleware
 from fastmcp.tools.tool import ToolResult
 from fastmcp.utilities.logging import get_logger
 
 from plane_mcp.coercion import coerce_arguments
-from plane_mcp.tools.registry import action_arguments
+from plane_mcp.tools.registry import action_arguments, alias_table
 
 logger = get_logger(__name__)
 
@@ -91,15 +92,44 @@ async def _schema(context: MiddlewareContext) -> dict | None:
 
 
 class PlaneLoggingMiddleware(StructuredLoggingMiddleware):
-    """StructuredLoggingMiddleware that also records the tool name."""
-
-    def _with_tool_name(self, context: MiddlewareContext, message: dict) -> dict:
-        if context.method == "tools/call":
-            message["tool"] = getattr(context.message, "name", "unknown")
-        return message
+    """StructuredLoggingMiddleware that records which operation ran, not just which tool.
+
+    A dispatch tool's name is not its operation -- `workitem` covers 23 of them -- so
+    `resource` and `action` are recorded beside it, resolved through the alias table for
+    a retired name, which carries no `action` of its own. `resource` + `action` then
+    names one operation however it was reached, and `tool != resource` is exactly the
+    set of calls still arriving on a retired name.
+
+    `tool` keeps its previous meaning -- the name the caller used -- so dashboards built
+    on it keep counting the same thing. The two additions are additive, and they are on
+    the start record as well, which previously carried neither.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        # Built once; per record this is a dict lookup.
+        self._aliases = alias_table()
+
+    def _operation(self, context: MiddlewareContext) -> dict[str, str]:
+        """What the caller called, and which operation that is."""
+        if context.method != "tools/call":
+            return {}
+        name = getattr(context.message, "name", "unknown")
+        if alias := self._aliases.get(name):
+            resource, action = alias
+        else:
+            resource = name
+            action = (getattr(context.message, "arguments", None) or {}).get("action")
+        fields = {"tool": name, "resource": resource}
+        if action:
+            fields["action"] = action
+        return fields
+
+    def _create_before_message(self, context: MiddlewareContext, *args: Any, **kwargs: Any) -> dict:
+        return super()._create_before_message(context, *args, **kwargs) | self._operation(context)
 
     def _create_after_message(self, context: MiddlewareContext, start_time: float) -> dict:
-        return self._with_tool_name(context, super()._create_after_message(context, start_time))
+        return super()._create_after_message(context, start_time) | self._operation(context)
 
     def _create_error_message(self, context: MiddlewareContext, start_time: float, error: Exception) -> dict:
-        return self._with_tool_name(context, super()._create_error_message(context, start_time, error))
+        return super()._create_error_message(context, start_time, error) | self._operation(context)

plane_mcp/server.py

@@ -48,9 +48,12 @@ def get_allowed_client_redirect_uris() -> list[str]:
     return allowed
 
 
+LOG_PAYLOADS = os.getenv("LOG_PAYLOADS", "true").lower() == "true"
+
+
 def _configured(mcp: FastMCP) -> FastMCP:
     """The middleware stack and tools every transport shares."""
-    mcp.add_middleware(PlaneLoggingMiddleware(include_payloads=True))
+    mcp.add_middleware(PlaneLoggingMiddleware(include_payloads=LOG_PAYLOADS))
     mcp.add_middleware(CoerceArguments())
     mcp.add_middleware(ValidateActionArguments())
     register_tools(mcp)

plane_mcp/toolkit/README.md

@@ -0,0 +1,53 @@
+# toolkit
+
+Shared building blocks for the tool surface, split by *when* they act. All re-exported from `__init__.py`, so a resource module needs one import.
+
+| Module | Acts at | Provides |
+|---|---|---|
+| `spec.py` | declaration | `Action`, `build_description`, `build_annotations` |
+| `runtime.py` | call | `missing`, `needs`, `require`, `one_of`, `opt`, `coerce_list`, `page_params`, `as_params`, `ids_of` |
+| `paging.py` | response | `envelope`, `dump_results`, `pql_failure`, `workitem_page` |
+| `governance.py` | policy | `workspace_owns_resource`, `workspace_owns`, `scoped`, `plan_gated` |
+| `transforms.py` | listing | `StripOutputSchemas` |
+
+Nothing here knows which catalogue is calling it. Anything encoding this server's own history — the `RESOURCES` tuple, retired names — lives under `tools/`.
+
+## Workspace governance
+
+Plane can move a resource's catalogue from the project to the workspace. Which scope owns it decides where writes go, and the wrong scope is refused in **both** directions:
+
+| Write | Refused with | Means |
+|---|---|---|
+| project-scoped, workspace owns it | `workspace_managed` | omit `project_id` |
+| catalogue, project still owns it | `workspace_not_managed` | pass `project_id` |
+
+**There is no single flag.** `GOVERNED_BY` maps each resource to the one that governs it:
+
+| Resource | Flag |
+|---|---|
+| work item types, epics, properties | `work_item_types` |
+| states, labels, workflows, templates, automations | `states_owned_by_workspace` |
+
+A workspace can own one and not the other, so never read one flag for the other resource.
+
+**Two ways to ask, both needed:**
+
+| Call | Reads | Use |
+|---|---|---|
+| `workspace_owns_resource(client, slug, resource)` | the flag | pick a scope *before* writing |
+| `workspace_owns(exc, *fields)` | the refusal | after — the flag is cached and the lockout outlives it being toggled off |
+
+### Adding a newly governed resource
+
+1. **Add a row to `GOVERNED_BY`** naming its flag.
+2. **Decorate the tool with `@scoped("<noun>")`**, below `@mcp.tool`. Either refusal becomes a message naming the scope that owns it. Where the API refuses by field rather than code — work item types do — pass the field: `@scoped("work item types", "work_item_types")`.
+3. **Resolve the scope once** at the top of the dispatch, not per call site. Shape is yours: `workitem_type` returns a tuple, `state` and `workitem_property` a small local `_Scope`.
+4. **Refuse fields the other scope lacks.** A catalogue state has no ordering, triage flag or default; sent anyway they are dropped in silence, which reads as success.
+
+`workitem_type resolve` is the worked ask-first example: reads the flag, adopts the type from the catalogue, imports it into the project — and still handles the refusal in case the flag is stale.
+
+`test_a_wrong_scope_refusal_is_answered_not_raised` drives a real refusal through every scoped resource, so step 2 cannot be forgotten.
+
+## Plan gates
+
+`@plan_gated("<feature>")` turns a 402 — or a 400 whose prose says "upgrade your plan" — into a message naming the feature, rather than an error a caller will retry. The argument is the fallback label: where the refusal names the feature itself, that wins, since one resource can trip several gates (`project` trips five).

plane_mcp/toolkit/__init__.py

@@ -28,6 +28,8 @@
     migration_in_progress,
     plan_gated,
     plan_required,
+    project_owns,
+    scoped,
     workspace_owns,
     workspace_owns_resource,
 )
@@ -71,8 +73,10 @@
     "page_params",
     "plan_gated",
     "plan_required",
+    "project_owns",
     "pql_failure",
     "require",
+    "scoped",
     "workspace_owns",
     "workspace_owns_resource",
     "workitem_page",

plane_mcp/toolkit/governance.py

@@ -10,6 +10,8 @@
 from plane.errors.errors import HttpError
 
 WORKSPACE_MANAGED = "workspace_managed"
+# Its inverse: a catalogue endpoint called in a workspace that still owns per project.
+WORKSPACE_NOT_MANAGED = "workspace_not_managed"
 MIGRATION_IN_PROGRESS = "governance_migration_in_progress"
 
 # The governed resources, named as this server refers to them.
@@ -29,6 +31,8 @@
     AUTOMATIONS: "states_owned_by_workspace",
 }
 
+NOT_MANAGED_PROSE = re.compile(r"workspace work item type.*not enabled", re.IGNORECASE)
+
 # Some validators raise 400 with the plan gate only in prose; matched as a fallback.
 PLAN_GATE_PROSE = "upgrade your plan"
 
@@ -56,6 +60,41 @@ def workspace_owns_resource(client: Any, workspace_slug: str, resource: str) ->
     return bool(features.model_dump().get(flag))
 
 
+def project_owns(exc: HttpError) -> bool:
+    """Whether a refusal means this resource still lives per project."""
+    body = _body(exc)
+    if body.get("code") == WORKSPACE_NOT_MANAGED:
+        return True
+    return bool(NOT_MANAGED_PROSE.search(str(body.get("error", ""))))
+
+
+def wrong_scope(exc: HttpError, resource: str, *fields: str, project_id: str = "") -> str | None:
+    """The message telling a caller which scope owns `resource`, or None."""
+    if workspace_owns(exc, *fields):
+        return f"Error: this workspace owns its {resource}. Omit project_id to work with the catalogue."
+    if not project_id and project_owns(exc):
+        return f"Error: this workspace keeps {resource} per project. Pass project_id."
+    return None
+
+
+def scoped(resource: str, *fields: str) -> Callable[[F], F]:
+    """Turn a wrong-scope refusal anywhere in a resource's dispatch into that message."""
+
+    def decorate(fn: F) -> F:
+        @functools.wraps(fn)
+        def guarded(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return fn(*args, **kwargs)
+            except HttpError as exc:
+                if message := wrong_scope(exc, resource, *fields, project_id=kwargs.get("project_id", "")):
+                    return message
+                raise
+
+        return guarded  # type: ignore[return-value]
+
+    return decorate
+
+
 def migration_in_progress(exc: HttpError) -> bool:
     """Whether a refusal means a governance migration is running, so the write may be retried."""
     return _body(exc).get("code") == MIGRATION_IN_PROGRESS