punchline-mcp 1.3.0 → 1.4.1

package/README.md

@@ -49,7 +49,7 @@ claude mcp add punchline --env PUNCHLINE_API_KEY=pnchl_live_... -- node /path/to
 | Variable | Required | Default | Notes |
 |---|---|---|---|
 | `PUNCHLINE_API_KEY` | Yes | — | A `pnchl_live_…` project key or a `pnchl_user_…` user provisioning key. Sent as `X-Punchline-Key`. |
-| `PUNCHLINE_BASE_URL` | No | `https://proding.co:8050` | Punchline API origin. |
+| `PUNCHLINE_BASE_URL` | No | `https://proding.co:8050` | Punchline API base URL. A path prefix (e.g. `https://host/punchline`) is kept in front of `/api/v1/…` *(1.4.1+)*. |
 
 Any other key prefix, or a missing key, fails at startup with a `ConfigError` on stderr.
 
@@ -71,10 +71,10 @@ the server twice under two names with two different keys, e.g. `punchline` (proj
 
 | Tool | Available with | Description |
 |---|---|---|
-| `create_ticket` | project key | Create a ticket. `reporter_email` is required. Supports idempotent retries via `idempotency_key`, sent to the API as the `idempotencyKey` body field. Optional `custom_fields` (sent as `customFields`) is an array of `{ name, value }` pairs; `name` must match a custom-field definition configured on the project or the request is rejected with 400. |
+| `create_ticket` | project key | Create a ticket. `reporter_email` is required. Supports idempotent retries via `idempotency_key`, sent to the API as the `idempotencyKey` body field. Optional `custom_fields` (sent as `customFields`) is an array of `{ name, value }` pairs; `name` must match a custom-field definition configured on the project or the request is rejected with 400. `description` is at most 16 000 characters, the API's limit *(1.4.1+; was wrongly 50 000)*. |
 | `list_tickets` | project key | List tickets visible to the key (own tickets, or the whole project with `read:all`). Paginated. |
 | `get_ticket` | project key | Fetch one ticket by display id (e.g. `ACM-7`). |
-| `update_ticket` | project key | Change a ticket's workflow status, its priority, its labels, and/or customer-facing public summary. Setting `priority` records a **triage ruling** — confirming the current value counts as one — which a project enforcing triage requires before a ticket can close. Priority is applied before status, so one call can triage and close. A ticket created through this API arrives untriaged: the priority sent at creation is the reporter's proposal, not a ruling. *(1.2.0+)* `labels` is a **replace-set** applied before everything else: omit it to leave the labels alone, send the full list to change them, send `[]` to clear them — unknown names are created, exactly as at `create_ticket`; a blank name is refused by both tools rather than silently dropped, and surrounding whitespace is stripped server-side. *(1.3.0+)* |
+| `update_ticket` | project key | Change a ticket's workflow status, its priority, its labels, and/or customer-facing public summary. Setting `priority` records a **triage ruling** — confirming the current value counts as one — which a project enforcing triage requires before a ticket can close. Priority is applied before status, so one call can triage and close. A ticket created through this API arrives untriaged: the priority sent at creation is the reporter's proposal, not a ruling. *(1.2.0+)* `labels` is a **replace-set** applied before everything else: omit it to leave the labels alone, send the full list to change them, send `[]` to clear them — unknown names are created, exactly as at `create_ticket`; a blank name is refused by both tools rather than silently dropped, and surrounding whitespace is stripped server-side. *(1.3.0+)* `title` and `description` may also be patched: `title` is trimmed and rejected if blank, `description` **replaces only the reporter-authored body**, preserving the `**Reported by** … via …` provenance header the ticket was created with — send `""` to clear the body and keep just the header. Both are applied before `labels`, `priority` and `status`. *(1.4.0+)* |
 | `add_communication` | project key | Post a customer-facing communication (external comment) on a ticket. |
 | `link_tickets` | project key | Link two tickets. `relation` is one of `BLOCKS`, `BLOCKED_BY`, `DUPLICATES`, `DUPLICATE_OF`, `RELATES_TO`, read from the perspective of the ticket in `display_id` — the same vocabulary `get_ticket` returns in `linkedTickets`, so a relation round-trips. ⚠️ `close_as_duplicate: true` also **closes the `display_id` ticket and emails its reporter**; it requires `relation=DUPLICATES` and is not undone by `unlink_tickets`. |
 | `unlink_tickets` | project key | Remove a link. `relation` must match how the link reads from the ticket in `display_id`. |

package/dist/client.js

@@ -1,4 +1,17 @@
 export const DEFAULT_BASE_URL = 'https://proding.co:8050';
+/**
+ * Joins an API path onto the base URL keeping any path prefix the base carries. `new URL('/api/v1/x', base)`
+ * would resolve the absolute path against the origin and drop a prefix such as `https://host/punchline`.
+ */
+export function joinUrl(baseUrl, path) {
+    const base = new URL(baseUrl);
+    const prefix = base.pathname.replace(/\/+$/, '');
+    const suffix = path.startsWith('/') ? path : `/${path}`;
+    base.pathname = `${prefix}${suffix}`;
+    base.search = '';
+    base.hash = '';
+    return base;
+}
 export class ApiError extends Error {
     status;
     title;
@@ -25,7 +38,7 @@ export class PunchlineClient {
         this.baseUrl = baseUrl;
     }
     async request(method, path, opts = {}) {
-        const url = new URL(path, this.baseUrl);
+        const url = joinUrl(this.baseUrl, path);
         for (const [k, v] of Object.entries(opts.query ?? {})) {
             if (v !== undefined)
                 url.searchParams.set(k, String(v));

package/dist/server.js

@@ -1,3 +1,4 @@
+import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { DEFAULT_BASE_URL, PunchlineClient } from './client.js';
 import { registerCommunicationTools, COMMUNICATION_TOOL_NAMES } from './tools/communications.js';
@@ -5,6 +6,9 @@ import { registerLinkTools, LINK_TOOL_NAMES } from './tools/links.js';
 import { registerMetaTools, META_TOOL_NAMES } from './tools/meta.js';
 import { registerProvisioningTools, PROVISIONING_TOOL_NAMES } from './tools/provisioning.js';
 import { registerTicketTools, TICKET_TOOL_NAMES } from './tools/tickets.js';
+// package.json sits one level above both src/ (tests) and dist/ (the built and published package; npm always
+// ships package.json), so the same relative path works everywhere.
+export const SERVER_VERSION = createRequire(import.meta.url)('../package.json').version;
 export const PROJECT_KEY_PREFIX = 'pnchl_live_';
 export const USER_KEY_PREFIX = 'pnchl_user_';
 export class ConfigError extends Error {
@@ -20,7 +24,7 @@ export function parseConfig(env) {
     return { apiKey, baseUrl: env.PUNCHLINE_BASE_URL?.trim() || DEFAULT_BASE_URL };
 }
 export function buildServer(config) {
-    const server = new McpServer({ name: 'punchline', version: '0.1.0' });
+    const server = new McpServer({ name: 'punchline', version: SERVER_VERSION });
     const client = new PunchlineClient(config.apiKey, config.baseUrl);
     const registeredTools = [];
     if (config.apiKey.startsWith(USER_KEY_PREFIX)) {

package/dist/tools/tickets.js

@@ -18,6 +18,8 @@ export const CROSS_PROJECT_LINK_NOTE = ' Links to tickets in other projects are
 const LABEL_NAME = z.string().max(100)
     .refine((n) => n.trim().length > 0, { message: 'Label names must not be blank' });
 export const TICKETS_PATH = '/api/v1/external/tickets';
+/** ExternalTicketRequest / ExternalTicketPatchRequest: `@Size(max = 16_000) String description`. */
+export const DESCRIPTION_MAX = 16_000;
 export function ticketPath(displayId) {
     return `${TICKETS_PATH}/${encodeURIComponent(displayId)}`;
 }
@@ -31,7 +33,8 @@ export function registerTicketTools(server, client) {
         inputSchema: {
             title: z.string().min(1).max(500).describe('Ticket title'),
             reporter_email: z.string().min(1).email().max(320).describe('Reporter email (required by the API)'),
-            description: z.string().max(50000).optional(),
+            description: z.string().max(DESCRIPTION_MAX).optional()
+                .describe('Ticket description (markdown), at most 16 000 characters.'),
             type: z.enum(TICKET_TYPES).optional().describe('Defaults to BUG'),
             priority: z.enum(TICKET_PRIORITIES).optional().describe('Defaults to MEDIUM'),
             labels: z.array(LABEL_NAME).max(100).optional().describe('Label names; unknown labels are created'),
@@ -94,7 +97,7 @@ export function registerTicketTools(server, client) {
         },
     }, tool(async (a) => client.request('GET', ticketPath(a.display_id))));
     server.registerTool('update_ticket', {
-        description: 'Update a ticket: change its workflow status, its priority, its labels, and/or the customer-facing public summary. At least one field is required; an empty public_summary clears it. Setting priority records a triage ruling — confirming the existing value counts — which is what a project requiring triage before close demands. Priority is applied before status, so one call can triage and close. Labels are applied first, and are a replace-set: omit the field to leave them alone, pass the full list to change them, pass [] to clear them.'
+        description: 'Update a ticket: change its workflow status, its priority, its labels, and/or the customer-facing public summary. At least one field is required; an empty public_summary clears it. Setting priority records a triage ruling — confirming the existing value counts — which is what a project requiring triage before close demands. Priority is applied before status, so one call can triage and close. Labels are applied first, and are a replace-set: omit the field to leave them alone, pass the full list to change them, pass [] to clear them. Title and description may also be patched; a description patch replaces only the reporter-authored body and keeps the "Reported by" header the ticket was created with.'
             + CROSS_PROJECT_LINK_NOTE,
         inputSchema: {
             display_id: z.string().min(1),
@@ -105,11 +108,18 @@ export function registerTicketTools(server, client) {
             labels: z.array(LABEL_NAME).max(100).optional()
                 .describe('Replaces the ticket\'s labels with exactly these names; unknown labels are created.'
                 + ' Omit to leave them untouched, [] to clear them.'),
+            title: z.string().min(1).max(500).optional()
+                .describe('Replaces the ticket title. Must not be blank.'),
+            description: z.string().max(DESCRIPTION_MAX).optional()
+                .describe('Replaces the reporter-authored body of the description (at most 16 000 characters). The'
+                + ' "Reported by … via …" header a ticket was created with is preserved;'
+                + ' pass "" to clear the body and keep only that header.'),
         },
     }, tool(async (a) => {
         if (a.status === undefined && a.public_summary === undefined
-            && a.priority === undefined && a.labels === undefined) {
-            throw new Error('Provide status, priority, labels and/or public_summary');
+            && a.priority === undefined && a.labels === undefined
+            && a.title === undefined && a.description === undefined) {
+            throw new Error('Provide status, priority, labels, title, description and/or public_summary');
         }
         // JSON.stringify drops undefined keys, which is what keeps "omitted" distinct from "[]" on
         // the wire — the API reads an absent labels key as "leave them alone" (RUBE-46).
@@ -117,6 +127,7 @@ export function registerTicketTools(server, client) {
             body: {
                 status: a.status, publicSummary: a.public_summary,
                 priority: a.priority, labels: a.labels,
+                title: a.title, description: a.description,
             },
         });
     }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "punchline-mcp",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "MCP stdio server exposing the Punchline external API as tools",
   "type": "module",
   "license": "MIT",