punchline-mcp 1.0.0 → 1.2.0

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 | `http://proding.co:8050` | Punchline API origin. |
+| `PUNCHLINE_BASE_URL` | No | `https://proding.co:8050` | Punchline API origin. |
 
 Any other key prefix, or a missing key, fails at startup with a `ConfigError` on stderr.
 
@@ -57,8 +57,9 @@ Any other key prefix, or a missing key, fails at startup with a `ConfigError` on
 
 The server registers a different tool set depending on the key prefix:
 
-- **`pnchl_live_…` (project key)** — registers the 7 ticket/project tools: `create_ticket`,
-  `list_tickets`, `get_ticket`, `update_ticket`, `add_communication`, `whoami`, `get_changelog`.
+- **`pnchl_live_…` (project key)** — registers the 9 ticket/project tools: `create_ticket`,
+  `list_tickets`, `get_ticket`, `update_ticket`, `add_communication`, `link_tickets`,
+  `unlink_tickets`, `whoami`, `get_changelog`.
 - **`pnchl_user_…` (user provisioning key)** — registers only `create_project`, which returns a
   ONE-TIME project API key.
 
@@ -70,11 +71,19 @@ 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. |
+| `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. |
 | `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 and/or customer-facing public summary. |
+| `update_ticket` | project key | Change a ticket's workflow status, its priority, 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+)* |
 | `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`. |
+
+> **Cross-project links are omitted from every response.** These endpoints can only create links
+> within your own project, but a staff member can link one of your tickets to a ticket in another
+> project from the Punchline UI. Those are filtered out of `linkedTickets` and `links` alike — so a
+> ticket may carry links you cannot see, and a `409 Link already exists` from `link_tickets` can
+> refer to one of them.
 | `whoami` | project key | Introspect the configured key: project, key name, scopes, last use. Useful for self-diagnosing 403s. |
 | `get_changelog` | project key | Recent externally-visible ticket changes for the project. |
 | `create_project` | user key | Provision a new Punchline project. Returns the project and a ONE-TIME project API key. |
@@ -88,7 +97,7 @@ Or run the server directly and check the startup log on stderr:
 
 ```bash
 PUNCHLINE_API_KEY=pnchl_live_... node dist/index.js
-# punchline-mcp: 7 tool(s) registered [create_ticket, list_tickets, get_ticket, update_ticket, add_communication, whoami, get_changelog]
+# punchline-mcp: 9 tool(s) registered [create_ticket, list_tickets, get_ticket, update_ticket, add_communication, link_tickets, unlink_tickets, whoami, get_changelog]
 ```
 
 ## Errors

package/dist/client.js

@@ -1,4 +1,4 @@
-export const DEFAULT_BASE_URL = 'http://proding.co:8050';
+export const DEFAULT_BASE_URL = 'https://proding.co:8050';
 export class ApiError extends Error {
     status;
     title;

package/dist/server.js

@@ -1,6 +1,7 @@
 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';
+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';
@@ -29,8 +30,9 @@ export function buildServer(config) {
     else if (config.apiKey.startsWith(PROJECT_KEY_PREFIX)) {
         registerTicketTools(server, client);
         registerCommunicationTools(server, client);
+        registerLinkTools(server, client);
         registerMetaTools(server, client);
-        registeredTools.push(...TICKET_TOOL_NAMES, ...COMMUNICATION_TOOL_NAMES, ...META_TOOL_NAMES);
+        registeredTools.push(...TICKET_TOOL_NAMES, ...COMMUNICATION_TOOL_NAMES, ...LINK_TOOL_NAMES, ...META_TOOL_NAMES);
     }
     else {
         throw new ConfigError(`Unrecognized API key prefix. Expected ${PROJECT_KEY_PREFIX}… or ${USER_KEY_PREFIX}….`);

package/dist/tools/links.js

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { ticketPath } from './tickets.js';
+import { tool } from './util.js';
+/**
+ * The wire vocabulary is directional and mirrors what `get_ticket` returns in
+ * `linkedTickets`, so a relation read from one call can be passed straight back
+ * into another. BLOCKED_BY and DUPLICATE_OF are stored by flipping source and
+ * target server-side.
+ */
+export const LINK_RELATIONS = [
+    'BLOCKS',
+    'BLOCKED_BY',
+    'DUPLICATES',
+    'DUPLICATE_OF',
+    'RELATES_TO',
+];
+export const LINK_TOOL_NAMES = ['link_tickets', 'unlink_tickets'];
+function linksPath(displayId) {
+    return `${ticketPath(displayId)}/links`;
+}
+export function registerLinkTools(server, client) {
+    server.registerTool('link_tickets', {
+        description: 'Link two tickets in the project bound to the API key. `relation` is read from the ' +
+            'perspective of the ticket in `display_id`, using the same vocabulary `get_ticket` ' +
+            'returns in `linkedTickets`. Both tickets must be in this project and visible to the key. ' +
+            'WARNING: `close_as_duplicate` is destructive — it closes the `display_id` ticket and ' +
+            'emails its reporter. It requires relation=DUPLICATES and cannot be undone by unlinking. ' +
+            'Note: links to tickets in OTHER projects are omitted from every response this server ' +
+            'returns, so a ticket may carry links you cannot see; a 409 "link already exists" can ' +
+            'therefore refer to a link absent from get_ticket.',
+        inputSchema: {
+            display_id: z.string().min(1).describe('The ticket the relation is stated from, e.g. ACM-7'),
+            target_display_id: z.string().min(1).describe('The other ticket, e.g. ACM-9'),
+            relation: z.enum(LINK_RELATIONS).describe('From display_id\'s perspective: BLOCKS (it blocks the target), BLOCKED_BY (it is ' +
+                'blocked by the target), DUPLICATES (it is a duplicate of the target), DUPLICATE_OF ' +
+                '(the target duplicates it), RELATES_TO (undirected)'),
+            close_as_duplicate: z.boolean().optional().describe('Default false. When true, also closes the display_id ticket as a duplicate and emails ' +
+                'its reporter. Rejected with 400 unless relation is exactly DUPLICATES — that guard is ' +
+                'what keeps the closed ticket the one you named, rather than the target.'),
+        },
+    }, tool(async (a) => client.request('POST', linksPath(a.display_id), {
+        body: {
+            targetDisplayId: a.target_display_id,
+            relation: a.relation,
+            closeAsDuplicate: a.close_as_duplicate ?? false,
+        },
+    })));
+    server.registerTool('unlink_tickets', {
+        description: 'Remove a link between two tickets. `relation` must match how the link reads from the ' +
+            'ticket in `display_id` — pass back the value `get_ticket` reported in `linkedTickets`. ' +
+            'Removing a duplicate link does NOT reopen a ticket that was closed by ' +
+            'close_as_duplicate; that stays a separate status change.',
+        inputSchema: {
+            display_id: z.string().min(1).describe('The ticket the relation is stated from, e.g. ACM-7'),
+            target_display_id: z.string().min(1).describe('The other ticket, e.g. ACM-9'),
+            relation: z.enum(LINK_RELATIONS).describe('As reported by get_ticket for this ticket'),
+        },
+    }, tool(async (a) => {
+        // The API answers 204 with no body, which the client surfaces as undefined —
+        // JSON.stringify(undefined) is not a string, so return an explicit result
+        // rather than letting that reach the tool output.
+        await client.request('DELETE', `${linksPath(a.display_id)}/${encodeURIComponent(a.target_display_id)}`, {
+            query: { relation: a.relation },
+        });
+        return { deleted: true, displayId: a.display_id, targetDisplayId: a.target_display_id, relation: a.relation };
+    }));
+}

package/dist/tools/tickets.js

@@ -1,15 +1,26 @@
 import { z } from 'zod';
 import { tool } from './util.js';
-export const TICKET_TYPES = ['BUG', 'FEATURE', 'TASK', 'IMPROVEMENT', 'IDEA', 'TECHNICAL'];
+export const TICKET_TYPES = ['BUG', 'FEATURE', 'TASK', 'ENHANCEMENT', 'IDEA', 'TECHNICAL'];
 export const TICKET_PRIORITIES = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'];
 export const TICKET_TOOL_NAMES = ['create_ticket', 'list_tickets', 'get_ticket', 'update_ticket'];
+/**
+ * Appended to the description of every tool whose response carries ticket links.
+ * The API filters cross-project links out of all external responses, so an agent that
+ * treats an absent link as "no such link exists" will be wrong.
+ */
+export const CROSS_PROJECT_LINK_NOTE = ' Links to tickets in other projects are omitted from the response — a ticket may carry links'
+    + ' that are not shown here.';
 export const TICKETS_PATH = '/api/v1/external/tickets';
 export function ticketPath(displayId) {
     return `${TICKETS_PATH}/${encodeURIComponent(displayId)}`;
 }
 export function registerTicketTools(server, client) {
     server.registerTool('create_ticket', {
-        description: 'Create a ticket in the project bound to the API key. Supports idempotent retries via idempotency_key.',
+        description: 'Create a ticket in the project bound to the API key. Supports idempotent retries via idempotency_key.'
+            + ' custom_fields lets you stamp name-keyed values that other project tooling (e.g. outbound webhooks) reads back'
+            + ' later; each name must match a custom-field definition already configured on the project — an unknown name is'
+            + ' rejected with a 400 error rather than silently ignored.'
+            + CROSS_PROJECT_LINK_NOTE,
         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)'),
@@ -23,6 +34,11 @@ export function registerTicketTools(server, client) {
             app_version: z.string().max(100).optional(),
             idempotency_key: z.string().max(255).optional()
                 .describe('Same key on the same API key returns the original ticket instead of creating a duplicate'),
+            custom_fields: z.array(z.object({
+                name: z.string().min(1).max(255).describe('Must match a custom-field name configured on the project'),
+                value: z.string().max(4096),
+            })).max(50).optional()
+                .describe('Name-keyed custom field values, e.g. [{ name: "rubedyne_user_id", value: "3172" }]. An unknown name is rejected with 400.'),
         },
     }, tool(async (a) => client.request('POST', TICKETS_PATH, {
         body: {
@@ -37,10 +53,12 @@ export function registerTicketTools(server, client) {
             userAgent: a.user_agent,
             appVersion: a.app_version,
             idempotencyKey: a.idempotency_key,
+            customFields: a.custom_fields,
         },
     })));
     server.registerTool('list_tickets', {
-        description: 'List tickets visible to this API key (own tickets; whole project with the read:all scope). Paginated.',
+        description: 'List tickets visible to this API key (own tickets; whole project with the read:all scope). Paginated.'
+            + CROSS_PROJECT_LINK_NOTE,
         inputSchema: {
             page: z.number().int().min(0).optional().describe('0-based page index'),
             size: z.number().int().min(1).max(100).optional().describe('Page size (default 20)'),
@@ -62,24 +80,28 @@ export function registerTicketTools(server, client) {
         },
     })));
     server.registerTool('get_ticket', {
-        description: 'Fetch one ticket by display id (project prefix + number, e.g. ACM-7).',
+        description: 'Fetch one ticket by display id (project prefix + number, e.g. ACM-7).'
+            + CROSS_PROJECT_LINK_NOTE,
         inputSchema: {
             display_id: z.string().min(1).describe('e.g. ACM-7'),
         },
     }, tool(async (a) => client.request('GET', ticketPath(a.display_id))));
     server.registerTool('update_ticket', {
-        description: 'Update a ticket: change its workflow status and/or the customer-facing public summary. At least one field is required; an empty public_summary clears it.',
+        description: 'Update a ticket: change its workflow status, its priority, 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.'
+            + CROSS_PROJECT_LINK_NOTE,
         inputSchema: {
             display_id: z.string().min(1),
             status: z.string().max(100).optional(),
             public_summary: z.string().max(10000).optional(),
+            priority: z.enum(TICKET_PRIORITIES).optional()
+                .describe('Records a triage ruling. Required before closing in a project that enforces triage.'),
         },
     }, tool(async (a) => {
-        if (a.status === undefined && a.public_summary === undefined) {
-            throw new Error('Provide status and/or public_summary');
+        if (a.status === undefined && a.public_summary === undefined && a.priority === undefined) {
+            throw new Error('Provide status, priority and/or public_summary');
         }
         return client.request('PATCH', ticketPath(a.display_id), {
-            body: { status: a.status, publicSummary: a.public_summary },
+            body: { status: a.status, publicSummary: a.public_summary, priority: a.priority },
         });
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "punchline-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "MCP stdio server exposing the Punchline external API as tools",
   "type": "module",
   "license": "MIT",
@@ -17,15 +17,21 @@
     "tickets",
     "agent-tools"
   ],
-  "bin": { "punchline-mcp": "dist/index.js" },
-  "files": ["dist"],
+  "bin": {
+    "punchline-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
     "start": "node dist/index.js",
     "prepublishOnly": "npm run build"
   },
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.0"