Simplete

Modern project management for self-hosted teams — Kanban, timeline, overview, RBAC, and MCP so AI agents can work your board over HTTP.

Built with React 18, TypeScript, Tailwind CSS, Fastify, and MongoDB.

Beta (0.1.0-beta.x) — the portable npx simplete-pms install path is new. APIs and config may still change before 1.0. Feedback and bug reports welcome in Issues.

Features

• Multi-project workspaces — favorites, archive, and quick project switching
• Kanban — drag-and-drop columns, WIP limits, Soft UI cards
• Timeline & Overview — due-date grouping and project health at a glance
• Table & List views — dense sorting and a clean task list
• Rich tasks — priority, tags, assignees, due dates, subtasks, comments, time tracking
• Filters — search, priority, assignee, tags, due date
• Auth & RBAC — owner / admin / member / viewer with permission scopes
• API & MCP tokens — personal access tokens for agents and HTTP clients
• Light & dark themes — semantic design tokens
• Export / import — JSON workspace backups

Views

Tasks (Kanban)

Drag cards across columns, set WIP limits, and open the task modal for details.

Timeline

Tasks grouped by due date for planning and sequencing.

Overview

Counts, completion, pipeline breakdown, and recent tasks.

Quick start

The fastest way to run Simplete: one command, any machine with Node.js 20+, no Docker.

npx simplete-pms@beta --mongodb-uri "mongodb://127.0.0.1:27017/simplete"

That serves the built SPA and the API from a single port. On first run it prompts for the Mongo URI if you omit --mongodb-uri, and persists it (plus a generated cookie secret) so subsequent runs just need npx simplete-pms@beta. Open the printed URL (default http://127.0.0.1:4000) and create the owner account.

Options:
  --mongodb-uri <uri>   MongoDB connection string (persisted after first run)
  --host <host>         Bind address (default: 127.0.0.1)
  --port <port>         Port to listen on (default: 4000)
  --open                Open the app in your default browser once ready

No MongoDB handy? Any free-tier MongoDB Atlas cluster works — just pass its connection string as --mongodb-uri.

Monorepo layout: frontend at the repo root (src/), API in server/.

1. Frontend dependencies

npm install

2. API (separate terminal)

cd server
npm install
cp .env.example .env
# Ensure MongoDB is running, then:
npm run dev

3. Vite app

npm run dev

Open http://localhost:3000. On first visit, create the owner account.

Vite proxies /api, /mcp, /health, /docs, and /openapi.json to http://127.0.0.1:4000.

• Swagger UI: http://localhost:4000/docs
• API notes: docs/api-docs.md

4. Production frontend build

npm run build

5. Build the npx-installable release locally

npm run build:release        # writes ./release
npm pack ./release           # -> simplete-pms-<version>.tgz
npm install -g ./simplete-pms-<version>.tgz
simplete-pms --mongodb-uri "mongodb://127.0.0.1:27017/simplete"

Upgrading from an older version

Password hashing moved from argon2id to node:crypto scrypt (zero native dependencies, so npx simplete-pms works on any machine without a C++ toolchain). This is a hard cut: existing accounts created before this change cannot log in afterwards, since there is no in-place rehash and no forgot-password flow.

To recover, drop the users collection in your MongoDB database (e.g. mongosh <uri> --eval "db.users.drop()"). GET /api/setup/status will report needsSetup: true again, and the app's first-run screen lets you re-create the owner account.

Docker

# From repo root — MongoDB + API on port 4000
docker compose up -d

Serve Vite dist/ with any static host and point it at the API. For local UI against Docker, keep npm run dev with the default proxy.

Connect AI agents via MCP

Simplete exposes a Streamable HTTP MCP server. Agents use one URL plus a personal access token (PAT).

| | | | --- | --- | | Endpoint | http://localhost:4000/mcp (API) or http://localhost:3000/mcp (Vite proxy) | | Transport | Streamable HTTP (POST / GET / DELETE) | | Auth | Authorization: Bearer tok_… | | Server name | simplete-mcp-server |

For production, use your public HTTPS URL and set MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS in server/.env.

Unauthenticated GET /.well-known/oauth-protected-resource returns PAT-only RFC 9728 metadata. Clients still need Authorization: Bearer tok_… — metadata does not replace a PAT.

1. Create a PAT

1. Sign in at http://localhost:3000
2. Open API & MCP tokens (key icon in the icon rail)
3. Create a token with the scopes (and optional project allow-list) you need
4. Copy the raw token once (tok_…) — it is not shown again

Owner / admin / member can manage tokens (token:manage). Effective MCP permissions = role ∩ token scopes.

2. Cursor

Project: .cursor/mcp.json · Global: ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json)

{
  "mcpServers": {
    "simplete": {
      "url": "http://localhost:4000/mcp",
      "headers": {
        "Authorization": "Bearer tok_YOUR_TOKEN_HERE"
      }
    }
  }
}

Prefer env-based secrets:

{
  "mcpServers": {
    "simplete": {
      "url": "http://localhost:4000/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SIMPLETE_PAT}"
      }
    }
  }
}

3. Claude Code

claude mcp add --transport http simplete http://localhost:4000/mcp \
  --header "Authorization: Bearer tok_YOUR_TOKEN_HERE"

Or project .mcp.json (type is required):

{
  "mcpServers": {
    "simplete": {
      "type": "http",
      "url": "http://localhost:4000/mcp",
      "headers": {
        "Authorization": "Bearer ${SIMPLETE_PAT}"
      }
    }
  }
}

4. Claude Desktop / Connectors

Remote MCP needs a reachable HTTPS URL for Claude.ai. For Desktop, bridge with mcp-remote:

{
  "mcpServers": {
    "simplete": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:4000/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer tok_YOUR_TOKEN_HERE"
      }
    }
  }
}

5. Other HTTP MCP clients

URL:     http://localhost:4000/mcp
Header:  Authorization: Bearer tok_…

Works with VS Code Copilot, Windsurf, MCP Inspector (npx @modelcontextprotocol/inspector), and the official SDK Streamable HTTP client. Add "type": "http" when the client requires it.

What agents can do

Tools are prefixed simplete_ (projects, tasks, comments, subtasks, tags, members, standup prompt). Full list: server/README.md.

Project/column/member admin, token CRUD, import, and audit stay on REST (/api/*).

Troubleshooting

| Symptom | Fix | | --- | --- | | 401 Unauthorized | Missing/invalid PAT; use Authorization: Bearer tok_… | | DNS / host errors | Add host to MCP_ALLOWED_HOSTS (and origin to MCP_ALLOWED_ORIGINS) | | Claude.ai cannot reach server | Expose HTTPS; localhost is not reachable from Anthropic cloud | | Claude Code: url but no type | Add "type": "http" | | Tools missing / permission denied | Widen PAT scopes or use a stronger role |

Architecture

Vite React SPA  --session cookie-->  Fastify REST (/api)
AI agents       --Bearer PAT------>  MCP Streamable HTTP (/mcp)
                      |
                 AuthContext + can()
                      |
                 Domain services
                      |
                   MongoDB

| Path | Role | | --- | --- | | src/ | React SPA | | server/ | Fastify API + MCP | | src/services/api.ts | Frontend API client | | src/types/kanban.ts | Shared shapes (wire-compatible with server Zod) | | docs/ | API docs and user stories |

Stack

Frontend: React 18, TypeScript, Vite, Tailwind CSS, @hello-pangea/dnd

Backend: Fastify, MongoDB, node:crypto scrypt password hashing, Streamable HTTP MCP (@modelcontextprotocol/sdk)