devto-mcp 0.4.3 → 0.4.5

package/dist/index.js

@@ -68,20 +68,72 @@ DevTo connects to the developer's project tracker (Jira, Linear, etc.) and manag
 - When the developer asks to read comments on a ticket, use get_comments.
 
 ## Tools
-- get_project_summary — Lightweight snapshot of all active work. Call at session start.
+
+### Project Overview
+- get_project_summary — Lightweight snapshot of all active work with epic progress. Call at session start.
+- get_status — Aggregate project metrics (task counts, sprint info).
+- list_epics — List all epics with progress bars (done/in-progress/todo counts).
+- get_epic — Deep dive into a single epic: all child tasks + recent comments.
+
+### Planning
 - create_plan — AI-powered plan generation (epic + stories + subtasks). Returns preview only.
 - confirm_plan — Execute a previously previewed plan.
+
+### Issue Management
 - create_epic — Create a single epic.
-- create_task — Create a story/task, optionally linked to an epic.
+- create_task — Create a story/task, optionally linked to an epic via epic_key.
 - create_subtask — Create a subtask under a parent issue.
+- update_task — Update ANY field on a task: status, title, description, assignee, priority, labels, epic_key (link to epic), or add a comment. All fields optional except issue_key. Accepts natural language references.
+- update_epic — Update an epic's status, title, description, or add a comment.
+- delete_issue — Permanently delete any ticket. Cannot be undone.
 - get_tasks — Fetch open tasks. Optionally filter by epic.
-- update_task — Update task status AND/OR add a comment to a ticket. Accepts natural language references. You can: (1) change status only, (2) add a comment only, or (3) do both at once. When the developer says "add a comment to PROJ-5", use this tool with just the comment parameter and no status. When transitioning status, include a brief comment summarizing why.
-- get_comments — Read recent comments on a ticket. Use this when the developer asks to see comments, or before adding your own comment to understand existing context. Returns the 20 most recent comments.
-- list_epics — List all epics with progress breakdown (done/in-progress/todo counts). Use when the developer asks about epics, roadmap, or high-level progress.
-- update_epic — Update an epic's status, title, description, or add a comment. Accepts natural language references.
-- get_epic — Deep dive into a single epic: all child tasks with statuses plus recent comments.
-- delete_comment — Delete a comment by ID. Use get_comments first to find the comment ID you want to remove.
-- get_status — Aggregate project metrics and current sprint.`;
+
+### Comments
+- add_comment — Add a comment to any ticket. This is the simplest way to comment on a task, epic, or any issue.
+- get_comments — Read recent comments on a ticket (20 most recent).
+- delete_comment — Delete a comment by ID.
+
+### Sprint Management
+- list_sprints — See active and upcoming sprints.
+- create_sprint — Create a new sprint with optional start/end dates.
+- move_to_sprint — Move one or more issues into a sprint. Resolves sprint by name.
+- manage_sprint — Start or close a sprint.
+
+### Search
+- search_issues — Search for issues using JQL (Jira Query Language). Supports any valid JQL query.
+
+### Custom Fields
+- get_custom_fields — List available custom fields and their IDs. Use when setting custom_fields on create_task or update_task.
+
+### Issue Linking
+- link_issues — Link two issues together (e.g. blocks, duplicates, relates to). Use get_link_types to see available types.
+- get_issue_links — Get all links for an issue (blocks, duplicates, relates to, etc.).
+- get_link_types — List available issue link types with inward/outward descriptions.
+
+### Time Tracking
+- log_work — Log time spent on an issue. Time format: '2h', '30m', '1d', '2h 30m'.
+- get_worklog — Get work log entries for an issue. Shows who logged what time and when.
+- set_estimate — Set the time estimate for an issue. Format: '4h', '1d', '2w'.
+
+### Versions/Releases
+- list_versions — List all versions/releases for the project.
+- create_version — Create a new version/release.
+- release_version — Mark a version as released. Resolves by name.
+
+### Backlog
+- get_backlog — Get issues in the backlog (not assigned to any sprint).
+- move_to_backlog — Move issues from a sprint back to the backlog.
+
+### Bulk Operations
+- bulk_create_tasks — Create multiple tasks at once. Each task gets a title, description, optional type and epic_key.
+- bulk_update_tasks — Update multiple tasks at once. Useful for batch status changes.
+
+### Attachments
+- attach_file — Attach a local file to an issue. Reads from your filesystem.
+- list_attachments — List all attachments on an issue.
+
+### Watchers
+- manage_watchers — List, add, or remove watchers on an issue.`;
 const server = new index_js_1.Server({
     name: "devto",
     version: config_1.VERSION,
@@ -145,15 +197,19 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: "create_task",
-            description: "Create a single story or task, optionally linked to an epic. You can reference the epic by exact key or natural description.",
+            description: "Create a work item (Story, Bug, Task, or any type available in the project), optionally linked to an epic.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    title: { type: "string", description: "Task title" },
-                    description: { type: "string", description: "Task description" },
+                    title: { type: "string", description: "Title" },
+                    description: { type: "string", description: "Description" },
                     epic_key: {
                         type: "string",
-                        description: "Optional epic key (e.g. PROJ-1) or description to link this task to",
+                        description: "Optional epic key or description to link this task to",
+                    },
+                    type: {
+                        type: "string",
+                        description: "Issue type name (e.g. 'Story', 'Bug', 'Task'). Defaults to Story. Use get_status to see available types for this project.",
                     },
                 },
                 required: ["title", "description"],
@@ -191,7 +247,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: "update_task",
-            description: "Update a task's status and/or add a comment to any ticket. This is the PRIMARY way to add comments. You can: (1) change status only, (2) add a comment WITHOUT changing status — just pass comment alone, or (3) do both. Accepts natural language references (e.g. 'the auth task'). At least one of status or comment is required.",
+            description: "Update any field on a task: status, title, description, assignee, priority, labels, epic_key, or add a comment. This is also the PRIMARY way to add comments — just pass comment alone. Accepts natural language references (e.g. 'the auth task'). At least one field is required.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -201,7 +257,15 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                     },
                     status: {
                         type: "string",
-                        description: "New status: 'todo', 'in_progress', 'in_review', 'done', or any custom Jira status name (e.g. 'QA', 'Blocked'). Optional if adding a comment only.",
+                        description: "New status: 'todo', 'in_progress', 'in_review', 'done', or any custom Jira status name (e.g. 'QA', 'Blocked'). Optional.",
+                    },
+                    title: {
+                        type: "string",
+                        description: "New title/summary for the ticket. Use this to rename or fix typos.",
+                    },
+                    description: {
+                        type: "string",
+                        description: "New description for the ticket. Replaces the existing description.",
                     },
                     comment: {
                         type: "string",
@@ -263,8 +327,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                     },
                     status: {
                         type: "string",
-                        enum: ["todo", "in_progress", "in_review", "done"],
-                        description: "New status for the epic",
+                        description: "New status: 'todo', 'in_progress', 'in_review', 'done', or any custom Jira status name (e.g. 'QA', 'Blocked').",
                     },
                     title: {
                         type: "string",
@@ -314,6 +377,98 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                 required: ["issue_key", "comment_id"],
             },
         },
+        {
+            name: "add_comment",
+            description: "Add a comment to any ticket (task, epic, story, subtask). This is the simplest way to comment. Use this whenever the developer asks to add a comment.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    issue_key: {
+                        type: "string",
+                        description: "Issue key (e.g. PROJ-5) or natural language description",
+                    },
+                    comment: {
+                        type: "string",
+                        description: "The comment text to add",
+                    },
+                },
+                required: ["issue_key", "comment"],
+            },
+        },
+        {
+            name: "delete_issue",
+            description: "Permanently delete a ticket from your project. This cannot be undone. Use this when the developer asks to remove or delete a task, epic, story, or subtask.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    issue_key: {
+                        type: "string",
+                        description: "Issue key (e.g. PROJ-5) or natural language description of the issue to delete",
+                    },
+                },
+                required: ["issue_key"],
+            },
+        },
+        {
+            name: "list_sprints",
+            description: "List active and upcoming sprints for the project. Shows sprint name, state, and date range.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "create_sprint",
+            description: "Create a new sprint. Dates are optional — you can start the sprint later.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Sprint name (e.g. 'Sprint 5')" },
+                    start_date: { type: "string", description: "Start date (ISO 8601, e.g. '2026-03-24'). Optional." },
+                    end_date: { type: "string", description: "End date (ISO 8601, e.g. '2026-04-07'). Optional." },
+                },
+                required: ["name"],
+            },
+        },
+        {
+            name: "move_to_sprint",
+            description: "Move one or more issues into a sprint. You can reference the sprint by name or ID, and issues by key or natural language.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    sprint: {
+                        type: "string",
+                        description: "Sprint name (e.g. 'Sprint 5') or sprint ID number",
+                    },
+                    issue_keys: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Issue keys to move (e.g. ['PROJ-1', 'PROJ-2'])",
+                    },
+                },
+                required: ["sprint", "issue_keys"],
+            },
+        },
+        {
+            name: "manage_sprint",
+            description: "Start or close a sprint. Use 'start' to activate a future sprint, or 'close' to complete an active sprint.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    sprint: {
+                        type: "string",
+                        description: "Sprint name or ID",
+                    },
+                    action: {
+                        type: "string",
+                        enum: ["start", "close"],
+                        description: "Action to perform: 'start' or 'close'",
+                    },
+                },
+                required: ["sprint", "action"],
+            },
+        },
         {
             name: "get_status",
             description: "Get a summary of your project: task counts and current sprint",
@@ -323,6 +478,305 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                 required: [],
             },
         },
+        {
+            name: "search_issues",
+            description: "Search for issues using JQL (Jira Query Language). Examples: 'assignee = currentUser()', 'status = \"In Progress\"', 'labels = bug AND priority = High'.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    jql: {
+                        type: "string",
+                        description: "JQL query string",
+                    },
+                    max_results: {
+                        type: "number",
+                        description: "Maximum number of results to return (default 50)",
+                    },
+                },
+                required: ["jql"],
+            },
+        },
+        {
+            name: "get_custom_fields",
+            description: "List all custom fields available in the project. Shows field IDs needed when setting custom_fields on create_task or update_task.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "link_issues",
+            description: "Link two issues together (e.g. blocks, duplicates, relates to). Use get_link_types to see available link types.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    issue_key_1: {
+                        type: "string",
+                        description: "First issue key or natural language description",
+                    },
+                    issue_key_2: {
+                        type: "string",
+                        description: "Second issue key or natural language description",
+                    },
+                    link_type: {
+                        type: "string",
+                        description: "Link type name (e.g. 'Blocks', 'Duplicate', 'Relates')",
+                    },
+                },
+                required: ["issue_key_1", "issue_key_2", "link_type"],
+            },
+        },
+        {
+            name: "get_issue_links",
+            description: "Get all links for an issue (blocks, duplicates, relates to, etc.).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    issue_key: {
+                        type: "string",
+                        description: "Issue key (e.g. PROJ-5) or natural language description",
+                    },
+                },
+                required: ["issue_key"],
+            },
+        },
+        {
+            name: "get_link_types",
+            description: "List available issue link types (e.g. Blocks, Duplicate, Relates).",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "log_work",
+            description: "Log time spent on an issue. Time format: '2h', '30m', '1d', '2h 30m'.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    issue_key: {
+                        type: "string",
+                        description: "Issue key (e.g. PROJ-5) or natural language description",
+                    },
+                    time_spent: {
+                        type: "string",
+                        description: "Time spent (e.g. '2h', '30m', '1d', '2h 30m')",
+                    },
+                    comment: {
+                        type: "string",
+                        description: "Optional comment describing the work done",
+                    },
+                },
+                required: ["issue_key", "time_spent"],
+            },
+        },
+        {
+            name: "get_worklog",
+            description: "Get work log entries for an issue. Shows who logged what time and when.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    issue_key: {
+                        type: "string",
+                        description: "Issue key (e.g. PROJ-5) or natural language description",
+                    },
+                },
+                required: ["issue_key"],
+            },
+        },
+        {
+            name: "set_estimate",
+            description: "Set the time estimate for an issue. Format: '4h', '1d', '2w'.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    issue_key: {
+                        type: "string",
+                        description: "Issue key (e.g. PROJ-5) or natural language description",
+                    },
+                    estimate: {
+                        type: "string",
+                        description: "Time estimate (e.g. '4h', '1d', '2w')",
+                    },
+                },
+                required: ["issue_key", "estimate"],
+            },
+        },
+        {
+            name: "list_versions",
+            description: "List all versions/releases for the project.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "create_version",
+            description: "Create a new version/release for the project.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "Version name (e.g. 'v1.0.0')",
+                    },
+                    description: {
+                        type: "string",
+                        description: "Version description. Optional.",
+                    },
+                    release_date: {
+                        type: "string",
+                        description: "Planned release date (ISO 8601, e.g. '2026-04-01'). Optional.",
+                    },
+                },
+                required: ["name"],
+            },
+        },
+        {
+            name: "release_version",
+            description: "Mark a version as released. Resolves by name.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    version: {
+                        type: "string",
+                        description: "Version name (e.g. 'v1.0.0') or ID",
+                    },
+                },
+                required: ["version"],
+            },
+        },
+        {
+            name: "get_backlog",
+            description: "Get issues in the backlog (not assigned to any sprint).",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "move_to_backlog",
+            description: "Move issues from a sprint back to the backlog.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    issue_keys: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Issue keys to move to backlog (e.g. ['PROJ-1', 'PROJ-2'])",
+                    },
+                },
+                required: ["issue_keys"],
+            },
+        },
+        {
+            name: "bulk_create_tasks",
+            description: "Create multiple tasks at once. Each task gets a title, description, optional type and epic_key.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tasks: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                title: { type: "string", description: "Task title" },
+                                description: { type: "string", description: "Task description" },
+                                type: { type: "string", description: "Issue type (e.g. 'Story', 'Bug', 'Task'). Optional." },
+                                epic_key: { type: "string", description: "Epic key to link to. Optional." },
+                            },
+                            required: ["title", "description"],
+                        },
+                        description: "Array of tasks to create",
+                    },
+                },
+                required: ["tasks"],
+            },
+        },
+        {
+            name: "bulk_update_tasks",
+            description: "Update multiple tasks at once. Useful for batch status changes.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    updates: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                issue_key: { type: "string", description: "Issue key or natural language description" },
+                                status: { type: "string", description: "New status. Optional." },
+                                comment: { type: "string", description: "Comment to add. Optional." },
+                                assignee: { type: "string", description: "Assignee name. Optional." },
+                                priority: { type: "string", description: "Priority level. Optional." },
+                            },
+                            required: ["issue_key"],
+                        },
+                        description: "Array of updates to apply",
+                    },
+                },
+                required: ["updates"],
+            },
+        },
+        {
+            name: "attach_file",
+            description: "Attach a file from your local machine to a Jira issue. Provide the full file path.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    issue_key: {
+                        type: "string",
+                        description: "Issue key (e.g. PROJ-5) or natural language description",
+                    },
+                    file_path: {
+                        type: "string",
+                        description: "Absolute path to the file on your local machine",
+                    },
+                },
+                required: ["issue_key", "file_path"],
+            },
+        },
+        {
+            name: "list_attachments",
+            description: "List all attachments on an issue.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    issue_key: {
+                        type: "string",
+                        description: "Issue key (e.g. PROJ-5) or natural language description",
+                    },
+                },
+                required: ["issue_key"],
+            },
+        },
+        {
+            name: "manage_watchers",
+            description: "Manage watchers on an issue: list, add, or remove.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    issue_key: {
+                        type: "string",
+                        description: "Issue key (e.g. PROJ-5) or natural language description",
+                    },
+                    action: {
+                        type: "string",
+                        enum: ["list", "add", "remove"],
+                        description: "Action to perform: 'list', 'add', or 'remove'",
+                    },
+                    user_name: {
+                        type: "string",
+                        description: "Display name of the user (required for 'add' and 'remove' actions)",
+                    },
+                },
+                required: ["issue_key", "action"],
+            },
+        },
     ],
 }));
 // ─── Tool handler ────────────────────────────────────────────────────────────
@@ -356,6 +810,19 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
     }
     try {
         let result;
+        // Read-only mode: block all write operations
+        const READ_ONLY_TOOLS = new Set([
+            "get_project_summary", "get_status", "get_tasks", "get_comments", "list_epics",
+            "get_epic", "list_sprints", "search_issues", "get_custom_fields", "get_issue_links",
+            "get_link_types", "get_worklog", "list_versions", "get_backlog", "list_attachments",
+            // manage_watchers excluded — has write actions (add/remove)
+        ]);
+        if ((0, config_1.isReadOnly)() && !READ_ONLY_TOOLS.has(name)) {
+            return {
+                content: [{ type: "text", text: "DevTo is in **read-only mode** (DEVTO_READ_ONLY=true). Write operations are disabled. Remove the DEVTO_READ_ONLY environment variable to enable writes." }],
+                isError: true,
+            };
+        }
         switch (name) {
             case "get_project_summary":
                 result = await (0, tools_1.getProjectSummary)();
@@ -370,7 +837,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 result = await (0, tools_1.createEpic)(args?.title, args?.description);
                 break;
             case "create_task":
-                result = await (0, tools_1.createTask)(args?.title, args?.description, args?.epic_key);
+                result = await (0, tools_1.createTask)(args?.title, args?.description, args?.epic_key, args?.type);
                 break;
             case "create_subtask":
                 result = await (0, tools_1.createSubtask)(args?.title, args?.description, args?.parent_key);
@@ -379,7 +846,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 result = await (0, tools_1.getTasks)(args?.epic_key);
                 break;
             case "update_task":
-                result = await (0, tools_1.updateTask)(args?.issue_key, args?.status, args?.comment, args?.assignee, args?.priority, args?.labels, args?.epic_key);
+                result = await (0, tools_1.updateTask)(args?.issue_key, args?.status, args?.comment, args?.assignee, args?.priority, args?.labels, args?.epic_key, args?.title, args?.description);
                 break;
             case "get_comments":
                 result = await (0, tools_1.getComments)(args?.issue_key);
@@ -396,9 +863,81 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "delete_comment":
                 result = await (0, tools_1.deleteComment)(args?.issue_key, args?.comment_id);
                 break;
+            case "add_comment":
+                result = await (0, tools_1.addCommentTool)(args?.issue_key, args?.comment);
+                break;
+            case "delete_issue":
+                result = await (0, tools_1.deleteIssueTool)(args?.issue_key);
+                break;
+            case "list_sprints":
+                result = await (0, tools_1.listSprints)();
+                break;
+            case "create_sprint":
+                result = await (0, tools_1.createSprintTool)(args?.name, args?.start_date, args?.end_date);
+                break;
+            case "move_to_sprint":
+                result = await (0, tools_1.moveToSprintTool)(args?.sprint, args?.issue_keys);
+                break;
+            case "manage_sprint":
+                result = await (0, tools_1.manageSprintTool)(args?.sprint, args?.action);
+                break;
             case "get_status":
                 result = await (0, tools_1.getStatus)();
                 break;
+            case "search_issues":
+                result = await (0, tools_1.searchIssues)(args?.jql, args?.max_results);
+                break;
+            case "get_custom_fields":
+                result = await (0, tools_1.getCustomFields)();
+                break;
+            case "link_issues":
+                result = await (0, tools_1.linkIssues)(args?.issue_key_1, args?.issue_key_2, args?.link_type);
+                break;
+            case "get_issue_links":
+                result = await (0, tools_1.getIssueLinks)(args?.issue_key);
+                break;
+            case "get_link_types":
+                result = await (0, tools_1.getLinkTypes)();
+                break;
+            case "log_work":
+                result = await (0, tools_1.logWork)(args?.issue_key, args?.time_spent, args?.comment);
+                break;
+            case "get_worklog":
+                result = await (0, tools_1.getWorklog)(args?.issue_key);
+                break;
+            case "set_estimate":
+                result = await (0, tools_1.setEstimate)(args?.issue_key, args?.estimate);
+                break;
+            case "list_versions":
+                result = await (0, tools_1.listVersions)();
+                break;
+            case "create_version":
+                result = await (0, tools_1.createVersion)(args?.name, args?.description, args?.release_date);
+                break;
+            case "release_version":
+                result = await (0, tools_1.releaseVersion)(args?.version);
+                break;
+            case "get_backlog":
+                result = await (0, tools_1.getBacklog)();
+                break;
+            case "move_to_backlog":
+                result = await (0, tools_1.moveToBacklog)(args?.issue_keys);
+                break;
+            case "bulk_create_tasks":
+                result = await (0, tools_1.bulkCreateTasks)(args?.tasks);
+                break;
+            case "bulk_update_tasks":
+                result = await (0, tools_1.bulkUpdateTasks)(args?.updates);
+                break;
+            case "attach_file":
+                result = await (0, tools_1.attachFile)(args?.issue_key, args?.file_path);
+                break;
+            case "list_attachments":
+                result = await (0, tools_1.listAttachments)(args?.issue_key);
+                break;
+            case "manage_watchers":
+                result = await (0, tools_1.manageWatchers)(args?.issue_key, args?.action, args?.user_name);
+                break;
             default:
                 throw new types_js_1.McpError(types_js_1.ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
         }