@ezmodo/mcp-server 0.13.0

package/tools/recurring-tasks.js

@@ -0,0 +1,115 @@
+/**
+ * Recurring Task Schedule Tools
+ * MCP tools for the E-211 recurrence engine.
+ *
+ * A recurring task schedule is a durable record of "what task to create, on what
+ * cadence, until when" (e.g. "every weekday at 9am for three weeks, create a
+ * 'check app stats' task"). A scheduled runner instantiates the task each time
+ * the schedule fires. The payload is either an inline task definition or a
+ * reference to a work template (manage_work_template).
+ */
+
+import { TASK_TYPE_PROPERTY } from './task-type.js';
+
+const RECURRENCE_SCHEMA = {
+  type: 'object',
+  description: 'The recurrence spec. Occurrences fire at atHour:atMinute local to timezone.',
+  properties: {
+    frequency: {
+      type: 'string',
+      enum: ['daily', 'weekly', 'monthly'],
+      description: 'Base cadence.',
+    },
+    interval: {
+      type: 'number',
+      description: 'Every N units (e.g. interval 2 + weekly = biweekly). Must be >= 1. Default 1.',
+    },
+    byWeekdays: {
+      type: 'array',
+      items: { type: 'number' },
+      description: 'Weekly only: weekdays to fire on, 0=Sunday .. 6=Saturday. Required for weekly.',
+    },
+    byMonthDay: {
+      type: 'number',
+      description: 'Monthly only: day-of-month 1..31 (clamped to shorter months). Required for monthly.',
+    },
+    atHour: { type: 'number', description: 'Hour of day 0..23.' },
+    atMinute: { type: 'number', description: 'Minute of hour 0..59. Default 0.' },
+    timezone: { type: 'string', description: 'IANA timezone (e.g. "America/New_York"). Default "UTC".' },
+  },
+  required: ['frequency'],
+};
+
+const INLINE_TASK_SCHEMA = {
+  type: 'object',
+  description: 'Inline task definition to create each time the schedule fires (alternative to templateId).',
+  properties: {
+    title: { type: 'string', description: 'Task title (required for an inline schedule).' },
+    description: { type: 'string' },
+    steps: { type: 'array', items: { type: 'string' } },
+    priority: { type: 'string', enum: ['low', 'medium', 'high', 'urgent'] },
+    taskType: TASK_TYPE_PROPERTY,
+    componentId: { type: 'string' },
+    epicId: { type: 'string' },
+    tagIds: { type: 'array', items: { type: 'string' } },
+    assigneeId: { type: 'string' },
+    assigneeName: { type: 'string' },
+    assigneeType: { type: 'string', enum: ['human', 'ai'] },
+  },
+};
+
+export const RECURRING_TASK_TOOLS = [
+  {
+    name: 'manage_recurring_task',
+    description: 'Create, update, pause, resume, delete, list, or get a recurring task schedule ' +
+      '(E-211). A schedule creates a task on a cadence (e.g. "every weekday at 9am for three weeks"). ' +
+      'The payload is either an inlineTask definition OR a templateId (a work template). Returns the ' +
+      'schedule including its computed nextRunAt so you can confirm when it will next fire.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create', 'update', 'pause', 'resume', 'delete', 'list', 'get'],
+          description: 'Action to perform. "pause"/"resume" toggle whether the runner fires the ' +
+            'schedule (resume recomputes nextRunAt from now). "list" needs organizationId ' +
+            '(optionally projectId); "get"/"update"/"pause"/"resume"/"delete" need scheduleId.',
+        },
+        // --- Identifiers ---
+        organizationId: { type: 'string', description: 'Organization ID (required for create, list).' },
+        projectId: {
+          type: 'string',
+          description: 'Project the created task(s) belong to (required for create; optional filter for list).',
+        },
+        scheduleId: {
+          type: 'string',
+          description: 'Schedule ID (required for get, update, pause, resume, delete).',
+        },
+        // --- Create / update fields ---
+        title: {
+          type: 'string',
+          description: 'Human name for the schedule (required for create), e.g. "Daily app-stats check".',
+        },
+        recurrence: RECURRENCE_SCHEMA,
+        startsAt: {
+          type: 'string',
+          description: 'ISO 8601 timestamp: earliest the schedule may fire (required for create).',
+        },
+        until: {
+          type: 'string',
+          description: 'ISO 8601 timestamp end bound (optional). The schedule stops after this time.',
+        },
+        count: {
+          type: 'number',
+          description: 'Max number of occurrences (optional end bound). The schedule stops after this many tasks.',
+        },
+        templateId: {
+          type: 'string',
+          description: 'A work template to instantiate each fire (mutually exclusive with inlineTask).',
+        },
+        inlineTask: INLINE_TASK_SCHEMA,
+      },
+      required: ['action'],
+    },
+  },
+];

package/tools/tags.js

@@ -0,0 +1,219 @@
+/**
+ * Tag Tools
+ * MCP tools for managing tags (organization-scoped categorization)
+ *
+ * Consolidated: manage_tag (create/update/delete/merge/bulk_tag) + list_tags (get/list/find/suggest)
+ *
+ * NOTE for future sweeps: the `['task', 'epic', 'document', 'goal']` enums below
+ * are the TAGGABLE set, NOT the LINKABLE set. They are deliberately NOT
+ * `LINKABLE_TYPES` (tools/linkable-types.js) — entity_tags covers a different,
+ * smaller set of entities than entity_links, and widening these to the 14
+ * linkable types would offer agents combinations the tagging API rejects.
+ * Do not "fix" them to LINKABLE_TYPES.
+ */
+
+export const TAG_TOOLS = [
+  {
+    name: 'manage_tag',
+    description: 'Create, update, delete, merge, or bulk-apply tags. ' +
+      'Tags are organization-scoped categorization labels for tasks, epics, and other entities.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create', 'update', 'delete', 'merge', 'bulk_tag'],
+          description: 'Action to perform',
+        },
+        // --- Identifiers ---
+        tagId: {
+          type: 'string',
+          description: 'Tag ID (required for update, delete)',
+        },
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required for create, merge, bulk_tag)',
+        },
+        // --- Create fields ---
+        name: {
+          type: 'string',
+          description: 'Tag name (required for create, optional for update)',
+        },
+        color: {
+          type: 'string',
+          description: 'Hex color code e.g. "#FF5733" (required for create, optional for update)',
+        },
+        category: {
+          type: 'string',
+          enum: ['priority', 'status', 'type', 'team', 'customer', 'custom'],
+          description: 'Tag category (default: custom). Used by create and update.',
+        },
+        description: {
+          type: 'string',
+          description: 'Tag description. Used by create and update.',
+        },
+        aliases: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Alternative names for search/matching. Used by create and update.',
+        },
+        pinned: {
+          type: 'boolean',
+          description: 'Whether the tag should be pinned (shown prominently). Used by create and update.',
+        },
+        // --- Update-only fields ---
+        hidden: {
+          type: 'boolean',
+          description: 'Whether the tag should be hidden (update only)',
+        },
+        // --- Merge fields ---
+        sourceTagIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'IDs of tags to merge — will be deleted after merge (merge only)',
+        },
+        targetTagId: {
+          type: 'string',
+          description: 'ID of the tag to merge into — will be kept (merge only)',
+        },
+        createAlias: {
+          type: 'boolean',
+          description: 'Add source tag names as aliases to the target tag (merge only, default: true)',
+        },
+        // --- Bulk tag fields ---
+        tagIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'IDs of tags to apply (bulk_tag only)',
+        },
+        entities: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              entityType: {
+                type: 'string',
+                enum: ['task', 'epic', 'document', 'goal'],
+                description: 'Type of entity',
+              },
+              entityId: {
+                type: 'string',
+                description: 'ID of the entity',
+              },
+            },
+            required: ['entityType', 'entityId'],
+          },
+          description: 'List of entities to tag (bulk_tag only)',
+        },
+        operation: {
+          type: 'string',
+          enum: ['add', 'remove', 'set'],
+          description: 'Operation: add, remove, or set/replace all tags (bulk_tag only)',
+        },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name: 'list_tags',
+    description: 'List, get, find entities by tags, or get AI tag suggestions. ' +
+      'Modes: (1) Provide tagId for single tag lookup. ' +
+      '(2) Provide organizationId to list tags with optional filters. ' +
+      '(3) Set findEntities=true with tagIds array to search entities by tags. ' +
+      '(4) Set suggest=true with queryText for AI-powered tag suggestions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        // --- Single tag lookup ---
+        tagId: {
+          type: 'string',
+          description: 'Get a single tag by ID',
+        },
+        // --- List mode ---
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required for list, find, suggest modes)',
+        },
+        category: {
+          type: 'string',
+          enum: ['priority', 'status', 'type', 'team', 'customer', 'custom'],
+          description: 'Filter by tag category (list mode)',
+        },
+        projectId: {
+          type: 'string',
+          description: 'Filter by project ID (list and find modes)',
+        },
+        searchQuery: {
+          type: 'string',
+          description: 'Search query to filter tags by name, description, or aliases (list mode)',
+        },
+        pinnedOnly: {
+          type: 'boolean',
+          description: 'Only return pinned tags (list mode)',
+        },
+        includeHidden: {
+          type: 'boolean',
+          description: 'Include hidden tags in results (list mode)',
+        },
+        // --- Get by name (alternative to tagId) ---
+        name: {
+          type: 'string',
+          description: 'Tag name to look up (used with organizationId instead of tagId)',
+        },
+        // --- Find entities mode ---
+        findEntities: {
+          type: 'boolean',
+          description: 'Set to true to search for entities by tags',
+        },
+        tagIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'IDs of tags to filter by (findEntities mode)',
+        },
+        operator: {
+          type: 'string',
+          enum: ['AND', 'OR'],
+          description: 'Match all tags (AND) or any tag (OR) (findEntities mode, default: AND)',
+        },
+        entityTypes: {
+          type: 'array',
+          items: {
+            type: 'string',
+            enum: ['task', 'epic', 'document', 'goal'],
+          },
+          description: 'Types of entities to search (findEntities mode, default: all)',
+        },
+        epicId: {
+          type: 'string',
+          description: 'Scope search to a specific epic (findEntities mode)',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum results (findEntities default: 50, suggest default: 5)',
+        },
+        // --- Suggest mode ---
+        suggest: {
+          type: 'boolean',
+          description: 'Set to true for AI-powered tag suggestions',
+        },
+        queryText: {
+          type: 'string',
+          description: 'Text to find matching tags for, e.g. task title+description (suggest mode)',
+        },
+        entityType: {
+          type: 'string',
+          enum: ['task', 'epic', 'document', 'goal'],
+          description: 'Type of entity being tagged — for context (suggest mode)',
+        },
+        entityId: {
+          type: 'string',
+          description: 'ID of entity being tagged — for context (suggest mode)',
+        },
+        minSimilarity: {
+          type: 'number',
+          description: 'Minimum similarity threshold 0-1 (suggest mode, default: 0.3)',
+        },
+      },
+    },
+  },
+];

package/tools/task-item-schema.js

@@ -0,0 +1,57 @@
+/**
+ * Shared per-item task schema for the batch create paths.
+ *
+ * Two tools create tasks in bulk: `create_tasks` (a batch under an existing
+ * epic) and `manage_epic action:"create"` with a `tasks` array (an epic and its
+ * breakdown in one request, #2247). They accept the SAME item, and duplicating
+ * ~20 field descriptions across both is how the two drift apart — an agent then
+ * learns that a field it may pass to one is not accepted by the other.
+ *
+ * The shared part deliberately excludes projectId and epicId. Those are batch-
+ * level in `create_tasks` and fixed by the epic in the nested case, so each tool
+ * adds them (or does not) for itself.
+ */
+import { TASK_TYPE_PROPERTY } from './task-type.js';
+
+export const TASK_ITEM_PROPERTIES = {
+  title: { type: 'string', description: 'Task title (required)' },
+  description: {
+    type: 'string',
+    description: 'Task description (markdown). Explain WHY, WHERE and HOW, ' +
+      'referencing specific file paths — same guidance as manage_task.',
+  },
+  steps: {
+    type: 'array',
+    items: { type: 'string' },
+    description: 'Implementation steps referencing specific files',
+  },
+  priority: { type: 'string', enum: ['low', 'medium', 'high', 'urgent'] },
+  status: {
+    type: 'string',
+    enum: ['backlog', 'todo', 'in_progress', 'in_review', 'blocked', 'completed'],
+    description: 'Initial status (defaults to todo)',
+  },
+  taskType: TASK_TYPE_PROPERTY,
+  componentId: { type: 'string', description: 'DEPRECATED single component; overrides the shared componentId. Prefer componentIds.' },
+  componentIds: {
+    type: 'array',
+    items: { type: 'string' },
+    description: 'Every component this task touches; overrides the shared componentId/componentIds.',
+  },
+  parentTaskId: { type: 'string', description: 'Parent task link' },
+  estimatedHours: { type: 'number' },
+  assigneeType: { type: 'string', enum: ['human', 'ai'] },
+  assigneeId: { type: 'string' },
+  assigneeName: { type: 'string' },
+  tagIds: { type: 'array', items: { type: 'string' } },
+  origin: {
+    type: 'string',
+    enum: ['planned', 'discovered', 'scope-creep', 'rework', 'untracked'],
+  },
+  aiWork: { type: 'boolean' },
+  changedFiles: {
+    type: 'array',
+    items: { type: 'string' },
+    description: 'Repo-relative paths this task touches',
+  },
+};

package/tools/task-type.js

@@ -0,0 +1,33 @@
+/**
+ * The one definition of a task's kind.
+ *
+ * These four values are a Postgres enum (`task_type`, api migration 000001), so
+ * this list is not a convention the tools agree on — it is a constraint the
+ * database enforces, and a fifth value added here would be rejected on write.
+ *
+ * It lives in its own module because four unrelated tools need it and none of
+ * them owns it: `manage_task`, the shared batch item in `task-item-schema.js`,
+ * `manage_recurring_task` and `manage_work_template`. Three of those declared
+ * their own copy of the same four strings, and `manage_task` — the tool agents
+ * actually reach for — declared nothing at all, so a task's kind could be set
+ * in bulk but never set or changed one at a time.
+ */
+export const TASK_TYPES = ['feature', 'bug', 'testing', 'chore'];
+
+/**
+ * The property as it appears in a tool's inputSchema. `description` is worth
+ * carrying everywhere because task type is not decoration: it drives the
+ * per-area open-bug count on the project overview, the milestone freeze gates,
+ * and estimation weighting. An agent choosing a value should know that.
+ */
+export const TASK_TYPE_PROPERTY = {
+  type: 'string',
+  enum: TASK_TYPES,
+  description:
+    'The kind of work. Not cosmetic — "bug" feeds the per-area open-bug count ' +
+    'on the project overview, milestone freezes gate on it (a "stabilization" ' +
+    'freeze admits only bug and testing), and estimation weights past tasks of ' +
+    'the same kind more heavily. Omit it and the task is stored as "feature". ' +
+    'Prefer "testing" only for a task that verifies another task\'s work; it ' +
+    'is expected to carry parentTaskId and drives the testing-split flow.',
+};