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;