automd-mcp 0.2.0 → 0.2.2

package/dist/index.js

@@ -40506,6 +40506,16 @@ var api = {
     body: JSON.stringify(data)
   }),
   deleteProject: (id) => request(`/api/projects/${id}`, { method: "DELETE" }),
+  // Tags
+  getTags: (projectId) => {
+    const query = new URLSearchParams();
+    if (projectId) query.set("projectId", projectId);
+    return request(`/api/tags?${query.toString()}`);
+  },
+  updateInstanceTags: (tags) => request("/api/tags", {
+    method: "PUT",
+    body: JSON.stringify({ tags })
+  }),
   // Health
   health: () => request("/api/health")
 };
@@ -40524,7 +40534,7 @@ function errorResponse(err) {
 function registerTools(server2) {
   server2.registerTool("list_items", {
     title: "List Items",
-    description: "List all items (boards, checklists, and pages) with their task counts"
+    description: "List all items (boards, checklists, pages, and knowledge bases) with their task counts. Returns array of {id, name, itemType, projectId, taskCount}."
   }, async () => {
     try {
       const items = await api.listFiles();
@@ -40535,8 +40545,8 @@ function registerTools(server2) {
   });
   server2.registerTool("get_item", {
     title: "Get Item",
-    description: "Get an item (board, checklist, or page) with its columns and tasks",
-    inputSchema: { itemId: external_exports.string().describe("The item ID") }
+    description: "Get an item (board, checklist, page, or knowledge base) with its columns and tasks",
+    inputSchema: { itemId: external_exports.string().describe("The item ID (obtain from list_items)") }
   }, async ({ itemId }) => {
     try {
       const item = await api.getFile(itemId);
@@ -40559,11 +40569,11 @@ function registerTools(server2) {
   });
   server2.registerTool("create_item", {
     title: "Create Item",
-    description: "Create a new board, checklist, or page. Boards use # (H1) for columns and ## (H2) for tasks. Checklists use ## (H2) with [ ]/[x] prefixes. Pages are free-form markdown for knowledge, specs, and documentation. All support YAML frontmatter, plain paragraphs (description), blockquotes (>) for acceptance criteria, and GFM checkboxes for subtasks.",
+    description: "Create a new board, checklist, page, or knowledge base. Boards use # (H1) for columns and ## (H2) for tasks. Checklists use ## (H2) with [ ]/[x] prefixes. Pages are free-form markdown. Knowledge bases are structured collections of entries (## H2) without checkboxes or progress \u2014 ideal for decisions, patterns, and reference material. All support YAML frontmatter, descriptions, blockquotes (>) for acceptance criteria, and GFM checkboxes for subtasks.",
     inputSchema: {
       name: external_exports.string().describe("Name for the new item"),
-      itemType: external_exports.enum(["board", "checklist", "page"]).optional().describe("Type of item to create: board (kanban columns), checklist (task list with checkboxes), or page (free-form markdown for knowledge and documentation). Defaults to board"),
-      markdown: external_exports.string().optional().describe("Initial markdown content. Start with YAML frontmatter (board:, description:). Use # for columns, ## for tasks. Paragraphs = description, blockquotes (>) = acceptance criteria, checkboxes = subtasks"),
+      itemType: external_exports.enum(["board", "checklist", "page", "knowledge"]).optional().describe("Type of item to create: board (kanban columns), checklist (task list with checkboxes), page (free-form markdown), or knowledge (structured entries without checkboxes/progress). Defaults to board"),
+      markdown: external_exports.string().optional().describe("Initial markdown content. Omit for an empty item. For boards: use # for columns, ## for tasks. For checklists: ## with [ ] prefix. For pages/knowledge: free-form markdown. All types support YAML frontmatter (board:, description:, vocabulary:)."),
       projectId: external_exports.string().optional().describe("Project ID to add the item to (optional)")
     }
   }, async ({ name, itemType, markdown, projectId }) => {
@@ -40605,10 +40615,10 @@ function registerTools(server2) {
   });
   server2.registerTool("add_task", {
     title: "Add Task",
-    description: "Add a new task (H2 heading) to a column. Content supports inline metadata like @user #label priority:high due:2025-03-20 est:4h",
+    description: "Add a new task (## H2 heading) to a column. Content supports inline metadata: @user #label priority:high|medium|low due:YYYY-MM-DD est:4h knowledge:true. Do not include built-by: manually \u2014 use the agentName parameter. Call list_tags to discover existing labels before inventing new ones.",
     inputSchema: {
       itemId: external_exports.string().describe("The item ID"),
-      columnId: external_exports.string().describe("The column/heading ID to add the task to"),
+      columnId: external_exports.string().describe("The column ID (found in get_item response columns[].id)"),
       content: external_exports.string().describe("Task content with optional inline metadata"),
       agentName: external_exports.string().regex(/^[\w-]+$/).optional().describe("Name of the agent making this change (tagged as built-by)")
     }
@@ -40623,10 +40633,10 @@ function registerTools(server2) {
   });
   server2.registerTool("update_task", {
     title: "Update Task",
-    description: "Update a task's content",
+    description: "Update a task's title/content text only. For metadata use update_task_metadata, for completion use toggle_task, for position use move_task, for AC use update_acceptance_criteria, for learnings use update_learnings.",
     inputSchema: {
       itemId: external_exports.string().describe("The item ID"),
-      taskId: external_exports.string().describe("The task ID"),
+      taskId: external_exports.string().describe("The task ID (found in get_item response columns[].tasks[].id)"),
       content: external_exports.string().optional().describe("New task content"),
       agentName: external_exports.string().regex(/^[\w-]+$/).optional().describe("Name of the agent making this change (tagged as built-by)")
     }
@@ -40647,7 +40657,7 @@ function registerTools(server2) {
   });
   server2.registerTool("toggle_task", {
     title: "Toggle Task",
-    description: "Toggle a task between checked and unchecked",
+    description: "Toggle a task between checked [ ] and unchecked [x]. Only applies to tasks with checkbox prefixes. Sets completedAt on check, clears on uncheck.",
     inputSchema: {
       itemId: external_exports.string().describe("The item ID"),
       taskId: external_exports.string().describe("The task ID")
@@ -40667,7 +40677,7 @@ function registerTools(server2) {
       itemId: external_exports.string().describe("The item ID"),
       taskId: external_exports.string().describe("The task ID"),
       targetColumnId: external_exports.string().describe("Target column ID"),
-      targetIndex: external_exports.number().describe("Position in the target column (0-based)")
+      targetIndex: external_exports.number().describe("Position in target column (0-based). Use 0 to place at top. To append, use the column task count from get_item.")
     }
   }, async ({ itemId, taskId, targetColumnId, targetIndex }) => {
     try {
@@ -40698,7 +40708,7 @@ function registerTools(server2) {
   });
   server2.registerTool("add_column", {
     title: "Add Column",
-    description: "Add a new column (H1 heading) to an item",
+    description: 'Add a new column (# H1 heading) to a board or checklist. Columns group tasks into workflow stages like "To Do", "In Progress", "Done".',
     inputSchema: {
       itemId: external_exports.string().describe("The item ID"),
       title: external_exports.string().describe("Column title")
@@ -40750,7 +40760,7 @@ function registerTools(server2) {
   });
   server2.registerTool("update_task_metadata", {
     title: "Update Task Metadata",
-    description: "Update a task's metadata (priority, assignees, labels, due date, estimate) without rewriting its content",
+    description: "Update a task's metadata (priority, assignees, labels, due date, estimate) without rewriting its content. Call list_tags to discover existing labels before adding new ones.",
     inputSchema: {
       itemId: external_exports.string().describe("The item ID"),
       taskId: external_exports.string().describe("The task ID"),
@@ -40834,7 +40844,9 @@ function registerTools(server2) {
         targetColumnId: external_exports.string().optional().describe("Target column (for move)"),
         targetIndex: external_exports.number().optional().describe("Target index (for move)"),
         displayContent: external_exports.string().optional().describe("Display content (for updateMetadata)"),
-        metadata: external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe("Metadata fields (for updateMetadata)")
+        metadata: external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe("Metadata fields (for updateMetadata)"),
+        acceptanceCriteria: external_exports.string().nullable().optional().describe("Acceptance criteria text (for updateAcceptanceCriteria). Pass null to remove."),
+        learnings: external_exports.string().nullable().optional().describe("Learnings text (for updateLearnings). Pass null to remove.")
       })).describe("Array of task updates to apply")
     }
   }, async ({ itemId, agentName, updates }) => {
@@ -40869,7 +40881,7 @@ function registerTools(server2) {
   });
   server2.registerTool("search_tasks", {
     title: "Search Tasks",
-    description: "Search for tasks across all items by text, assignee, label, or status",
+    description: "Search for tasks across all items by text, assignee, label, or status. Use list_tags to discover valid label values.",
     inputSchema: {
       query: external_exports.string().optional().describe("Text to search for in task content"),
       assignee: external_exports.string().optional().describe("Filter by assignee (without @)"),
@@ -40913,7 +40925,7 @@ function registerTools(server2) {
   });
   server2.registerTool("search_context", {
     title: "Search Context",
-    description: 'Search for institutional knowledge across all items. Searches task descriptions, acceptance criteria, and learnings \u2014 not just titles. Use this to find relevant context before starting work on a task (e.g. "what do we know about auth?" or "what was learned about pricing?").',
+    description: "Search for contextual detail (descriptions, acceptance criteria, learnings) across all items. Returns any task with rich content \u2014 broader than find_knowledge which only returns knowledge:true items. Use this for finding implementation details, past decisions, and context before starting work. Use list_tags to discover valid label values.",
     inputSchema: {
       query: external_exports.string().optional().describe("Text to search for across descriptions, AC, learnings, and task content"),
       label: external_exports.string().optional().describe("Filter by label (without #). Also matches #tags inside learnings text."),
@@ -40934,14 +40946,18 @@ function registerTools(server2) {
                 task.content,
                 task.description,
                 task.acceptanceCriteria,
-                task.learnings
+                task.learnings,
+                ...item.meta?.tags ?? []
               ].filter(Boolean).join(" ").toLowerCase();
               let match = true;
               if (q && !searchable.includes(q)) match = false;
               if (label) {
                 const hasLabel = task.metadata.labels.includes(label);
                 const hasInlineLabelTag = searchable.includes(`#${label.toLowerCase()}`);
-                if (!hasLabel && !hasInlineLabelTag) match = false;
+                const hasFrontmatterTag = item.meta?.tags?.some(
+                  (t) => t.toLowerCase() === label.toLowerCase()
+                );
+                if (!hasLabel && !hasInlineLabelTag && !hasFrontmatterTag) match = false;
               }
               const hasContext = task.description || task.acceptanceCriteria || task.learnings;
               if (!hasContext) match = false;
@@ -40972,7 +40988,7 @@ function registerTools(server2) {
   });
   server2.registerTool("list_projects", {
     title: "List Projects",
-    description: "List all projects"
+    description: "List all projects with their curated tags. Returns array of {id, name, color, tags}. Use project id as projectId in create_item, get_project_items, or list_tags."
   }, async () => {
     try {
       const projects = await api.listProjects();
@@ -41013,9 +41029,23 @@ function registerTools(server2) {
       return errorResponse(err);
     }
   });
+  server2.registerTool("list_tags", {
+    title: "List Tags",
+    description: "Discover available tags/labels before searching or tagging content. Returns curated tags (defined by humans), project-specific tags, and tags already in use across items. ALWAYS call this before inventing new tags \u2014 reuse existing ones to keep the knowledge base consistent.",
+    inputSchema: {
+      projectId: external_exports.string().optional().describe("Optional project ID to scope tags to a specific project")
+    }
+  }, async ({ projectId }) => {
+    try {
+      const result = await api.getTags(projectId);
+      return json2(result);
+    } catch (err) {
+      return errorResponse(err);
+    }
+  });
   server2.registerTool("add_knowledge", {
     title: "Add Knowledge",
-    description: "Add a knowledge item. Knowledge items are tasks with knowledge:true \u2014 they store decisions, patterns, references, and institutional memory. They reuse the task infrastructure but skip the checkbox/completion workflow.",
+    description: "Add a knowledge item. Knowledge items are tasks with knowledge:true \u2014 they store decisions, patterns, references, and institutional memory. They reuse the task infrastructure but skip the checkbox/completion workflow. Call list_tags first to reuse existing labels.",
     inputSchema: {
       itemId: external_exports.string().describe("The item ID"),
       columnId: external_exports.string().describe("The column ID"),
@@ -41095,7 +41125,7 @@ function registerTools(server2) {
   });
   server2.registerTool("find_knowledge", {
     title: "Find Knowledge",
-    description: "Search for knowledge items across all items. Returns tasks with knowledge:true OR tasks that have learnings. Use this to find institutional memory, past decisions, and patterns.",
+    description: "Search specifically for curated knowledge items (knowledge:true) and tasks with captured learnings. Use for institutional decisions, patterns, and reference. For broader task history including descriptions, use search_context instead. Use list_tags to discover valid label values.",
     inputSchema: {
       query: external_exports.string().optional().describe("Text to search for in knowledge items"),
       label: external_exports.string().optional().describe("Filter by label (without #)")
@@ -41118,14 +41148,18 @@ function registerTools(server2) {
                   task.content,
                   task.description,
                   task.acceptanceCriteria,
-                  task.learnings
+                  task.learnings,
+                  ...item.meta?.tags ?? []
                 ].filter(Boolean).join(" ").toLowerCase();
                 if (!searchable.includes(q)) continue;
               }
               if (label) {
                 const hasLabel = task.metadata?.labels?.includes(label);
                 const hasInlineTag = task.learnings?.toLowerCase().includes(`#${label.toLowerCase()}`);
-                if (!hasLabel && !hasInlineTag) continue;
+                const hasFrontmatterTag = item.meta?.tags?.some(
+                  (t) => t.toLowerCase() === label.toLowerCase()
+                );
+                if (!hasLabel && !hasInlineTag && !hasFrontmatterTag) continue;
               }
               results.push({
                 itemId: itemSummary.id,
@@ -41153,7 +41187,7 @@ function registerTools(server2) {
     description: "Gather all knowledge about a topic and return a structured summary. This collects and organizes existing knowledge items \u2014 it does NOT generate AI content. Returns a paste-ready context brief.",
     inputSchema: {
       topic: external_exports.string().describe('Topic to synthesize knowledge about (e.g. "authentication", "pricing", "deployment")'),
-      labels: external_exports.string().optional().describe('Comma-separated labels to filter by (e.g. "backend,security")')
+      labels: external_exports.string().optional().describe('Comma-separated labels to filter by (e.g. "backend,security"). Unlike label on other tools which takes a single value, this accepts multiple comma-separated.')
     }
   }, async ({ topic, labels }) => {
     try {
@@ -41340,12 +41374,13 @@ function registerSystemPrompts(server2) {
 
 ## Core Concepts
 
-AutoMD has three item types:
+AutoMD has four item types:
 - **Boards** \u2014 Kanban-style markdown files with columns (H1) and tasks (H2). Each has YAML frontmatter with metadata.
 - **Checklists** \u2014 Task lists using ## (H2) headings with [ ]/[x] checkbox prefixes. Great for simple to-do lists and tracking.
-- **Pages** \u2014 Free-form markdown documents for knowledge, specs, documentation, and reference material.
+- **Pages** \u2014 Free-form markdown documents for specs, documentation, and reference material.
+- **Knowledge Bases** \u2014 Structured collections of knowledge entries (## H2) without checkboxes or progress tracking. Ideal for decisions, patterns, and institutional memory.
 
-All three types support YAML frontmatter, descriptions, acceptance criteria, subtasks, and learnings.
+All four types support YAML frontmatter, descriptions, acceptance criteria, subtasks, and learnings.
 
 **Knowledge items** are tasks with \`knowledge:true\` \u2014 they store decisions, patterns, references, and institutional memory. They use the same task infrastructure but represent knowledge, not work to be done.
 
@@ -41389,7 +41424,7 @@ Description paragraph \u2014 background, context, the "why".
 - Use \`synthesize_topic\` to assemble context briefs about a topic
 
 ## Available Tools
-- Item management: list_items, get_item, create_item (supports board/checklist/page types), delete_item, rename_item
+- Item management: list_items, get_item, create_item (supports board/checklist/page/knowledge types), delete_item, rename_item
 - Task management: add_task, update_task, toggle_task, move_task, delete_task
 - Metadata: update_task_metadata, update_acceptance_criteria, update_learnings
 - Knowledge: add_knowledge, update_knowledge, find_knowledge, synthesize_topic, import_memories
@@ -41433,7 +41468,7 @@ Please:
 3. Identify any dependencies between subtasks
 4. Suggest which subtasks could be parallelized
 
-Provide the specific add_subtask tool calls to create each subtask.`
+Subtasks are GFM checkboxes (\`- [ ] text\`) inside the parent task's content. Use update_task to add them to the parent task's body, or use add_task to create standalone tasks.`
         }
       }]
     };
@@ -41741,7 +41776,7 @@ Analyze completed tasks and the board state to provide:
 3. **Action Items** \u2014 Concrete improvements for next iteration
 4. **Learnings to Capture** \u2014 Key decisions and patterns worth preserving as knowledge items
 
-For each learning worth capturing, provide add_knowledge or add_learning tool calls so they're preserved for future reference.`
+For each learning worth capturing, provide add_knowledge tool calls for new knowledge items, or update_learnings tool calls to attach learnings to existing tasks.`
         }
       }]
     };

package/package.json

@@ -1,40 +1,41 @@
-{
-  "name": "automd-mcp",
-  "version": "0.2.0",
-  "description": "MCP server for AutoMD — manage boards, checklists, and pages stored as markdown",
-  "type": "module",
-  "main": "./dist/index.js",
-  "bin": {
-    "automd-mcp": "./dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "kanban",
-    "markdown",
-    "automd",
-    "task-management"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/luka-zivkovic/automd"
-  },
-  "license": "SEE LICENSE IN LICENSE",
-  "author": "Luka Zivkovic",
-  "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "@types/mdast": "^4.0.4",
-    "tsup": "^8.0.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.2",
-    "zod": "^4.3.6"
-  },
-  "scripts": {
-    "dev": "tsx watch src/index.ts",
-    "start": "node dist/index.js",
-    "build": "tsup"
-  }
-}
+{
+  "name": "automd-mcp",
+  "version": "0.2.2",
+  "description": "MCP server for AutoMD — manage boards, checklists, and pages stored as markdown",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "automd-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "build": "tsup",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "kanban",
+    "markdown",
+    "automd",
+    "task-management"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/luka-zivkovic/automd"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Luka Zivkovic",
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@types/mdast": "^4.0.4",
+    "tsup": "^8.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.2",
+    "zod": "^4.3.6"
+  }
+}

package/LICENSE.md

@@ -1,60 +0,0 @@
-# License
-
-Portions of this software are licensed as follows:
-
-- Content of branches other than the main branch (i.e. "master") is not licensed.
-- Source code files that contain ".ee." in their filename or ".ee" in their dirname are NOT licensed under the Sustainable Use License. To use source code files that contain ".ee." in their filename or ".ee" in their dirname you must hold a valid AutoMD Enterprise License specifically allowing you access to such source code files, as defined in "LICENSE_EE.md".
-- All third party components incorporated into the AutoMD Software are licensed under the original license provided by the owner of the applicable component.
-- Content outside of the above mentioned files or restrictions is available under the "Sustainable Use License" as defined below.
-
-# Sustainable Use License
-
-Version 1.0
-
-## Acceptance
-
-By using the software, you agree to all of the terms and conditions below.
-
-## Copyright License
-
-The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations below.
-
-## Limitations
-
-You may use or modify the software only for your own internal business purposes or for non-commercial or personal use. You may distribute the software or provide it to others only if you do so free of charge for non-commercial purposes. You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software. You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key. You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor's trademarks is subject to applicable law.
-
-## Patents
-
-The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
-
-## Notices
-
-You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms. If you modify the software, you must include in any modified copies of the software a prominent notice stating that you have modified the software.
-
-## No Other Rights
-
-These terms do not imply any licenses other than those expressly granted in these terms.
-
-## Termination
-
-If you use the software in violation of these terms, such use is not licensed, and your license will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your license will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your license to terminate automatically and permanently.
-
-## No Liability
-
-As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
-
-## Definitions
-
-The **licensor** is the entity offering these terms, AutoMD (automd.io).
-
-The **software** is the software the licensor makes available under these terms, including any portion of it.
-
-**You** refers to the individual or entity agreeing to these terms.
-
-**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. Control means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
-
-**Your license** is the license granted to you for the software under these terms.
-
-**Use** means anything you do with the software requiring your license.
-
-**Trademark** means trademarks, service marks, and similar rights.