@microagents/server-asana/README.md

MCP server for Asana API integration

# Asana MCP Server

This MCP server allows AI systems to interact with the Asana API. This package is based on the original [Asana MCP Server](https://github.com/roychri/mcp-server-asana) project by Christian Roy, adapted to work with the MicroAgents ecosystem.

## Features

- Create, update, and manage tasks
- Work with projects and workspaces
- Add comments and attachments
- Search and filter tasks
- Create and manage subtasks
- Work with tags and custom fields
- Set task dependencies
- Create project status updates

## Setup

1. Create an Asana account if you don't have one
2. Generate a Personal Access Token from the Asana developer console:
   - Visit [https://app.asana.com/0/my-apps](https://app.asana.com/0/my-apps)
   - Follow the instructions to create a Personal Access Token
3. Set up your environment variables:
   ```bash
   export ASANA_ACCESS_TOKEN=your_personal_access_token
   ```

## Installation

```bash
npm install @microagents/server-asana
```

## Tools

The server provides numerous tools to interact with Asana:

1. `asana_list_workspaces`
   * List all available workspaces in Asana
   * Optional input:
      * opt_fields (string): Comma-separated list of optional fields to include
   * Returns: List of workspaces

2. `asana_search_projects`
   * Search for projects in Asana using name pattern matching
   * Required input:
      * workspace (string): The workspace to search in
      * name_pattern (string): Regular expression pattern to match project names
   * Optional input:
      * archived (boolean): Only return archived projects (default: false)
      * opt_fields (string): Comma-separated list of optional fields to include
   * Returns: List of matching projects

3. `asana_search_tasks`
   * Search tasks in a workspace with advanced filtering options
   * Required input:
      * workspace (string): The workspace to search in
   * Optional input:
      * text (string): Text to search for in task names and descriptions
      * resource_subtype (string): Filter by task subtype (e.g. milestone)
      * completed (boolean): Filter for completed tasks
      * is_subtask (boolean): Filter for subtasks
      * has_attachment (boolean): Filter for tasks with attachments
      * is_blocked (boolean): Filter for tasks with incomplete dependencies
      * is_blocking (boolean): Filter for incomplete tasks with dependents
      * assignee, projects, sections, tags, teams, and many other advanced filters
      * sort_by (string): Sort by due_date, created_at, completed_at, likes, modified_at (default: modified_at)
      * sort_ascending (boolean): Sort in ascending order (default: false)
      * opt_fields (string): Comma-separated list of optional fields to include
      * custom_fields (object): Object containing custom field filters
   * Returns: List of matching tasks

4. `asana_get_task`
   * Get detailed information about a specific task
   * Required input:
      * task_id (string): The task ID to retrieve
   * Optional input:
      * opt_fields (string): Comma-separated list of optional fields to include
   * Returns: Detailed task information

5. `asana_create_task`
   * Create a new task in a project
   * Required input:
      * project_id (string): The project to create the task in
      * name (string): Name of the task
   * Optional input:
      * notes (string): Description of the task
      * html_notes (string): HTML-like formatted description of the task
      * due_on (string): Due date in YYYY-MM-DD format
      * assignee (string): Assignee (can be 'me' or a user ID)
      * followers (array of strings): Array of user IDs to add as followers
      * parent (string): The parent task ID to set this task under
      * projects (array of strings): Array of project IDs to add this task to
      * resource_subtype (string): The type of the task (default_task or milestone)
      * custom_fields (object): Object mapping custom field GID strings to their values
   * Returns: Created task information

And many more tools for managing tasks, projects, comments, and other Asana resources.

## Example

```typescript
// Get current user information
const meResult = await mcp.callTool("asana_get_me");

// List all workspaces
const workspacesResult = await mcp.callTool("asana_list_workspaces");

// Create a new task
const taskResult = await mcp.callTool("asana_create_task", {
  project_id: "1234567890",
  name: "Implement new feature",
  notes: "This task involves implementing the new feature as discussed in the planning meeting."
});
```

## Development

```bash
npm install
npm run build
npm start
```

## Credits

This package is based on the original [Asana MCP Server](https://github.com/roychri/mcp-server-asana) project by Christian Roy. We've adapted it to work with the MicroAgents ecosystem while maintaining the comprehensive functionality of the original project.

## License

MIT