@ezmodo/mcp-server 0.13.0

package/prompts/zephly-usage-guide.js

@@ -0,0 +1,119 @@
+/**
+ * Zephly Usage Guide Prompt
+ * Guidelines for using Zephly MCP tools effectively
+ */
+
+export const ZEPHLY_USAGE_GUIDE = `# Zephly MCP Integration Guide
+
+You have access to Zephly's intelligent project management tools.
+Zephly uses a **project-first** model where projects are the primary
+work containers.
+
+## Session Start - Discover Context
+
+At the start of each session, discover the user's context:
+
+\`\`\`
+1. list_organizations()                              # Get user's workspaces (usually one)
+2. list_projects({ organizationId })                 # Get projects
+\`\`\`
+
+This gives you the organizationId and projects needed for all other operations.
+
+## Project-First Hierarchy
+
+\`\`\`
+Organization
+  └── Projects (primary work containers)
+        └── Epics (milestones within projects)
+              └── Tasks (individual work items)
+  └── Goals (strategic alignment, links to epics)
+\`\`\`
+
+**Key points:**
+- Tasks belong to **projects** (projectId is required)
+- Epics are project-scoped milestones
+- Goals provide strategic alignment and can link to epics
+
+## When to Use Zephly Tools
+
+**Proactively use these tools when:**
+- User mentions tasks, projects, epics, sprints, or team coordination
+- User asks about project status, health, or blockers
+- User needs help prioritizing work or deciding what to work on next
+- User is planning team assignments or workload distribution
+- User is breaking down features into tasks
+- User asks about timelines or estimates
+- User mentions dependencies, blockers, or handoffs
+
+## Core Tools
+
+### Discovery
+- \`list_organizations\` - List all workspaces
+- \`list_projects\` - List projects for an organization
+- \`search_projects\` - Search/filter projects
+
+### Project Management
+- \`create_project\` - Create new project
+- \`get_project_context\` - Get project details with progress
+
+### Task Operations
+- \`create_task\` - Create task in a project (requires projectId)
+- \`update_task\` - Update task properties and steps
+- \`complete_task\` - Mark task completed
+- \`search_tasks\` - Semantic search or filter tasks
+- \`get_task\` - Get task by ID or number
+
+### Epic Management
+- \`create_epic\` - Create epic in project
+- \`update_epic\` - Update epic
+- \`list_epics\` - List epics for project
+- \`get_epic\` - Get epic details
+
+### Goal Management
+- \`create_goal\` - Create strategic goal
+- \`update_goal\` - Update goal
+- \`list_goals\` - List goals for organization
+- \`link_epic_to_goal\` - Link epic to goal for alignment
+
+### AI Intelligence
+- \`get_project_insights\` - Project health analysis
+- \`suggest_next_actions\` - Task recommendations
+- \`analyze_dependency_graph\` - Critical path analysis
+- \`estimate_task_duration\` - AI time estimates
+
+### Team Coordination
+- \`analyze_team_capacity\` - Resource allocation
+- \`suggest_task_assignments\` - Smart task matching
+- \`bulk_task_operations\` - Batch operations
+- \`identify_handoff_needs\` - Detect blocked tasks
+- \`pull_ai_task_from_queue\` - AI agent task queue
+
+## Example Workflow
+
+\`\`\`javascript
+// 1. Discover context
+const orgs = await list_organizations();
+const orgId = orgs.organizations[0].id;
+
+const projects = await list_projects({ organizationId: orgId });
+const projectId = projects.projects[0].id;
+
+// 2. Create a task
+await create_task({
+  projectId,
+  title: 'Implement user authentication',
+  description: 'Add login/logout functionality',
+  priority: 'high'
+});
+
+// 3. Search existing tasks
+await search_tasks({ projectId, status: 'in_progress' });
+\`\`\`
+
+## Best Practices
+
+1. **Discover context first** - Call list_organizations + list_projects at session start
+2. **Project-first** - Always have a projectId before creating tasks
+3. **Check health proactively** - Use get_project_insights to identify issues
+4. **Track AI work** - Create tasks for significant work you're doing`;

package/tools/access-entity-types.js

@@ -0,0 +1,28 @@
+/**
+ * The entity types that support access control, declared once.
+ *
+ * This mirrors `access.IsValidEntityType` in the Go API (api/internal/core/
+ * access/models.go), which is the authority. The API side exposes the same list
+ * via `handlers.SupportedAccessEntityTypes()` and a test
+ * (TestSupportedAccessEntityTypes_MatchesService) fails if access.EntityType
+ * gains or loses a member without that list being updated.
+ *
+ * Getting this wrong in either direction is the bug this tool exists downstream
+ * of (#2168): advertising a type the service rejects turns a clear schema error
+ * into a confusing 400 — or worse, reads as a capability that silently does
+ * nothing — while omitting a supported type hides real capability from agents.
+ *
+ * Adding a type: add it to access.EntityType and IsValidEntityType in Go, to
+ * SupportedAccessEntityTypes, then here.
+ */
+export const ACCESS_ENTITY_TYPES = [
+  'goal',
+  'project',
+  'epic',
+  'task',
+  'document',
+  'folder',
+];
+
+/** The roles an access entry can grant, most permissive first. */
+export const ACCESS_ROLES = ['owner', 'admin', 'member', 'viewer'];

package/tools/access.js

@@ -0,0 +1,152 @@
+/**
+ * Entity Access Tools (#2170)
+ *
+ * Polymorphic access control — one read tool and one write tool covering every
+ * entity type the access service supports, mirroring the generic REST shape at
+ * /api/v1/access/{entityType}/{id} and following manage_link's precedent.
+ *
+ * Deliberately NOT modelled as an `access` field on each manage_* tool: that
+ * would duplicate the same object across a dozen schemas and invite exactly the
+ * drift that produced #2168, where manage_folder advertised an `access`
+ * parameter that no code path implemented.
+ *
+ * Permissions, twice over. Reading requires viewer access to the entity, so an
+ * agent cannot enumerate permissions on something it cannot already see. Every
+ * mutation requires admin on the entity AND an API key holding the dedicated
+ * `write:access` scope — an ordinary write:tasks key cannot change who can see
+ * a task, because granting visibility is a larger privilege than editing.
+ */
+
+import { ACCESS_ENTITY_TYPES, ACCESS_ROLES } from './access-entity-types.js';
+
+const entityTypeProperty = {
+  type: 'string',
+  enum: ACCESS_ENTITY_TYPES,
+  description:
+    'The type of entity whose access is being read or changed. Only these ' +
+    'types support access control; anything else is rejected rather than ' +
+    'accepted and ignored.',
+};
+
+const entityIdProperty = {
+  type: 'string',
+  description: 'ID of the entity (required)',
+};
+
+const organizationIdProperty = {
+  type: 'string',
+  description:
+    'Organization the entity belongs to (required). Also guards against ' +
+    'cross-org lookups: an entity in a different org resolves to no access.',
+};
+
+export const ACCESS_TOOLS = [
+  {
+    name: 'get_access',
+    description:
+      'Read who can access an entity. Returns `resolvedAccess` — the effective ' +
+      'entries after inheritance, with the source of each — plus `rawAccess`, the ' +
+      'entity\'s own unresolved settings, which is included only when you hold ' +
+      'admin on the entity. Requires at least viewer access to the entity itself. ' +
+      'Supported entity types: ' + ACCESS_ENTITY_TYPES.join(', ') + '. ' +
+      'To ask whether a specific role is held, use manage_access action:"check".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        entityType: entityTypeProperty,
+        entityId: entityIdProperty,
+        organizationId: organizationIdProperty,
+      },
+      required: ['entityType', 'entityId', 'organizationId'],
+    },
+  },
+  {
+    name: 'manage_access',
+    description:
+      'Change or test an entity\'s access control. Actions: ' +
+      '"update_settings" replaces the access configuration wholesale ' +
+      '(inheritFromParent / accessList / publicAccess); ' +
+      '"add_entry" grants one user or team a role; ' +
+      '"remove_entry" revokes a single entry by its id; ' +
+      '"check" reports whether you currently hold a given role (a denial is a ' +
+      'normal result, not an error). ' +
+      'The three mutating actions require admin on the entity AND an API key ' +
+      'with the `write:access` scope — a key that can edit an entity cannot ' +
+      'change who may see it unless it was issued that scope explicitly. ' +
+      'Note that some entities cannot carry their own access: projects do not ' +
+      'support publicAccess, nested folders inherit from their root folder, and ' +
+      'documents inside a folder inherit from that folder.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['update_settings', 'add_entry', 'remove_entry', 'check'],
+          description: 'Action to perform',
+        },
+        entityType: entityTypeProperty,
+        entityId: entityIdProperty,
+        organizationId: organizationIdProperty,
+
+        // --- update_settings ---
+        inheritFromParent: {
+          type: 'boolean',
+          description:
+            'If true the entity inherits access from its parent and accessList is ' +
+            'ignored; if false it uses its own accessList. (update_settings only)',
+        },
+        accessList: {
+          type: 'array',
+          description:
+            'The complete access list, replacing any existing one. Each entry sets ' +
+            'exactly one of userId or teamId, plus a role. (update_settings only)',
+          items: {
+            type: 'object',
+            properties: {
+              userId: { type: 'string', description: 'Grant to this user (mutually exclusive with teamId)' },
+              teamId: { type: 'string', description: 'Grant to this team (mutually exclusive with userId)' },
+              role: { type: 'string', enum: ACCESS_ROLES, description: 'Role granted to this user or team' },
+            },
+            required: ['role'],
+          },
+        },
+        publicAccess: {
+          type: 'boolean',
+          description:
+            'Enable public read-only access. Not supported for projects. (update_settings only)',
+        },
+
+        // --- add_entry ---
+        userId: {
+          type: 'string',
+          description: 'User to grant a role to (mutually exclusive with teamId). (add_entry only)',
+        },
+        teamId: {
+          type: 'string',
+          description: 'Team to grant a role to (mutually exclusive with userId). (add_entry only)',
+        },
+        role: {
+          type: 'string',
+          enum: ACCESS_ROLES,
+          description: 'Role to grant. (add_entry only)',
+        },
+
+        // --- remove_entry ---
+        entryId: {
+          type: 'string',
+          description:
+            'ID of the access entry to revoke, as returned in get_access rawAccess ' +
+            'entries. (remove_entry only)',
+        },
+
+        // --- check ---
+        requiredRole: {
+          type: 'string',
+          enum: ACCESS_ROLES,
+          description: 'Role to test for; defaults to viewer. (check only)',
+        },
+      },
+      required: ['action', 'entityType', 'entityId', 'organizationId'],
+    },
+  },
+];

package/tools/activity.js

@@ -0,0 +1,38 @@
+/**
+ * Activity Timeline Tools
+ * MCP tools for querying project activity/changes
+ */
+
+export const ACTIVITY_TOOLS = [
+  {
+    name: 'get_project_changes',
+    description: 'Get recent activity and changes for a project. Returns structured events (task created/completed, epic progress, doc updates, etc.) with an aggregate summary. Use this to understand what happened in a project since a given date.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'The project ID to get changes for (required)',
+        },
+        since: {
+          type: 'string',
+          description: 'ISO 8601 date or relative duration. Examples: "2026-04-01T00:00:00Z", "7d" (last 7 days), "2w" (last 2 weeks), "30d" (last 30 days). Default: 7 days ago.',
+        },
+        entityTypes: {
+          type: 'string',
+          description: 'Comma-separated entity types to filter by. Options: task, epic, goal, document, project, comment. Example: "task,epic"',
+        },
+        eventTypes: {
+          type: 'string',
+          description: 'Comma-separated event types to filter by. Examples: "task_completed,task_created", "epic_status_changed"',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of events to return (default: 20, max: 100)',
+          default: 20,
+        },
+      },
+      required: ['projectId'],
+    },
+  },
+];

package/tools/agents.js

@@ -0,0 +1,208 @@
+/**
+ * Background Agents Tools (E-150)
+ *
+ * Control-plane tools for EzModo's background hygiene agents. The agents
+ * themselves (Stale Sentinel, Dependency Mapper, Related Linker, Duplicate
+ * Hunter) run on EzModo's infra; these tools let an MCP client (e.g. the
+ * user's Claude) review and act on what they produced.
+ */
+
+export const AGENT_TOOLS = [
+  {
+    name: 'list_agent_suggestions',
+    description:
+      'List pending background-agent suggestions for the current organization. ' +
+      'Returns the newest first — review and either accept_agent_suggestion or ' +
+      'reject_agent_suggestion each one. Action types: \'link\' (create entity_link), ' +
+      '\'archive\' (set tasks.archived=true), \'merge\' / \'unblock_check\' / \'enrich\' ' +
+      '(no destructive side effect on accept — intent only).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 500,
+          description: 'Max suggestions to return (default 100).',
+        },
+        entityType: {
+          type: 'string',
+          description:
+            'Narrow to one entity, e.g. entityType="task" with entityId. ' +
+            'Use this to ask "what is pending on THIS task?" instead of ' +
+            'scanning the whole organization. Matches EITHER end of the ' +
+            'suggestion — you get it whether your entity is what the proposal ' +
+            'is about or what it points at, so a PR-link suggestion keyed on ' +
+            'the pull request still shows up under its target task.',
+        },
+        entityId: {
+          type: 'string',
+          description: 'The entity id. Only meaningful together with entityType.',
+        },
+        action: {
+          type: 'string',
+          enum: ['link', 'archive', 'merge', 'unblock_check', 'enrich', 'status_change', 'verify_link', 'regenerate_how_it_works'],
+          description:
+            'Narrow to one suggestion verb. action="link" is what a ' +
+            'links-focused review asks for — the queue is shared with every ' +
+            'other agent, so without this you page through their findings too.',
+        },
+        agentType: {
+          type: 'string',
+          description: 'Narrow to one producing agent, e.g. "autolink" or "related_linker".',
+        },
+        minConfidence: {
+          type: 'number',
+          minimum: 0,
+          maximum: 1,
+          description:
+            'Drop findings below this confidence. Raise it when the queue is ' +
+            'noisy — past three or four items people stop reading and start ' +
+            'bulk-accepting, which is worse than seeing fewer.',
+        },
+      },
+    },
+  },
+
+  {
+    name: 'accept_agent_suggestion',
+    description:
+      'Accept a pending suggestion. The framework runs the side effect tied ' +
+      'to the suggestion\'s action (e.g. action=\'link\' inserts the entity_link, ' +
+      'action=\'archive\' archives the task) BEFORE flipping the status to ' +
+      'accepted, so a failed side effect leaves the suggestion pending.',
+    inputSchema: {
+      type: 'object',
+      required: ['id'],
+      properties: {
+        id: {
+          type: 'string',
+          description: 'The agent_suggestions.id returned by list_agent_suggestions.',
+        },
+        reviewNote: {
+          type: 'string',
+          description: 'Optional free-text note recorded with the acceptance.',
+        },
+      },
+    },
+  },
+
+  {
+    name: 'reject_agent_suggestion',
+    description:
+      'Reject a pending suggestion. Flips status to rejected and frees the ' +
+      'dedup slot so the agent may re-propose the same idea in a future run ' +
+      'if conditions change. Use a reviewNote to teach future judgement.',
+    inputSchema: {
+      type: 'object',
+      required: ['id'],
+      properties: {
+        id: { type: 'string' },
+        reviewNote: { type: 'string' },
+      },
+    },
+  },
+
+  {
+    name: 'run_agent_now',
+    description:
+      'Manually enqueue an agent run, bypassing the scheduler\'s cadence. ' +
+      'Useful for testing or for \'check this entity for duplicates now\' ' +
+      'flows. The agent type must be registered server-side. Quota is ' +
+      'respected — if the org has exhausted its monthly suggestion cap the ' +
+      'run completes with status=\'quota_exhausted\' and zero new suggestions.',
+    inputSchema: {
+      type: 'object',
+      required: ['agentType'],
+      properties: {
+        agentType: {
+          type: 'string',
+          enum: ['stale_sentinel', 'dependency_mapper', 'related_linker', 'duplicate_hunter'],
+        },
+        scope: {
+          type: 'object',
+          description:
+            'Optional narrowing of the run to a single entity. Omit for a ' +
+            'full org/project sweep.',
+          properties: {
+            entity_type: { type: 'string', enum: ['task', 'epic', 'goal', 'doc'] },
+            entity_id: { type: 'string' },
+          },
+          required: ['entity_type', 'entity_id'],
+        },
+      },
+    },
+  },
+
+  {
+    name: 'configure_agent',
+    description:
+      'Enable, disable, or change cadence for an agent in the current org. ' +
+      'First enable on a fresh org schedules the agent\'s first run for NOW() ' +
+      'so initial suggestions arrive within a scheduler tick (~60s).',
+    inputSchema: {
+      type: 'object',
+      required: ['agentType'],
+      properties: {
+        agentType: {
+          type: 'string',
+          enum: ['stale_sentinel', 'dependency_mapper', 'related_linker', 'duplicate_hunter'],
+        },
+        enabled: { type: 'boolean' },
+        cadenceSeconds: {
+          type: 'integer',
+          minimum: 60,
+          description:
+            'Run interval in seconds. Omit to use the agent\'s default cadence ' +
+            '(typically 24h). Minimum 60s to prevent abuse.',
+        },
+      },
+    },
+  },
+
+  {
+    name: 'resolve_link_suggestions',
+    description:
+      'Accept and/or reject several pending suggestions in ONE call.\n\n' +
+      'This exists because clearing a queue item-by-item costs a call each, and ' +
+      'anything that expensive gets skipped — leaving suggestions to pile up until ' +
+      'someone bulk-dismisses them unread. Pass the ids you agree with in `accept` ' +
+      'and the ones you do not in `reject`.\n\n' +
+      'Rejecting is a real answer, not a failure: a rejection with a reason is how ' +
+      'the linker learns. Leaving items pending is the only wrong outcome.\n\n' +
+      'WHERE THE IDS COME FROM: the `suggestionId` on each entry of a manage_task / ' +
+      'manage_epic response\'s `linkSuggestions`, or — authoritatively — ' +
+      'list_agent_suggestions with action:"link" plus entityType/entityId. Prefer ' +
+      'list_agent_suggestions when a response says its list may be partial: the ' +
+      'engine\'s semantic rules finish a beat after the deterministic ones, so an ' +
+      'inline list can legitimately show fewer than are actually queued.\n\n' +
+      'Partial failure is reported per id rather than aborting — one bad id must not ' +
+      'cost the rest of the batch.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        accept: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Suggestion ids to accept (the side effect runs for each).',
+        },
+        reject: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+              reason: { type: 'string', description: 'Why — recorded to teach future judgement.' },
+            },
+            required: ['id'],
+          },
+          description: 'Suggestions to reject, each with an optional reason.',
+        },
+        reviewNote: {
+          type: 'string',
+          description: 'Note applied to every acceptance in this batch.',
+        },
+      },
+    },
+  },
+];

package/tools/ai-intelligence.js

@@ -0,0 +1,111 @@
+/**
+ * AI Intelligence Tools
+ * MCP tools for project insights and intelligent analysis
+ *
+ * Consolidated: get_ai_insights (project_insights/suggest_next/dependency_graph)
+ */
+
+export const AI_INTELLIGENCE_TOOLS = [
+  {
+    name: 'get_ai_insights',
+    description: 'Get AI-powered project analysis. ' +
+      'Types: "project_insights" for health analysis (blockers, velocity, workload), ' +
+      '"suggest_next" for personalized task recommendations, ' +
+      '"dependency_graph" for critical path and bottleneck analysis, ' +
+      '"build_failure" for why CI is red (failing checks with their output, plus which checks are ' +
+      'consistently broken vs merely flaky), ' +
+      '"deployment_risk" for how risky a deploy is (CI state on the commit + the environment\'s ' +
+      'recent history, returned with the signals behind the score). ' +
+      'build_failure and deployment_risk are DETERMINISTIC — computed from captured CI/CD data, ' +
+      'no model call and no AI quota. They return evidence for you to reason over, not a verdict.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: {
+          type: 'string',
+          enum: ['project_insights', 'suggest_next', 'dependency_graph', 'build_failure', 'deployment_risk'],
+          description: 'Type of AI insight to retrieve',
+        },
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required for all types)',
+        },
+        // --- suggest_next fields ---
+        userId: {
+          type: 'string',
+          description: 'User ID — defaults to API key owner (suggest_next only)',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of recommendations (suggest_next only, default: 10). ' +
+            'For build_failure and deployment_risk this is the ANALYSIS WINDOW — how many recent ' +
+            'runs/deployments to read (default: 50). Results report the window they used.',
+        },
+        // --- build_failure fields ---
+        headSha: {
+          type: 'string',
+          description: 'Narrow the analysis to one commit (build_failure only)',
+        },
+        taskId: {
+          type: 'string',
+          description: 'Narrow to the CI that ran on a task\'s linked commits (build_failure only)',
+        },
+        kind: {
+          type: 'string',
+          enum: ['check_run', 'workflow_run'],
+          description: 'Analyse individual CI jobs ("check_run") or whole runs ("workflow_run"). ' +
+            'Omit for both. Use workflow_run for "did CI pass"; check_run to see which job broke. ' +
+            '(build_failure only)',
+        },
+        // --- deployment_risk fields ---
+        environment: {
+          type: 'string',
+          description: 'Environment being deployed to, e.g. "production" (REQUIRED for ' +
+            'deployment_risk — it is not defaulted, since assuming production would answer a ' +
+            'different question than the one asked)',
+        },
+        sha: {
+          type: 'string',
+          description: 'Commit being deployed (deployment_risk). Without it the assessment cannot ' +
+            'check CI and reports that as an unverified-change risk rather than borrowing another ' +
+            'commit\'s result.',
+        },
+      },
+      required: ['type', 'projectId'],
+    },
+  },
+  {
+    name: 'estimate_task',
+    description: 'Get a Bayesian AI estimate for how long a task will take, based on similar completed tasks. ' +
+      'Returns median and P80 (80% confidence) hour estimates, confidence level, and the similar tasks used as reference. ' +
+      'Automatically adjusts for the assignee\'s historical accuracy if calibration data exists.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        taskId: {
+          type: 'string',
+          description: 'Task ID to estimate (required)',
+        },
+      },
+      required: ['taskId'],
+    },
+  },
+  {
+    name: 'infer_dependencies',
+    description: 'Infer task-to-task dependencies from file-level import graphs. ' +
+      'Uses the project\'s context manifest (file dependencies) and task-to-file links (linkedFiles) ' +
+      'to deterministically suggest which tasks depend on which. No AI required. ' +
+      'Returns suggestions only — does not auto-create dependencies. ' +
+      'Requires tasks to have linkedFiles populated (via addLinkedFile or git commit linking).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required)',
+        },
+      },
+      required: ['projectId'],
+    },
+  },
+];