tapd-mcp 1.0.4 → 1.0.6

package/dist/config-store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Read-only story config sourced from the TAPD_STORY_CONFIG env var.
+ *
+ * The env var holds a JSON document with this shape:
+ *
+ *   {
+ *     "workspaces": {
+ *       "<wsid>": {
+ *         "story_defaults": {
+ *           "<field-label-or-api-name>": "<value>"
+ *         },
+ *         "story_field_rules": {
+ *           "<field-label-or-api-name>": [
+ *             { "match": "题库",                "value": "常规项目/题库" },
+ *             { "match": "课程|财经云",         "value": "常规项目/课程产品" }
+ *           ]
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * As a convenience, callers may also pass the inner WorkspaceConfig directly
+ * (i.e. just `{ "story_defaults": ..., "story_field_rules": ... }`); it will
+ * be applied to every workspace when a per-workspace section is missing.
+ *
+ * `match` is a case-insensitive regex tested against the caller-supplied
+ * `hint` (or, when absent, the story's `name`). First match wins.
+ */
+export interface FieldRule {
+    match: string;
+    value: string;
+}
+export interface WorkspaceConfig {
+    story_defaults?: Record<string, string>;
+    story_field_rules?: Record<string, FieldRule[]>;
+}
+export interface TapdUserConfig {
+    workspaces?: Record<string, WorkspaceConfig>;
+    story_defaults?: Record<string, string>;
+    story_field_rules?: Record<string, FieldRule[]>;
+}
+export declare function getConfigSource(): {
+    env: string;
+    raw: string | undefined;
+};
+export declare function readConfig(): TapdUserConfig;
+export declare function getWorkspaceConfig(config: TapdUserConfig, workspaceId: string): WorkspaceConfig;
+/**
+ * Pick the first matching value from a list of rules.
+ * `match` is treated as a case-insensitive regex. Falls back to literal
+ * substring match if the regex fails to compile.
+ */
+export declare function pickRuleValue(rules: FieldRule[] | undefined, hint: string): string | undefined;
+//# sourceMappingURL=config-store.d.ts.map

package/dist/config-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-store.d.ts","sourceRoot":"","sources":["../src/config-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;CACjD;AAID,wBAAgB,eAAe,IAAI;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAE1E;AAED,wBAAgB,UAAU,IAAI,cAAc,CAS3C;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,cAAc,EACtB,WAAW,EAAE,MAAM,GAClB,eAAe,CAUjB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAY9F"}

package/dist/config-store.js

@@ -0,0 +1,78 @@
+/**
+ * Read-only story config sourced from the TAPD_STORY_CONFIG env var.
+ *
+ * The env var holds a JSON document with this shape:
+ *
+ *   {
+ *     "workspaces": {
+ *       "<wsid>": {
+ *         "story_defaults": {
+ *           "<field-label-or-api-name>": "<value>"
+ *         },
+ *         "story_field_rules": {
+ *           "<field-label-or-api-name>": [
+ *             { "match": "题库",                "value": "常规项目/题库" },
+ *             { "match": "课程|财经云",         "value": "常规项目/课程产品" }
+ *           ]
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * As a convenience, callers may also pass the inner WorkspaceConfig directly
+ * (i.e. just `{ "story_defaults": ..., "story_field_rules": ... }`); it will
+ * be applied to every workspace when a per-workspace section is missing.
+ *
+ * `match` is a case-insensitive regex tested against the caller-supplied
+ * `hint` (or, when absent, the story's `name`). First match wins.
+ */
+const ENV_VAR = 'TAPD_STORY_CONFIG';
+export function getConfigSource() {
+    return { env: ENV_VAR, raw: process.env[ENV_VAR] };
+}
+export function readConfig() {
+    const raw = process.env[ENV_VAR];
+    if (!raw || !raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function getWorkspaceConfig(config, workspaceId) {
+    const ws = config.workspaces?.[workspaceId];
+    if (ws)
+        return ws;
+    if (config.story_defaults || config.story_field_rules) {
+        return {
+            story_defaults: config.story_defaults,
+            story_field_rules: config.story_field_rules,
+        };
+    }
+    return {};
+}
+/**
+ * Pick the first matching value from a list of rules.
+ * `match` is treated as a case-insensitive regex. Falls back to literal
+ * substring match if the regex fails to compile.
+ */
+export function pickRuleValue(rules, hint) {
+    if (!rules || !hint)
+        return undefined;
+    for (const rule of rules) {
+        let matched = false;
+        try {
+            matched = new RegExp(rule.match, 'i').test(hint);
+        }
+        catch {
+            matched = hint.toLowerCase().includes(rule.match.toLowerCase());
+        }
+        if (matched)
+            return rule.value;
+    }
+    return undefined;
+}
+//# sourceMappingURL=config-store.js.map

package/dist/config-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-store.js","sourceRoot":"","sources":["../src/config-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAkBH,MAAM,OAAO,GAAG,mBAAmB,CAAC;AAEpC,MAAM,UAAU,eAAe;IAC7B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;QACjD,OAAO,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,MAAsB,EACtB,WAAmB;IAEnB,MAAM,EAAE,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC,WAAW,CAAC,CAAC;IAC5C,IAAI,EAAE;QAAE,OAAO,EAAE,CAAC;IAClB,IAAI,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC,iBAAiB,EAAE,CAAC;QACtD,OAAO;YACL,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;SAC5C,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAA8B,EAAE,IAAY;IACxE,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IACtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,OAAO;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/fields-cache.d.ts

@@ -0,0 +1,33 @@
+/**
+ * On-disk cache for TAPD field schema (one file per workspace + entity_type).
+ *
+ * Layout: <cacheDir>/fields/<entity_type>/<workspace_id>.json
+ *
+ * cacheDir resolution: TAPD_CACHE_DIR env var → otherwise ~/.tapd-mcp/cache.
+ *
+ * The cache stores whatever the resolver feeds in (typically the parsed
+ * /stories/get_fields_info payload) plus a fetched-at timestamp; reads return
+ * null when the file is missing or unreadable so callers fall back to the API.
+ */
+export interface CachedFields<T = unknown> {
+    workspace_id: string;
+    entity_type: string;
+    fetched_at: string;
+    data: T;
+}
+export declare function getCacheDir(): string;
+export declare function readFieldsCache<T = unknown>(workspaceId: string, entityType?: string): Promise<CachedFields<T> | null>;
+export declare function writeFieldsCache<T = unknown>(workspaceId: string, entityType: string, data: T): Promise<string>;
+/**
+ * Clear cache entries.
+ *   - workspaceId + entityType: remove that single file
+ *   - workspaceId only: remove all entity types for that workspace
+ *   - neither: remove the entire <cacheDir>/fields tree
+ *
+ * Returns the list of paths removed.
+ */
+export declare function clearFieldsCache(options?: {
+    workspaceId?: string;
+    entityType?: string;
+}): Promise<string[]>;
+//# sourceMappingURL=fields-cache.d.ts.map

package/dist/fields-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields-cache.d.ts","sourceRoot":"","sources":["../src/fields-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,CAAC,CAAC;CACT;AAED,wBAAgB,WAAW,IAAI,MAAM,CAIpC;AAMD,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,WAAW,EAAE,MAAM,EACnB,UAAU,SAAU,GACnB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAWjC;AAED,wBAAsB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAChD,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,CAAC,GACN,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,CAAC,EAAE;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA2BpB"}

package/dist/fields-cache.js

@@ -0,0 +1,88 @@
+/**
+ * On-disk cache for TAPD field schema (one file per workspace + entity_type).
+ *
+ * Layout: <cacheDir>/fields/<entity_type>/<workspace_id>.json
+ *
+ * cacheDir resolution: TAPD_CACHE_DIR env var → otherwise ~/.tapd-mcp/cache.
+ *
+ * The cache stores whatever the resolver feeds in (typically the parsed
+ * /stories/get_fields_info payload) plus a fetched-at timestamp; reads return
+ * null when the file is missing or unreadable so callers fall back to the API.
+ */
+import { mkdir, readFile, writeFile, rm, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export function getCacheDir() {
+    const override = process.env.TAPD_CACHE_DIR;
+    if (override && override.trim())
+        return override;
+    return join(homedir(), '.tapd-mcp', 'cache');
+}
+function fileFor(workspaceId, entityType) {
+    return join(getCacheDir(), 'fields', entityType, `${workspaceId}.json`);
+}
+export async function readFieldsCache(workspaceId, entityType = 'story') {
+    const file = fileFor(workspaceId, entityType);
+    if (!existsSync(file))
+        return null;
+    try {
+        const text = await readFile(file, 'utf8');
+        const parsed = JSON.parse(text);
+        if (parsed && parsed.data)
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeFieldsCache(workspaceId, entityType, data) {
+    const file = fileFor(workspaceId, entityType);
+    await mkdir(dirname(file), { recursive: true });
+    const payload = {
+        workspace_id: workspaceId,
+        entity_type: entityType,
+        fetched_at: new Date().toISOString(),
+        data,
+    };
+    await writeFile(file, JSON.stringify(payload, null, 2), 'utf8');
+    return file;
+}
+/**
+ * Clear cache entries.
+ *   - workspaceId + entityType: remove that single file
+ *   - workspaceId only: remove all entity types for that workspace
+ *   - neither: remove the entire <cacheDir>/fields tree
+ *
+ * Returns the list of paths removed.
+ */
+export async function clearFieldsCache(options) {
+    const root = join(getCacheDir(), 'fields');
+    if (!existsSync(root))
+        return [];
+    if (options?.workspaceId && options.entityType) {
+        const file = fileFor(options.workspaceId, options.entityType);
+        if (!existsSync(file))
+            return [];
+        await rm(file);
+        return [file];
+    }
+    if (options?.workspaceId) {
+        const removed = [];
+        const types = await readdir(root, { withFileTypes: true });
+        for (const t of types) {
+            if (!t.isDirectory())
+                continue;
+            const file = join(root, t.name, `${options.workspaceId}.json`);
+            if (existsSync(file)) {
+                await rm(file);
+                removed.push(file);
+            }
+        }
+        return removed;
+    }
+    await rm(root, { recursive: true, force: true });
+    return [root];
+}
+//# sourceMappingURL=fields-cache.js.map

package/dist/fields-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields-cache.js","sourceRoot":"","sources":["../src/fields-cache.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -8,6 +8,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { TapdClient } from './tapd-client.js';
+import { readConfig, getConfigSource, } from './config-store.js';
 const API_TOKEN = process.env.TAPD_API_TOKEN;
 const DEFAULT_WORKSPACE_ID = process.env.TAPD_WORKSPACE_ID;
 const CURRENT_USER = process.env.TAPD_CURRENT_USER;
@@ -109,6 +110,35 @@ const tools = [
             required: ['workspace_id', 'story_id'],
         },
     },
+    {
+        name: 'tapd_set_story_custom_field',
+        description: 'Set a story custom field by user-facing name (e.g. "提测时间") or by API name ' +
+            '(e.g. "custom_field_one"). Resolves the name against the workspace\'s custom-field ' +
+            'definitions before writing, and returns the previous value. ' +
+            '`field` accepts a comma-separated alias list — the first one that resolves wins, ' +
+            'so `field="提测时间,提测日期,TestDate"` covers labels that vary across workspaces. ' +
+            'Pass `refresh=true` after a workspace admin edits the field config to bypass the ' +
+            'on-disk schema cache (~/.tapd-mcp/cache or $TAPD_CACHE_DIR).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace_id: { type: 'string', description: 'Workspace ID' },
+                story_id: { type: 'string', description: 'Story ID (required unless `url` is provided)' },
+                url: { type: 'string', description: 'TAPD story URL (alternative to workspace_id + story_id)' },
+                field: {
+                    type: 'string',
+                    description: 'Field to write — a label like "提测时间" / "TestDate" or an API name like ' +
+                        '"custom_field_one". Comma-separated for fuzzy match; first hit wins.',
+                },
+                value: { type: 'string', description: 'New value to write' },
+                refresh: {
+                    type: 'boolean',
+                    description: 'Drop the field-schema cache for this workspace before resolving (default false).',
+                },
+            },
+            required: ['field', 'value'],
+        },
+    },
     // ==================== Task Tools ====================
     {
         name: 'tapd_get_task',
@@ -511,7 +541,10 @@ const tools = [
     // ==================== Custom Fields Settings Tool ====================
     {
         name: 'tapd_get_custom_fields_settings',
-        description: 'Get custom field schema / definitions for stories (or other entry types) in a workspace. Useful for discovering available custom field names and their types/options before reading or writing custom fields.',
+        description: 'Get custom field schema / definitions for stories (or other entry types) in a workspace. ' +
+            'Useful for discovering available custom field names and their types/options before reading ' +
+            'or writing custom fields. Pass `refresh=true` to drop the on-disk cache before reading ' +
+            '(use after a workspace admin changes labels / adds fields).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -520,11 +553,94 @@ const tools = [
                     type: 'string',
                     description: 'Entry type to query custom fields for. Defaults to "story".',
                 },
+                refresh: {
+                    type: 'boolean',
+                    description: 'Drop the field-schema cache for this workspace + entry_type before reading.',
+                },
             },
             required: ['workspace_id'],
         },
     },
+    // ==================== Per-user config ====================
+    {
+        name: 'tapd_get_config',
+        description: 'Read the story config sourced from the TAPD_STORY_CONFIG environment variable. ' +
+            'Returns the parsed config plus the env var name. ' +
+            'Pass `workspace_id` to scope the response to one workspace.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace_id: { type: 'string', description: 'Optional: only return that workspace section' },
+            },
+        },
+    },
+    {
+        name: 'tapd_apply_story_defaults',
+        description: 'Apply the per-workspace story defaults + matched field rules from $TAPD_STORY_CONFIG ' +
+            'to a single story. Use after tapd_create_story to populate attribution fields ' +
+            '(需求类型 / 项目归属 / 成本归属, etc.) without hard-coding them in the agent. ' +
+            'Caller-supplied `overrides` always win over config; cascade fields are retried on a second pass ' +
+            'so parent/child write order is automatic. Set `dry_run=true` to preview without writing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace_id: { type: 'string', description: 'Workspace ID (falls back to TAPD_WORKSPACE_ID)' },
+                story_id: { type: 'string', description: 'Story ID (required unless `url` is provided)' },
+                url: { type: 'string', description: 'TAPD story URL (alternative to workspace_id + story_id)' },
+                hint: {
+                    type: 'string',
+                    description: 'Text used to evaluate field rules (e.g. "题库后台增加批量导入"). Defaults to the story name when omitted.',
+                },
+                overrides: {
+                    type: 'object',
+                    description: 'Field -> value pairs that override both defaults and rules.',
+                    additionalProperties: { type: 'string' },
+                },
+                dry_run: { type: 'boolean', description: 'Preview the plan without writing' },
+            },
+        },
+    },
+    {
+        name: 'tapd_get_story_changes',
+        description: 'Get the change history of a story (who changed which field, when, old → new value). ' +
+            'Backed by /story_changes. Useful for audit trails and figuring out who flipped a status or ' +
+            'rewrote the description.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace_id: { type: 'string', description: 'Workspace ID' },
+                story_id: { type: 'string', description: 'Story ID' },
+                limit: { type: 'number', description: 'Max results (default 20)' },
+                page: { type: 'number', description: 'Page number (default 1)' },
+            },
+            required: ['story_id'],
+        },
+    },
+    {
+        name: 'tapd_list_workspace_users',
+        description: 'List members of a workspace via /users/get_users_by_workspace_id. ' +
+            'Use this to look up English user ids (the only form TAPD accepts for owner / current_owner / timesheet owner) ' +
+            'when the user only knows a Chinese display name.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace_id: { type: 'string', description: 'Workspace ID (falls back to TAPD_WORKSPACE_ID)' },
+            },
+        },
+    },
     // ==================== Release Tools ====================
+    {
+        name: 'tapd_get_release',
+        description: 'Get details of a specific release by ID',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace_id: { type: 'string', description: 'Workspace ID' },
+                release_id: { type: 'string', description: 'Release ID' },
+            },
+            required: ['release_id'],
+        },
+    },
     {
         name: 'tapd_list_releases',
         description: 'List releases in a workspace',
@@ -700,6 +816,32 @@ async function handleToolCall(name, args) {
                 due: args.due,
             });
         }
+        case 'tapd_set_story_custom_field': {
+            const field = args.field;
+            const value = args.value;
+            if (!field)
+                throw new Error('field is required');
+            if (value === undefined || value === null)
+                throw new Error('value is required');
+            let workspaceId;
+            let storyId;
+            if (args.url) {
+                const parsed = client.parseUrl(args.url);
+                if (!parsed)
+                    throw new Error('Invalid TAPD URL');
+                workspaceId = parsed.workspaceId;
+                storyId = parsed.resourceId;
+            }
+            else {
+                workspaceId = getWorkspaceId(args);
+                storyId = args.story_id;
+                if (!storyId)
+                    throw new Error('story_id (or url) is required');
+            }
+            return await client.setStoryCustomField(workspaceId, storyId, field, value, {
+                refresh: args.refresh === true,
+            });
+        }
         // Task handlers
         case 'tapd_get_task': {
             if (args.url) {
@@ -901,9 +1043,60 @@ async function handleToolCall(name, args) {
         }
         // Custom fields settings handler
         case 'tapd_get_custom_fields_settings': {
-            return await client.getCustomFieldsSettings(getWorkspaceId(args), args.entry_type || 'story');
+            return await client.getCustomFieldsSettings(getWorkspaceId(args), args.entry_type || 'story', { refresh: args.refresh === true });
+        }
+        case 'tapd_get_config': {
+            const config = readConfig();
+            const { env, raw } = getConfigSource();
+            const source = { env, configured: Boolean(raw && raw.trim()) };
+            if (args.workspace_id) {
+                const wsid = args.workspace_id;
+                const ws = config.workspaces?.[wsid] ??
+                    (config.story_defaults || config.story_field_rules
+                        ? {
+                            story_defaults: config.story_defaults,
+                            story_field_rules: config.story_field_rules,
+                        }
+                        : {});
+                return { source, workspace_id: wsid, config: ws };
+            }
+            return { source, config };
+        }
+        case 'tapd_apply_story_defaults': {
+            let workspaceId;
+            let storyId;
+            if (args.url) {
+                const parsed = client.parseUrl(args.url);
+                if (!parsed)
+                    throw new Error('Invalid TAPD URL');
+                workspaceId = parsed.workspaceId;
+                storyId = parsed.resourceId;
+            }
+            else {
+                workspaceId = getWorkspaceId(args);
+                storyId = args.story_id;
+                if (!storyId)
+                    throw new Error('story_id (or url) is required');
+            }
+            return await client.applyStoryDefaults(workspaceId, storyId, {
+                hint: args.hint,
+                overrides: args.overrides ?? undefined,
+                dryRun: args.dry_run === true,
+            });
+        }
+        case 'tapd_get_story_changes': {
+            return await client.getStoryChanges(getWorkspaceId(args), args.story_id, {
+                limit: args.limit,
+                page: args.page,
+            });
+        }
+        case 'tapd_list_workspace_users': {
+            return await client.getWorkspaceUsers(getWorkspaceId(args));
         }
         // Release handlers
+        case 'tapd_get_release': {
+            return await client.getRelease(getWorkspaceId(args), args.release_id);
+        }
         case 'tapd_list_releases': {
             return await client.listReleases(getWorkspaceId(args), {
                 status: args.status,