mcp-server-asana

Instructions

Implementation Reference

• src/tool-handler.ts:124-130 (handler)

  Dispatches the tool call by extracting workspace and options, invoking AsanaClientWrapper.searchTasks, and returning JSON response.
  case "asana_search_tasks": { const { workspace, ...searchOpts } = args; const response = await asanaClient.searchTasks(workspace, searchOpts); return { content: [{ type: "text", text: JSON.stringify(response) }], }; }
• src/tools/task-tools.ts:3-242 (schema)

  Defines the Tool object with name, description, and detailed inputSchema for filtering tasks by various criteria including custom fields.
  export const searchTasksTool: Tool = { name: "asana_search_tasks", description: "Search tasks in a workspace with advanced filtering options", inputSchema: { type: "object", properties: { workspace: { type: "string", description: "The workspace to search in" }, text: { type: "string", description: "Text to search for in task names and descriptions" }, resource_subtype: { type: "string", description: "Filter by task subtype (e.g. milestone)" }, "portfolios_any": { type: "string", description: "Comma-separated list of portfolio IDs" }, "assignee_any": { type: "string", description: "Comma-separated list of user IDs" }, "assignee_not": { type: "string", description: "Comma-separated list of user IDs to exclude" }, "projects_any": { type: "string", description: "Comma-separated list of project IDs" }, "projects_not": { type: "string", description: "Comma-separated list of project IDs to exclude" }, "projects_all": { type: "string", description: "Comma-separated list of project IDs that must all match" }, "sections_any": { type: "string", description: "Comma-separated list of section IDs" }, "sections_not": { type: "string", description: "Comma-separated list of section IDs to exclude" }, "sections_all": { type: "string", description: "Comma-separated list of section IDs that must all match" }, "tags_any": { type: "string", description: "Comma-separated list of tag IDs" }, "tags_not": { type: "string", description: "Comma-separated list of tag IDs to exclude" }, "tags_all": { type: "string", description: "Comma-separated list of tag IDs that must all match" }, "teams_any": { type: "string", description: "Comma-separated list of team IDs" }, "followers_not": { type: "string", description: "Comma-separated list of user IDs to exclude" }, "created_by_any": { type: "string", description: "Comma-separated list of user IDs" }, "created_by_not": { type: "string", description: "Comma-separated list of user IDs to exclude" }, "assigned_by_any": { type: "string", description: "Comma-separated list of user IDs" }, "assigned_by_not": { type: "string", description: "Comma-separated list of user IDs to exclude" }, "liked_by_not": { type: "string", description: "Comma-separated list of user IDs to exclude" }, "commented_on_by_not": { type: "string", description: "Comma-separated list of user IDs to exclude" }, "due_on": { type: "string", description: "ISO 8601 date string or null" }, "due_on_before": { type: "string", description: "ISO 8601 date string" }, "due_on_after": { type: "string", description: "ISO 8601 date string" }, "due_at_before": { type: "string", description: "ISO 8601 datetime string" }, "due_at_after": { type: "string", description: "ISO 8601 datetime string" }, "start_on": { type: "string", description: "ISO 8601 date string or null" }, "start_on_before": { type: "string", description: "ISO 8601 date string" }, "start_on_after": { type: "string", description: "ISO 8601 date string" }, "created_on": { type: "string", description: "ISO 8601 date string or null" }, "created_on_before": { type: "string", description: "ISO 8601 date string" }, "created_on_after": { type: "string", description: "ISO 8601 date string" }, "created_at_before": { type: "string", description: "ISO 8601 datetime string" }, "created_at_after": { type: "string", description: "ISO 8601 datetime string" }, "completed_on": { type: "string", description: "ISO 8601 date string or null"}, "completed_on_before": { type: "string", description: "ISO 8601 date string" }, "completed_on_after": { type: "string", description: "ISO 8601 date string" }, "completed_at_before": { type: "string", description: "ISO 8601 datetime string" }, "completed_at_after": { type: "string", description: "ISO 8601 datetime string" }, "modified_on": { type: "string", description: "ISO 8601 date string or null" }, "modified_on_before": { type: "string", description: "ISO 8601 date string" }, "modified_on_after": { type: "string", description: "ISO 8601 date string" }, "modified_at_before": { type: "string", description: "ISO 8601 datetime string" }, "modified_at_after": { type: "string", description: "ISO 8601 datetime string" }, completed: { type: "boolean", description: "Filter for completed tasks" }, is_subtask: { type: "boolean", description: "Filter for subtasks" }, has_attachment: { type: "boolean", description: "Filter for tasks with attachments" }, is_blocked: { type: "boolean", description: "Filter for tasks with incomplete dependencies" }, is_blocking: { type: "boolean", description: "Filter for incomplete tasks with dependents" }, sort_by: { type: "string", description: "Sort by: due_date, created_at, completed_at, likes, modified_at", default: "modified_at" }, sort_ascending: { type: "boolean", description: "Sort in ascending order", default: false }, opt_fields: { type: "string", description: "Comma-separated list of optional fields to include" }, custom_fields: { type: "object", description: `Object containing custom field filters. Keys should be in the format "{gid}.{operation}" where operation can be: - {gid}.is_set: Boolean - For all custom field types, check if value is set - {gid}.value: String|Number|String(enum_option_gid) - Direct value match for Text, Number or Enum fields - {gid}.starts_with: String - For Text fields only, check if value starts with string - {gid}.ends_with: String - For Text fields only, check if value ends with string - {gid}.contains: String - For Text fields only, check if value contains string - {gid}.less_than: Number - For Number fields only, check if value is less than number - {gid}.greater_than: Number - For Number fields only, check if value is greater than number Example: { "12345.value": "high", "67890.contains": "urgent" }` } }, required: ["workspace"] } };
• src/asana-client-wrapper.ts:40-115 (helper)

  Implements task search logic: processes input options into Asana API params, handles custom field filters, invokes SDK searchTasksForWorkspace, transforms custom fields for better readability.
  async searchTasks(workspace: string, searchOpts: any = {}) { // Extract known parameters const { text, resource_subtype, completed, is_subtask, has_attachment, is_blocked, is_blocking, sort_by, sort_ascending, opt_fields, ...otherOpts } = searchOpts; // Build search parameters const searchParams: any = { ...otherOpts // Include any additional filter parameters }; // Handle custom fields if provided if (searchOpts.custom_fields) { if ( typeof searchOpts.custom_fields == "string" ) { try { searchOpts.custom_fields = JSON.parse( searchOpts.custom_fields ); } catch ( err ) { if (err instanceof Error) { err.message = "custom_fields must be a JSON object : " + err.message; } throw err; } } Object.entries(searchOpts.custom_fields).forEach(([key, value]) => { searchParams[`custom_fields.${key}`] = value; }); delete searchParams.custom_fields; // Remove the custom_fields object since we've processed it } // Add optional parameters if provided if (text) searchParams.text = text; if (resource_subtype) searchParams.resource_subtype = resource_subtype; if (completed !== undefined) searchParams.completed = completed; if (is_subtask !== undefined) searchParams.is_subtask = is_subtask; if (has_attachment !== undefined) searchParams.has_attachment = has_attachment; if (is_blocked !== undefined) searchParams.is_blocked = is_blocked; if (is_blocking !== undefined) searchParams.is_blocking = is_blocking; if (sort_by) searchParams.sort_by = sort_by; if (sort_ascending !== undefined) searchParams.sort_ascending = sort_ascending; if (opt_fields) searchParams.opt_fields = opt_fields; const response = await this.tasks.searchTasksForWorkspace(workspace, searchParams); // Transform the response to simplify custom fields if present const transformedData = response.data.map((task: any) => { if (!task.custom_fields) return task; return { ...task, custom_fields: task.custom_fields.reduce((acc: any, field: any) => { const key = `${field.name} (${field.gid})`; let value = field.display_value; // For enum fields with a value, include the enum option GID if (field.type === 'enum' && field.enum_value) { value = `${field.display_value} (${field.enum_value.gid})`; } acc[key] = value; return acc; }, {}) }; }); return transformedData; }
• src/tool-handler.ts:36-87 (registration)

  Registers searchTasksTool in the all_tools array and READ_ONLY_TOOLS list, exports filtered list_of_tools for MCP tool discovery.
  // List of all available tools const all_tools: Tool[] = [ listWorkspacesTool, searchProjectsTool, searchTasksTool, getTaskTool, createTaskTool, getStoriesForTaskTool, updateTaskTool, getProjectTool, getProjectTaskCountsTool, getProjectSectionsTool, createTaskStoryTool, addTaskDependenciesTool, addTaskDependentsTool, createSubtaskTool, getMultipleTasksByGidTool, getProjectStatusTool, getProjectStatusesForProjectTool, createProjectStatusTool, deleteProjectStatusTool, setParentForTaskTool, getTasksForTagTool, getTagsForWorkspaceTool, ]; // List of tools that only read Asana state const READ_ONLY_TOOLS = [ 'asana_list_workspaces', 'asana_search_projects', 'asana_search_tasks', 'asana_get_task', 'asana_get_task_stories', 'asana_get_project', 'asana_get_project_task_counts', 'asana_get_project_status', 'asana_get_project_statuses', 'asana_get_project_sections', 'asana_get_multiple_tasks_by_gid', 'asana_get_tasks_for_tag', 'asana_get_tags_for_workspace' ]; // Filter tools based on READ_ONLY_MODE const isReadOnlyMode = process.env.READ_ONLY_MODE === 'true'; // Export filtered list of tools export const list_of_tools = isReadOnlyMode ? all_tools.filter(tool => READ_ONLY_TOOLS.includes(tool.name)) : all_tools;