mcp-server-asana: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Development Commands

# Build the project (uses esbuild)
npm run build

# Run in development mode with ts-node (requires Node.js 18-22, fails on v24+)
npm run dev

# Start the built server
npm start

# Watch mode for TypeScript compilation
npm run watch

# Test with MCP Inspector UI (opens client on port 5173, server on port 3000)
npm run inspector

# Use custom ports if defaults are taken
CLIENT_PORT=5009 SERVER_PORT=3009 npm run inspector

Node.js Version Requirements

• Node.js 18-22: Required for npm run dev (ts-node ESM loader)
• Node.js 22+: Required for MCP Inspector CLI mode
• Build/Start: Works on all modern Node.js versions

Use nvm to switch versions: nvm use 22

Environment Variables

• ASANA_ACCESS_TOKEN - Required. Your Asana personal access token
• READ_ONLY_MODE - Optional. Set to 'true' to disable all write operations

Architecture

This is an MCP (Model Context Protocol) server that exposes Asana functionality to AI assistants like Claude.

Core Components

• src/index.ts - Entry point. Creates the MCP Server instance, initializes the Asana client, and registers all handlers (tools, prompts, resources)
• src/asana-client-wrapper.ts - Wraps the asana npm package, providing typed methods for all Asana API operations
• src/tool-handler.ts - Defines the list_of_tools array, READ_ONLY_TOOLS array, and the main tool_handler function that routes tool calls to the appropriate Asana client methods
• src/prompt-handler.ts - Defines MCP prompts (task-summary, task-completeness, create-task). Prompts are pre-built conversation starters
• src/resource-handler.ts - Exposes Asana workspaces and projects as MCP resources (readable via asana://workspace/{gid} and asana://project/{gid} URIs)
• src/asana-validate-xml.ts - Validates HTML/XML content for Asana's html_notes and html_text fields