@ezmodo/mcp-server 0.13.0

package/tools/feature-flags.js

@@ -0,0 +1,300 @@
+/**
+ * Feature Flag Tools
+ * MCP tools for Feature Flags (E-149) — PM-aware, lifecycle-tracked runtime gates.
+ *
+ * A Feature Flag is an org-level (projectId nullable) runtime gate with a
+ * lifecycle (draft → … → enabled/disabled → sunset → archived), a served value
+ * (boolean | multivariate | config), optional prerequisite nesting
+ * (parentFeatureFlagId — a child only serves "on" when its parent chain is on
+ * for the same subject), and targeting rules + percentage rollout. Flags LINK to
+ * the feature(s) they gate via the generic link graph — they do not contain them.
+ *
+ * Prefer the polymorphic manage_link (sourceType "feature", targetType
+ * "feature_flag") to attach a flag to a feature; the link/unlink actions here are
+ * a convenience that go through the flag's own link surface.
+ */
+
+import { LINKABLE_TYPES } from './linkable-types.js';
+import { LINKS_ARRAY_SCHEMA } from './link-params.js';
+
+export const FEATURE_FLAG_TOOLS = [
+  {
+    name: 'manage_feature_flag',
+    description: 'Create, update, or delete a Feature Flag (a PM-aware runtime gate: key, name, ' +
+      'kind boolean|multivariate|config, rollout %, prerequisite parent, governance properties), ' +
+      'advance its lifecycle status (action "transition"), or link/unlink it to the feature(s) it ' +
+      'gates. Flags are org-level and LINK to features/epics/tasks/etc., they do not contain them. ' +
+      'Status changes go through action "transition" (recorded in history), NOT update.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create', 'update', 'delete', 'transition', 'link', 'unlink', 'set_environment_config'],
+          description: 'Action to perform. "transition" advances lifecycle status (pass flagId + ' +
+            'status + reason). "link"/"unlink" attach/detach the flag to an artifact (pass flagId + ' +
+            'targetType + targetId). "set_environment_config" sets the flag\'s served state in ONE ' +
+            'environment (pass flagId + environmentId + enabled + rolloutPercentage [+ defaultVariantId]) — ' +
+            'this is how you turn a flag on in dev but off in prod (E-186).',
+        },
+        // --- per-environment served state (E-186, action set_environment_config) ---
+        environmentId: {
+          type: 'string',
+          description: 'Environment ID whose served state to set (set_environment_config). Get ids ' +
+            'from manage_environment action "list".',
+        },
+        enabled: {
+          type: 'boolean',
+          description: 'Per-environment kill switch — when false the flag serves off in this ' +
+            'environment regardless of rules/rollout (set_environment_config)',
+        },
+        // --- Identifiers ---
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required for create)',
+        },
+        flagId: {
+          type: 'string',
+          description: 'Feature flag ID (required for update, delete, transition, link, unlink)',
+        },
+        // --- Create / update fields ---
+        key: {
+          type: 'string',
+          description: 'Stable programmatic identifier used by code gates and the evaluator ' +
+            '(e.g. "analytics.behavioral_source"). Unique per organization. Required for create.',
+        },
+        name: {
+          type: 'string',
+          description: 'Human-friendly flag name (required for create) (create, update)',
+        },
+        description: {
+          type: 'string',
+          description: 'What the flag gates and when it can be removed, supports markdown (create, update)',
+        },
+        kind: {
+          type: 'string',
+          enum: ['boolean', 'multivariate', 'config'],
+          description: 'What the flag serves: "boolean" on/off (default), "multivariate" named ' +
+            'weighted variants, or "config" a JSON payload (create, update)',
+        },
+        rolloutPercentage: {
+          type: 'number',
+          description: 'Percentage rollout 0–100 (default 0). Subjects are bucketed by a consistent ' +
+            'hash of (key, subjectId); those below the cutoff are served on (create, update)',
+        },
+        projectId: {
+          type: 'string',
+          description: 'Scope the flag to a project. Omit/empty = org-wide / system flag ' +
+            '(e.g. a backend gate) (create, update)',
+        },
+        parentFeatureFlagId: {
+          type: 'string',
+          description: 'Prerequisite parent flag ID — this flag serves "on" for a subject only if ' +
+            'the parent chain is also on for that subject. Omit/empty = root flag. Cycles are ' +
+            'rejected (create, update)',
+        },
+        defaultVariantId: {
+          type: 'string',
+          description: 'Variant served when the flag is on and no rule matched (fallthrough). ' +
+            'Empty string clears it (update)',
+        },
+        properties: {
+          type: 'object',
+          description: 'Governance metadata (owner, expiry/ttl, ticket link, environment, custom ' +
+            'k/v). Does NOT affect evaluation (create, update)',
+        },
+        // --- transition fields ---
+        status: {
+          type: 'string',
+          enum: ['draft', 'in_development', 'rolling_out', 'enabled', 'disabled',
+            'sunset', 'archived', 'cancelled'],
+          description: 'For action "create": the initial lifecycle status (default "draft"). For ' +
+            'action "transition": the target status to move to.',
+        },
+        reason: {
+          type: 'string',
+          description: 'Why the status changed — recorded in the flag\'s history (transition)',
+        },
+        // --- link / unlink fields ---
+        targetType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description: 'Type of artifact to link/unlink — usually "feature" (required for link, unlink)',
+        },
+        targetId: {
+          type: 'string',
+          description: 'ID of the artifact to link/unlink (required for link, unlink)',
+        },
+        // --- create-time link fields ---
+        linkToType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description: 'Optionally link the new flag to this artifact type on creation (create)',
+        },
+        linkToId: {
+          type: 'string',
+          description: 'ID of the artifact to link the new flag to on creation (create; requires linkToType)',
+        },
+        links: LINKS_ARRAY_SCHEMA,
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name: 'get_feature_flag',
+    description: 'Retrieve a single Feature Flag (with its variants + rules) by ID, or by ' +
+      'organizationId + key (key is unique per org). Provide flagId, OR organizationId + key.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        flagId: {
+          type: 'string',
+          description: 'Feature flag ID for a single lookup',
+        },
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (with key, for a lookup by key)',
+        },
+        key: {
+          type: 'string',
+          description: 'Flag key (with organizationId, for a lookup by key)',
+        },
+        includeLinks: {
+          type: 'boolean',
+          description: 'If true, also return the flag\'s linked artifacts',
+        },
+      },
+    },
+  },
+  {
+    name: 'list_feature_flags',
+    description: 'List an organization\'s Feature Flags, optionally filtered by project, status, or ' +
+      'kind — or list the flags linked to a given entity (e.g. all flags on a feature) via ' +
+      'linkedType + linkedId.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required)',
+        },
+        projectId: {
+          type: 'string',
+          description: 'Filter to a single project\'s flags',
+        },
+        status: {
+          type: 'string',
+          enum: ['draft', 'in_development', 'rolling_out', 'enabled', 'disabled',
+            'sunset', 'archived', 'cancelled'],
+          description: 'Filter by lifecycle status',
+        },
+        kind: {
+          type: 'string',
+          enum: ['boolean', 'multivariate', 'config'],
+          description: 'Filter by flag kind',
+        },
+        includeOrgWide: {
+          type: 'boolean',
+          description: 'When filtering by projectId, also include org-wide (project-less) flags',
+        },
+        linkedType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description: 'List flags linked to this entity type (requires linkedId), e.g. all flags on a feature',
+        },
+        linkedId: {
+          type: 'string',
+          description: 'ID of the entity to list linked flags for (requires linkedType)',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results',
+        },
+      },
+      required: ['organizationId'],
+    },
+  },
+  {
+    name: 'evaluate_feature_flag',
+    description: 'Evaluate a Feature Flag for a subject and return the served Result ({ on, ' +
+      'variantKey, value, reason }) — for debugging a flag\'s behavior from chat. Resolves the ' +
+      'prerequisite chain and runs the deterministic evaluator (status → targeting rules → ' +
+      'percentage rollout). Look up by organizationId + key.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required)',
+        },
+        key: {
+          type: 'string',
+          description: 'Flag key to evaluate (required)',
+        },
+        subjectId: {
+          type: 'string',
+          description: 'Stable subject identifier for percentage bucketing (e.g. a userId). ' +
+            'Same subject always lands in the same bucket per flag.',
+        },
+        environment: {
+          type: 'string',
+          description: 'Environment KEY to evaluate in (e.g. "production", "development"). ' +
+            'Omit to use the flag scope\'s default environment (E-186).',
+        },
+        attributes: {
+          type: 'object',
+          description: 'Targeting facts the rules test against (e.g. { plan: "pro", country: "US" })',
+        },
+      },
+      required: ['organizationId', 'key'],
+    },
+  },
+  {
+    name: 'manage_environment',
+    description: 'Manage the configurable ENVIRONMENT registry (E-186): the named environments ' +
+      '(e.g. development/staging/production) a flag can be served differently in. Environments are ' +
+      'per-scope: org-wide (omit projectId) or project-scoped (set projectId). Exactly one per scope ' +
+      'is the default (used when an evaluation does not name an environment). To set a flag\'s value ' +
+      'IN an environment, use manage_feature_flag action "set_environment_config".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'create', 'update', 'delete', 'set_default'],
+          description: 'list (by organizationId [+projectId]); create; update (name/order); delete; ' +
+            'set_default (make this the scope\'s default environment).',
+        },
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required for list and create)',
+        },
+        projectId: {
+          type: 'string',
+          description: 'Project scope. Omit/empty = the org-wide environment set (used by org-wide flags).',
+        },
+        environmentId: {
+          type: 'string',
+          description: 'Environment ID (required for update, delete, set_default)',
+        },
+        key: {
+          type: 'string',
+          description: 'Stable environment key, lowercase (e.g. "production"). Immutable. Required for create.',
+        },
+        name: {
+          type: 'string',
+          description: 'Human-friendly environment name (create, update)',
+        },
+        order: {
+          type: 'number',
+          description: 'Display order within the scope (create, update)',
+        },
+        isDefault: {
+          type: 'boolean',
+          description: 'Make this the scope\'s default environment on create (create)',
+        },
+      },
+      required: ['action'],
+    },
+  },
+];

package/tools/features.js

@@ -0,0 +1,246 @@
+/**
+ * Feature Tools
+ * MCP tools for the Feature Compendium (E-162).
+ *
+ * A Feature is a durable, user-facing product CAPABILITY — a NOUN, on a
+ * separate axis from work. Epics/tasks are VERBS (work); features LINK to work,
+ * they do not own it. Features are ORG-LEVEL, and a feature SPANS MULTIPLE
+ * PROJECTS (E-242) — a real capability like "Push notifications" lives in api +
+ * web + mobile at once:
+ *  - projectIds []    → every project the capability spans; the FIRST is the
+ *                       primary/owner. An empty set = cross-project / org-wide,
+ *                       which is in scope for every project.
+ *  - projectId        → DEPRECATED single-project form, treated as a
+ *                       one-element projectIds. Still accepted everywhere.
+ *  - parent_feature_id builds a sub-feature tree.
+ *
+ * The "is this a feature?" test: would a PM/user call it "a feature of the app"?
+ * (push notifications = yes; "refactor auth middleware" = no, that's an epic).
+ * Discipline: features track the product-capability map, NOT every change — do
+ * not create a feature per task.
+ */
+
+import { LINKABLE_TYPES } from './linkable-types.js';
+
+export const FEATURE_TOOLS = [
+  {
+    name: 'manage_feature',
+    description: 'Create, update, or delete a Feature (a durable product capability), or link/unlink it ' +
+      'to existing work artifacts. Features are org-level and live on a separate axis from work — they ' +
+      'LINK to epics/tasks/milestones/etc., they do not contain them.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create', 'update', 'delete', 'link', 'unlink', 'promote_epic', 'generate_how_it_works', 'apply_how_it_works', 'apply_init'],
+          description: 'Action to perform. "promote_epic" creates a feature from an existing epic ' +
+            '(inheriting its title/description/scope) and links the epic to it. ' +
+            '"generate_how_it_works" (re)generates the feature\'s grounded, source-attributed ' +
+            '"how it works" living description from its linked work + code (requires featureId; ' +
+            '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_feature with includeDetail. ' +
+            '"apply_init" commits a human-approved init/backfill proposal (E-167): pass ' +
+            'organizationId + nodes (a candidate-feature tree) to create features parents→children, ' +
+            'backfill links, and persist any agent-authored "how it works". Inference itself runs ' +
+            'locally with the user\'s AI — this only applies the approved result.',
+        },
+        // --- Identifiers ---
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required for create)',
+        },
+        featureId: {
+          type: 'string',
+          description: 'Feature ID (required for update, delete, link, unlink, 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 feature\'s grounded context; the server drops fabricated ones.',
+        },
+        epicId: {
+          type: 'string',
+          description: 'Epic ID to promote into a feature (required for promote_epic)',
+        },
+        // --- Create / update fields ---
+        title: {
+          type: 'string',
+          description: 'Feature title (required for create), e.g. "Push Notifications"',
+        },
+        description: {
+          type: 'string',
+          description: 'Feature description, supports markdown (create, update). ' +
+            'Writing this stays plain text; it does not create a backing document.',
+        },
+        status: {
+          type: 'string',
+          enum: ['proposed', 'active', 'deprecated', 'removed'],
+          description: 'Capability lifecycle status (default: "active") (create, update)',
+        },
+        projectId: {
+          type: 'string',
+          description: 'DEPRECATED single-project form — prefer projectIds. Treated as a ' +
+            'one-element projectIds. Omit/empty = cross-project / org-wide; on update an empty ' +
+            'string clears the scope back to org-wide.',
+        },
+        projectIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Every project this capability spans (create, update). The FIRST id is ' +
+            'the primary/owner. On UPDATE this REPLACES the whole set — pass the full list, not ' +
+            'just additions — and an empty array makes the feature org-wide. Omitting it on an ' +
+            'update leaves the existing projects alone. Wins over projectId.',
+        },
+        parentFeatureId: {
+          type: 'string',
+          description: 'Parent feature ID for the sub-feature tree. Omit/empty = root feature. ' +
+            'On update, an empty string makes it a root.',
+        },
+        // --- link / unlink fields ---
+        targetType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description: 'Type of artifact to link/unlink (required for link, unlink). ' +
+            'test_suite surfaces read-only pass/fail coverage on the feature (E-173).',
+        },
+        targetId: {
+          type: 'string',
+          description: 'ID of the artifact to link/unlink (required for link, unlink)',
+        },
+        // --- apply_init fields (E-167) ---
+        nodes: {
+          type: 'array',
+          description: 'Approved candidate-feature tree to commit (required for apply_init). Each node: ' +
+            '{ tempId, title, description?, status?, parentTempId?|parentFeatureId?, mergeIntoFeatureId?, ' +
+            'projectId?, links?:[{targetType,targetId}], howItWorks?:{markdown, sources, validSources?} }. ' +
+            'tempId lets nodes reference each other before creation; mergeIntoFeatureId picks the dedup path.',
+          items: { type: 'object' },
+        },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name: 'get_feature',
+    description: 'Retrieve a single Feature, list features for a project, view the feature tree, ' +
+      'or list a feature\'s links. Provide featureId (or organizationId + featureSlug) for a single ' +
+      'lookup; for list/tree provide organizationId AND a project scope (projectId, or ' +
+      'projectIds for several at once) — an org can span several products, so list/tree is ' +
+      'project-scoped (it still includes org-wide capabilities, i.e. features spanning no ' +
+      'project). List mode is PAGINATED: the response carries total/hasMore alongside features, ' +
+      'so use offset to page rather than assuming you got everything. ' +
+      '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: {
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required for list/tree, alongside projectId; ' +
+            'with featureSlug for slug lookup)',
+        },
+        featureId: {
+          type: 'string',
+          description: 'Feature ID for a single lookup',
+        },
+        featureSlug: {
+          type: 'string',
+          description: 'Feature slug for a single lookup (requires organizationId)',
+        },
+        tree: {
+          type: 'boolean',
+          description: 'If true, return the nested feature forest instead of a flat list',
+        },
+        includeLinks: {
+          type: 'boolean',
+          description: 'If true (single lookup), also return the feature\'s linked artifacts',
+        },
+        includeDetail: {
+          type: 'boolean',
+          description: 'If true (single lookup), return the aggregated detail: linked artifacts ' +
+            'hydrated + grouped by type + a progress rollup over linked epics/tasks, plus the ' +
+            'generated "how it works" summary (howItWorks/howItWorksSources/generatedAt/model on ' +
+            'the feature) and a coarse howItWorksStale flag. Supersedes includeLinks.',
+        },
+        // --- List/tree filters ---
+        projectId: {
+          type: 'string',
+          description: 'Scope the listing to one project. Either this or projectIds is REQUIRED ' +
+            'for list/tree mode. Returns features spanning that project PLUS org-wide ' +
+            '(cross-project) ones. Ignored for a single lookup by featureId/featureSlug.',
+        },
+        projectIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Scope the listing to several projects at once — satisfies the list/tree ' +
+            'scope requirement in place of projectId. Use it when working across projects ' +
+            '(e.g. api + web) to get one call instead of two. Wins over projectId.',
+        },
+        status: {
+          type: 'string',
+          enum: ['proposed', 'active', 'deprecated', 'removed'],
+          description: 'Filter by status (list/tree mode)',
+        },
+        search: {
+          type: 'string',
+          description: 'Substring filter over title, description and slug (list mode). This is a ' +
+            'literal text match — for "does this capability already exist?" use search_features, ' +
+            'which ranks by meaning.',
+        },
+        sortBy: {
+          type: 'string',
+          enum: ['title', 'status', 'createdAt', 'updatedAt', 'howItWorksGeneratedAt'],
+          description: 'Sort column (list mode, default "title"). An unrecognised value is an error.',
+        },
+        sortDir: {
+          type: 'string',
+          enum: ['asc', 'desc'],
+          description: 'Sort direction (list mode, default "asc")',
+        },
+        limit: {
+          type: 'number',
+          description: 'Page size (list mode, default 25, max 500)',
+        },
+        offset: {
+          type: 'number',
+          description: 'Rows to skip (list mode, default 0). Page with this while hasMore is true.',
+        },
+      },
+    },
+  },
+  {
+    name: 'search_features',
+    description: 'Semantic search over an organization\'s Features. Returns existing features ' +
+      'ranked by meaning-similarity to a query — use this BEFORE creating a new feature to find ' +
+      'an existing capability the work belongs to, so the compendium stays small and free of ' +
+      'duplicates (capture-at-build, E-164). Each result is {feature, similarity}.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID to search within (required)',
+        },
+        query: {
+          type: 'string',
+          description: 'Natural-language description of the capability to find ' +
+            '(e.g. "let users get notified about activity"). Required.',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results (default: 10)',
+        },
+      },
+      required: ['organizationId', 'query'],
+    },
+  },
+];

package/tools/folders.js

@@ -0,0 +1,122 @@
+/**
+ * Folder Tools
+ * MCP tools for managing document folders within projects
+ */
+
+export const FOLDER_TOOLS = [
+  {
+    name: 'manage_folder',
+    description: 'Create, update, or delete document folders. Folders are usually ' +
+      'project-scoped (pass projectId), but a folder can also be ORG-SCOPED ' +
+      '(project-less) by passing organizationId with NO projectId — exactly one of the two. ' +
+      'Org-scoped folders are the org\'s document "areas"; the reserved areas (Goals, ' +
+      'Features, ADRs, How it works) are managed via get_org_areas. (E-195)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create', 'update', 'delete'],
+          description: 'Action to perform',
+        },
+        // --- Identifiers ---
+        projectId: {
+          type: 'string',
+          description: 'Project ID. Provide for a PROJECT-SCOPED folder. ' +
+            'Mutually exclusive with organizationId — supply exactly one when creating.',
+        },
+        organizationId: {
+          type: 'string',
+          description: 'Org scope — provide organizationId with NO projectId to create/list an ' +
+            'ORG-SCOPED (project-less) folder (an org document "area"). Exactly one of projectId ' +
+            'or organizationId. (E-195)',
+        },
+        folderId: {
+          type: 'string',
+          description: 'Folder ID (required for update, delete)',
+        },
+        // --- Create / Update fields ---
+        name: {
+          type: 'string',
+          description: 'Folder name (required for create, optional for update)',
+        },
+        color: {
+          type: 'string',
+          description: 'Folder color (e.g., "blue", "red", "#FF0000") (create, update)',
+        },
+        icon: {
+          type: 'string',
+          description: 'Folder icon identifier (create, update)',
+        },
+        // NOTE: there is deliberately no `access` parameter. Folder access
+        // control is real, but it is generic across entity types rather than a
+        // property of folders — folders.CreateFolderRequest /
+        // UpdateFolderRequest carry no access field, so a previously-advertised
+        // `access` object was decoded away to nothing on both create and update
+        // (#2168). Use the `manage_access` / `get_access` tools with
+        // entityType:"folder" instead; passing `access` here is reported back as
+        // a warning rather than silently accepted, see handlers/folders.js.
+        // Note that only ROOT folders carry their own access — nested folders
+        // inherit from their root, and manage_access rejects them accordingly.
+        // --- Create-only fields ---
+        parentFolderId: {
+          type: 'string',
+          description: 'Parent folder ID for nested folders (create only). For update, use this to move the folder. Use "root" or empty string to move to root level.',
+        },
+        // --- Delete-only fields ---
+        cascade: {
+          type: 'boolean',
+          description: 'If true, delete all contents recursively. If false (default), move contents to root. (delete only)',
+          default: false,
+        },
+      },
+      // projectId OR organizationId is required for create (see scope descriptions);
+      // update/delete require folderId. Enforced server-side.
+      required: ['action'],
+    },
+  },
+  {
+    name: 'list_folders',
+    description: 'List document folders. Provide projectId for a project\'s folders, OR ' +
+      'organizationId (with no projectId) for the org\'s ORG-SCOPED (project-less) folders / ' +
+      'document areas (E-195). Use mode "tree" for hierarchical parent-child view, or "flat" ' +
+      '(default) for a flat list with document counts.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'The project ID. Mutually exclusive with organizationId.',
+        },
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID — list the org\'s ORG-SCOPED (project-less) folders ' +
+            'instead of a project\'s. Mutually exclusive with projectId. (E-195)',
+        },
+        mode: {
+          type: 'string',
+          enum: ['flat', 'tree'],
+          description: 'Output mode: "flat" (default) for list with document counts, "tree" for hierarchical parent-child view',
+          default: 'flat',
+        },
+      },
+    },
+  },
+  {
+    name: 'get_org_areas',
+    description: 'List the org\'s reserved document areas (Goals, Features, ADRs, How it works), ' +
+      'creating any missing ones. Areas are org-scoped (project-less) system folders that ' +
+      'organize cross-project documents — e.g. org-scoped "adr" and "how-it-works" documents ' +
+      'are auto-filed into the ADRs / How it works areas. (E-195)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required)',
+        },
+      },
+      required: ['organizationId'],
+    },
+  },
+];