Asana MCP Server

Exposes asana_create_task and asana_update_task tools that translate MCP tool call requests into Asana REST API mutations, with built-in JSON schema validation for required fields (name, projects, assignee, due_date, custom_fields). The tool-handler layer validates input against Asana's API contract before dispatching to the asana-client-wrapper, which constructs authenticated HTTP requests and handles response transformation into structured JSON for AI clients.

Implements asana_search_tasks tool that queries Asana's search API with optional filters for workspace, project, assignee, and tag. The tool constructs parameterized API requests that leverage Asana's server-side search indexing, returning paginated results with task metadata (gid, name, assignee, due_date, status). Search results are transformed into structured JSON for AI consumption, enabling semantic understanding of task relationships and status.

Implements asana-client-wrapper.ts that encapsulates Asana REST API communication, handling authentication (Bearer token in Authorization header), request construction, error handling, and response transformation. The wrapper abstracts Asana's API details (endpoint URLs, query parameters, pagination) from tool handlers, providing a clean interface for CRUD operations. All requests include the Asana Personal Access Token from environment variables, and responses are transformed into structured JSON for MCP clients.

Implements tool-handler.ts that registers all 22 Asana tools with the MCP server and dispatches incoming tool call requests to appropriate handlers. The handler layer validates tool arguments against JSON schemas, constructs API requests via the asana-client-wrapper, and transforms responses into structured JSON for MCP clients. Tool registration includes metadata (name, description, input schema) that enables Claude to understand tool capabilities and invoke them with correct arguments.

Implements prompt-handler.ts that registers three MCP prompts (task-summary, task-completeness, create-task) with the MCP server. Each prompt includes instructions that guide Claude's reasoning for specific Asana workflows, along with argument schemas for required inputs (task GID, creation parameters). Prompts are returned as structured MCP prompt objects that Claude can discover and invoke, enabling guided workflows without explicit tool calls.

Implements resource-handler.ts that exposes Asana workspaces and projects as MCP resources with URI schemes (asana://workspace/{gid}, asana://project/{gid}). The handler maintains an in-memory cache of resource metadata and returns structured JSON when resources are accessed. This enables AI clients to reference and cache project/workspace data via URIs, reducing repeated API calls and providing a consistent interface for resource navigation.

Exposes asana_get_project and asana_list_sections tools that retrieve project metadata and section hierarchies from Asana, with results accessible via MCP resource URIs (asana://project/{gid}). The resource-handler layer caches project and section data, enabling AI clients to navigate organizational structure without repeated API calls. Section data includes ordering and task counts, supporting agentic workflows that need to understand project layout.

Implements asana_list_workspaces tool that retrieves all workspaces accessible to the authenticated user, returning workspace metadata (gid, name, is_organization) as structured JSON. This tool serves as the entry point for workspace-scoped operations, enabling AI clients to discover available workspaces and resolve workspace identifiers for downstream tool calls. Results are cached via the resource handler for repeated access.

Exposes asana_add_task_dependency and asana_remove_task_dependency tools that manage task blocking relationships (task A blocks task B, or task A depends on task B). These tools translate MCP requests into Asana's dependency API, maintaining task relationship graphs. The implementation validates that both task GIDs exist before creating dependencies, preventing orphaned relationships. Dependency data is returned as structured JSON indicating dependency type (blocks vs depends_on).

Exposes asana_add_task_story (for comments) and asana_get_task_stories tools that manage task activity streams and comments. The add_task_story tool appends comments to task activity threads, while get_task_stories retrieves the full comment history with timestamps and author information. Stories are returned as structured JSON arrays with text, author, and created_at metadata, enabling AI clients to understand task history and context.

Implements asana_add_task_tag and asana_remove_task_tag tools that manage task tags (labels/categories). Tags are applied to tasks for organization and filtering, and the tools validate that tags exist in the workspace before assignment. Tag data is returned as structured JSON with tag gid and name. The search_tasks tool includes optional tag filtering, enabling AI clients to query tasks by tag without manual iteration.

Exposes three MCP prompts (task-summary, task-completeness, create-task) that provide AI-optimized instructions for common Asana workflows. Prompts are templates that guide Claude's reasoning and tool usage for specific tasks: task-summary generates concise task overviews, task-completeness checks if a task has all required fields, and create-task provides step-by-step guidance for task creation. Prompts are registered in the prompt-handler and returned as structured MCP prompt objects with instructions and argument schemas.

Implements environment variable-based access control (READ_ONLY_MODE=true) that gates write operations (create_task, update_task, add_task_story, add_task_tag, add_task_dependency) while preserving read operations (search_tasks, get_project, list_workspaces, get_task_stories). The server initialization checks READ_ONLY_MODE and conditionally registers tool handlers, preventing mutation tools from being exposed to MCP clients. This enables safe, read-only Asana integration for audit, reporting, or preview workflows.

Implements the MCP server using Node.js stdio transport, communicating with MCP clients via JSON-RPC 2.0 protocol over stdin/stdout. The server initialization (src/index.ts) creates an MCP Server instance, registers tool, prompt, and resource handlers, and starts listening for incoming JSON-RPC requests. The transport layer handles message framing, error handling, and response serialization, enabling integration with any MCP-compatible client (Claude Desktop, custom agents, etc.) without additional configuration.