Dira — Project Management API

A RESTful API for a Jira-like project management application. Supports boards, workflow statuses (columns), tasks, subtasks, comments, JWT-based authentication, and invite-code board sharing.

Prerequisites

• Node.js v18 or higher
• MongoDB v6 or higher running locally (or a remote URI)

MongoDB must be running before starting the server. By default the app connects to mongodb://localhost:27017/dira.

Getting Started

1. Install dependencies

npm install

2. Configure environment variables

cp .env.example .env

Edit .env and set your values:

3. Start the server

# Development (restarts on file changes)
npm run dev

# Production
npm start

The API will be available at http://localhost:3000/v1.

MCP Server

Dira ships an MCP (Model Context Protocol) server that exposes all 27 API endpoints as tools, letting AI assistants like Claude interact with your boards, tasks, subtasks, and comments directly in the chat.

Starting the MCP server

The REST API must be running before the MCP server starts.

# Terminal 1 — REST API (port 3000)
npm start

# Terminal 2 — MCP server (port 4000)
npm run mcp

# Development mode (restarts on file changes)
npm run mcp:dev

The MCP server listens on http://0.0.0.0:4000 and exposes two endpoints:

MCP environment variables

Connecting from Claude Code

For yourself (local):

claude mcp add dira --transport sse http://localhost:4000/sse

For teammates on the same network — replace the IP with your machine's local IP (e.g. from ifconfig / ipconfig):

claude mcp add dira --transport sse http://192.168.1.x:4000/sse

Verify the server was added:

claude mcp list

Connecting from Claude Desktop

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "dira": {
      "transport": "sse",
      "url": "http://localhost:4000/sse"
    }
  }
}

Restart Claude Desktop after saving.

Available tools

Authentication: all tools except register and login require a token parameter. Use the token returned by either of those tools.

Example conversation with Claude

"Log me in with email jane@example.com and password S3cr3t!pass, then show me all my boards."

Claude will call login first, capture the token, then call list_boards automatically.

Web UI

Dira ships a browser-based Kanban interface built as a vanilla JS SPA served by a lightweight Express BFF (Backend-for-Frontend) that proxies requests to the REST API.

Features

• Login / Register — tab-based auth form with automatic redirect on valid token
• Boards list — grid of your project boards with create and delete actions; each board shows its invite code on hover (click to copy); members see a "member" badge instead of the delete button
• Join a board — "Join Board" button opens a modal where you enter an invite code to gain full access to that board (except deleting it)
• Kanban board — multi-column view with drag-and-drop tasks between status columns, color-coded columns, and task detail modals (title, description, priority, due date, subtasks, comments); the invite code is shown in the navbar for easy sharing

Starting the UI

The REST API must be running first (port 3000).

# Terminal 1 — REST API (if not already running)
npm start

# Terminal 2 — UI / BFF server
cd ui
npm install
npm start        # production
npm run dev      # development (restarts on file changes)

The UI is available at http://localhost:3001.

UI environment variables

UI structure

ui/
├── package.json
├── server.js          # Express BFF — serves static files and proxies API requests
└── public/
    ├── index.html     # Login / Register page
    ├── boards.html    # Boards list page
    ├── board.html     # Kanban board page
    └── js/
        ├── auth.js    # Auth API calls and JWT helpers
        ├── boards.js  # Board CRUD functions
        └── board.js   # Board rendering, drag-and-drop, task management

API Documentation

Interactive Swagger UI is served at:

http://localhost:3000/docs

The spec source is swagger.yaml.

API Overview

Board sharing

Every board has a unique 8-character invite code (e.g. A1B2C3D4). Share it with anyone who has a Dira account — they join by posting the code:

curl -X POST http://localhost:3000/v1/boards/join \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"inviteCode":"A1B2C3D4"}'

Members have full access (create/edit/delete tasks, subtasks, comments, manage columns) except they cannot delete the board itself. The owner can always see and share the invite code from the board header in the UI.

All protected endpoints require an Authorization: Bearer <token> header obtained from POST /v1/auth/login.

Quick example

# Register
curl -X POST http://localhost:3000/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","email":"jane@example.com","password":"S3cr3t!pass"}'

# Login
curl -X POST http://localhost:3000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","password":"S3cr3t!pass"}'

# Create a board (use the token from login)
curl -X POST http://localhost:3000/v1/boards \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"My First Board"}'

Project Structure

dira/
├── swagger.yaml              # OpenAPI 3.0 specification
├── .env.example              # Environment variable template
├── ui/                       # Web UI (BFF + SPA)
│   ├── server.js             # Express BFF — static files + API proxy (port 3001)
│   └── public/               # Vanilla JS SPA
│       ├── index.html        # Login / Register page
│       ├── boards.html       # Boards list page
│       ├── board.html        # Kanban board page
│       └── js/               # Client-side JS modules
└── src/
    ├── server.js             # Entry point — connects to MongoDB and starts Express
    ├── app.js                # Express app setup, routes, Swagger UI
    ├── mcp-server.js         # MCP server (SSE transport, 27 tools)
    ├── models/               # Mongoose schemas
    │   ├── user.model.js
    │   ├── board.model.js
    │   ├── status.model.js
    │   ├── task.model.js
    │   ├── subtask.model.js
    │   └── comment.model.js
    ├── controllers/          # Request handlers and business logic
    │   ├── auth.controller.js
    │   ├── users.controller.js
    │   ├── boards.controller.js
    │   ├── statuses.controller.js
    │   ├── tasks.controller.js
    │   ├── subtasks.controller.js
    │   └── comments.controller.js
    ├── routes/               # Express routers
    │   ├── auth.routes.js
    │   ├── users.routes.js
    │   ├── boards.routes.js
    │   ├── statuses.routes.js
    │   ├── tasks.routes.js
    │   ├── subtasks.routes.js
    │   └── comments.routes.js
    ├── middlewares/
    │   ├── authenticate.js   # JWT guard
    │   ├── validate.js       # Zod request validation
    │   └── errorHandler.js   # Global error handler
    ├── schemas/              # Zod validation schemas (mirror swagger models)
    │   ├── shared.js
    │   ├── auth.schema.js
    │   ├── board.schema.js
    │   ├── status.schema.js
    │   ├── task.schema.js
    │   ├── subtask.schema.js
    │   └── comment.schema.js
    └── utils/
        ├── AppError.js       # Typed HTTP error class
        ├── asyncHandler.js   # Wraps async controllers for Express error forwarding
        └── boardGuard.js     # Checks board existence and ownership

Tech Stack