@ezmodo/mcp-server 0.13.0

package/tools/git-context.js

@@ -0,0 +1,109 @@
+/**
+ * Git Context Tools
+ * MCP tools for git repository detection and project context management
+ *
+ * Project-First Hierarchy: Projects are the primary container.
+ * Use these tools to auto-detect which Zephly project you're working on.
+ */
+
+export const GIT_CONTEXT_TOOLS = [
+  {
+    name: 'detect_git_repository',
+    description: 'Detect if current directory is a git repository and match it ' +
+      'against accessible ezmodo projects by git URL. Returns matching ' +
+      'projects with confidence scores, and for each match the git ' +
+      'repositories linked to that project — including the `repoId` that ' +
+      'manage_pull_request requires. Use this to auto-suggest which ezmodo ' +
+      'project corresponds to a git repo, and to get from a checkout to a ' +
+      'repoId in one call.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        workingDirectory: {
+          type: 'string',
+          description: 'Directory to check for git repository (defaults to current directory)',
+        },
+      },
+    },
+  },
+  {
+    name: 'get_current_project_context',
+    description: 'Detect and read existing .ezmodo/config.json (or legacy ' +
+      '.zephly/config.json) from current directory or parent directories. ' +
+      'Returns project context if found, ' +
+      'or null if not configured. Use this BEFORE other MCP tools to ' +
+      'auto-detect which project you\'re working on. Project-First: ' +
+      'Returns projectId, components, and tags that can be used ' +
+      'directly with task/epic creation tools. Caches tags and ' +
+      'components locally with 1-day TTL for fast access. ' +
+      'Also returns `projectType` and `terminology` — the words this project ' +
+      'uses for epics, tasks and components and for their statuses (E-107). ' +
+      'Write anything a person reads in those words: a marketing project calls ' +
+      'an epic a "Campaign" and a component a "Channel". Keep the API field ' +
+      'names (epicId, taskId) as they are. A null `terminology` means plain ' +
+      'English, not an error.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        workingDirectory: {
+          type: 'string',
+          description: 'Starting directory to search from (defaults to current directory)',
+        },
+      },
+    },
+  },
+  {
+    name: 'initialize_project_context',
+    description: 'Create .ezmodo/config.json for project context. Helps AI ' +
+      'agents understand which ezmodo project they\'re working on. ' +
+      'Supports single projects and monorepos. Usage: (1) Single ' +
+      'project: provide projectId + organizationId. (2) Monorepo: ' +
+      'provide organizationId + monorepoProjects array (no projectId ' +
+      'needed). (3) Interactive: omit projectId to get available ' +
+      'projects list.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'Project ID for single-project setup. Not needed ' +
+            'for monorepo setup (use monorepoProjects instead).',
+        },
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required for both single project and monorepo setup)',
+        },
+        workingDirectory: {
+          type: 'string',
+          description: 'Directory to create .ezmodo/config.json in (defaults to current directory). If a legacy .zephly/ directory already exists in the repo, the existing location is reused for writes.',
+        },
+        addToGitignore: {
+          type: 'boolean',
+          description: 'Whether to add the config directory (.ezmodo/ or legacy .zephly/) to .gitignore (default: true)',
+          default: true,
+        },
+        addClaudeMd: {
+          type: 'boolean',
+          description: 'Whether to generate/update CLAUDE.md with work tracking instructions (default: true)',
+          default: true,
+        },
+        monorepoProjects: {
+          type: 'array',
+          description: 'For monorepos: Array of {projectId, name, path} ' +
+            'objects mapping subdirectories to projects. When provided ' +
+            'with organizationId (without projectId), writes monorepo ' +
+            'config directly.',
+          items: {
+            type: 'object',
+            properties: {
+              projectId: { type: 'string' },
+              name: { type: 'string' },
+              path: { type: 'string' },
+            },
+            required: ['projectId', 'name', 'path'],
+          },
+        },
+      },
+    },
+  },
+];

package/tools/github.js

@@ -0,0 +1,172 @@
+/**
+ * GitHub Tools
+ * MCP tools for managing GitHub pull requests and integration
+ *
+ * Consolidated: manage_pull_request (create/update/merge/close/request_review)
+ */
+
+export const GITHUB_TOOLS = [
+  {
+    name: 'list_repositories',
+    description: 'List the git repositories linked to a project, each with the ' +
+      '`repoId` that every manage_pull_request action requires. Call this first ' +
+      'when you need a repoId — it is the only way to get one. The id is ' +
+      '"installationId:owner/repo" and the installation id is not derivable ' +
+      'from anywhere else: no other ezmodo tool exposes it, and GitHub only ' +
+      'answers for it with an app JWT or an app-authorized token. ' +
+      '`installationStatus` tells a live link from one whose GitHub App was ' +
+      'uninstalled or suspended; a repoId from a non-active installation will ' +
+      'parse and then fail at the GitHub call.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'Project whose linked repositories to list (required)',
+        },
+      },
+      required: ['projectId'],
+    },
+  },
+  {
+    name: 'manage_pull_request',
+    description: 'Create, update, merge, close, or request review on GitHub pull requests. ' +
+      'Also suggests reviewers ("suggest_reviewers") ranked from CODEOWNERS and file history — ' +
+      'that action only SUGGESTS; use "request_review" to actually request them.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create', 'update', 'merge', 'close', 'request_review', 'suggest_reviewers'],
+          description: 'Action to perform',
+        },
+        // --- Identifiers (used by all actions) ---
+        repoId: {
+          type: 'string',
+          description: 'Repository ID in format "installationId:owner/repo" (e.g., "12345678:acme-corp/backend"). ' +
+            'Get it from `list_repositories` (or from the `repositories` on a `detect_git_repository` match) — ' +
+            'the installation id is not derivable from the repo, and GitHub will not tell you it.',
+        },
+        number: {
+          type: 'number',
+          description: 'PR number (required for update, merge, close, request_review)',
+        },
+        // --- Create fields ---
+        title: {
+          type: 'string',
+          description: 'PR title (required for create, optional for update)',
+        },
+        body: {
+          type: 'string',
+          description: 'PR description in markdown format. Used by create and update.',
+        },
+        headBranch: {
+          type: 'string',
+          description: 'Source branch name without refs/heads/ (required for create)',
+        },
+        baseBranch: {
+          type: 'string',
+          description: 'Target branch name e.g. "main" (required for create, optional for update)',
+        },
+        draft: {
+          type: 'boolean',
+          description: 'Create as draft PR (create only, default: false)',
+        },
+        maintainerCanModify: {
+          type: 'boolean',
+          description: 'Allow maintainers to modify the PR. Used by create and update (default: true).',
+        },
+        assignees: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'GitHub usernames to assign to the PR (create only)',
+        },
+        reviewers: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'GitHub usernames to request review from. Used by create and request_review.',
+        },
+        teamReviewers: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'GitHub team slugs to request review from (e.g., "backend-team"). Used by create and request_review.',
+        },
+        labels: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Labels to add to the PR (create only)',
+        },
+        milestoneNumber: {
+          type: 'number',
+          description: 'Milestone number to associate with the PR (create only)',
+        },
+        // --- Work linkage (E-233) ---
+        taskId: {
+          type: 'string',
+          description: 'ezmodo task this PR implements. Used by create and update. ' +
+            'You already know which task you are on, so passing it here records the ' +
+            'strongest possible link — better than relying on the resolver to infer ' +
+            'one from the branch name or the PR body afterwards.',
+        },
+        epicId: {
+          type: 'string',
+          description: 'ezmodo epic this PR advances. Used by create and update. ' +
+            'Usually unnecessary when taskId is set and the task already belongs to the epic.',
+        },
+        // --- Update-only fields ---
+        state: {
+          type: 'string',
+          enum: ['open', 'closed'],
+          description: 'Update PR state (update only)',
+        },
+        // --- Merge fields ---
+        mergeMethod: {
+          type: 'string',
+          enum: ['merge', 'squash', 'rebase'],
+          description: 'Merge method to use (merge only, default: "merge")',
+        },
+        commitTitle: {
+          type: 'string',
+          description: 'Custom merge commit title for squash/merge (merge only)',
+        },
+        commitMessage: {
+          type: 'string',
+          description: 'Custom merge commit message body (merge only)',
+        },
+        sha: {
+          type: 'string',
+          description: 'Head SHA to validate before merge — prevents race conditions (merge only)',
+        },
+        // --- suggest_reviewers fields ---
+        projectId: {
+          type: 'string',
+          description: 'Project ID — required by every action. It scopes access, and on create/update it is ' +
+            'what the PR is stored and linked against.',
+        },
+        changedPaths: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Repo-relative paths this change touches (REQUIRED for suggest_reviewers). ' +
+            'Without them there is nothing to reason from; guessing "the whole repo" would just ' +
+            'suggest whoever commits most. Capped at 50 — file history is one API call per path.',
+        },
+        excludeLogins: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Logins to never suggest (suggest_reviewers only). Passing `number` also ' +
+            'excludes the PR author automatically.',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum suggestions to return (suggest_reviewers only, default 5, max 25). ' +
+            'The response sets `truncated` when the list was capped.',
+        },
+      },
+      // Every action's server handler rejects a missing projectId, so the schema
+      // says so too. It used to be documented as "required for suggest_reviewers",
+      // which read as optional everywhere else and was not.
+      required: ['action', 'repoId', 'projectId'],
+    },
+  },
+];

package/tools/graph.js

@@ -0,0 +1,70 @@
+/**
+ * Graph Tools
+ *
+ * The living navigation graph (E-209): a browsable, cross-entity projection
+ * over the entity_links link graph (relates_to / blocked_by). One read lets an
+ * agent walk "what connects to this" from any node — features, epics, tasks,
+ * goals, milestones, components, designs, decisions, documents, test suites,
+ * feature flags — instead of issuing N separate list_links calls and stitching
+ * the results together.
+ *
+ * It is a READ VIEW, not a hierarchy: features/goals stay org-level; nothing is
+ * re-parented. Backed by the graph projection endpoint (proxies GET-equivalent
+ * server-side traversal, org-scoped + RLS).
+ */
+
+import { LINKABLE_TYPES } from './linkable-types.js';
+
+export const GRAPH_TOOLS = [
+  {
+    name: 'get_graph',
+    description:
+      'Walk the compendium navigation graph outward from a root node and return ' +
+      'the hydrated neighborhood as nodes + edges. Nodes carry lightweight ' +
+      'display fields (type, id, title, status, projectId, kind, number, depth); ' +
+      'edges are the entity_links relations (relates_to / blocked_by) between ' +
+      'them, direction preserved. Use it to answer "what connects to this?" in ' +
+      'one call. Traversal is a breadth-first walk bounded by depth and a node ' +
+      'cap (truncated:true in the response means the cap was hit). A root ' +
+      '(rootType + rootId) is REQUIRED — the graph is always explored from a ' +
+      'node, not listed wholesale.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description:
+            'Project that scopes access (authorizes the caller and sets the org ' +
+            'scope). Required. The graph itself can still reach org-level nodes ' +
+            '(features/goals) under scope "org".',
+        },
+        rootType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description: 'Type of the node to explore from (required).',
+        },
+        rootId: {
+          type: 'string',
+          description: 'ID of the root node to explore from (required).',
+        },
+        scope: {
+          type: 'string',
+          enum: ['org', 'project'],
+          description:
+            'org (default): keep every reachable in-org node. project: drop nodes ' +
+            'that belong to a different project than the root (org-level nodes and ' +
+            'the root are always kept).',
+        },
+        depth: {
+          type: 'number',
+          description: 'Hops from the root to traverse. Default 2, max 5.',
+        },
+        maxNodes: {
+          type: 'number',
+          description: 'Cap on the number of nodes returned. Default 150, max 500.',
+        },
+      },
+      required: ['projectId', 'rootType', 'rootId'],
+    },
+  },
+];

package/tools/index.js

@@ -0,0 +1,77 @@
+/**
+ * Tool Definitions Index
+ * Aggregates all MCP tool definitions
+ *
+ * Consolidated tool set (~40 tools, down from 116):
+ * - One "manage_*" tool per entity (mutations with action param)
+ * - One "get_*" or "list_*" tool per entity (reads)
+ * - One unified "get_context" tool (replaces 8 context/graph tools)
+ */
+
+import { ORGANIZATION_TOOLS } from './organizations.js';
+import { PROJECT_TOOLS } from './projects.js';
+import { COMPONENT_TOOLS } from './components.js';
+import { EPIC_TOOLS } from './epics.js';
+import { MILESTONE_TOOLS } from './milestones.js';
+import { FEATURE_TOOLS } from './features.js';
+import { DECISION_TOOLS } from './decisions.js';
+import { DESIGN_TOOLS } from './designs.js';
+import { CATALOG_TOOLS } from './catalogs.js';
+import { FEATURE_FLAG_TOOLS } from './feature-flags.js';
+import { TASK_TOOLS } from './tasks.js';
+import { DOCUMENT_TOOLS } from './documents.js';
+import { FOLDER_TOOLS } from './folders.js';
+import { ATTACHMENT_TOOLS } from './attachments.js';
+import { ENTITY_TOOLS } from './entities.js';
+import { LINK_TOOLS } from './links.js';
+import { ACCESS_TOOLS } from './access.js';
+import { GRAPH_TOOLS } from './graph.js';
+import { TAG_TOOLS } from './tags.js';
+import { WATCHER_TOOLS } from './watchers.js';
+import { AI_INTELLIGENCE_TOOLS } from './ai-intelligence.js';
+import { GIT_CONTEXT_TOOLS } from './git-context.js';
+import { WORKTREE_TOOLS } from '../lib/worktree-tools.js';
+import { GITHUB_TOOLS } from './github.js';
+import { TODO_TOOLS } from './todos.js';
+import { TESTING_TOOLS } from './testing.js';
+import { CONTEXT_MANIFEST_TOOLS } from './context-manifest.js';
+import { ACTIVITY_TOOLS } from './activity.js';
+import { FACT_TOOLS } from './facts.js';
+import { AGENT_TOOLS } from './agents.js';
+import { RECURRING_TASK_TOOLS } from './recurring-tasks.js';
+import { WORK_TEMPLATE_TOOLS } from './work-templates.js';
+
+export const TOOLS = [
+  ...ORGANIZATION_TOOLS,
+  ...PROJECT_TOOLS,
+  ...COMPONENT_TOOLS,
+  ...EPIC_TOOLS,
+  ...MILESTONE_TOOLS,
+  ...FEATURE_TOOLS,
+  ...DECISION_TOOLS,
+  ...DESIGN_TOOLS,
+  ...CATALOG_TOOLS,
+  ...FEATURE_FLAG_TOOLS,
+  ...TASK_TOOLS,
+  ...RECURRING_TASK_TOOLS,
+  ...WORK_TEMPLATE_TOOLS,
+  ...DOCUMENT_TOOLS,
+  ...FOLDER_TOOLS,
+  ...ATTACHMENT_TOOLS,
+  ...ENTITY_TOOLS,
+  ...LINK_TOOLS,
+  ...ACCESS_TOOLS,
+  ...GRAPH_TOOLS,
+  ...TAG_TOOLS,
+  ...WATCHER_TOOLS,
+  ...AI_INTELLIGENCE_TOOLS,
+  ...GIT_CONTEXT_TOOLS,
+  ...WORKTREE_TOOLS,
+  ...GITHUB_TOOLS,
+  ...TODO_TOOLS,
+  ...TESTING_TOOLS,
+  ...CONTEXT_MANIFEST_TOOLS,
+  ...ACTIVITY_TOOLS,
+  ...FACT_TOOLS,
+  ...AGENT_TOOLS,
+];

package/tools/link-params.js

@@ -0,0 +1,93 @@
+/**
+ * The reusable link-shaped tool parameters, declared once.
+ *
+ * Two problems these exist to fix (E-225):
+ *
+ * 1. No creation tool could attach a link at CREATE time. An agent had to
+ *    create the entity, then remember a second `manage_link` call — which it
+ *    usually didn't, so work landed unlinked from the feature/flag/goal it
+ *    belonged to. `LINKS_ARRAY_SCHEMA` gives every `create` action a `links`
+ *    param so the graph edge is born with the entity.
+ *
+ * 2. Six tool files inlined a stale 4-type `['task','epic','project','document']`
+ *    enum on addRelatedItem/removeRelatedItem that predated LINKABLE_TYPES, so
+ *    a task could not be given a related design or decision except through
+ *    `manage_link`. `RELATED_ITEM_SCHEMA` is the drop-in replacement.
+ *
+ * Everything here reuses the shared `LINKABLE_TYPES` array BY REFERENCE — the
+ * `link-params` test asserts identity, not equality, so a copy that happens to
+ * agree today cannot silently drift tomorrow.
+ */
+
+import { LINKABLE_TYPES } from './linkable-types.js';
+
+/** Link semantics an agent may request. Mirrors links.LinkType in the Go API. */
+export const LINK_TYPES = ['relates_to', 'blocked_by'];
+
+/**
+ * One link to attach, as used inside `links: [...]`. Mirrors the node shape
+ * already carried by manage_feature's apply_init (`links:[{targetType,targetId}]`).
+ */
+export const LINK_ITEM_SCHEMA = {
+  type: 'object',
+  properties: {
+    targetType: {
+      type: 'string',
+      enum: LINKABLE_TYPES,
+      description: 'Type of the entity to link to (required)',
+    },
+    targetId: {
+      type: 'string',
+      description: 'ID of the entity to link to (required)',
+    },
+    linkType: {
+      type: 'string',
+      enum: LINK_TYPES,
+      default: 'relates_to',
+      description:
+        'relates_to: soft cross-entity link (any combo, the default). ' +
+        'blocked_by: source is blocked by target (only task→task or epic→epic).',
+    },
+  },
+  required: ['targetType', 'targetId'],
+};
+
+/**
+ * The `links` array parameter. Attach on create so the entity is born
+ * connected — no follow-up manage_link round trip, and no orphan work.
+ *
+ * Best-effort by contract: a link that fails is reported back in
+ * `links.failed` on the response, it never fails the entity create.
+ */
+export const LINKS_ARRAY_SCHEMA = {
+  type: 'array',
+  items: LINK_ITEM_SCHEMA,
+  description:
+    'Links to attach at creation time, e.g. the feature this work advances, ' +
+    'the goal it serves, or the document it implements: ' +
+    '[{ targetType: "feature", targetId: "abc" }]. Prefer this over a ' +
+    'follow-up manage_link call — work that is not linked when it is created ' +
+    'usually never gets linked. Applied best-effort: failures are returned in ' +
+    'the response\'s `links.failed` and never fail the create.',
+};
+
+/**
+ * A single cross-entity related item — the shape used by the legacy
+ * addRelatedItem / removeRelatedItem update params. Kept working, but
+ * deprecated in favour of `addLinks` / `removeLinks`.
+ */
+export const RELATED_ITEM_SCHEMA = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      enum: LINKABLE_TYPES,
+      description: 'Type of the related entity',
+    },
+    id: {
+      type: 'string',
+      description: 'ID of the related entity',
+    },
+  },
+  required: ['type', 'id'],
+};

package/tools/linkable-types.js

@@ -0,0 +1,36 @@
+/**
+ * The entity types a link can point at, declared once.
+ *
+ * This mirrors `links.allEntityTypes` in the Go API (api/internal/core/links/
+ * service.go), which is the authority — an enum here that the API rejects just
+ * turns a clear tool-schema error into a confusing 400, and an enum here that
+ * is MISSING a type the API accepts hides a capability from agents entirely.
+ *
+ * Before this, six tool files each spelled the list out inline and every one of
+ * them was frozen at the set of types that existed the day it was written:
+ * decisions and designs stopped at `project`, features knew about design and
+ * test_suite but not feature_flag or catalog, links.js knew feature_flag but
+ * not milestone or goal. Adding a linkable type meant editing six lists and
+ * forgetting one was invisible until an agent tried it.
+ *
+ * Adding a type: add it in the Go `allEntityTypes` list, then here.
+ */
+export const LINKABLE_TYPES = [
+  'task',
+  'epic',
+  'project',
+  'document',
+  'component',
+  'feature',
+  'decision',
+  'design',
+  'test_suite',
+  'feature_flag',
+  'catalog',
+  'catalog_item',
+  'milestone',
+  'goal',
+  // One row of git_pull_requests (E-233). A PR is linked to the work it
+  // implements, rather than the PR table carrying task/epic columns.
+  'pull_request',
+];