@ezmodo/mcp-server 0.13.0

package/tools/entities.js

@@ -0,0 +1,223 @@
+/**
+ * Entity Management Tools
+ * MCP tools for managing goals, teams, and labels
+ *
+ * Consolidated: manage_goal (create/update/delete), manage_team (create), get_goal (get/list)
+ */
+
+export const ENTITY_TOOLS = [
+  {
+    name: 'manage_goal',
+    description: 'Create, update, or delete organization-wide strategic goals, or ' +
+      '(re)generate a goal\'s grounded "how it works" living description.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create', 'update', 'delete', 'generate_how_it_works', 'apply_how_it_works'],
+          description: 'Action to perform. "generate_how_it_works" (re)generates the ' +
+            'goal\'s grounded, source-attributed "how it works" living description from ' +
+            'its linked work (requires goalId; AI-quota gated). "apply_how_it_works" (BYO-AI) ' +
+            'persists a summary YOU authored (markdown + sources); the server validates your cited ' +
+            'sources against the real grounded context before saving — no server model call. Read ' +
+            'the result back via get_goal.',
+        },
+        // --- Identifiers ---
+        goalId: {
+          type: 'string',
+          description: 'Goal ID (required for update, delete, generate_how_it_works, apply_how_it_works)',
+        },
+        // --- apply_how_it_works (BYO-AI) ---
+        markdown: {
+          type: 'string',
+          description: 'Rendered markdown body for apply_how_it_works (the how-it-works YOU authored).',
+        },
+        sources: {
+          type: 'object',
+          description: 'Structured backing for apply_how_it_works: { claims: [{ text, sources: [ref...], ' +
+            'confidence: "grounded"|"unverified" }], divergences: [{ intent, reality, severity }] }. Cite ' +
+            'real source refs from the goal\'s grounded context; the server drops fabricated ones.',
+        },
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required for create)',
+        },
+        // --- Create fields ---
+        title: {
+          type: 'string',
+          description: 'Goal title (required for create, optional for update)',
+        },
+        description: {
+          type: 'string',
+          description: 'Goal description — supports markdown. Used by create and update.',
+        },
+        targetDate: {
+          type: 'string',
+          description: 'Target completion date (RFC3339 format, e.g., 2026-03-31T00:00:00Z). Used by create and update.',
+        },
+        status: {
+          type: 'string',
+          enum: ['active', 'completed', 'archived'],
+          description: 'Goal status (default: active). Used by create and update.',
+        },
+        parentGoalId: {
+          type: 'string',
+          description: 'Parent goal ID for goal hierarchy (create only)',
+        },
+        metrics: {
+          type: 'array',
+          description: 'Goal metrics. Used by create and update.',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+              name: { type: 'string' },
+              target: { type: 'number' },
+              unit: { type: 'string' },
+              current: { type: 'number' },
+              description: { type: 'string' },
+            },
+            required: ['name', 'target', 'unit'],
+          },
+        },
+        linkedMilestones: {
+          type: 'array',
+          description: 'Milestones to link to this goal. Used by create and update.',
+          items: {
+            type: 'object',
+            properties: {
+              projectId: { type: 'string', description: 'Project ID containing the milestone' },
+              milestoneId: { type: 'string', description: 'Milestone ID to link' },
+            },
+            required: ['projectId', 'milestoneId'],
+          },
+        },
+        epicIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Array of linked epic IDs (update only)',
+        },
+        labels: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Array of label IDs. Used by create and update.',
+        },
+        teamIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Array of team IDs responsible for this goal. Used by create and update.',
+        },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name: 'manage_team',
+    description: 'Create a team within an organization.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create'],
+          description: 'Action to perform',
+        },
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required for create)',
+        },
+        name: {
+          type: 'string',
+          description: 'Team name (required for create)',
+        },
+        description: {
+          type: 'string',
+          description: 'Team description',
+        },
+        memberIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Array of user IDs to add as team members',
+        },
+        slug: {
+          type: 'string',
+          description: 'URL-friendly slug (e.g., "frontend-team")',
+        },
+        color: {
+          type: 'string',
+          description: 'Hex color for visual identification (e.g., "#3B82F6")',
+        },
+        leaderId: {
+          type: 'string',
+          description: 'User ID of team lead/manager',
+        },
+        sprintOverride: {
+          type: 'object',
+          description: 'Sprint configuration override',
+          properties: {
+            enabled: { type: 'boolean' },
+            duration: { type: 'number', enum: [7, 10, 14, 21] },
+            startDate: { type: 'string', description: 'RFC3339 format (e.g., 2026-01-01T00:00:00Z)' },
+            offset: { type: 'number', description: 'Days offset from org sprint' },
+          },
+        },
+        capacityOverrides: {
+          type: 'array',
+          description: 'Individual capacity overrides per member',
+          items: {
+            type: 'object',
+            properties: {
+              memberId: { type: 'string' },
+              pointsPerSprint: { type: 'number' },
+            },
+          },
+        },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name: 'get_goal',
+    description: 'Retrieve a single goal or list all goals. ' +
+      'Modes: (1) Provide goalId for single lookup. ' +
+      '(2) Provide organizationId + goalNumber for number lookup. ' +
+      '(3) Provide organizationId to list all goals with optional filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        // --- Single goal lookup ---
+        goalId: {
+          type: 'string',
+          description: 'Document ID of the goal to retrieve',
+        },
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required for goalNumber lookup or listing)',
+        },
+        goalNumber: {
+          type: 'number',
+          description: 'Sequential goal number (e.g., 7 for goal g-7). Must be used with organizationId.',
+        },
+        includeEpics: {
+          type: 'boolean',
+          description: 'Include linked epic details (single goal mode)',
+        },
+        // --- List filters ---
+        status: {
+          type: 'string',
+          enum: ['active', 'completed', 'archived'],
+          description: 'Filter by goal status (list mode)',
+        },
+        teamId: {
+          type: 'string',
+          description: 'Filter by team assignment (list mode)',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results (list mode, default: 50)',
+        },
+      },
+    },
+  },
+];

package/tools/epics.js

@@ -0,0 +1,267 @@
+/**
+ * Epic Tools
+ * MCP tools for managing epics
+ *
+ * Project-First Hierarchy: Epics belong to projects (required),
+ * with optional component grouping and milestone linking. *
+ * NAMING (E-107): an epic is not called "Epic" everywhere. A project's type
+ * decides its vocabulary — a marketing project calls this a Campaign, a sales
+ * project a Deal, a research project a Study. Read the words from
+ * `get_current_project_context().terminology` (or `get_project`) and use them in
+ * anything a person reads. The field names here — epicId, epicNumber — never
+ * change.
+ */
+
+import { LINKS_ARRAY_SCHEMA, RELATED_ITEM_SCHEMA } from './link-params.js';
+import { TASK_ITEM_PROPERTIES } from './task-item-schema.js';
+
+export const EPIC_TOOLS = [
+  {
+    name: 'manage_epic',
+    description: 'Create or update an epic within a project. Epics belong to projects (required). ' +
+      'IMPORTANT when creating: Call get_context first for each area the epic covers to discover relevant ' +
+      'files and integration points. Include in the description which layers/services are affected and ' +
+      'reference specific file paths. Create child tasks that each reference specific files from context queries. ' +
+      'Auto-applies matching tags from cached project context based on content analysis. ' +
+      'To align an epic to an organization goal, link it to a milestone that is linked to that goal ' +
+      '(set milestoneId) — epics have no direct goal field. ' +
+      'BREAKING DOWN A FEATURE: pass the child tasks in the `tasks` array on create and the epic and its ' +
+      'whole breakdown are created in ONE request — do not follow a create with a separate create_tasks call. ' +
+      'Besides the saved request, it removes the gap between the two: a failure part-way can no longer ' +
+      'leave an epic with no tasks that you then have to reconcile.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create', 'update', 'generate_how_it_works', 'apply_how_it_works'],
+          description: 'Action to perform. "generate_how_it_works" (re)generates the epic\'s grounded, ' +
+            'source-attributed "how it works" living description from its reality — its tasks\' status ' +
+            'rollup, their captured decisions and their linked commits (requires epicId; AI-quota gated). ' +
+            'An epic is where intent and reality drift furthest apart: intent is a charter written once, ' +
+            'reality is months of accumulated work. "apply_how_it_works" (BYO-AI) persists a summary YOU ' +
+            'authored: pass markdown + sources; the server validates your cited sources against the real ' +
+            'grounded context (dropping fabricated ones) before saving — no server model call.',
+        },
+        // --- Identifiers ---
+        epicId: {
+          type: 'string',
+          description: 'Epic ID (required for update, generate_how_it_works, apply_how_it_works)',
+        },
+        markdown: {
+          type: 'string',
+          description: 'Rendered markdown body for apply_how_it_works (the how-it-works YOU authored).',
+        },
+        sources: {
+          type: 'object',
+          description: 'Structured backing for apply_how_it_works: { claims: [{ text, sources: [ref...], ' +
+            'confidence }], divergences: [{ intent, reality, severity }] }. Cite real source refs from the ' +
+            'epic\'s grounded context ("task:<id>", "commit:<sha>", "epic:<id>"); the server drops ' +
+            'fabricated ones.',
+        },
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required for create)',
+        },
+        // --- Shared fields ---
+        title: {
+          type: 'string',
+          description: 'Epic title (required for create)',
+        },
+        description: {
+          type: 'string',
+          description: 'Epic description (supports markdown). Use real newlines, not literal \\n. ' +
+            'Writing this stays plain text; it does not create a backing document.',
+        },
+        status: {
+          type: 'string',
+          enum: ['backlog', 'ready', 'active', 'completed', 'cancelled', 'archived'],
+          description: 'Epic status (default: backlog for create)',
+        },
+        milestoneId: {
+          type: 'string',
+          description: 'Link to project milestone (set to empty string to remove on update). ' +
+            'This is also how an epic aligns to an organization goal: link the epic to a ' +
+            'milestone that is linked to the goal — there is no direct goal field on an epic.',
+        },
+        featureId: {
+          type: 'string',
+          description: 'Tie this epic to a durable Feature it advances (E-210). When the project ' +
+            'has feature-link governance enabled, this is REQUIRED on create (and on updating an ' +
+            'unlinked epic): the epic is linked to the feature via a relates_to edge. If a create/update ' +
+            'is rejected with "requires every epic to be linked to a Feature", find an existing ' +
+            'capability or propose a new one with search_features, then pass its id here.',
+        },
+        startDate: {
+          type: 'string',
+          description: 'Start date (RFC3339 format, e.g., 2026-01-01T00:00:00Z)',
+        },
+        endDate: {
+          type: 'string',
+          description: 'End/deadline date (RFC3339 format). Enforced — incomplete tasks auto-move to backlog when passed.',
+        },
+        estimatedHours: {
+          type: 'number',
+          description: 'Epic-level effort estimate in HOURS. Stored as given — the API does not ' +
+            'derive dates from it (the web rail does that client-side, at 8h per work day). Distinct ' +
+            'from the points shown on the epic detail, which are a read-only rollup of the child ' +
+            'tasks\' sprintPoints: this is the epic\'s own input, that is what the tasks add up to.',
+        },
+        owner: {
+          type: 'object',
+          description: 'Epic owner (userId and name)',
+          properties: {
+            userId: { type: 'string' },
+            name: { type: 'string' },
+          },
+        },
+        labels: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Array of label names',
+        },
+        color: {
+          type: 'string',
+          description: 'Hex color for visual identification (e.g., "#3B82F6"). Set to empty string to remove on update.',
+        },
+        links: LINKS_ARRAY_SCHEMA,
+        // --- Create-only: the epic's breakdown, created in the same request ---
+        componentId: {
+          type: 'string',
+          description: 'Component applied to every task in `tasks` that does not set its own ' +
+            '(create only). Get available components from get_current_project_context().',
+        },
+        tasks: {
+          type: 'array',
+          description: 'Child tasks to create WITH the epic, in the same request (create only, 1-40). ' +
+            'Each item takes the same fields as manage_task action:"create"; only title is required. ' +
+            'projectId and epicId are taken from the epic — do not set them per item. ' +
+            'The response reports the epic separately from a per-item task result: if some tasks fail, ' +
+            'the epic still exists and you retry ONLY the failed items, never the whole call. ' +
+            'For more than 40 tasks, create the epic here with the first 40 and send the rest with create_tasks.',
+          items: {
+            type: 'object',
+            properties: { ...TASK_ITEM_PROPERTIES },
+            required: ['title'],
+          },
+        },
+        // --- Update-only fields ---
+        addLinks: {
+          type: 'array',
+          items: LINKS_ARRAY_SCHEMA.items,
+          description: 'Add cross-entity links to an existing epic (update only). ' +
+            'Same shape as `links` on create.',
+        },
+        removeLinks: {
+          type: 'array',
+          items: LINKS_ARRAY_SCHEMA.items,
+          description: 'Remove cross-entity links from an existing epic (update only).',
+        },
+        addRelatedItem: {
+          ...RELATED_ITEM_SCHEMA,
+          description: 'DEPRECATED — use addLinks. Add a cross-entity related item ' +
+            'link (update only). Still works; addLinks takes several at once and ' +
+            'supports linkType.',
+        },
+        removeRelatedItem: {
+          ...RELATED_ITEM_SCHEMA,
+          description: 'DEPRECATED — use removeLinks. Remove a cross-entity related ' +
+            'item link (update only). Still works.',
+        },
+        addDependency: {
+          type: 'string',
+          description: 'Add a cross-project blocking dependency by epic ID. ' +
+            'Same-org only. Rejected as ErrCircularDependency if it would close a cycle. (update only)',
+        },
+        removeDependency: {
+          type: 'string',
+          description: 'Remove a blocking dependency by target epic ID. ' +
+            'Idempotent — no error if absent. (update only)',
+        },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name: 'search_epics',
+    description: 'Search and filter epics by project, status, or text. ' +
+      'Primary filter is by project. If no scope (projectId) is provided, ' +
+      'searches across all projects accessible to the API key. ' +
+      'To find epics aligned to a goal, filter by the goal\'s milestone (milestoneId).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'Filter by project ID (primary filter)',
+        },
+        milestoneId: {
+          type: 'string',
+          description: 'Filter by milestone ID (release)',
+        },
+        status: {
+          type: 'string',
+          enum: ['backlog', 'ready', 'active', 'completed', 'cancelled', 'archived'],
+          description: 'Filter by epic status',
+        },
+        searchText: {
+          type: 'string',
+          description: 'Text to search in epic title or description (case-insensitive)',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results (default: 50, max: 1000)',
+          default: 50,
+        },
+      },
+    },
+  },
+  {
+    name: 'list_epics',
+    description: 'List all epics for a specific project. For advanced filtering use search_epics. Requires projectId.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'The ID of the project to list epics for (required)',
+        },
+      },
+    },
+  },
+  {
+    name: 'get_epic',
+    description: 'Retrieve a single epic by ID or epic number with ' +
+      'full details. Provide EITHER epicId OR both epicNumber and projectId. ' +
+      'Optionally include lightweight task information ' +
+      '(id, title, status, priority, assignee). ' +
+      'Responses include `descriptionDocumentId` — the id of the backing rich-description Document ' +
+      'when the description has been promoted to one (E-189), otherwise omitted. ' +
+      'Responses also include `derivedGoalIds` — the organization goal(s) this epic aligns to, ' +
+      'derived via its milestone (epics have no direct goal field).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epicId: {
+          type: 'string',
+          description: 'The document ID of the epic to retrieve',
+        },
+        epicNumber: {
+          type: 'number',
+          description: 'The sequential epic number (e.g., 7 for ' +
+            'epic #7). Must be used with projectId. This is the ' +
+            'human-friendly number displayed in the UI.',
+        },
+        projectId: {
+          type: 'string',
+          description: 'The project ID. Required when using epicNumber instead of epicId.',
+        },
+        includeTasks: {
+          type: 'boolean',
+          description: 'If true, includes lightweight task info (id, title, status, priority, assignee) ' +
+            'for all tasks in this epic. This is the recommended way to get all tasks in an epic.',
+        },
+      },
+    },
+  },
+];

package/tools/facts.js

@@ -0,0 +1,70 @@
+/**
+ * Fact Tools
+ * MCP tools for managing project-scoped facts (knowledge entries)
+ *
+ * Facts are short, tagged knowledge items scoped to a project — useful for
+ * capturing decisions, conventions, and reference info that humans and AI
+ * agents need.
+ */
+
+export const FACT_TOOLS = [
+  {
+    name: 'manage_fact',
+    description: 'Create, update, or delete project facts (knowledge entries). ' +
+      'Facts are short, tagged knowledge items scoped to a project — useful for capturing decisions, conventions, and reference info that humans and AI agents need.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create', 'update', 'delete'],
+          description: 'Action to perform',
+        },
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required for create and delete)',
+        },
+        factId: {
+          type: 'string',
+          description: 'Fact ID (required for update and delete)',
+        },
+        title: {
+          type: 'string',
+          description: 'Fact title (required for create)',
+        },
+        content: {
+          type: 'string',
+          description: 'Fact content (supports markdown)',
+        },
+        pinned: {
+          type: 'boolean',
+          description: 'Pin fact to top of list',
+        },
+        tagIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Tag IDs for categorization',
+        },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name: 'list_facts',
+    description: 'List all project facts (knowledge entries) for a project. Returns pinned facts first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required)',
+        },
+        factId: {
+          type: 'string',
+          description: 'Optional: get a single fact by ID instead of listing all',
+        },
+      },
+      required: ['projectId'],
+    },
+  },
+];