Projexus

A comprehensive multi-user TODO management system built as an MCP (Model Context Protocol) server with GitHub OAuth authentication. Features collaborative project management, time tracking, markdown import, and complete audit trails.

🚀 Features

🔐 Multi-User Authentication

• GitHub OAuth Integration: Secure authentication via GitHub
• User Management: Invite users by GitHub username
• Session Management: 30-day secure session tokens
• Project Switching: Users can switch between projects

📁 Project Management

• Shared Projects: All users can see and access all projects
• Active Project Context: Each user has an active project for TODO operations
• Project Creation: Create and manage multiple projects
• Collaborative Workflow: Team-based TODO management

✅ Rich TODO Management

• Full CRUD Operations: Create, read, update, delete TODOs
• Priority System: P1 (highest) to P5 (lowest)
• Status Tracking: Pending, active, completed, cancelled
• Time Tracking: Start/stop work sessions with automatic calculation
• Complete History: Full audit trail of all changes

📝 Advanced Features

• Markdown Import: Import structured TODOs with dependency detection
• Search & Filter: Find TODOs across projects
• Statistics: Project and user analytics
• Dependencies: Automatic parent-child relationships from indentation

🛠️ Installation & Setup

Prerequisites

• Node.js 18+
• npm or yarn
• GitHub account
• Claude Desktop (for MCP integration)

1. Clone & Install

git clone <repository-url>
cd projexus
npm install

2. GitHub OAuth Setup

The GitHub OAuth app is already configured with these credentials:

• Client ID: Ov23li6CyILKNqODPHoe
• Client Secret: f2e8d7adeab3ebe756004f19f357b307e059586a
• Callback URL: https://home.j3-enterprises.com:3001/auth/github/callback

3. Environment Configuration

# Copy the development environment file
cp .env.development .env

# Or create your own .env with:
GITHUB_CLIENT_ID=Ov23li6CyILKNqODPHoe
GITHUB_CLIENT_SECRET=f2e8d7adeab3ebe756004f19f357b307e059586a
BASE_URL=https://home.j3-enterprises.com
DEV_PORT=3001
NODE_ENV=development

4. Start the Server

# Development mode (includes OAuth server)
NODE_ENV=development npm run dev

# Production mode
npm run build
npm start

🔧 Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "projexus": {
      "command": "node",
      "args": ["/absolute/path/to/projexus/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

🤖 Claude Code MCP Integration

Projexus integrates seamlessly with Claude Code as an MCP server, allowing you to manage your TODOs directly through AI conversations.

Setup Instructions

1. Generate an API Key

   # First, authenticate with Projexus
   projexus auth login
   
   # Generate an API key for Claude Code
   projexus api-key generate "Claude Code Integration"

   Save the generated API key (starts with pjx_).

2. Configure Claude Code Create or update your .mcp.json file in your project root:

   {
     "mcpServers": {
       "projexus": {
         "command": "npx",
         "args": ["-y", "projexus@latest"],
         "env": {
           "PROJEXUS_API_KEY": "your_api_key_here"
         }
       }
     }
   }

3. Start Using Projexus in Claude Code You can now use natural language to manage your TODOs:

   "Add a new task to implement user authentication"
   "Show me my current TODOs"
   "Create a new project called 'Website Redesign'"
   "Mark task #5 as complete"

Available Commands in Claude Code

All standard Projexus CLI commands work through Claude Code:

• Project Management: projexus projects, projexus project create "name", projexus project switch "name"
• TODO Management: projexus add "task", projexus list, projexus done <id>
• Organization: projexus orgs, projexus org create "name"
• Collaboration: projexus invite <username>, projexus stats

Benefits of Claude Code Integration

• 🤖 Natural Language Interface: Describe what you want in plain English
• 🔄 Real-time Sync: All changes sync with the remote Projexus server
• 👥 Team Collaboration: Share projects and TODOs with your team
• 📊 Context Aware: Claude can help prioritize and organize your tasks
• 🔒 Secure: API key authentication ensures your data stays private

🌐 Claude.ai Web Integration

You can also use Projexus directly with Claude.ai through our HTTP MCP server for web-based todo management.

Setup Instructions

1. Generate an API Key (if you haven't already)

   # First, authenticate with Projexus
   projexus auth login
   
   # Generate an API key for Claude.ai
   projexus api-key generate "Claude.ai Integration"

   Save the generated API key (starts with pjx_).

2. Get the MCP Server URL Our HTTP MCP server is running at: https://app.projexus.dev/mcp

3. Add to Claude.ai

   • Go to Claude.ai in your browser
   • Open Settings → Connectors
   • Click "Add custom connector"
   • Add your MCP server with:
     • Name: Projexus
     • URL: https://app.projexus.dev/mcp
     • API Key: Your generated API key (starts with pjx_)
   • The server uses GitHub OAuth for authentication

4. Start Using Projexus You can now chat with Claude.ai and manage your TODOs:

   "Show me my current projects in Projexus"
   "Add a new todo to implement user authentication"
   "Create a project called 'Mobile App Development'"
   "What are my top priority tasks?"

Available Features via Claude.ai

• 📋 TODO Management: Create, list, update, and complete tasks
• 📁 Project Organization: Create and switch between projects
• 👥 Team Collaboration: Invite users and manage organizations
• 📊 Analytics: View project statistics and progress
• 🔍 Smart Search: Find tasks across all projects
• ⏱️ Time Tracking: Start/stop work sessions on tasks

Example Claude.ai Conversations

You: "Show me my Projexus projects"
Claude: I'll check your Projexus projects for you...
[Lists your projects with details]

You: "Add a high priority task to implement user authentication"
Claude: I'll add that task to your current project...
[Creates the task and confirms]

You: "What tasks am I currently working on?"
Claude: Let me check your active tasks...
[Shows tasks with status and time tracking]

🎯 Getting Started

🚀 Super Quick Start (Automatic)

# One command to do everything!
npx tsx px-auth.js

This script automatically:

• ✅ Starts the OAuth server
• ✅ Opens your browser for GitHub authentication
• ✅ Saves your token securely (encrypted)
• ✅ Sets up shell aliases
• ✅ No copy/paste needed!

Step 1: Authenticate (Manual Method)

# Alternative: Manual authentication
auth_github --action=get_url

# Visit the URL, complete OAuth, copy your session token

Step 2: Project Management

# List all projects
project_list --session_token=YOUR_TOKEN

# Create a new project
project_create --name="My Project" --description="Project description" --session_token=YOUR_TOKEN

# Switch to a project
project_switch --project_name="My Project" --session_token=YOUR_TOKEN

Step 3: TODO Management

# Add a TODO (to your active project)
todo --task="Build authentication system" --priority=1 --session_token=YOUR_TOKEN

# Mark complete
done --id=1 --notes="Implemented OAuth flow" --session_token=YOUR_TOKEN

# Import from markdown
import --file="./imports/project-plan.md" --session_token=YOUR_TOKEN

Step 4: Team Collaboration

# Invite team members
user_invite --github_username="teammate" --session_token=YOUR_TOKEN

# List all users
user_list --session_token=YOUR_TOKEN

# View project statistics
stats --project="My Project" --session_token=YOUR_TOKEN

📋 Available MCP Tools

Authentication & User Management

• auth_github - Authenticate with GitHub OAuth
• user_invite - Invite users by GitHub username
• user_list - List all system users

Project Management

• project_create - Create new project
• project_list - List all projects
• project_switch - Switch active project

TODO Operations

• todo - Quick add TODO
• done - Mark TODO complete
• todo_update - Update TODO details
• todo_detail - Add descriptions/notes
• start / stop - Time tracking
• search - Search TODOs
• stats - Project statistics
• history - View change history
• import - Import from markdown

📝 Markdown Import Format

Import structured TODOs with this format:

# Project Name

- [ ] Epic task [P1] (8h) #backend @john
  High-level description of the epic

  - [ ] Subtask 1 [P2] (2h) #database
    Database schema design

  - [ ] Subtask 2 [P3] (4h) #api
    REST API implementation

- [x] Completed task [P1] (3h) #frontend
  This task is already done

Format Guide:

• [P1-P5] - Priority (1=highest, 5=lowest)
• (2h) - Estimated hours
• #tag - Tags for categorization
• @mention - User mentions
• Indentation creates dependencies
• [x] vs [ ] - Completed vs pending

🏗️ Architecture

Database Schema

• users - GitHub user profiles and active projects
• projects - Project definitions and metadata
• user_sessions - Authentication session management
• todos - Main TODO data with user ownership
• todo_history - Complete audit trail
• tags - Tag relationships
• dependencies - Parent-child task relationships
• work_sessions - Time tracking data

Multi-User Flow

1. User authenticates via GitHub OAuth
2. Session token provided for API access
3. User switches to active project
4. All TODO operations scoped to active project
5. Projects visible to all users (collaborative)

🚀 Deployment

Development

NODE_ENV=development npm run dev
# OAuth server: https://home.j3-enterprises.com:3001
# MCP server: stdio connection

Production (Civo)

# Build and start
npm run build
NODE_ENV=production npm start

# Configure environment variables:
# GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, BASE_URL

🤝 Team Workflow Example

Project Setup

# Admin creates project
project_create --name="Mobile App" --description="iOS/Android app development"

# Team members authenticate and switch to project
auth_github --action=get_url
project_switch --project_name="Mobile App"

Sprint Planning

# Import sprint backlog
import --file="./sprints/sprint-1.md"

# Assign and start work
todo_update --id=5 --assigned_to="developer1"
start --id=5

Daily Standup

# Check team progress
stats --project="Mobile App"
search --query="status:active"
history --todo_id=5

📚 Examples

Complete Project Setup

# 1. Authenticate
auth_github --action=get_url
# -> Visit URL, get token: abc123...

# 2. Create project
project_create --name="E-commerce Site" --session_token=abc123

# 3. Import initial tasks
import --file="./project-plan.md" --session_token=abc123

# 4. Start working
todo --task="Setup development environment" --priority=1 --session_token=abc123
start --id=1 --session_token=abc123

Team Collaboration

# Invite team
user_invite --github_username="frontend-dev" --session_token=abc123
user_invite --github_username="backend-dev" --session_token=abc123

# Check team status
user_list --session_token=abc123
stats --session_token=abc123

Markdown Import Example

# E-commerce Site

- [ ] Frontend Development [P1] (40h) #frontend @frontend-dev
  Build the user-facing application

  - [ ] Setup React project [P2] (4h) #setup
  - [ ] Design system components [P2] (12h) #design
  - [ ] Product catalog [P1] (16h) #products
  - [ ] Shopping cart [P1] (8h) #cart

- [ ] Backend API [P1] (32h) #backend @backend-dev
  REST API and database

  - [ ] Database schema [P1] (8h) #database
  - [ ] User authentication [P1] (12h) #auth
  - [ ] Product endpoints [P2] (12h) #api

🔧 Development

Local Development

npm run dev     # Watch mode with auto-reload
npm run build   # TypeScript compilation
npm run start   # Production mode

Database Management

# Database location: ./data/todos.db
# Fresh start: rm -f data/todos.db
# Backup: cp data/todos.db data/backup-$(date +%Y%m%d).db

🚀 Deployment

Quick Start

1. Environment Setup:

   cp .env.example .env.production
   # Edit .env.production with your actual values

2. Docker Deployment:

   docker-compose up -d

3. Kubernetes Deployment:

   # Apply configurations
   kubectl apply -f k8s/
   
   # Check deployment status
   kubectl get pods -n projexus

Documentation

• 📋 DEPLOYMENT_CHECKLIST.md - Complete production deployment guide
• 🌊 civo-deployment.md - Civo Kubernetes deployment
• 🛠️ INSTALLATION.md - Local installation guide

Environment Configuration

See .env.example for all available environment variables:

• GitHub OAuth: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
• Server: BASE_URL, PORT, NODE_ENV
• Security: JWT_SECRET, ENCRYPTION_KEY

Built with ❤️ for collaborative TODO management GitHub OAuth • Multi-User • Real-time Collaboration • MCP Integration