Asana Connector

Project management integration console · DOO Builders League

Builder: Idrees Khaled · Provider: Asana · Version: v1.0.0

A production-oriented Asana connector: a reusable connector core with five typed actions, normalized errors, pagination and rate-limit handling, a thin MCP adapter, and a dark-first developer console over the top.

Quickstart

Runs with no credentials and no configuration. A fresh clone boots into clearly-labelled demo mode, so you can review the whole surface immediately.

git clone https://github.com/Idrees-02/doo-asana-connector.git
cd doo-asana-connector
npm install
npm run dev

• Console → http://localhost:5173

• API → http://localhost:8787

Requires Node ≥ 20.19 and nothing else. No Docker, no global installs, no hosted services.

Reviewing the engineering rather than the UI

npm test              # connector suite: all five actions, errors, pagination, rate limits
npm run test:frontend # console tests
npm run verify        # typecheck + lint + secret scan + tests
npm run mcp           # MCP server over stdio

Related MCP server: Asana MCP Server

The five actions

These IDs are fixed by the assignment and are used verbatim throughout the manifest, schemas, OpenAPI spec, MCP tools and console.

There is deliberately no delete action — it is not part of the assignment, and the connector never requests a :delete OAuth scope.

Getting your Asana credentials

Never paste a token into a chat window, an issue, a screenshot, or any file that git tracks. It goes into .env on your machine and nowhere else. .env is gitignored, and a pre-commit hook blocks it even if that is bypassed.

Option A — Personal Access Token (recommended to start)

A PAT is the quickest path and is all you need for local review.

1. Sign in at https://app.asana.com — a free account is enough.

2. Open https://app.asana.com/0/my-apps (or: profile photo → My Settings → Apps → Manage Developer Apps).

3. Click Create new token.

4. Name it something identifiable, e.g. doo-asana-connector-dev.

5. Accept the API terms, then click Create token.

6. Copy it immediately — Asana shows it exactly once.

7. Run the setup command and paste it when prompted:

   npm run setup

   Input is hidden while you type, so the token never appears on screen, in a screen recording, or in your shell history. It is written to .env with permissions 0600 and verified against Asana immediately — without ever being displayed back to you.

   Prefer doing it by hand? cp .env.example .env, then edit the ASANA_ACCESS_TOKEN= line in your editor.

8. Restart npm run dev. The amber DEMO MODE banner disappears and Settings → Test Connection shows your real account and workspaces.

.env.example is tracked by git and is public. Only ever put placeholders there. Real values belong in .env, which is gitignored.

Tip: actions performed through a PAT are attributed to you in Asana's activity feed. For a shared or demo setup, create a dedicated bot user and generate the PAT from that account instead.

Option B — OAuth 2.0 (multi-user)

Needed only if you want the browser-based connect flow rather than a pre-shared token.

1. Same page: https://app.asana.com/0/my-apps → Create new app.

2. Name the app and accept the terms.

3. Under OAuth, add this exact redirect URL:

   http://localhost:8787/api/auth/oauth/callback

4. Copy the Client ID and Client Secret into .env:

   ASANA_OAUTH_CLIENT_ID=...
   ASANA_OAUTH_CLIENT_SECRET=...
   ASANA_OAUTH_REDIRECT_URI=http://localhost:8787/api/auth/oauth/callback

5. Restart, then use Settings → Connect with Asana.

Scopes requested (least privilege — nothing more than the five actions need):

projects:read  tasks:read  tasks:write  stories:write  users:read  workspaces:read

Recommended: a sandbox workspace

Before running any write action, create a throwaway project (e.g. Connector Sandbox) and point the connector at it. Write tests then never touch anything that matters. The connector never deletes anything, but it does create tasks and comments.

Secrets policy

Every credential lives in .env and nowhere else. This is enforced mechanically, not by convention:

• src/config.ts is the only module permitted to read process.env. An ESLint rule (no-restricted-properties) fails the build if anything else touches it, so credentials cannot spread through the codebase.

• describeConfig() is the only way config reaches a log, an API response or the UI, and its return type has no field capable of carrying a secret value — presence booleans and an opaque fingerprint only.

• npm run secrets:scan pattern-scans tracked files (Asana PAT format, bearer tokens, private keys, credential-shaped assignments) and runs in CI.

• A pre-commit hook blocks staged .env files outright and re-scans staged content.

• The test suite requires no credentials, so CI runs with no secrets configured at all.

Configuration

All configuration is environment-driven (12-factor), so the same build runs locally and deployed with nothing changed but the environment. See .env.example for every variable with inline documentation.

ASANA_MODE=live without credentials fails at startup on purpose — silently serving synthetic data to someone who asked for real data would be the worst possible failure mode.

Project structure

doo-asana-connector/
├── connector.yaml          # generated manifest
├── openapi.yaml            # generated from the same Zod schemas
├── src/
│   ├── connector.ts        # DooConnector: manifest, testConnection, listActions, execute
│   ├── client.ts           # Asana HTTP client: pagination, throttle, retry classification
│   ├── config.ts           # the only reader of process.env
│   ├── auth/               # PAT + OAuth 2.0
│   ├── actions/            # the five actions
│   ├── schemas/            # Zod schemas — single source of truth
│   ├── errors/             # normalized error system
│   ├── runtime/            # shared execution pipeline
│   └── demo/               # demo provider
├── mcp/server.ts           # thin MCP adapter
├── server/                 # HTTP API consumed by the console
├── frontend/               # the console
├── tests/ · fixtures/ · examples/ · docs/
└── .env.example

Documentation

In-app documentation is also available at /docs in the running console.

MCP

npm run mcp           # stdio — Claude Desktop, MCP Inspector
npm run mcp:inspect   # interactive tool explorer

Claude Desktop (claude_desktop_config.json), replacing the path with this project's absolute location:

{
  "mcpServers": {
    "asana-connector": {
      "command": "npx",
      "args": ["tsx", "/ABSOLUTE/PATH/TO/doo-asana-connector/mcp/server.ts"]
    }
  }
}

The adapter iterates connector.listActions() and registers each as a tool. It contains no Asana endpoint, no schema and no business logic — a test asserts the exposed tool ids equal the connector's action ids, so it cannot drift.

Assignment checklist

Marked honestly. Anything not demonstrated is called out rather than assumed.

The remaining gap is the HTTPS MCP endpoint, which is not met by design (local-first). See docs/LIMITATIONS.md.

Scripts

License

MIT