@studiometa/productive-mcp 0.10.9 → 0.10.11

package/dist/{version-BFw4junA.js.map → version-Dm6m3p60.js.map}

@@ -1 +1 @@
-{"version":3,"file":"version-BFw4junA.js","names":[],"sources":["../src/instructions.ts","../src/resources.ts","../src/version.ts"],"sourcesContent":["/**\n * MCP Server Instructions\n *\n * These instructions are sent to Claude Desktop during initialization\n * and used as context/hints for the LLM. This ensures the AI agent\n * knows how to properly use the Productive.io MCP server.\n *\n * The content is derived from skills/SKILL.md (without YAML frontmatter).\n */\n\nimport { readFileSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\n/**\n * Load instructions from SKILL.md file\n * Removes YAML frontmatter (content between --- markers)\n */\nfunction loadInstructions(): string {\n  try {\n    // In dist/, go up to package root, then to skills/\n    const skillPath = join(__dirname, '..', 'skills', 'SKILL.md');\n    const content = readFileSync(skillPath, 'utf-8');\n\n    // Remove YAML frontmatter (between --- markers at start of file)\n    const withoutFrontmatter = content.replace(/^---\\n[\\s\\S]*?\\n---\\n+/, '');\n\n    return withoutFrontmatter.trim();\n  } catch {\n    // Fallback if file not found (shouldn't happen in production)\n    return 'Productive.io MCP Server - Use the productive tool with resource and action parameters.';\n  }\n}\n\nexport const INSTRUCTIONS = loadInstructions();\n","/**\n * MCP Resources handlers for Productive MCP Server\n *\n * Exposes Productive data via MCP resources/ capability so clients can browse\n * and read data without tool calls.\n *\n * Static resources (always available):\n *   productive://schema          — full resource schema overview\n *   productive://instructions    — server instructions / SKILL.md content\n *\n * Resource templates (parameterized, require API calls):\n *   productive://projects/{id}            — project details\n *   productive://tasks/{id}               — task details\n *   productive://people/{id}              — person details\n *   productive://deals/{id}               — deal details\n *   productive://projects/{id}/tasks      — tasks for a project\n *   productive://projects/{id}/services   — services for a project\n *\n * Dynamic resources (computed):\n *   productive://summaries/my_day         — personal dashboard\n *   productive://summaries/team_pulse     — team activity\n */\n\nimport type { ReadResourceResult as McpReadResourceResult } from '@modelcontextprotocol/sdk/types.js';\n\nimport { ProductiveApi } from '@studiometa/productive-api';\nimport { fromHandlerContext } from '@studiometa/productive-core';\n\nimport type { ProductiveCredentials } from './auth.js';\nimport type { HandlerContext } from './handlers/types.js';\n\nimport { handleDeals } from './handlers/deals.js';\nimport { handlePeople } from './handlers/people.js';\nimport { handleProjects } from './handlers/projects.js';\nimport { handleSchemaOverview } from './handlers/schema.js';\nimport { handleServices } from './handlers/services.js';\nimport { handleSummaries } from './handlers/summaries.js';\nimport { handleTasks } from './handlers/tasks.js';\nimport { INSTRUCTIONS } from './instructions.js';\n\n/** MIME type used for all resource content */\nconst MIME_TYPE = 'application/json';\n\n/**\n * A single resource content item returned in resources/read responses\n */\nexport interface ResourceContent {\n  uri: string;\n  mimeType: string;\n  text: string;\n}\n\n/**\n * Shape of a resources/read response (re-export of SDK type for consumers)\n */\nexport type ReadResourceResult = McpReadResourceResult;\n\n/**\n * Shape of a static resource descriptor (resources/list)\n */\nexport interface StaticResource {\n  uri: string;\n  name: string;\n  description: string;\n  mimeType: string;\n}\n\n/**\n * Shape of a resource template descriptor (resources/templates/list)\n */\nexport interface ResourceTemplate {\n  uriTemplate: string;\n  name: string;\n  description: string;\n  mimeType: string;\n}\n\n// ---------------------------------------------------------------------------\n// Static resource definitions\n// ---------------------------------------------------------------------------\n\n/**\n * Static resources that are always available without API credentials\n */\nexport const STATIC_RESOURCES: StaticResource[] = [\n  {\n    uri: 'productive://schema',\n    name: 'Schema',\n    description: 'Overview of all Productive.io resources, their actions and filters',\n    mimeType: MIME_TYPE,\n  },\n  {\n    uri: 'productive://instructions',\n    name: 'Instructions',\n    description: 'Server instructions and usage guide for the Productive.io MCP server',\n    mimeType: MIME_TYPE,\n  },\n];\n\n// ---------------------------------------------------------------------------\n// Dynamic resource definitions\n// ---------------------------------------------------------------------------\n\n/**\n * Dynamic resources that are computed at read time (require credentials)\n */\nexport const DYNAMIC_RESOURCES: StaticResource[] = [\n  {\n    uri: 'productive://summaries/my_day',\n    name: 'My Day',\n    description: \"Personal dashboard: open tasks, today's time entries, active timers\",\n    mimeType: MIME_TYPE,\n  },\n  {\n    uri: 'productive://summaries/team_pulse',\n    name: 'Team Pulse',\n    description: 'Team-wide time tracking activity for today',\n    mimeType: MIME_TYPE,\n  },\n];\n\n// ---------------------------------------------------------------------------\n// Resource template definitions\n// ---------------------------------------------------------------------------\n\n/**\n * Resource templates that accept URI parameters (require credentials)\n */\nexport const RESOURCE_TEMPLATES: ResourceTemplate[] = [\n  {\n    uriTemplate: 'productive://projects/{id}',\n    name: 'Project',\n    description: 'Details of a specific project by ID',\n    mimeType: MIME_TYPE,\n  },\n  {\n    uriTemplate: 'productive://tasks/{id}',\n    name: 'Task',\n    description: 'Details of a specific task by ID',\n    mimeType: MIME_TYPE,\n  },\n  {\n    uriTemplate: 'productive://people/{id}',\n    name: 'Person',\n    description: 'Details of a specific person by ID',\n    mimeType: MIME_TYPE,\n  },\n  {\n    uriTemplate: 'productive://deals/{id}',\n    name: 'Deal',\n    description: 'Details of a specific deal or budget by ID',\n    mimeType: MIME_TYPE,\n  },\n  {\n    uriTemplate: 'productive://projects/{id}/tasks',\n    name: 'Project Tasks',\n    description: 'All tasks belonging to a specific project',\n    mimeType: MIME_TYPE,\n  },\n  {\n    uriTemplate: 'productive://projects/{id}/services',\n    name: 'Project Services',\n    description: 'All services belonging to a specific project',\n    mimeType: MIME_TYPE,\n  },\n];\n\n// ---------------------------------------------------------------------------\n// URI pattern matching\n// ---------------------------------------------------------------------------\n\n/** Route patterns and their handler factories */\nconst URI_PATTERNS: Array<{\n  pattern: RegExp;\n  handler: (match: RegExpMatchArray, credentials: ProductiveCredentials) => Promise<unknown>;\n}> = [\n  // Static resources (no credentials needed)\n  {\n    pattern: /^productive:\\/\\/schema$/,\n    handler: async () => {\n      const result = handleSchemaOverview();\n      const text = result.content[0] as { text: string };\n      return JSON.parse(text.text);\n    },\n  },\n  {\n    pattern: /^productive:\\/\\/instructions$/,\n    handler: async () => ({ instructions: INSTRUCTIONS }),\n  },\n\n  // Dynamic summaries\n  {\n    pattern: /^productive:\\/\\/summaries\\/my_day$/,\n    handler: async (_, credentials) => {\n      const ctx = buildHandlerContext(credentials);\n      const result = await handleSummaries('my_day', {}, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n  {\n    pattern: /^productive:\\/\\/summaries\\/team_pulse$/,\n    handler: async (_, credentials) => {\n      const ctx = buildHandlerContext(credentials);\n      const result = await handleSummaries('team_pulse', {}, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n\n  // Project nested resources (before single project to avoid conflict)\n  {\n    pattern: /^productive:\\/\\/projects\\/([^/]+)\\/tasks$/,\n    handler: async ([, id], credentials) => {\n      const ctx = buildHandlerContext(credentials, { filter: { project_id: id } });\n      const result = await handleTasks('list', { project_id: id }, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n  {\n    pattern: /^productive:\\/\\/projects\\/([^/]+)\\/services$/,\n    handler: async ([, id], credentials) => {\n      const ctx = buildHandlerContext(credentials, { filter: { project_id: id } });\n      // handleServices uses CommonArgs; project_id is passed via ctx.filter\n      const result = await handleServices('list', {}, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n\n  // Single entity resources\n  {\n    pattern: /^productive:\\/\\/projects\\/([^/]+)$/,\n    handler: async ([, id], credentials) => {\n      const ctx = buildHandlerContext(credentials);\n      const result = await handleProjects('get', { id }, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n  {\n    pattern: /^productive:\\/\\/tasks\\/([^/]+)$/,\n    handler: async ([, id], credentials) => {\n      const ctx = buildHandlerContext(credentials);\n      const result = await handleTasks('get', { id }, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n  {\n    pattern: /^productive:\\/\\/people\\/([^/]+)$/,\n    handler: async ([, id], credentials) => {\n      const ctx = buildHandlerContext(credentials);\n      const result = await handlePeople('get', { id }, ctx, credentials);\n      return extractJsonFromResult(result);\n    },\n  },\n  {\n    pattern: /^productive:\\/\\/deals\\/([^/]+)$/,\n    handler: async ([, id], credentials) => {\n      const ctx = buildHandlerContext(credentials);\n      const result = await handleDeals('get', { id }, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n];\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Build a HandlerContext from credentials, with optional filter overrides.\n */\nfunction buildHandlerContext(\n  credentials: ProductiveCredentials,\n  overrides: { filter?: Record<string, string> } = {},\n): HandlerContext {\n  const api = new ProductiveApi({\n    config: {\n      apiToken: credentials.apiToken,\n      organizationId: credentials.organizationId,\n      userId: credentials.userId,\n      baseUrl: process.env.PRODUCTIVE_BASE_URL,\n    },\n  });\n\n  const execCtx = fromHandlerContext({ api }, { userId: credentials.userId });\n\n  return {\n    formatOptions: { compact: false },\n    filter: overrides.filter,\n    perPage: 50,\n    includeHints: false,\n    includeSuggestions: false,\n    executor: () => execCtx,\n  };\n}\n\n/**\n * Extract the parsed JSON data from a ToolResult.\n * Throws if the result is an error or not parseable.\n */\nfunction extractJsonFromResult(result: { content: unknown[]; isError?: boolean }): unknown {\n  if (result.isError) {\n    const text = (result.content[0] as { text: string }).text;\n    throw new Error(text);\n  }\n  const text = (result.content[0] as { text: string }).text;\n  try {\n    return JSON.parse(text);\n  } catch {\n    return { text };\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * List all static and dynamic resources (no credentials needed for static).\n */\nexport function listResources(): StaticResource[] {\n  return [...STATIC_RESOURCES, ...DYNAMIC_RESOURCES];\n}\n\n/**\n * List all resource templates.\n */\nexport function listResourceTemplates(): ResourceTemplate[] {\n  return RESOURCE_TEMPLATES;\n}\n\n/**\n * Read a resource by URI.\n *\n * Routes the URI to the appropriate handler. Throws on unknown URI.\n */\nexport async function readResource(\n  uri: string,\n  credentials: ProductiveCredentials,\n): Promise<ReadResourceResult> {\n  for (const { pattern, handler } of URI_PATTERNS) {\n    const match = uri.match(pattern);\n    if (match) {\n      const data = await handler(match, credentials);\n      return {\n        contents: [\n          {\n            uri,\n            mimeType: MIME_TYPE,\n            text: JSON.stringify(data, null, 2),\n          },\n        ],\n      };\n    }\n  }\n\n  throw new Error(\n    `Unknown resource URI: ${uri}. ` +\n      `Available static resources: ${STATIC_RESOURCES.map((r) => r.uri).join(', ')}. ` +\n      `Available dynamic resources: ${DYNAMIC_RESOURCES.map((r) => r.uri).join(', ')}. ` +\n      `Resource templates: ${RESOURCE_TEMPLATES.map((t) => t.uriTemplate).join(', ')}.`,\n  );\n}\n","/**\n * Package version - injected from package.json at build time\n */\ndeclare const __VERSION__: string;\nexport const VERSION = __VERSION__;\n"],"mappings":"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"}
+{"version":3,"file":"version-Dm6m3p60.js","names":[],"sources":["../src/instructions.ts","../src/resources.ts","../src/version.ts"],"sourcesContent":["/**\n * MCP Server Instructions\n *\n * These instructions are sent to Claude Desktop during initialization\n * and used as context/hints for the LLM. This ensures the AI agent\n * knows how to properly use the Productive.io MCP server.\n *\n * The content is derived from skills/SKILL.md (without YAML frontmatter).\n */\n\nimport { readFileSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\n/**\n * Load instructions from SKILL.md file\n * Removes YAML frontmatter (content between --- markers)\n */\nfunction loadInstructions(): string {\n  try {\n    // In dist/, go up to package root, then to skills/\n    const skillPath = join(__dirname, '..', 'skills', 'SKILL.md');\n    const content = readFileSync(skillPath, 'utf-8');\n\n    // Remove YAML frontmatter (between --- markers at start of file)\n    const withoutFrontmatter = content.replace(/^---\\n[\\s\\S]*?\\n---\\n+/, '');\n\n    return withoutFrontmatter.trim();\n  } catch {\n    // Fallback if file not found (shouldn't happen in production)\n    return 'Productive.io MCP Server - Use the productive tool with resource and action parameters.';\n  }\n}\n\nexport const INSTRUCTIONS = loadInstructions();\n","/**\n * MCP Resources handlers for Productive MCP Server\n *\n * Exposes Productive data via MCP resources/ capability so clients can browse\n * and read data without tool calls.\n *\n * Static resources (always available):\n *   productive://schema          — full resource schema overview\n *   productive://instructions    — server instructions / SKILL.md content\n *\n * Resource templates (parameterized, require API calls):\n *   productive://projects/{id}            — project details\n *   productive://tasks/{id}               — task details\n *   productive://people/{id}              — person details\n *   productive://deals/{id}               — deal details\n *   productive://projects/{id}/tasks      — tasks for a project\n *   productive://projects/{id}/services   — services for a project\n *\n * Dynamic resources (computed):\n *   productive://summaries/my_day         — personal dashboard\n *   productive://summaries/team_pulse     — team activity\n */\n\nimport type { ReadResourceResult as McpReadResourceResult } from '@modelcontextprotocol/sdk/types.js';\n\nimport { ProductiveApi } from '@studiometa/productive-api';\nimport { fromHandlerContext } from '@studiometa/productive-core';\n\nimport type { ProductiveCredentials } from './auth.js';\nimport type { HandlerContext } from './handlers/types.js';\n\nimport { handleDeals } from './handlers/deals.js';\nimport { handlePeople } from './handlers/people.js';\nimport { handleProjects } from './handlers/projects.js';\nimport { handleSchemaOverview } from './handlers/schema.js';\nimport { handleServices } from './handlers/services.js';\nimport { handleSummaries } from './handlers/summaries.js';\nimport { handleTasks } from './handlers/tasks.js';\nimport { INSTRUCTIONS } from './instructions.js';\n\n/** MIME type used for all resource content */\nconst MIME_TYPE = 'application/json';\n\n/**\n * A single resource content item returned in resources/read responses\n */\nexport interface ResourceContent {\n  uri: string;\n  mimeType: string;\n  text: string;\n}\n\n/**\n * Shape of a resources/read response (re-export of SDK type for consumers)\n */\nexport type ReadResourceResult = McpReadResourceResult;\n\n/**\n * Shape of a static resource descriptor (resources/list)\n */\nexport interface StaticResource {\n  uri: string;\n  name: string;\n  description: string;\n  mimeType: string;\n}\n\n/**\n * Shape of a resource template descriptor (resources/templates/list)\n */\nexport interface ResourceTemplate {\n  uriTemplate: string;\n  name: string;\n  description: string;\n  mimeType: string;\n}\n\n// ---------------------------------------------------------------------------\n// Static resource definitions\n// ---------------------------------------------------------------------------\n\n/**\n * Static resources that are always available without API credentials\n */\nexport const STATIC_RESOURCES: StaticResource[] = [\n  {\n    uri: 'productive://schema',\n    name: 'Schema',\n    description: 'Overview of all Productive.io resources, their actions and filters',\n    mimeType: MIME_TYPE,\n  },\n  {\n    uri: 'productive://instructions',\n    name: 'Instructions',\n    description: 'Server instructions and usage guide for the Productive.io MCP server',\n    mimeType: MIME_TYPE,\n  },\n];\n\n// ---------------------------------------------------------------------------\n// Dynamic resource definitions\n// ---------------------------------------------------------------------------\n\n/**\n * Dynamic resources that are computed at read time (require credentials)\n */\nexport const DYNAMIC_RESOURCES: StaticResource[] = [\n  {\n    uri: 'productive://summaries/my_day',\n    name: 'My Day',\n    description: \"Personal dashboard: open tasks, today's time entries, active timers\",\n    mimeType: MIME_TYPE,\n  },\n  {\n    uri: 'productive://summaries/team_pulse',\n    name: 'Team Pulse',\n    description: 'Team-wide time tracking activity for today',\n    mimeType: MIME_TYPE,\n  },\n];\n\n// ---------------------------------------------------------------------------\n// Resource template definitions\n// ---------------------------------------------------------------------------\n\n/**\n * Resource templates that accept URI parameters (require credentials)\n */\nexport const RESOURCE_TEMPLATES: ResourceTemplate[] = [\n  {\n    uriTemplate: 'productive://projects/{id}',\n    name: 'Project',\n    description: 'Details of a specific project by ID',\n    mimeType: MIME_TYPE,\n  },\n  {\n    uriTemplate: 'productive://tasks/{id}',\n    name: 'Task',\n    description: 'Details of a specific task by ID',\n    mimeType: MIME_TYPE,\n  },\n  {\n    uriTemplate: 'productive://people/{id}',\n    name: 'Person',\n    description: 'Details of a specific person by ID',\n    mimeType: MIME_TYPE,\n  },\n  {\n    uriTemplate: 'productive://deals/{id}',\n    name: 'Deal',\n    description: 'Details of a specific deal or budget by ID',\n    mimeType: MIME_TYPE,\n  },\n  {\n    uriTemplate: 'productive://projects/{id}/tasks',\n    name: 'Project Tasks',\n    description: 'All tasks belonging to a specific project',\n    mimeType: MIME_TYPE,\n  },\n  {\n    uriTemplate: 'productive://projects/{id}/services',\n    name: 'Project Services',\n    description: 'All services belonging to a specific project',\n    mimeType: MIME_TYPE,\n  },\n];\n\n// ---------------------------------------------------------------------------\n// URI pattern matching\n// ---------------------------------------------------------------------------\n\n/** Route patterns and their handler factories */\nconst URI_PATTERNS: Array<{\n  pattern: RegExp;\n  handler: (match: RegExpMatchArray, credentials: ProductiveCredentials) => Promise<unknown>;\n}> = [\n  // Static resources (no credentials needed)\n  {\n    pattern: /^productive:\\/\\/schema$/,\n    handler: async () => {\n      const result = handleSchemaOverview();\n      const text = result.content[0] as { text: string };\n      return JSON.parse(text.text);\n    },\n  },\n  {\n    pattern: /^productive:\\/\\/instructions$/,\n    handler: async () => ({ instructions: INSTRUCTIONS }),\n  },\n\n  // Dynamic summaries\n  {\n    pattern: /^productive:\\/\\/summaries\\/my_day$/,\n    handler: async (_, credentials) => {\n      const ctx = buildHandlerContext(credentials);\n      const result = await handleSummaries('my_day', {}, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n  {\n    pattern: /^productive:\\/\\/summaries\\/team_pulse$/,\n    handler: async (_, credentials) => {\n      const ctx = buildHandlerContext(credentials);\n      const result = await handleSummaries('team_pulse', {}, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n\n  // Project nested resources (before single project to avoid conflict)\n  {\n    pattern: /^productive:\\/\\/projects\\/([^/]+)\\/tasks$/,\n    handler: async ([, id], credentials) => {\n      const ctx = buildHandlerContext(credentials, { filter: { project_id: id } });\n      const result = await handleTasks('list', { project_id: id }, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n  {\n    pattern: /^productive:\\/\\/projects\\/([^/]+)\\/services$/,\n    handler: async ([, id], credentials) => {\n      const ctx = buildHandlerContext(credentials, { filter: { project_id: id } });\n      // handleServices uses CommonArgs; project_id is passed via ctx.filter\n      const result = await handleServices('list', {}, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n\n  // Single entity resources\n  {\n    pattern: /^productive:\\/\\/projects\\/([^/]+)$/,\n    handler: async ([, id], credentials) => {\n      const ctx = buildHandlerContext(credentials);\n      const result = await handleProjects('get', { id }, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n  {\n    pattern: /^productive:\\/\\/tasks\\/([^/]+)$/,\n    handler: async ([, id], credentials) => {\n      const ctx = buildHandlerContext(credentials);\n      const result = await handleTasks('get', { id }, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n  {\n    pattern: /^productive:\\/\\/people\\/([^/]+)$/,\n    handler: async ([, id], credentials) => {\n      const ctx = buildHandlerContext(credentials);\n      const result = await handlePeople('get', { id }, ctx, credentials);\n      return extractJsonFromResult(result);\n    },\n  },\n  {\n    pattern: /^productive:\\/\\/deals\\/([^/]+)$/,\n    handler: async ([, id], credentials) => {\n      const ctx = buildHandlerContext(credentials);\n      const result = await handleDeals('get', { id }, ctx);\n      return extractJsonFromResult(result);\n    },\n  },\n];\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Build a HandlerContext from credentials, with optional filter overrides.\n */\nfunction buildHandlerContext(\n  credentials: ProductiveCredentials,\n  overrides: { filter?: Record<string, string> } = {},\n): HandlerContext {\n  const api = new ProductiveApi({\n    config: {\n      apiToken: credentials.apiToken,\n      organizationId: credentials.organizationId,\n      userId: credentials.userId,\n      baseUrl: process.env.PRODUCTIVE_BASE_URL,\n    },\n  });\n\n  const execCtx = fromHandlerContext({ api }, { userId: credentials.userId });\n\n  return {\n    formatOptions: { compact: false },\n    filter: overrides.filter,\n    perPage: 50,\n    includeHints: false,\n    includeSuggestions: false,\n    executor: () => execCtx,\n  };\n}\n\n/**\n * Extract the parsed JSON data from a ToolResult.\n * Throws if the result is an error or not parseable.\n */\nfunction extractJsonFromResult(result: { content: unknown[]; isError?: boolean }): unknown {\n  if (result.isError) {\n    const text = (result.content[0] as { text: string }).text;\n    throw new Error(text);\n  }\n  const text = (result.content[0] as { text: string }).text;\n  try {\n    return JSON.parse(text);\n  } catch {\n    return { text };\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * List all static and dynamic resources (no credentials needed for static).\n */\nexport function listResources(): StaticResource[] {\n  return [...STATIC_RESOURCES, ...DYNAMIC_RESOURCES];\n}\n\n/**\n * List all resource templates.\n */\nexport function listResourceTemplates(): ResourceTemplate[] {\n  return RESOURCE_TEMPLATES;\n}\n\n/**\n * Read a resource by URI.\n *\n * Routes the URI to the appropriate handler. Throws on unknown URI.\n */\nexport async function readResource(\n  uri: string,\n  credentials: ProductiveCredentials,\n): Promise<ReadResourceResult> {\n  for (const { pattern, handler } of URI_PATTERNS) {\n    const match = uri.match(pattern);\n    if (match) {\n      const data = await handler(match, credentials);\n      return {\n        contents: [\n          {\n            uri,\n            mimeType: MIME_TYPE,\n            text: JSON.stringify(data, null, 2),\n          },\n        ],\n      };\n    }\n  }\n\n  throw new Error(\n    `Unknown resource URI: ${uri}. ` +\n      `Available static resources: ${STATIC_RESOURCES.map((r) => r.uri).join(', ')}. ` +\n      `Available dynamic resources: ${DYNAMIC_RESOURCES.map((r) => r.uri).join(', ')}. ` +\n      `Resource templates: ${RESOURCE_TEMPLATES.map((t) => t.uriTemplate).join(', ')}.`,\n  );\n}\n","/**\n * Package version - injected from package.json at build time\n */\ndeclare const __VERSION__: string;\nexport const VERSION = __VERSION__;\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/productive-mcp",
-  "version": "0.10.9",
+  "version": "0.10.11",
   "description": "MCP server for Productive.io API - Model Context Protocol integration for Claude Desktop",
   "keywords": [
     "ai",
@@ -82,8 +82,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@studiometa/productive-api": "0.10.9",
-    "@studiometa/productive-core": "0.10.9",
+    "@studiometa/productive-api": "0.10.11",
+    "@studiometa/productive-core": "0.10.11",
     "h3": "^2.0.1-rc.14",
     "zod": "4.3.6"
   },

package/skills/SKILL.md

@@ -11,7 +11,11 @@ MCP (Model Context Protocol) server for Productive.io. Provides a single unified
 
 Before your first interaction with any resource, call `action=help` with that resource to discover valid filters, required fields, includes, and examples.
 
-## The `productive` Tool
+## MCP Tools
+
+This server exposes one high-level tool and two low-level raw API tools.
+
+### `productive`
 
 Single unified tool with this signature:
 
@@ -878,6 +882,111 @@ Returns: deal details + services + comments + time entries
 - 480 = 8 hours (full day)
 - 240 = 4 hours (half day)
 
+## Raw API Tools
+
+Use raw API tools only as escape hatches when the unified `productive` tool does not support the documented endpoint you need.
+
+### `api_read`
+
+Read-only access to documented Productive `GET` endpoints.
+
+**Use it for:** unsupported read endpoints, inspecting endpoint capabilities, or fetching raw shapes.
+
+**Parameters**
+
+- `path` — required relative API path starting with `/`
+- `describe` — return endpoint documentation instead of executing
+- `filter` — validated against the endpoint spec
+- `include` — related resources to include
+- `sort` — validated sort values
+- `page`, `per_page` — page number and size (`per_page` max `200`)
+- `paginate`, `max_pages` — safe auto-pagination (`max_pages` default `20`, max `50`)
+
+**Safety model**
+
+- `GET` only
+- relative paths only; absolute URLs are rejected
+- path traversal is rejected
+- only documented Productive endpoints are allowed
+- filter fields, operators, and sort values are validated
+
+**Recommended workflow**
+
+1. Call `api_read` with `describe=true`
+2. Review allowed methods, filters, and sort values
+3. Make the real read call with the validated path and params
+
+**Examples**
+
+```json
+{ "path": "/invoices", "describe": true }
+```
+
+```json
+{
+  "path": "/projects/123/tasks",
+  "filter": { "status": "open" },
+  "sort": ["due_date"],
+  "per_page": 50
+}
+```
+
+### `api_write`
+
+Raw write access to documented Productive endpoints.
+
+**Use it only when:** the user explicitly wants a mutation and the higher-level `productive` tool cannot perform it.
+
+**Parameters**
+
+- `method` — required, one of `POST`, `PATCH`, `PUT`, `DELETE`
+- `path` — required relative API path
+- `body` — request payload
+- `confirm` — required, must be `true`
+- `dry_run` — preview the normalized request without executing it
+
+**Safety model**
+
+- disabled by default
+- requires server env `PRODUCTIVE_MCP_ENABLE_API_WRITE=true`
+- requires `confirm=true` on every call
+- only documented Productive endpoints are allowed
+- relative paths only; absolute URLs and traversal are rejected
+- prefer `dry_run=true` before the real write
+
+**Agent rules**
+
+1. Do not use `api_write` for routine mutations already covered by `productive`
+2. Always confirm intent with the user before using `api_write`
+3. Prefer `dry_run=true` first, then execute only after approval
+4. Preserve Productive payloads exactly; do not invent fields or IDs
+
+**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 (stdio mode only)
 
 In local/stdio mode, additional configuration tools are available:
@@ -918,6 +1027,9 @@ Key points:
 5. **Check `people.me`** first to get the current user's ID for filters
 6. **Follow `_hints`** - When getting a resource, check the `_hints` field for suggestions on fetching related context
 7. **Act on `_suggestions`** - When present, `_suggestions` highlight data issues (overdue tasks, no time logged, etc.) that may need attention or should be surfaced to the user
+8. **Prefer `api_read` over `api_write`** when a raw endpoint is needed
+9. **Use `api_read.describe=true` first** before making raw API calls
+10. **Treat `api_write` as break-glass access** - confirm, dry-run, then execute
 
 ## Prompt Templates