@studiometa/productive-mcp 0.10.10 → 0.10.11

package/README.md

@@ -17,6 +17,7 @@ MCP (Model Context Protocol) server for [Productive.io](https://productive.io).
 - Two modes: **local (stdio)** for personal use, **remote (HTTP)** for teams
 - OAuth 2.0 support for Claude Desktop custom connectors
 - Built-in `help` action for self-documentation
+- Raw API escape hatches: `api_read` for documented GET endpoints and gated `api_write` for documented writes
 
 ## Mode 1: Local (stdio)
 
@@ -144,6 +145,125 @@ Use `action="help"` with any resource for detailed documentation on available pa
 | `include`           | string[] | Related resources to include (e.g. `["project", "assignee"]`) |
 | `query`             | string   | Text search for `list` actions                                |
 
+### Raw API Tools
+
+In addition to the unified `productive` tool, the server exposes two low-level tools for documented Productive API endpoints.
+
+| Tool        | Description                                                                              |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| `api_read`  | Read-only raw API access for documented `GET` endpoints                                  |
+| `api_write` | Gated raw API write access for documented `POST`, `PATCH`, `PUT`, and `DELETE` endpoints |
+
+#### `api_read`
+
+Use `api_read` when you need a documented endpoint that is not yet covered by the higher-level `productive` tool.
+
+**Parameters**
+
+| Parameter   | Type     | Description                                              |
+| ----------- | -------- | -------------------------------------------------------- |
+| `path`      | string   | Required relative API path, starting with `/`            |
+| `describe`  | boolean  | Return endpoint docs instead of executing the request    |
+| `filter`    | object   | Filter object, validated against the documented endpoint |
+| `include`   | string[] | Related resources to include                             |
+| `sort`      | string[] | Sort values, validated against the documented endpoint   |
+| `page`      | number   | Page number                                              |
+| `per_page`  | number   | Page size, max `200`                                     |
+| `paginate`  | boolean  | Follow pagination automatically                          |
+| `max_pages` | number   | Max pages when `paginate=true`, default `20`, max `50`   |
+
+**Safety model**
+
+- `GET` only
+- Path must be relative and start with `/`
+- Absolute URLs and path traversal are rejected
+- Only documented Productive endpoints are allowed
+- Filters and sort values are validated against the endpoint spec
+- `describe=true` is the safest way to inspect an endpoint before calling it
+
+**Examples**
+
+```json
+{
+  "path": "/invoices",
+  "describe": true
+}
+```
+
+```json
+{
+  "path": "/projects/123/tasks",
+  "filter": { "status": "open" },
+  "sort": ["due_date"],
+  "page": 1,
+  "per_page": 50
+}
+```
+
+```json
+{
+  "path": "/time_entries",
+  "filter": { "person_id": ["me"], "after": "2025-01-01", "before": "2025-01-31" },
+  "paginate": true,
+  "max_pages": 5
+}
+```
+
+#### `api_write`
+
+Use `api_write` only when the higher-level `productive` tool does not expose the mutation you need.
+
+**Parameters**
+
+| Parameter | Type    | Description                                        |
+| --------- | ------- | -------------------------------------------------- |
+| `method`  | string  | Required, one of `POST`, `PATCH`, `PUT`, `DELETE`  |
+| `path`    | string  | Required relative API path                         |
+| `body`    | object  | Request body for write methods                     |
+| `confirm` | boolean | Required, must be `true`                           |
+| `dry_run` | boolean | Return the normalized request without executing it |
+
+**Safety model**
+
+- Disabled by default
+- Requires `PRODUCTIVE_MCP_ENABLE_API_WRITE=true` on the server
+- Requires `confirm=true` on every call
+- Only documented Productive endpoints are allowed
+- Path must be relative; absolute URLs and traversal are rejected
+- `dry_run=true` lets you verify the exact method, path, and body before execution
+
+To enable writes in local or remote deployments:
+
+```bash
+PRODUCTIVE_MCP_ENABLE_API_WRITE=true productive-mcp-server
+```
+
+**Examples**
+
+```json
+{
+  "method": "PATCH",
+  "path": "/tasks/123",
+  "body": {
+    "data": {
+      "type": "tasks",
+      "id": "123",
+      "attributes": { "name": "Updated title" }
+    }
+  },
+  "confirm": true,
+  "dry_run": true
+}
+```
+
+```json
+{
+  "method": "DELETE",
+  "path": "/attachments/456",
+  "confirm": true
+}
+```
+
 ### Configuration Tools (Local mode only)
 
 | Tool                    | Description                                        |

package/dist/api-reference/generated.d.ts

@@ -0,0 +1,3 @@
+import type { ApiReference } from './types.js';
+export declare const PRODUCTIVE_API_REFERENCE: ApiReference;
+//# sourceMappingURL=generated.d.ts.map

package/dist/api-reference/generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../src/api-reference/generated.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,eAAO,MAAM,wBAAwB,EAAE,YAk3jD7B,CAAC"}

package/dist/api-reference/types.d.ts

@@ -0,0 +1,31 @@
+export interface ApiFilterOperatorSpec {
+    description?: string;
+}
+export interface ApiFilterSpec {
+    type?: string;
+    format?: string;
+    description?: string;
+    enum?: Array<string | number>;
+    operators?: Record<string, ApiFilterOperatorSpec>;
+}
+export interface ApiQueryParamSpec {
+    type?: string;
+    description?: string;
+}
+export interface ApiMethodSpec {
+    summary: string;
+    description?: string;
+    operationId?: string;
+    query?: Record<string, ApiQueryParamSpec>;
+    filters?: Record<string, ApiFilterSpec>;
+    sort?: string[];
+    pathParams?: Record<string, ApiQueryParamSpec>;
+    requestBodyFields?: string[];
+    supportsBody?: boolean;
+}
+export interface ApiEndpointSpec {
+    path: string;
+    methods: Partial<Record<'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', ApiMethodSpec>>;
+}
+export type ApiReference = Record<string, ApiEndpointSpec>;
+//# sourceMappingURL=types.d.ts.map

package/dist/api-reference/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api-reference/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC;CACtF;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC"}

package/dist/handlers/api-read.d.ts

@@ -0,0 +1,14 @@
+import type { HandlerContext, ToolResult } from './types.js';
+export interface ApiReadArgs {
+    path: string;
+    describe?: boolean;
+    filter?: Record<string, unknown>;
+    include?: string[];
+    sort?: string[];
+    page?: number;
+    per_page?: number;
+    paginate?: boolean;
+    max_pages?: number;
+}
+export declare function handleApiRead(args: ApiReadArgs, ctx: HandlerContext): Promise<ToolResult>;
+//# sourceMappingURL=api-read.d.ts.map

package/dist/handlers/api-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-read.d.ts","sourceRoot":"","sources":["../../src/handlers/api-read.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAa7D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CA0B/F"}

package/dist/handlers/api-utils.d.ts

@@ -0,0 +1,27 @@
+import type { ApiEndpointSpec, ApiMethodSpec } from '../api-reference/types.js';
+export declare const MAX_PER_PAGE = 200;
+export declare const DEFAULT_MAX_PAGES = 20;
+export declare const MAX_MAX_PAGES = 50;
+export interface ResolvedApiEndpoint {
+    spec: ApiEndpointSpec;
+    methodSpec: ApiMethodSpec;
+    normalizedPath: string;
+}
+export declare function normalizeApiPath(path: string): string;
+export declare function resolveApiEndpoint(path: string, method: keyof ApiEndpointSpec['methods']): ResolvedApiEndpoint;
+export declare function serializeFilter(filter?: Record<string, unknown>): Record<string, string>;
+export declare function buildApiReadQuery(args: {
+    filter?: Record<string, unknown>;
+    include?: string[];
+    sort?: string[];
+    page?: number;
+    per_page?: number;
+}): Record<string, string>;
+export declare function validatePagination(args: {
+    per_page?: number;
+    max_pages?: number;
+}): void;
+export declare function validateFilterSpec(filter: Record<string, unknown> | undefined, methodSpec: ApiMethodSpec): void;
+export declare function validateSort(sort: string[] | undefined, methodSpec: ApiMethodSpec): void;
+export declare function describeApiEndpoint(path: string): Record<string, unknown>;
+//# sourceMappingURL=api-utils.d.ts.map

package/dist/handlers/api-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-utils.d.ts","sourceRoot":"","sources":["../../src/handlers/api-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAKhF,eAAO,MAAM,YAAY,MAAM,CAAC;AAChC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,UAAU,EAAE,aAAa,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB;AAMD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAerD;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,eAAe,CAAC,SAAS,CAAC,GACvC,mBAAmB,CAgBrB;AAwBD,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxF;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASzB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQxF;AAwCD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,UAAU,EAAE,aAAa,GACxB,IAAI,CAIN;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,UAAU,EAAE,aAAa,GAAG,IAAI,CAYxF;AA+CD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmCzE"}

package/dist/handlers/api-write.d.ts

@@ -0,0 +1,10 @@
+import type { HandlerContext, ToolResult } from './types.js';
+export interface ApiWriteArgs {
+    method: 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+    path: string;
+    body?: unknown;
+    confirm?: boolean;
+    dry_run?: boolean;
+}
+export declare function handleApiWrite(args: ApiWriteArgs, ctx: HandlerContext): Promise<ToolResult>;
+//# sourceMappingURL=api-write.d.ts.map

package/dist/handlers/api-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-write.d.ts","sourceRoot":"","sources":["../../src/handlers/api-write.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7D,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAoCjG"}

package/dist/handlers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,KAAK,EAAkB,UAAU,EAAE,MAAM,YAAY,CAAC;AAgC7D,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA2I7C;;GAEG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,EAAE,qBAAqB,GACjC,OAAO,CAAC,UAAU,CAAC,CA0IrB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,KAAK,EAAkB,UAAU,EAAE,MAAM,YAAY,CAAC;AAuC7D,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA8I7C;;GAEG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,EAAE,qBAAqB,GACjC,OAAO,CAAC,UAAU,CAAC,CA0LrB"}