@ezmodo/mcp-server 0.13.0

package/tools/links.js

@@ -0,0 +1,199 @@
+/**
+ * Links Tools
+ *
+ * Polymorphic link management — exposes the unified entity_links surface
+ * (Phase 3 of the entity_links unification). One tool covers every link
+ * combo across tasks, epics, projects, and documents instead of having
+ * to remember which entity-specific tool to use.
+ *
+ * Use these in preference to manage_task / manage_epic's per-link fields
+ * (addDependency, addRelatedItem, ...) when the link's source and target
+ * are different entity types — e.g. linking a task to a related document.
+ */
+
+import { LINKABLE_TYPES } from './linkable-types.js';
+
+export const LINK_TOOLS = [
+  {
+    name: 'manage_link',
+    description:
+      'Add, remove, or verify a link between two entities. Covers blocking ' +
+      'dependencies (blocked_by) and soft cross-entity links (relates_to) ' +
+      'uniformly. blocked_by is only valid for task→task and epic→epic; ' +
+      'relates_to works between any of: task, epic, project, document, ' +
+      'component, feature, decision, design, test_suite, feature_flag ' +
+      '(e.g. link a feature to the feature_flag that gates it). ' +
+      'Idempotent — re-adding an existing link is a no-op, removing an ' +
+      'absent link is a no-op. Use action "verify" to stamp a link\'s ' +
+      'freshness (E-166/E-154): record that you confirmed it still correct, ' +
+      'optionally against a commitSha — call it after touching code a linked ' +
+      'document describes so the freshness signal stays accurate.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['add', 'remove', 'verify'],
+          description: 'Action to perform',
+        },
+        sourceType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description:
+            'The entity from which the link originates. For blocked_by ' +
+            'this is the entity being blocked.',
+        },
+        sourceId: {
+          type: 'string',
+          description: 'ID of the source entity (required)',
+        },
+        targetType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description:
+            'The entity the link points to. For blocked_by this is the ' +
+            'entity that must complete first.',
+        },
+        targetId: {
+          type: 'string',
+          description: 'ID of the target entity (required)',
+        },
+        linkType: {
+          type: 'string',
+          enum: ['blocked_by', 'relates_to'],
+          description:
+            'blocked_by: source is blocked by target (only task→task or ' +
+            'epic→epic). relates_to: soft cross-entity link (any combo).',
+        },
+        commitSha: {
+          type: 'string',
+          description:
+            'Optional, for action "verify": the commit sha you confirmed the ' +
+            'link correct against. Recorded as the verification point.',
+        },
+      },
+      required: ['action', 'sourceType', 'sourceId', 'targetType', 'targetId', 'linkType'],
+    },
+  },
+  {
+    name: 'list_links',
+    description:
+      'List an entity\'s links. Returns one row per ' +
+      'link (source, target, linkType, createdAt, and freshness fields ' +
+      'lastVerifiedAt / lastVerifiedBy / lastVerifiedCommitSha). By default ' +
+      'only OUTGOING links (the entity as source) are returned — set ' +
+      'direction:"incoming" for links pointing AT it (e.g. the features that ' +
+      'reference this task), or "both" for the full neighbourhood, since ' +
+      'relates_to is not always stored bidirectionally. Optionally ' +
+      'filter by linkType (e.g. only blockers) or targetType (e.g. only ' +
+      'related documents). Set hydrate:true to also get each target\'s ' +
+      'title/status, so you can read the graph without a get_* per link.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sourceType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description: 'Type of the source entity (required)',
+        },
+        sourceId: {
+          type: 'string',
+          description: 'ID of the source entity (required)',
+        },
+        linkType: {
+          type: 'string',
+          enum: ['blocked_by', 'relates_to'],
+          description: 'Optional filter: only return this kind of link',
+        },
+        targetType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description: 'Optional filter: only return links to this entity type',
+        },
+        direction: {
+          type: 'string',
+          enum: ['outgoing', 'incoming', 'both'],
+          default: 'outgoing',
+          description:
+            'Which edges to return relative to the given entity. "outgoing" ' +
+            '(default) = links where it is the source. "incoming" = links ' +
+            'pointing at it. "both" = either. Use "both" when you want the ' +
+            'entity\'s whole neighbourhood — relates_to is not always stored ' +
+            'in both directions.',
+        },
+        includeSuggested: {
+          type: 'boolean',
+          description:
+            'When true, also return machine-suggested (not yet confirmed) ' +
+            'links alongside confirmed ones, so you can review and confirm ' +
+            'them. Off by default — suggestions are not facts.',
+        },
+        hydrate: {
+          type: 'boolean',
+          description:
+            'When true, each row gains a `related` object with the target\'s ' +
+            'title/status/kind. Costs one lookup per link, so leave it off ' +
+            'when you only need the edges.',
+        },
+      },
+      required: ['sourceType', 'sourceId'],
+    },
+  },
+  {
+    name: 'resolve_links',
+    description:
+      'Given files you have touched (or are about to), return the entities you should link to: ' +
+      'the components — screens, pages, codebase areas — that own those paths, plus how confident ' +
+      'the match is. Read-only; nothing is written.\n\n' +
+      'Call it BEFORE creating work to fill in the `links` param, or after a change set to check ' +
+      'you have not missed anything. If it returns a component you did not expect, that is a signal ' +
+      'your change is broader than you thought — worth reading before you continue.\n\n' +
+      'Paths are repo-relative (e.g. "mobile/lib/features/auth/screens/login_screen.dart").',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string', description: 'Project ID (required)' },
+        paths: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Repo-relative file paths to resolve (required)',
+        },
+      },
+      required: ['projectId', 'paths'],
+    },
+  },
+  {
+    name: 'preview_links',
+    description:
+      'Show what ezmodo WOULD link an entity to, without writing anything. Each proposal reports ' +
+      '`autoApplies`: true means ezmodo records it on its own, false means it wants a human or you ' +
+      'to confirm.\n\n' +
+      'Use it when you want to see and choose rather than let linking happen — confirm the ones you ' +
+      'agree with via manage_link, which records them as deliberately asserted rather than derived.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string', description: 'Project ID' },
+        subjectType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description: 'Type of the entity the links would hang off (required)',
+        },
+        subjectId: { type: 'string', description: 'ID of that entity (required)' },
+        paths: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Repo-relative file paths the work touches',
+        },
+        componentId: { type: 'string', description: 'A component the work explicitly names' },
+        epicId: { type: 'string', description: 'The epic the work belongs to' },
+        trigger: {
+          type: 'string',
+          enum: ['files_linked', 'commit_linked', 'work_created', 'work_reparented', 'plan_approved', 'surface_imported'],
+          description: 'What kind of event to simulate. Defaults sensibly from whether paths were supplied.',
+        },
+      },
+      required: ['subjectType', 'subjectId'],
+    },
+  },
+];

package/tools/milestones.js

@@ -0,0 +1,176 @@
+/**
+ * Milestone Tools
+ * MCP tools for managing project milestones (version releases and initiatives)
+ *
+ * Milestones are project-scoped containers for tracking:
+ * - Version releases (e.g., v1.2.0, v2.0.0-beta)
+ * - Initiatives (e.g., Q1 2025, Sprint 5)
+ *
+ * Epics can be linked to milestones to track which features/work
+ * will be included in a release or initiative.
+ */
+
+import { LINKS_ARRAY_SCHEMA } from './link-params.js';
+
+export const MILESTONE_TOOLS = [
+  {
+    name: 'manage_milestone',
+    description: 'Create, update, delete milestones, or manage epic/suite linking and changelog generation. ' +
+      'Milestones can be version releases or initiatives.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: [
+            'create', 'update', 'delete',
+            'link_epic', 'unlink_epic',
+            'generate_changelog', 'reorder_epics',
+            'link_suite', 'unlink_suite',
+          ],
+          description: 'Action to perform',
+        },
+        // --- Identifiers (used by most actions) ---
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required for all actions)',
+        },
+        milestoneId: {
+          type: 'string',
+          description: 'Milestone ID (required for update, delete, link_epic, unlink_epic, generate_changelog, reorder_epics, link_suite, unlink_suite)',
+        },
+        milestoneSlug: {
+          type: 'string',
+          description: 'URL-friendly slug of the milestone (alternative to milestoneId)',
+        },
+        // --- Create fields ---
+        name: {
+          type: 'string',
+          description: 'Milestone name (required for create, e.g., "v1.2.0", "Q1 2025 Launch")',
+        },
+        type: {
+          type: 'string',
+          enum: ['version', 'initiative'],
+          description: 'Milestone type (required for create): "version" for releases, "initiative" for initiatives',
+        },
+        description: {
+          type: 'string',
+          description: 'Milestone description, supports markdown (create, update). ' +
+            'Writing this stays plain text; it does not create a backing document.',
+        },
+        version: {
+          type: 'string',
+          description: 'Semantic version string for version type milestones (e.g., "1.2.0", "2.0.0-beta") (create, update)',
+        },
+        targetDate: {
+          type: 'string',
+          description: 'Target completion/release date (RFC3339, e.g., 2026-03-31T00:00:00Z) (create, update)',
+        },
+        parentMilestoneId: {
+          type: 'string',
+          description: 'Nest this milestone under an overarching parent milestone (tiered milestones, E-217). ' +
+            'On create: empty/omitted = top-level. On update: omit = leave unchanged, empty string "" = clear (promote to top-level), ' +
+            'a milestone ID = re-parent. Validated for existence, cycles, and max nesting depth (3); parent must be in the same project. (create, update)',
+        },
+        status: {
+          type: 'string',
+          enum: ['planned', 'in_progress', 'released', 'archived'],
+          description: 'Milestone status (default: "planned") (create, update)',
+        },
+        links: LINKS_ARRAY_SCHEMA,
+        items: {
+          type: 'array',
+          description: 'Initial linked items, e.g., epics (create, update)',
+          items: {
+            type: 'object',
+            properties: {
+              entityId: { type: 'string', description: 'ID of the entity to link' },
+              entityType: { type: 'string', description: 'Type of entity', enum: ['epic'], default: 'epic' },
+              priority: { type: 'string', description: 'Priority level', enum: ['critical', 'high', 'medium', 'low'] },
+              order: { type: 'number', description: 'Display order' },
+            },
+            required: ['entityId'],
+          },
+        },
+        changelog: {
+          type: 'string',
+          description: 'Markdown changelog for version type milestones (create, update)',
+        },
+        // --- Update-only fields ---
+        releasedDate: {
+          type: 'string',
+          description: 'Actual release date (RFC3339, typically set when status changes to "released") (update only)',
+        },
+        // --- link_epic / unlink_epic fields ---
+        epicId: {
+          type: 'string',
+          description: 'Epic ID to link/unlink (required for link_epic, unlink_epic)',
+        },
+        entityType: {
+          type: 'string',
+          enum: ['epic'],
+          description: 'Type of entity being linked (default: "epic") (link_epic only)',
+          default: 'epic',
+        },
+        priority: {
+          type: 'string',
+          enum: ['critical', 'high', 'medium', 'low'],
+          description: 'Priority of epic/suite within milestone (default: "medium") (link_epic, link_suite)',
+        },
+        // --- reorder_epics fields ---
+        itemIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Ordered array of item IDs — must contain same set as currently linked (reorder_epics only)',
+        },
+        // --- link_suite / unlink_suite fields ---
+        suiteId: {
+          type: 'string',
+          description: 'Test suite ID to link/unlink (required for link_suite, unlink_suite)',
+        },
+      },
+      required: ['action', 'projectId'],
+    },
+  },
+  {
+    name: 'get_milestone',
+    description: 'Retrieve a single milestone by ID, or list all milestones for a project. ' +
+      'Provide milestoneId (or milestoneSlug) for single lookup, or just projectId to list all. ' +
+      'Optionally include progress data. ' +
+      'Responses include `descriptionDocumentId` — the id of the backing rich-description Document ' +
+      'when the description has been promoted to one (E-189), otherwise omitted.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'The project ID (required)',
+        },
+        milestoneId: {
+          type: 'string',
+          description: 'Milestone ID for single lookup',
+        },
+        milestoneSlug: {
+          type: 'string',
+          description: 'Milestone slug for single lookup (alternative to milestoneId)',
+        },
+        includeProgress: {
+          type: 'boolean',
+          description: 'If true, include progress data (overall percentage, epic breakdown)',
+        },
+        // --- List filters (used when no milestoneId/milestoneSlug) ---
+        type: {
+          type: 'string',
+          enum: ['version', 'initiative'],
+          description: 'Filter by milestone type (list mode only)',
+        },
+        status: {
+          type: 'string',
+          enum: ['planned', 'in_progress', 'released', 'archived'],
+          description: 'Filter by milestone status (list mode only)',
+        },
+      },
+      required: ['projectId'],
+    },
+  },
+];

package/tools/organizations.js

@@ -0,0 +1,23 @@
+/**
+ * Organization Tools
+ * MCP tools for managing organizations (workspaces)
+ */
+
+export const ORGANIZATION_TOOLS = [
+  {
+    name: 'get_organization',
+    description: 'Get organization info. Returns the default/primary organization, ' +
+      'or lists all organizations the user has access to. Use mode "list" to see all ' +
+      'workspaces, or omit/use "default" to get the primary one.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mode: {
+          type: 'string',
+          enum: ['default', 'list'],
+          description: 'Mode: "default" returns primary organization, "list" returns all. Default: "default"',
+        },
+      },
+    },
+  },
+];

package/tools/projects.js

@@ -0,0 +1,172 @@
+/**
+ * Project Tools
+ * MCP tools for managing projects (primary container for work)
+ *
+ * Projects are long-lived containers that hold tasks and epics.
+ * Types: software, marketing, sales, operations, design, infrastructure,
+ * creative, research, implementation, custom.
+ *
+ * A project's type decides what its work is CALLED (E-107). A marketing project
+ * calls an epic a "Campaign" and a component a "Channel"; a sales project calls
+ * a task an "Activity". `get_project` returns the resolved vocabulary as
+ * `terminology`, and `get_current_project_context` caches it. Use those words
+ * when writing anything a person reads — titles, descriptions, chat replies —
+ * while keeping the API's own field names (epicId, taskId) unchanged.
+ */
+
+export const PROJECT_TOOLS = [
+  {
+    name: 'manage_project',
+    description: 'Create a new project within an organization, update an existing one, ' +
+      'or (re)generate a project\'s grounded "how it works" living description.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create', 'update', 'generate_how_it_works', 'apply_how_it_works'],
+          description: 'Action to perform. "update" changes an existing project ' +
+            '(requires projectId); only the fields you pass are touched — accepts name, ' +
+            'description, slug, ownerId, gitUrl and gitProvider. Setting gitUrl after ' +
+            'creation is what enables commit-to-task linking. "generate_how_it_works" (re)generates the ' +
+            'project\'s grounded, source-attributed "how it works" living description from ' +
+            'its linked work (requires projectId; 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_project.',
+        },
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required for update, 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 project\'s grounded context; the server drops fabricated ones.',
+        },
+        organizationId: {
+          type: 'string',
+          description: 'The ID of the organization to create the project in (required for create)',
+        },
+        name: {
+          type: 'string',
+          description: 'The project name (required for create, optional for update)',
+        },
+        slug: {
+          type: 'string',
+          description: 'URL slug for the project (update only). Changing this changes the ' +
+            'project\'s URLs.',
+        },
+        description: {
+          type: 'string',
+          description: 'Project description (supports markdown). ' +
+            'Writing this stays plain text; it does not create a backing document.',
+        },
+        type: {
+          type: 'string',
+          enum: ['software', 'marketing', 'sales', 'operations', 'design', 'infrastructure',
+            'creative', 'research', 'implementation', 'custom'],
+          description: 'Project type (default: software)',
+          default: 'software',
+        },
+        customType: {
+          type: 'string',
+          description: 'Custom type name (only used when type is "custom")',
+        },
+        gitUrl: {
+          type: 'string',
+          description: 'Git repository URL (for software projects). Settable on create and ' +
+            'update — this is what links the project to its repo so commits can be matched ' +
+            'back to tasks.',
+        },
+        gitProvider: {
+          type: 'string',
+          enum: ['github', 'gitlab', 'bitbucket'],
+          description: 'Git provider (create and update)',
+        },
+        ownerId: {
+          type: 'string',
+          description: 'User ID of the project owner (defaults to API key user on create; ' +
+            'reassigns the owner on update)',
+        },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name: 'get_project',
+    description: 'Get project info by ID (context/memory), search projects by text, or list all projects. ' +
+      'Provide projectId for context retrieval, query for search, or neither to list all. ' +
+      'Responses include `descriptionDocumentId` — the id of the backing rich-description Document ' +
+      'when the description has been promoted to one (E-189), otherwise omitted. ' +
+      'By-ID responses also carry `type` and `terminology` — the words this project uses for ' +
+      'epics, tasks and components, and for their statuses (E-107). Write prose in those words; ' +
+      'a marketing project calls an epic a "Campaign". `terminology` is absent for a type with no ' +
+      'template, which means plain English, not an error.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'Project ID — returns project context including memory, knowledge, ' +
+            'configuration, the project `type`, and the `terminology` that type speaks',
+        },
+        query: {
+          type: 'string',
+          description: 'Search text for project name or description (case-insensitive)',
+        },
+        type: {
+          type: 'string',
+          enum: ['software', 'marketing', 'sales', 'operations', 'design', 'infrastructure',
+            'creative', 'research', 'implementation', 'custom'],
+          description: 'Filter by project type (search/list mode)',
+        },
+        organizationId: {
+          type: 'string',
+          description: 'Filter by organization ID (search/list mode)',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results (default: 50)',
+          default: 50,
+        },
+      },
+    },
+  },
+  {
+    name: 'get_project_story',
+    description: 'Project Story (E-208): a grounded, source-attributed narrative of what has happened to a project ' +
+      'since it began in ezmodo — the time-axis complement to "how it works". Use it to catch up on a project. ' +
+      'Returns rendered markdown plus validated claims (each citing real event:/decision: sources), the resolved ' +
+      'window, and generatedAt. Returns a fresh cached story when available, otherwise generates one (AI-quota gated).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'Project ID to narrate',
+        },
+        window: {
+          type: 'string',
+          enum: ['since_inception', 'last_release', 'last_sprint', 'custom'],
+          description: 'Time window for the story (default: since_inception). last_release/last_sprint/custom require from+to.',
+        },
+        from: {
+          type: 'string',
+          description: 'Window start, RFC3339 (e.g. 2026-01-02T15:04:05Z). Required for custom/last_release/last_sprint.',
+        },
+        to: {
+          type: 'string',
+          description: 'Window end, RFC3339. Required for custom/last_release/last_sprint.',
+        },
+      },
+      required: ['projectId'],
+    },
+  },
+];