punchline-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 drmzperx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# punchline-mcp
+
+A local stdio [MCP](https://modelcontextprotocol.io) server that exposes the Punchline external
+API as agent tools. Authorization is entirely server-side — the tools you get depend on the API
+key you configure, not on any client-side flag.
+
+## Setup
+
+The server is published to npm — no repo access needed, just Node ≥ 18. With the Claude Code CLI:
+
+```bash
+claude mcp add punchline --env PUNCHLINE_API_KEY=pnchl_live_... -- npx -y punchline-mcp
+```
+
+Or with the generic MCP client JSON config:
+
+```json
+{
+  "mcpServers": {
+    "punchline": {
+      "command": "npx",
+      "args": ["-y", "punchline-mcp"],
+      "env": { "PUNCHLINE_API_KEY": "pnchl_live_..." }
+    }
+  }
+}
+```
+
+### From source
+
+Working from a checkout of this repo instead:
+
+```bash
+cd punchline-mcp
+npm install
+npm run build
+```
+
+Then register the built entry point in place of npx — e.g. with the Claude Code CLI:
+
+```bash
+claude mcp add punchline --env PUNCHLINE_API_KEY=pnchl_live_... -- node /path/to/punchline/punchline-mcp/dist/index.js
+```
+
+(For the JSON config, use `"command": "node"` and `"args": ["/path/to/punchline/punchline-mcp/dist/index.js"]`.)
+
+## Environment variables
+
+| 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. |
+
+Any other key prefix, or a missing key, fails at startup with a `ConfigError` on stderr.
+
+## Key-type behavior
+
+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_user_…` (user provisioning key)** — registers only `create_project`, which returns a
+  ONE-TIME project API key.
+
+A single server instance only ever exposes one set. To give an agent both capabilities, register
+the server twice under two names with two different keys, e.g. `punchline` (project key) and
+`punchline-provisioning` (user key).
+
+## Tools
+
+| 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. |
+| `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. |
+| `add_communication` | project key | Post a customer-facing communication (external comment) on a ticket. |
+| `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. |
+
+## Manual smoke test
+
+With a real key configured in your MCP client, ask the agent to run `whoami` and confirm it
+returns your project/key details.
+
+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]
+```
+
+## Errors
+
+Tool errors carry the API's problem detail: 403 scope errors (e.g. missing `write:own`), 409
+conflicts (e.g. duplicate project slug/prefix), and 429 rate limits with `Retry-After`.
+
+## Development
+
+```bash
+npx vitest run   # unit tests
+npm run build    # tsc --noEmit-equivalent build to dist/
+```

package/dist/client.js

@@ -0,0 +1,67 @@
+export const DEFAULT_BASE_URL = 'http://proding.co:8050';
+export class ApiError extends Error {
+    status;
+    title;
+    detail;
+    retryAfter;
+    rateLimitRemaining;
+    rateLimitLimit;
+    constructor(status, title, detail, retryAfter, rateLimitRemaining, rateLimitLimit) {
+        super(`${status} ${title}${detail ? `: ${detail}` : ''}`);
+        this.status = status;
+        this.title = title;
+        this.detail = detail;
+        this.retryAfter = retryAfter;
+        this.rateLimitRemaining = rateLimitRemaining;
+        this.rateLimitLimit = rateLimitLimit;
+        this.name = 'ApiError';
+    }
+}
+export class PunchlineClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl = DEFAULT_BASE_URL) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    async request(method, path, opts = {}) {
+        const url = new URL(path, this.baseUrl);
+        for (const [k, v] of Object.entries(opts.query ?? {})) {
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        }
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers: {
+                    'X-Punchline-Key': this.apiKey,
+                    ...(opts.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                },
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            });
+        }
+        catch (err) {
+            throw new Error(`Cannot reach Punchline API at ${this.baseUrl}: ${err.message}`);
+        }
+        if (!res.ok) {
+            let title = res.statusText || 'Error';
+            let detail;
+            const raw = await res.text();
+            try {
+                const problem = JSON.parse(raw);
+                if (problem.title)
+                    title = problem.title;
+                detail = problem.detail;
+            }
+            catch {
+                // non-JSON error body — fall back to a raw text snippet for diagnostics
+                detail = raw.slice(0, 200) || undefined;
+            }
+            throw new ApiError(res.status, title, detail, res.headers.get('Retry-After') ?? undefined, res.headers.get('X-RateLimit-Remaining') ?? undefined, res.headers.get('X-RateLimit-Limit') ?? undefined);
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+}

package/dist/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildServer, ConfigError, parseConfig } from './server.js';
+async function main() {
+    const config = parseConfig(process.env);
+    const { server, registeredTools } = buildServer(config);
+    // The stdio protocol owns stdout — diagnostics MUST go to stderr.
+    console.error(`punchline-mcp: ${registeredTools.length} tool(s) registered [${registeredTools.join(', ')}]`);
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    console.error(err instanceof ConfigError ? `punchline-mcp: ${err.message}` : err);
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,39 @@
+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 { 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';
+export const PROJECT_KEY_PREFIX = 'pnchl_live_';
+export const USER_KEY_PREFIX = 'pnchl_user_';
+export class ConfigError extends Error {
+}
+export function parseConfig(env) {
+    const apiKey = env.PUNCHLINE_API_KEY?.trim();
+    if (!apiKey) {
+        throw new ConfigError('PUNCHLINE_API_KEY is required: a pnchl_live_… project key (ticket tools) or a pnchl_user_… provisioning key (create_project).');
+    }
+    if (!apiKey.startsWith(PROJECT_KEY_PREFIX) && !apiKey.startsWith(USER_KEY_PREFIX)) {
+        throw new ConfigError(`Unrecognized API key prefix. Expected ${PROJECT_KEY_PREFIX}… (project key) or ${USER_KEY_PREFIX}… (user provisioning key).`);
+    }
+    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 client = new PunchlineClient(config.apiKey, config.baseUrl);
+    const registeredTools = [];
+    if (config.apiKey.startsWith(USER_KEY_PREFIX)) {
+        registerProvisioningTools(server, client);
+        registeredTools.push(...PROVISIONING_TOOL_NAMES);
+    }
+    else if (config.apiKey.startsWith(PROJECT_KEY_PREFIX)) {
+        registerTicketTools(server, client);
+        registerCommunicationTools(server, client);
+        registerMetaTools(server, client);
+        registeredTools.push(...TICKET_TOOL_NAMES, ...COMMUNICATION_TOOL_NAMES, ...META_TOOL_NAMES);
+    }
+    else {
+        throw new ConfigError(`Unrecognized API key prefix. Expected ${PROJECT_KEY_PREFIX}… or ${USER_KEY_PREFIX}….`);
+    }
+    return { server, registeredTools };
+}

package/dist/tools/communications.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { ticketPath } from './tickets.js';
+import { tool } from './util.js';
+export const COMMUNICATION_TOOL_NAMES = ['add_communication'];
+export function registerCommunicationTools(server, client) {
+    server.registerTool('add_communication', {
+        description: 'Post a customer-facing communication (external comment) on a ticket.',
+        inputSchema: {
+            display_id: z.string().min(1).describe('e.g. ACM-7'),
+            body: z.string().min(1).max(10000).describe('Message text'),
+        },
+    }, tool(async (a) => client.request('POST', `${ticketPath(a.display_id)}/communications`, {
+        body: { body: a.body },
+    })));
+}

package/dist/tools/meta.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { TICKET_TYPES } from './tickets.js';
+import { tool } from './util.js';
+export const META_TOOL_NAMES = ['whoami', 'get_changelog'];
+export function registerMetaTools(server, client) {
+    server.registerTool('whoami', {
+        description: 'Introspect the configured API key: project, key name, scopes, last use. Use this to self-diagnose 403 errors.',
+        inputSchema: {},
+    }, tool(async () => client.request('GET', '/api/v1/external/me')));
+    server.registerTool('get_changelog', {
+        description: 'Recent externally-visible ticket changes for the project bound to this key.',
+        inputSchema: {
+            from: z.string().datetime().optional().describe('ISO-8601 instant'),
+            to: z.string().datetime().optional().describe('ISO-8601 instant'),
+            type: z.enum(TICKET_TYPES).optional(),
+        },
+    }, tool(async (a) => client.request('GET', '/api/v1/external/changelog', {
+        query: { from: a.from, to: a.to, type: a.type },
+    })));
+}

package/dist/tools/provisioning.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { formatError } from './util.js';
+export const PROVISIONING_TOOL_NAMES = ['create_project'];
+export function registerProvisioningTools(server, client) {
+    server.registerTool('create_project', {
+        description: 'Provision a new Punchline project (requires a pnchl_user_ provisioning key). Returns the project and a ONE-TIME project API key.',
+        inputSchema: {
+            name: z.string().max(255),
+            slug: z.string().regex(/^[a-z0-9-]{2,100}$/, 'lowercase letters, digits, hyphens; 2-100 chars'),
+            prefix: z.string().regex(/^[A-Z]{2,10}$/, '2-10 uppercase letters'),
+            description: z.string().max(65535).optional(),
+        },
+    }, async (a) => {
+        try {
+            const data = await client.request('POST', '/api/v1/external/projects', {
+                body: { name: a.name, slug: a.slug, prefix: a.prefix, description: a.description },
+            });
+            const text = [
+                'Project created. IMPORTANT: the apiKey below is a ONE-TIME project key —',
+                'surface it to the user now; do NOT log it or persist it anywhere.',
+                JSON.stringify(data, null, 2),
+            ].join('\n');
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: formatError(err) }], isError: true };
+        }
+    });
+}

package/dist/tools/tickets.js

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import { tool } from './util.js';
+export const TICKET_TYPES = ['BUG', 'FEATURE', 'TASK', 'IMPROVEMENT', 'IDEA', 'TECHNICAL'];
+export const TICKET_PRIORITIES = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'];
+export const TICKET_TOOL_NAMES = ['create_ticket', 'list_tickets', 'get_ticket', 'update_ticket'];
+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.',
+        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(),
+            type: z.enum(TICKET_TYPES).optional().describe('Defaults to BUG'),
+            priority: z.enum(TICKET_PRIORITIES).optional().describe('Defaults to MEDIUM'),
+            labels: z.array(z.string().max(100)).max(100).optional().describe('Label names; unknown labels are created'),
+            reporter_name: z.string().max(500).optional(),
+            page_url: z.string().max(2048).optional(),
+            user_agent: z.string().max(512).optional(),
+            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'),
+        },
+    }, tool(async (a) => client.request('POST', TICKETS_PATH, {
+        body: {
+            title: a.title,
+            reporterEmail: a.reporter_email,
+            description: a.description,
+            type: a.type,
+            priority: a.priority,
+            labels: a.labels,
+            reporterName: a.reporter_name,
+            pageUrl: a.page_url,
+            userAgent: a.user_agent,
+            appVersion: a.app_version,
+            idempotencyKey: a.idempotency_key,
+        },
+    })));
+    server.registerTool('list_tickets', {
+        description: 'List tickets visible to this API key (own tickets; whole project with the read:all scope). Paginated.',
+        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)'),
+            reporter_email: z.string().optional(),
+            status: z.string().optional().describe('Workflow status name, e.g. OPEN'),
+            type: z.enum(TICKET_TYPES).optional(),
+            created_after: z.string().datetime().optional().describe('ISO-8601 instant'),
+            created_before: z.string().datetime().optional().describe('ISO-8601 instant'),
+        },
+    }, tool(async (a) => client.request('GET', TICKETS_PATH, {
+        query: {
+            page: a.page,
+            size: a.size,
+            reporterEmail: a.reporter_email,
+            status: a.status,
+            type: a.type,
+            createdAfter: a.created_after,
+            createdBefore: a.created_before,
+        },
+    })));
+    server.registerTool('get_ticket', {
+        description: 'Fetch one ticket by display id (project prefix + number, e.g. ACM-7).',
+        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.',
+        inputSchema: {
+            display_id: z.string().min(1),
+            status: z.string().max(100).optional(),
+            public_summary: z.string().max(10000).optional(),
+        },
+    }, tool(async (a) => {
+        if (a.status === undefined && a.public_summary === undefined) {
+            throw new Error('Provide status and/or public_summary');
+        }
+        return client.request('PATCH', ticketPath(a.display_id), {
+            body: { status: a.status, publicSummary: a.public_summary },
+        });
+    }));
+}

package/dist/tools/util.js

@@ -0,0 +1,31 @@
+import { ApiError } from '../client.js';
+export function formatError(err) {
+    if (err instanceof ApiError) {
+        let msg = `${err.status} ${err.title}${err.detail ? `: ${err.detail}` : ''}`;
+        if (err.status === 429) {
+            const bits = [];
+            if (err.retryAfter)
+                bits.push(`Retry-After: ${err.retryAfter}s`);
+            if (err.rateLimitRemaining !== undefined)
+                bits.push(`X-RateLimit-Remaining: ${err.rateLimitRemaining}`);
+            if (err.rateLimitLimit !== undefined)
+                bits.push(`X-RateLimit-Limit: ${err.rateLimitLimit}`);
+            if (bits.length)
+                msg += ` (${bits.join(', ')})`;
+        }
+        return msg;
+    }
+    return err instanceof Error ? err.message : String(err);
+}
+/** Wraps a data-returning handler into an MCP tool result (pretty JSON text; errors as isError). */
+export function tool(fn) {
+    return async (args) => {
+        try {
+            const data = await fn(args);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: formatError(err) }], isError: true };
+        }
+    };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "punchline-mcp",
+  "version": "1.0.0",
+  "description": "MCP stdio server exposing the Punchline external API as tools",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drmzperx/punchline.git",
+    "directory": "punchline-mcp"
+  },
+  "homepage": "https://github.com/drmzperx/punchline/tree/master/punchline-mcp#readme",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "punchline",
+    "tickets",
+    "agent-tools"
+  ],
+  "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" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}