Task Trellis MCP

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/tools/listObjectsTool.ts:84-239 (handler)

  The primary handler function for the list_objects tool (registered as 'list_issues'). Validates and normalizes input parameters using helper functions, converts them to appropriate enum types, and delegates the listing logic to the TaskTrellisService.listObjects method.
  export async function handleListObjects( service: TaskTrellisService, repository: Repository, args: unknown, ) { const { type, scope, status, priority, includeClosed = false, } = args as { type?: string | string[]; scope?: string; status?: string | string[]; priority?: string | string[]; includeClosed?: boolean; }; // Enhanced helper function to convert type input to enum array const toTypeArray = ( input: string | string[] | undefined, ): TrellisObjectType[] | undefined => { if (!input) return undefined; const values = Array.isArray(input) ? input : [input]; if (values.length === 0) return undefined; const invalidValues: string[] = []; const validValues: TrellisObjectType[] = []; values.forEach((value) => { if ( Object.values(TrellisObjectType).includes(value as TrellisObjectType) ) { validValues.push(value as TrellisObjectType); } else { invalidValues.push(value); } }); if (invalidValues.length > 0) { throw new Error( `Invalid type value${invalidValues.length > 1 ? "s" : ""}: ${invalidValues.join(", ")}`, ); } return validValues; }; // Enhanced helper function to convert status input to enum array const toStatusArray = ( input: string | string[] | undefined, ): TrellisObjectStatus[] | undefined => { if (!input) return undefined; const values = Array.isArray(input) ? input : [input]; if (values.length === 0) return undefined; const invalidValues: string[] = []; const validValues: TrellisObjectStatus[] = []; values.forEach((value) => { if ( Object.values(TrellisObjectStatus).includes( value as TrellisObjectStatus, ) ) { validValues.push(value as TrellisObjectStatus); } else { invalidValues.push(value); } }); if (invalidValues.length > 0) { throw new Error( `Invalid status value${invalidValues.length > 1 ? "s" : ""}: ${invalidValues.join(", ")}`, ); } return validValues; }; // Enhanced helper function to convert priority input to enum array const toPriorityArray = ( input: string | string[] | undefined, ): TrellisObjectPriority[] | undefined => { if (!input) return undefined; const values = Array.isArray(input) ? input : [input]; if (values.length === 0) return undefined; const invalidValues: string[] = []; const validValues: TrellisObjectPriority[] = []; values.forEach((value) => { if ( Object.values(TrellisObjectPriority).includes( value as TrellisObjectPriority, ) ) { validValues.push(value as TrellisObjectPriority); } else { invalidValues.push(value); } }); if (invalidValues.length > 0) { throw new Error( `Invalid priority value${invalidValues.length > 1 ? "s" : ""}: ${invalidValues.join(", ")}`, ); } return validValues; }; try { // Convert inputs to enum arrays using enhanced helper functions const typeEnums = toTypeArray(type); const statusEnums = toStatusArray(status); const priorityEnums = toPriorityArray(priority); // Convert arrays back to single values or keep as arrays based on service signature const typeParam = typeEnums ? typeEnums.length === 1 ? typeEnums[0] : typeEnums : undefined; const statusParam = statusEnums ? statusEnums.length === 1 ? statusEnums[0] : statusEnums : undefined; const priorityParam = priorityEnums ? priorityEnums.length === 1 ? priorityEnums[0] : priorityEnums : undefined; // Delegate to service return await service.listObjects( repository, typeParam, scope, statusParam, priorityParam, includeClosed, ); } catch (error) { return { content: [ { type: "text", text: `Error listing objects: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } }
• src/tools/listObjectsTool.ts:9-82 (schema)

  Tool specification including the name 'list_issues', detailed description, and input schema defining parameters for filtering objects by type, scope, status, priority, and includeClosed.
  export const listObjectsTool = { name: "list_issues", description: `Lists issues from the task trellis system Use this tool to retrieve and filter issues based on various criteria. Essential for discovering existing work items, understanding project structure, and finding issues that need attention. Available issue types: - 'project': Top-level containers - 'epic': Large features within projects - 'feature': Specific functionality within epics - 'task': Individual work items Available status values: - 'draft': Initial state for new issues - 'open': Ready to begin work (default for new issues) - 'in-progress': Currently being worked on - 'done': Completed successfully - 'wont-do': Cancelled or decided against Available priority values: - 'high': Critical or urgent work - 'medium': Standard priority - 'low': Nice-to-have or future work Key filtering options: - 'type': Filter by issue category (project, epic, feature, task) - accepts single value or array - 'scope': Limit results to a specific project or area of work - 'status': Find issues in particular states (draft, open, in-progress, done, wont-do) - accepts single value or array - 'priority': Filter by importance level (high, medium, low) - accepts single value or array - 'includeClosed': Whether to show completed/archived issues (defaults to false) Usage patterns: - List all tasks in progress: type='task', status='in-progress' - Find high priority work: priority='high', includeClosed=false - Review project scope: type='project', scope='specific-project' - Audit completed work: includeClosed=true, status='done' - Find cancelled items: status='wont-do', includeClosed=true - List features and tasks: type=['feature', 'task'] - List all open objects: status='open' (no type filter) - Multiple statuses: status=['open', 'in-progress'] - Multiple priorities: priority=['high', 'medium'] The results provide issue summaries (TrellisObjectSummary instances) containing id, type, title, status, priority, parent, prerequisites, childrenIds, created, and updated fields to enable efficient filtering and further operations.`, inputSchema: { type: "object", properties: { type: { type: ["string", "array"], items: { type: "string" }, description: "Type of issues to list (optional)", }, scope: { type: "string", description: "Scope to filter issues (optional)", }, status: { type: ["string", "array"], items: { type: "string" }, description: "Status to filter issues (optional)", }, priority: { type: ["string", "array"], items: { type: "string" }, description: "Priority to filter issues (optional)", }, includeClosed: { type: "boolean", description: "Include closed issues (defaults to false)", default: false, }, }, required: [], }, } as const;
• src/server.ts:176-197 (registration)

  Registers listObjectsTool in the ListToolsRequest handler, making it discoverable by MCP clients.
  server.setRequestHandler(ListToolsRequestSchema, () => { const tools: unknown[] = [ createObjectTool, updateObjectTool, getObjectTool, deleteObjectTool, listObjectsTool, appendObjectLogTool, appendModifiedFilesTool, claimTaskTool, getNextAvailableIssueTool, completeTaskTool, ]; // Only include activate tool if server is not properly configured from command line // (i.e., local mode without projectRootFolder specified) if (serverConfig.mode === "local" && !serverConfig.planningRootFolder) { tools.push(activateTool); } return { tools }; });
• src/server.ts:265-265 (registration)

  Dispatches calls to the 'list_issues' tool to the handleListObjects function in the CallToolRequest handler.
  return handleListObjects(_getService(), repository, args);
• src/services/local/listObjects.ts:30-73 (helper)

  Core helper function implementing the object listing logic: normalizes filters, retrieves objects from repository, converts to summaries, and formats as JSON response.
  export async function listObjects( repository: Repository, type?: TrellisObjectType | TrellisObjectType[], scope?: string, status?: TrellisObjectStatus | TrellisObjectStatus[], priority?: TrellisObjectPriority | TrellisObjectPriority[], includeClosed: boolean = false, ): Promise<{ content: Array<{ type: string; text: string }> }> { try { // Normalize inputs to arrays const normalizedType = normalizeEnumInput(type); const normalizedStatus = normalizeEnumInput(status); const normalizedPriority = normalizeEnumInput(priority); // Get objects from repository const objects = await repository.getObjects( includeClosed, scope, normalizedType, normalizedStatus, normalizedPriority, ); const objectSummaries = objects.map(convertToSummary); return { content: [ { type: "text", text: JSON.stringify(objectSummaries, null, 2), }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error listing objects: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } }