@kanbodev/mcp 1.1.1 → 1.1.3

package/README.md

@@ -55,7 +55,7 @@ You can create tickets with as much or as little detail as you want:
 
 > "Create a ticket in the Frontend project called 'Fix login button not responding on mobile'"
 
-The assistant will look up your project, find available statuses, priorities, and sizes, then create the ticket. You can also be more specific:
+The assistant will look up your project, check for similar/related tickets, find available statuses, priorities, and sizes, then create the ticket with acceptance criteria. You can also be more specific:
 
 > "Create a high-priority bug in Frontend: 'Payment form crashes on Safari'. Assign it to me and put it in the To Do column."
 
@@ -65,6 +65,26 @@ For AI-assisted creation:
 
 This uses the AI tools (`polish_title`, `generate_description`, `suggest_attributes`) to craft a well-defined ticket before creating it.
 
+### Acceptance criteria
+
+Every ticket includes structured acceptance criteria — specific, testable conditions that define "done":
+
+> "Add acceptance criteria to PROJ-123: users can export in CSV and JSON, progress shows for large exports, and errors display a retry option"
+>
+> "Show me the acceptance criteria for PROJ-45"
+
+The assistant uses Given/When/Then format and includes both happy-path and edge-case criteria automatically.
+
+### Related tickets and subtasks
+
+The assistant checks for duplicates and related work before creating tickets, and supports parent-child relationships for breaking down work:
+
+> "Create a subtask under PROJ-100: 'Write unit tests for auth module'"
+>
+> "Show me the child tickets of PROJ-100"
+>
+> "Find tickets similar to 'password reset not working'"
+
 ### Finding and viewing tickets
 
 > "Show me all my assigned tickets"

package/dist/index.js

@@ -16839,7 +16839,7 @@ var CONFIG = {
 };
 var SERVER_INFO = {
   name: "kanbo-mcp",
-  version: "1.1.1",
+  version: "1.1.3",
   description: "MCP server for Kanbo project management"
 };
 var PAT_CONFIG = {
@@ -24375,7 +24375,8 @@ class KanboClient {
       }
     }
     const headers = {
-      "Content-Type": "application/json"
+      "Content-Type": "application/json",
+      "X-Kanbo-Source": "mcp"
     };
     if (this.useOidcAuth) {
       const oidcToken = await fetchOidcToken(this.apiUrl);
@@ -25475,7 +25476,29 @@ var getTicketByKeyTool = {
 var createTicketTool = {
   tool: {
     name: "create_ticket",
-    description: "Create a new ticket in a project. For high-quality tickets, always include: description (structured markdown with ## headings), acceptanceCriteria (Given/When/Then JSON), and typeSlug. After creation, call set_ticket_tags to add tags. Call find_similar_tickets first to check for duplicates. Use list_statuses, list_priorities, list_sizes to get required IDs.",
+    description: `Create a new ticket in a project.
+
+IMPORTANT — ALWAYS INCLUDE:
+- acceptanceCriteria: REQUIRED for every ticket. Provide 3-7 specific, testable criteria in Given/When/Then format. Include at least one happy-path and one error/edge-case criterion. This is the primary measure of "done" for a ticket.
+- find_similar_tickets: ALWAYS check for duplicates/related tickets before creating. Link as parentId if the new ticket is a subtask of an existing one.
+
+RECOMMENDED WORKFLOW for high-quality tickets:
+1. find_similar_tickets — check for duplicates and related tickets first. If related tickets exist, consider linking via parentId.
+2. check_clarity — verify the title is specific enough
+3. generate_description — AI-generate a structured description (or write your own following the format below)
+4. suggest_attributes — AI-suggest priority, size, and tags
+5. create_ticket — create with all fields populated, including acceptanceCriteria and parentId if applicable
+6. set_ticket_tags — add 2-5 tags after creation
+
+DESCRIPTION FORMAT: The description field accepts KanboEditor HTML (TipTap/ProseMirror). Use semantic HTML tags: <p>, <h2>, <h3>, <ul>, <ol>, <li>, <strong>, <em>, <code>. Do NOT use <h1> (reserved for title). Do NOT use markdown syntax (## headings, **bold**, etc.) — use HTML tags instead.
+
+DESCRIPTION STRUCTURE by ticket type:
+- Bug: <h2>Summary</h2>, <h2>Steps to Reproduce</h2>, <h2>Environment</h2>, <h2>Screenshots / Logs</h2>
+- Feature: <h2>Problem Statement</h2>, <h2>Proposed Solution</h2>, <h2>User Story</h2>, <h2>Scope</h2>
+- Task: <h2>Objective</h2>, <h2>Background</h2>, <h2>Technical Approach</h2>, <h2>Files / Areas Affected</h2>
+- Improvement: <h2>Current Behavior</h2>, <h2>Desired Behavior</h2>, <h2>Why This Matters</h2>, <h2>Proposed Changes</h2>
+- Story: <h2>User Story</h2>, <h2>Context</h2>, <h2>Design / Mockups</h2>, <h2>Notes</h2>
+Start with a <p> overview using user story format: "As a [role], I want [goal], so that [benefit]." Use <strong> for key terms, <code> for file names/APIs/env vars, <ul>/<li> for requirements lists.`,
     inputSchema: {
       type: "object",
       properties: {
@@ -25489,7 +25512,7 @@ var createTicketTool = {
         },
         description: {
           type: "string",
-          description: `Ticket description in markdown (max ${LIMITS.DESCRIPTION_MAX} chars). Structure with ## headings: "## Requirements" (bullet points), "## Technical Notes" (implementation details, APIs, constraints). Use **bold** for key terms, \`code\` for identifiers, bullet lists for readability. Start with a user story: "As a [role], I want [goal], so that [benefit]."`
+          description: `Ticket description as KanboEditor HTML (max ${LIMITS.DESCRIPTION_MAX} chars). Use <p> for paragraphs, <h2>/<h3> for section headings, <ul>/<ol>/<li> for lists, <strong> for emphasis, <code> for technical terms. Start with a <p> overview, then add structured sections per ticket type. Example: "<p>As a user, I want to <strong>export data</strong> in CSV format.</p><h2>Requirements</h2><ul><li>Support CSV and JSON formats</li><li>Show progress for large exports</li></ul><h2>Technical Notes</h2><ul><li>Use existing <code>/api/export</code> endpoint</li></ul>". Use generate_description to AI-generate this, or write manually following the structure in the tool description above.`
         },
         statusId: {
           type: "string",
@@ -25593,7 +25616,7 @@ var updateTicketTool = {
         },
         description: {
           type: "string",
-          description: `New description in markdown (max ${LIMITS.DESCRIPTION_MAX} chars). Structure with ## headings: Requirements, Technical Notes. Use **bold**, \`code\`, bullet lists.`
+          description: `New description as KanboEditor HTML (max ${LIMITS.DESCRIPTION_MAX} chars). Use <p>, <h2>, <h3>, <ul>, <li>, <strong>, <code> tags. Structure with <h2> section headings per ticket type. Use refine_description to AI-refine an existing description based on feedback instead of rewriting manually.`
         },
         assigneeId: {
           type: ["string", "null"],
@@ -28512,21 +28535,27 @@ var polishTitleTool = {
 var generateDescriptionTool = {
   tool: {
     name: "generate_description",
-    description: "AI-generated structured ticket description from a title. Returns markdown with headings and bullet points. Use as a starting point, then refine with refine_description if needed. Consumes AI token quota.",
+    description: `AI-generated structured ticket description from a title. Returns a JSON object with two fields:
+- "description": KanboEditor HTML string with <p>, <h2>, <h3>, <ul>, <li>, <strong>, <code> tags. Structured with section headings appropriate to the ticket type (e.g., Requirements, Technical Notes, Steps to Reproduce).
+- "acceptanceCriteria": Array of plain-text criteria strings in Given/When/Then format.
+
+RECOMMENDED WORKFLOW: Call check_clarity first to verify the title is specific enough. If it returns clarifying questions, ask the user, then call generate_description. After generation, call suggest_attributes to auto-fill priority, size, and tags. Then pass the description and acceptanceCriteria to create_ticket.
+
+The AI gathers project context automatically (related tickets, statuses, workflow) to produce relevant descriptions. Pass releaseId for release-specific context. Consumes AI token quota.`,
     inputSchema: {
       type: "object",
       properties: {
         title: {
           type: "string",
-          description: "Ticket title"
+          description: "Ticket title — be specific and action-oriented for best results"
         },
         projectId: {
           type: "string",
-          description: "Project ID (for context)"
+          description: "Project ID (used to gather project context: related tickets, statuses, workflow)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID for additional context (optional)"
+          description: "Release ID for additional context — helps generate release-relevant descriptions (optional)"
         }
       },
       required: ["title", "projectId"]
@@ -29351,30 +29380,54 @@ var TOOL_INDEX = {
   },
   content_quality_guidelines: {
     description: "Follow these guidelines when creating or updating tickets for professional-quality output.",
-    ticket_title: 'Concise, action-oriented. Start with a verb for tasks/bugs. 1-200 chars. Example: "Implement Google OAuth login flow"',
-    ticket_description: [
-      "Use markdown. Max 5000 chars. Structure with ## headings:",
-      "",
-      "As a [role], I want [goal], so that [benefit].",
-      "",
-      "## Requirements",
-      "- Bullet points of what needs to happen",
-      "",
-      "## Technical Notes",
-      "- Implementation hints, APIs, constraints, `code` references",
-      "",
-      "Use **bold** for key terms, `code` for identifiers, and bullet lists for readability."
-    ].join(`
-`),
-    acceptance_criteria: [
-      'JSON string of array: [{"id":"ac-1","text":"Given... When... Then...","isChecked":false}]',
-      "Write 3-8 criteria per ticket in Given/When/Then format.",
-      'Example: [{"id":"ac-1","text":"Given a user on the login page, When they click Sign in with Google, Then they are redirected to Google OAuth consent screen","isChecked":false}]',
-      "Use unique IDs (ac-1, ac-2, etc.). Set isChecked to false for new tickets. Max 10000 chars total."
-    ].join(`
-`),
-    tags: "Apply 2-5 tags per ticket after creation using set_ticket_tags. Use lowercase-kebab-case. Common categories: feature area (auth, billing), technology (react, api), work type (feature, bug, refactor). Create missing tags with create_tag first.",
-    ticket_type: "Always set typeSlug when creating tickets. Common types: feature, bug, task, improvement. Use list_ticket_types to see project-specific types."
+    ticket_title: 'Concise, action-oriented. Start with a verb for tasks/bugs. 1-200 chars. Example: "Implement Google OAuth login flow". Use polish_title to AI-improve vague titles.',
+    ticket_description: {
+      format: "KanboEditor HTML (TipTap/ProseMirror). Do NOT use markdown syntax — use HTML tags.",
+      max_chars: 5000,
+      allowed_tags: "<p>, <h2>, <h3>, <ul>, <ol>, <li>, <strong>, <em>, <code>, <a>. Do NOT use <h1> (reserved for ticket title).",
+      structure: [
+        '1. Overview — <p> with user story: "As a [role], I want [goal], so that [benefit]."',
+        "2. Section headings — use <h2> tags matching the ticket type template (see template_structures)",
+        "3. Requirements — <ul>/<li> bullet lists of specific deliverables",
+        "4. Technical Notes — implementation guidance, constraints, <code>API endpoints</code>"
+      ],
+      formatting_rules: [
+        "Use <strong> for key terms and important concepts",
+        "Use <code> for file names, API endpoints, env vars, function names",
+        "Use <ul>/<li> for requirements and lists — NOT <p> with dashes",
+        "Every sentence should add value — avoid generic filler"
+      ],
+      example: "<p>As a project manager, I want to <strong>export project data</strong> in multiple formats, so that I can share reports with stakeholders.</p><h2>Requirements</h2><ul><li>Support CSV, JSON, and PDF export formats</li><li>Include all tickets, comments, and attachment metadata</li><li>Show a progress indicator for exports with more than 100 items</li></ul><h2>Technical Notes</h2><ul><li>Use the existing <code>/api/export</code> endpoint as a base</li><li>Implement streaming for large exports to avoid memory issues</li><li>Rate limit: max 5 exports per user per hour</li></ul>"
+    },
+    template_structures: {
+      description: "Use these <h2> sections based on the ticket typeSlug. Each section should have meaningful content.",
+      bug: ["Summary", "Steps to Reproduce", "Environment", "Screenshots / Logs"],
+      feature: ["Problem Statement", "Proposed Solution", "User Story", "Scope"],
+      task: ["Objective", "Background", "Technical Approach", "Files / Areas Affected", "Dependencies"],
+      story: ["User Story", "Context", "Design / Mockups", "Notes"],
+      improvement: ["Current Behavior", "Desired Behavior", "Why This Matters", "Proposed Changes"],
+      spike: ["Research Question", "Background", "Areas to Investigate", "Timebox", "Expected Output"],
+      docs: ["Documentation Type", "What Needs Documenting", "Target Audience", "Sections to Include"]
+    },
+    acceptance_criteria: {
+      priority: 'HIGH — ALWAYS include acceptance criteria when creating tickets. This is the primary definition of "done".',
+      format: 'JSON string of array: [{"id":"ac-1","text":"...","isChecked":false}]',
+      rules: [
+        "REQUIRED for every ticket — never skip acceptance criteria",
+        "Provide 3-7 specific, testable criteria per ticket",
+        'Use Given/When/Then format for behavioral criteria: "Given [precondition], when [action], then [expected result]"',
+        'For simpler criteria, use direct statements: "Users can export data in CSV format"',
+        "Include at least one happy-path criterion and one error/edge-case criterion",
+        'Each criterion must be verifiable — someone can clearly say "yes, met" or "no, not met"',
+        'Do NOT include vague criteria like "Code is clean" or "Feature works correctly"'
+      ],
+      example: '[{"id":"ac-1","text":"Given a user on the project settings page, when they select CSV format and click Export, then a CSV file downloads containing all tickets","isChecked":false},{"id":"ac-2","text":"Given an export with more than 100 items, when export is initiated, then a progress indicator is visible until completion","isChecked":false},{"id":"ac-3","text":"Given an export in progress, when it exceeds 30 seconds, then the user sees a timeout error with a retry option","isChecked":false}]',
+      id_format: "Use unique IDs (ac-1, ac-2, etc.). Set isChecked to false for new tickets. Max 10000 chars total."
+    },
+    tags: "Apply 2-5 tags per ticket AFTER creation using set_ticket_tags. Use lowercase-kebab-case. Common categories: feature area (auth, billing), technology (react, api), work type (feature, bug, refactor). Create missing tags with create_tag first.",
+    ticket_type: "Always set typeSlug when creating tickets. Common types: feature, bug, task, improvement, story, spike, docs. Use list_ticket_types to see project-specific types. The typeSlug determines which template_structure sections to use.",
+    related_tickets: "ALWAYS call find_similar_tickets before creating a ticket to check for duplicates and related work. If a related parent ticket exists, link via parentId when creating. Use get_ticket_children to view subtasks of a ticket.",
+    ai_workflow: "For best results, use the AI tools in this order: find_similar_tickets (check duplicates/related) → check_clarity (verify title) → generate_description (AI-generate HTML + acceptance criteria) → suggest_attributes (AI-suggest priority, size, tags) → create_ticket (ALWAYS include acceptanceCriteria + parentId if related) → set_ticket_tags. The generate_description tool gathers project context (related tickets, workflow) automatically."
   },
   categories: {
     "Organization & Context": {
@@ -29455,8 +29508,8 @@ var TOOL_INDEX = {
     }
   },
   common_workflows: {
-    "Create a high-quality ticket": "list_statuses + list_priorities + list_sizes + list_ticket_types + list_tags (cache IDs) → find_similar_tickets (check duplicates) → create_ticket (with description, acceptanceCriteria, typeSlug) → set_ticket_tags (add 2-5 tags)",
-    "AI-assisted ticket creation": "check_clarity → polish_title → generate_description → suggest_attributes → create_ticket → set_ticket_tags",
+    "Create a high-quality ticket": "list_statuses + list_priorities + list_sizes + list_ticket_types + list_tags (cache IDs) → find_similar_tickets (ALWAYS check for duplicates/related tickets — link via parentId if related) → create_ticket (with description, acceptanceCriteria [REQUIRED], typeSlug) → set_ticket_tags (add 2-5 tags)",
+    "AI-assisted ticket creation": "find_similar_tickets (check duplicates/related first) → check_clarity → polish_title → generate_description → suggest_attributes → create_ticket (ALWAYS include acceptanceCriteria + parentId if related ticket found) → set_ticket_tags",
     "Move through workflow": "get_available_transitions → move_ticket (or complete_ticket / abandon_ticket)",
     "Sprint planning": "create_release → list_backlog_tickets → assign_tickets_to_release",
     "Daily standup": "get_my_tickets + get_overdue_tickets + get_tickets_due_soon",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanbodev/mcp",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "MCP (Model Context Protocol) server for Kanbo - AI-native project management",
   "type": "module",
   "main": "dist/index.js",