@k-system/tickr-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to `@tickr/mcp-server` will be documented here.
+
+## [0.1.0] — 2026-03-12
+
+### Added
+- Initial release
+- 17 MCP tools (ticket CRUD, triage, labels, cycles, epics)
+- 2 MCP resources (ticket detail, project overview)
+- API key and JWT authentication
+- Config via environment variables or `~/.tickr/config.json`

package/README.md

@@ -0,0 +1,87 @@
+# @tickr/mcp-server
+
+MCP (Model Context Protocol) server for [Tickr](https://tickr.io) project management.
+
+## Quick Start
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "tickr": {
+      "command": "npx",
+      "args": ["-y", "@tickr/mcp-server"],
+      "env": {
+        "TICKR_API_URL": "https://your-tickr-instance.com",
+        "TICKR_API_KEY": "tk_your_api_key"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add tickr -- npx -y @tickr/mcp-server
+```
+
+Set environment variables:
+```bash
+export TICKR_API_URL=https://your-tickr-instance.com
+export TICKR_API_KEY=tk_your_api_key
+```
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `TICKR_API_URL` | Yes | `https://localhost:6001` | Tickr API base URL |
+| `TICKR_API_KEY` | Yes | — | API key (`tk_...`) from Tickr admin |
+| `TICKR_DEFAULT_PROJECT` | No | — | Default project slug |
+
+Or use config file `~/.tickr/config.json`:
+```json
+{
+  "apiUrl": "https://your-tickr-instance.com",
+  "apiKey": "tk_your_api_key",
+  "defaultProject": "my-project"
+}
+```
+
+## Available Tools (17)
+
+| Tool | Description |
+|------|-------------|
+| `create_ticket` | Create a new ticket |
+| `list_tickets` | List tickets with filters |
+| `get_ticket` | Get ticket detail by number |
+| `update_ticket` | Update ticket fields |
+| `search_tickets` | Fulltext search |
+| `add_comment` | Add comment to ticket |
+| `update_implementation_item` | Update implementation table row |
+| `triage_list` | List untriaged tickets |
+| `triage_accept` | Accept triaged ticket |
+| `triage_reject` | Reject triaged ticket |
+| `list_labels` | List project labels |
+| `add_label` | Add label to ticket |
+| `remove_label` | Remove label from ticket |
+| `list_cycles` | List project cycles |
+| `assign_cycle` | Assign ticket to cycle |
+| `list_epics` | List project epics |
+| `assign_epic` | Assign ticket to epic |
+
+## Resources (2)
+
+| URI | Description |
+|-----|-------------|
+| `tickr://ticket/{number}` | Ticket detail as markdown |
+| `tickr://project/{slug}` | Project overview + recent tickets |
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,29 @@
+import type { TickrConfig } from "./config.js";
+/** Unified API response wrapper */
+export interface ApiResponse<T> {
+    success: boolean;
+    data: T | null;
+    error: {
+        code: string;
+        message: string;
+        traceId?: string;
+    } | null;
+    meta: {
+        totalCount?: number;
+        page?: number;
+        pageSize?: number;
+        totalPages?: number;
+    } | null;
+}
+/** Fetch wrapper pro Tickr REST API s automatickou autentizací */
+export declare class ApiClient {
+    private config;
+    constructor(config: TickrConfig);
+    get<T = unknown>(path: string): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    delete<T = unknown>(path: string): Promise<T>;
+    private request;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.js

@@ -0,0 +1,65 @@
+import { getAuthHeader } from "./auth.js";
+/** Fetch wrapper pro Tickr REST API s automatickou autentizací */
+export class ApiClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async get(path) {
+        return this.request("GET", path);
+    }
+    async post(path, body) {
+        return this.request("POST", path, body);
+    }
+    async patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    async put(path, body) {
+        return this.request("PUT", path, body);
+    }
+    async delete(path) {
+        return this.request("DELETE", path);
+    }
+    async request(method, path, body) {
+        const auth = await getAuthHeader(this.config);
+        const url = `${this.config.apiUrl}${path}`;
+        const headers = {
+            Authorization: auth,
+            Accept: "application/json",
+        };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            // Pokus o parsování unified error response
+            const text = await res.text().catch(() => "");
+            let errorMessage = `API ${method} ${path} failed: ${res.status} ${res.statusText}`;
+            try {
+                const json = JSON.parse(text);
+                if (json.error?.message) {
+                    errorMessage = json.error.message;
+                }
+            }
+            catch {
+                if (text)
+                    errorMessage += ` — ${text}`;
+            }
+            throw new Error(errorMessage);
+        }
+        // 204 No Content
+        if (res.status === 204) {
+            return undefined;
+        }
+        const json = await res.json();
+        if (!json.success) {
+            throw new Error(json.error?.message ?? `API ${method} ${path} failed`);
+        }
+        return json.data;
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/auth.d.ts

@@ -0,0 +1,18 @@
+import type { TickrConfig } from "./config.js";
+interface TokenPair {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+}
+/** Přihlášení přes username/password — vrátí JWT token pair */
+export declare function login(config: TickrConfig, username: string, password: string): Promise<TokenPair>;
+/** Refresh JWT tokenu */
+export declare function refreshToken(config: TickrConfig): Promise<TokenPair>;
+/**
+ * Vrátí Authorization header value.
+ * Pokud config má apiKey (tk_...), použije ho přímo.
+ * Jinak použije JWT token (auto-refresh pokud expiruje).
+ */
+export declare function getAuthHeader(config: TickrConfig): Promise<string>;
+export {};
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,60 @@
+let currentTokens = null;
+/** Přihlášení přes username/password — vrátí JWT token pair */
+export async function login(config, username, password) {
+    const res = await fetch(`${config.apiUrl}/api/auth/login`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ username, password }),
+    });
+    if (!res.ok) {
+        throw new Error(`Login failed: ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json());
+    currentTokens = {
+        accessToken: data.accessToken,
+        refreshToken: data.refreshToken,
+        expiresAt: Date.now() + data.expiresIn * 1000,
+    };
+    return currentTokens;
+}
+/** Refresh JWT tokenu */
+export async function refreshToken(config) {
+    if (!currentTokens) {
+        throw new Error("No tokens to refresh — login first");
+    }
+    const res = await fetch(`${config.apiUrl}/api/auth/refresh`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refreshToken: currentTokens.refreshToken }),
+    });
+    if (!res.ok) {
+        throw new Error(`Token refresh failed: ${res.status}`);
+    }
+    const data = (await res.json());
+    currentTokens = {
+        accessToken: data.accessToken,
+        refreshToken: data.refreshToken,
+        expiresAt: Date.now() + data.expiresIn * 1000,
+    };
+    return currentTokens;
+}
+/**
+ * Vrátí Authorization header value.
+ * Pokud config má apiKey (tk_...), použije ho přímo.
+ * Jinak použije JWT token (auto-refresh pokud expiruje).
+ */
+export async function getAuthHeader(config) {
+    // API key auth — jednoduché, bez expiry
+    if (config.apiKey) {
+        return config.apiKey;
+    }
+    // JWT auth — refresh pokud token brzy vyprší (30s buffer)
+    if (currentTokens && currentTokens.expiresAt - Date.now() < 30_000) {
+        await refreshToken(config);
+    }
+    if (!currentTokens) {
+        throw new Error("Not authenticated — set TICKR_API_KEY or call login()");
+    }
+    return `Bearer ${currentTokens.accessToken}`;
+}
+//# sourceMappingURL=auth.js.map

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+export interface TickrConfig {
+    apiUrl: string;
+    apiKey?: string;
+    defaultProject?: string;
+}
+/** Načte konfiguraci z env vars nebo ~/.tickr/config.json */
+export declare function loadConfig(): TickrConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,33 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+/** Načte konfiguraci z env vars nebo ~/.tickr/config.json */
+export function loadConfig() {
+    const apiUrl = process.env.TICKR_API_URL;
+    const apiKey = process.env.TICKR_API_KEY;
+    const defaultProject = process.env.TICKR_DEFAULT_PROJECT;
+    // Env vars mají prioritu
+    if (apiUrl && apiKey) {
+        return { apiUrl, apiKey, defaultProject };
+    }
+    // Fallback na config soubor
+    const configPath = join(homedir(), ".tickr", "config.json");
+    try {
+        const raw = readFileSync(configPath, "utf-8");
+        const file = JSON.parse(raw);
+        return {
+            apiUrl: apiUrl || file.apiUrl || "https://localhost:6001",
+            apiKey: apiKey || file.apiKey || "",
+            defaultProject: defaultProject || file.defaultProject,
+        };
+    }
+    catch {
+        // Config soubor neexistuje — použijeme defaults
+        return {
+            apiUrl: apiUrl || "https://localhost:6001",
+            apiKey: apiKey || "",
+            defaultProject,
+        };
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/formatters.d.ts

@@ -0,0 +1,10 @@
+import type { Ticket, Project } from "./types.js";
+/** Formátuje ticket do markdown pro resource/tool output */
+export declare function formatTicketMarkdown(t: Ticket): string;
+/** Formátuje projekt do markdown pro resource output */
+export declare function formatProjectMarkdown(p: Project, recentTickets?: Array<{
+    displayNumber: string;
+    title: string;
+    status: string;
+}>): string;
+//# sourceMappingURL=formatters.d.ts.map

package/dist/formatters.js

@@ -0,0 +1,58 @@
+/** Formátuje ticket do markdown pro resource/tool output */
+export function formatTicketMarkdown(t) {
+    const lines = [
+        `# ${t.displayNumber}: ${t.title}`,
+        "",
+        `| Field | Value |`,
+        `|-------|-------|`,
+        `| Type | ${t.type} |`,
+        `| Status | ${t.status} |`,
+        `| Priority | ${t.priority} |`,
+        `| Scope | ${t.scope || "-"} |`,
+        `| Assignee | ${t.assigneeName || "Unassigned"} |`,
+        `| Estimate | ${t.estimate || "-"} |`,
+        `| Created | ${t.createdAt} |`,
+        `| Updated | ${t.updatedAt} |`,
+    ];
+    if (t.affectedParts.length > 0) {
+        lines.push("", `**Affected parts:** ${t.affectedParts.join(", ")}`);
+    }
+    if (t.content) {
+        lines.push("", "---", "", t.content);
+    }
+    if (t.implementationItems.length > 0) {
+        lines.push("", "## Implementation Items", "", "| # | Area | Detail | Status | Note |", "|---|------|--------|--------|------|");
+        t.implementationItems.forEach((item, i) => {
+            lines.push(`| ${i} | ${item.area} | ${item.fileOrDetail} | ${item.status} | ${item.note || "-"} |`);
+        });
+    }
+    if (t.comments.length > 0) {
+        lines.push("", "## Comments", "");
+        for (const c of t.comments) {
+            lines.push(`**${c.authorName}** (${c.createdAt}):`);
+            lines.push(c.text, "");
+        }
+    }
+    return lines.join("\n");
+}
+/** Formátuje projekt do markdown pro resource output */
+export function formatProjectMarkdown(p, recentTickets) {
+    const lines = [
+        `# Project: ${p.name} (${p.slug})`,
+        "",
+        `**Prefix:** ${p.prefix}`,
+        `**Scope tags:** ${p.scopeTags.join(", ") || "-"}`,
+        `**Ticket types:** ${p.ticketTypes.join(", ") || "-"}`,
+    ];
+    if (p.description) {
+        lines.push("", p.description);
+    }
+    if (recentTickets && recentTickets.length > 0) {
+        lines.push("", "## Recent Tickets", "");
+        for (const t of recentTickets) {
+            lines.push(`- ${t.displayNumber} [${t.status}] ${t.title}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=formatters.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { ApiClient } from "./api-client.js";
+// Tools
+import { registerCreateTicket } from "./tools/create-ticket.js";
+import { registerListTickets } from "./tools/list-tickets.js";
+import { registerGetTicket } from "./tools/get-ticket.js";
+import { registerUpdateTicket } from "./tools/update-ticket.js";
+import { registerAddComment } from "./tools/add-comment.js";
+import { registerUpdateImplementationItem } from "./tools/update-implementation-item.js";
+import { registerSearchTickets } from "./tools/search-tickets.js";
+import { registerTriageList } from "./tools/triage-list.js";
+import { registerTriageAccept } from "./tools/triage-accept.js";
+import { registerTriageReject } from "./tools/triage-reject.js";
+import { registerListLabels } from "./tools/list-labels.js";
+import { registerAddLabel } from "./tools/add-label.js";
+import { registerRemoveLabel } from "./tools/remove-label.js";
+import { registerListCycles } from "./tools/list-cycles.js";
+import { registerAssignCycle } from "./tools/assign-cycle.js";
+import { registerListEpics } from "./tools/list-epics.js";
+import { registerAssignEpic } from "./tools/assign-epic.js";
+import { registerPollDevQueue } from "./tools/poll-dev-queue.js";
+import { registerCompleteDevTask } from "./tools/complete-dev-task.js";
+// Resources
+import { registerTicketResource } from "./resources/ticket-resource.js";
+import { registerProjectResource } from "./resources/project-resource.js";
+async function main() {
+    const config = loadConfig();
+    const api = new ApiClient(config);
+    const server = new McpServer({
+        name: "tickr",
+        version: "0.1.0",
+    });
+    // Registrace tools
+    registerCreateTicket(server, api);
+    registerListTickets(server, api);
+    registerGetTicket(server, api);
+    registerUpdateTicket(server, api);
+    registerAddComment(server, api);
+    registerUpdateImplementationItem(server, api);
+    registerSearchTickets(server, api);
+    registerTriageList(server, api);
+    registerTriageAccept(server, api);
+    registerTriageReject(server, api);
+    registerListLabels(server, api);
+    registerAddLabel(server, api);
+    registerRemoveLabel(server, api);
+    registerListCycles(server, api);
+    registerAssignCycle(server, api);
+    registerListEpics(server, api);
+    registerAssignEpic(server, api);
+    registerPollDevQueue(server, api);
+    registerCompleteDevTask(server, api);
+    // Registrace resources
+    registerTicketResource(server, api);
+    registerProjectResource(server, api);
+    // Spuštění na stdio transportu
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("MCP server failed to start:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/resources/project-resource.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../api-client.js";
+export declare function registerProjectResource(server: McpServer, api: ApiClient): void;
+//# sourceMappingURL=project-resource.d.ts.map

package/dist/resources/project-resource.js

@@ -0,0 +1,18 @@
+import { formatProjectMarkdown } from "../formatters.js";
+export function registerProjectResource(server, api) {
+    server.resource("project", "tickr://project/{slug}", { description: "Get project overview with recent tickets" }, async (uri) => {
+        const slug = uri.pathname.split("/").pop();
+        const project = await api.get(`/api/projects/${slug}`);
+        const tickets = await api.get(`/api/projects/${slug}/tickets?limit=20`);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "text/markdown",
+                    text: formatProjectMarkdown(project, tickets),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=project-resource.js.map

package/dist/resources/ticket-resource.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../api-client.js";
+export declare function registerTicketResource(server: McpServer, api: ApiClient): void;
+//# sourceMappingURL=ticket-resource.d.ts.map

package/dist/resources/ticket-resource.js

@@ -0,0 +1,17 @@
+import { formatTicketMarkdown } from "../formatters.js";
+export function registerTicketResource(server, api) {
+    server.resource("ticket", "tickr://ticket/{number}", { description: "Get full ticket detail as markdown" }, async (uri) => {
+        const number = uri.pathname.split("/").pop();
+        const ticket = await api.get(`/api/tickets/${number}`);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "text/markdown",
+                    text: formatTicketMarkdown(ticket),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=ticket-resource.js.map

package/dist/tools/add-comment.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../api-client.js";
+export declare function registerAddComment(server: McpServer, api: ApiClient): void;
+//# sourceMappingURL=add-comment.d.ts.map

package/dist/tools/add-comment.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export function registerAddComment(server, api) {
+    server.tool("add_comment", "Add a comment to a ticket", {
+        number: z.string().describe("Ticket display number, e.g. 'TKR-42' (legacy) or 'TKR-BUG-0042' (typed)"),
+        text: z.string().describe("Comment text (markdown)"),
+    }, async (params) => {
+        try {
+            await api.post(`/api/tickets/${params.number}/comments`, {
+                text: params.text,
+            });
+            return {
+                content: [
+                    { type: "text", text: `Comment added to ${params.number}` },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=add-comment.js.map

package/dist/tools/add-label.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../api-client.js";
+export declare function registerAddLabel(server: McpServer, api: ApiClient): void;
+//# sourceMappingURL=add-label.d.ts.map

package/dist/tools/add-label.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export function registerAddLabel(server, api) {
+    server.tool("add_label", "Add a label to a ticket", {
+        number: z.string().describe("Ticket display number, e.g. 'TKR-42' (legacy) or 'TKR-BUG-0042' (typed)"),
+        label_id: z.string().describe("UUID of the label to add"),
+    }, async (params) => {
+        try {
+            await api.post(`/api/tickets/${params.number}/labels/${params.label_id}`);
+            return {
+                content: [{ type: "text", text: `Label added to ${params.number}` }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=add-label.js.map

package/dist/tools/assign-cycle.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../api-client.js";
+export declare function registerAssignCycle(server: McpServer, api: ApiClient): void;
+//# sourceMappingURL=assign-cycle.d.ts.map

package/dist/tools/assign-cycle.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export function registerAssignCycle(server, api) {
+    server.tool("assign_cycle", "Assign a ticket to a cycle (sprint)", {
+        project: z.string().describe("Project slug"),
+        cycle_id: z.string().describe("UUID of the cycle"),
+        number: z.string().describe("Ticket display number, e.g. 'TKR-42' (legacy) or 'TKR-BUG-0042' (typed)"),
+    }, async (params) => {
+        try {
+            await api.post(`/api/projects/${params.project}/cycles/${params.cycle_id}/tickets/${params.number}`);
+            return {
+                content: [{ type: "text", text: `${params.number} assigned to cycle ${params.cycle_id}` }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=assign-cycle.js.map

package/dist/tools/assign-epic.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../api-client.js";
+export declare function registerAssignEpic(server: McpServer, api: ApiClient): void;
+//# sourceMappingURL=assign-epic.d.ts.map

package/dist/tools/assign-epic.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export function registerAssignEpic(server, api) {
+    server.tool("assign_epic", "Assign a ticket to an epic", {
+        project: z.string().describe("Project slug"),
+        epic_id: z.string().describe("UUID of the epic"),
+        number: z.string().describe("Ticket display number, e.g. 'TKR-42' (legacy) or 'TKR-BUG-0042' (typed)"),
+    }, async (params) => {
+        try {
+            await api.post(`/api/projects/${params.project}/epics/${params.epic_id}/tickets/${params.number}`);
+            return {
+                content: [{ type: "text", text: `${params.number} assigned to epic ${params.epic_id}` }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=assign-epic.js.map

package/dist/tools/complete-dev-task.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../api-client.js";
+export declare function registerCompleteDevTask(server: McpServer, api: ApiClient): void;
+//# sourceMappingURL=complete-dev-task.d.ts.map