AI Manager - Advanced Project Management System

A sophisticated full-stack web application for AI agent project management with real-time tracking capabilities, structured task management, and seamless integration with Model Context Protocol (MCP) servers.

🚀 Key Features

Core Project Management

Advanced Project Lifecycle: Complete CRUD operations with version tracking
Structured Task Management: JSON-based todo lists with rich metadata support
Real-time Status Tracking: Live project progress monitoring with in_progress/completed states
Directory & Git Integration: Automatic detection of working directory and git branch context
Intelligent Upsert Operations: Smart project creation/update logic based on unique identifiers

AI Agent Integration

MCP Server Integration: Native Model Context Protocol support for AI agent interactions
Public API Endpoints: Authentication-free APIs specifically designed for automated systems
Real-time Notifications: Audio notification system with "ding" endpoint for completion signals
Agent-Friendly Data Structures: Optimized JSON schemas for AI agent consumption

Modern User Experience

Responsive UI: Built with Shadcn/ui components and Tailwind CSS for optimal UX
TypeScript Throughout: Full type safety across frontend and backend interfaces
Real-time Updates: Live project status updates without page refreshes
Progressive Enhancement: Works seamlessly with and without JavaScript

🏗️ Architecture Overview

Backend Stack

Laravel 12.x: Robust PHP framework with advanced ORM capabilities
SQLite/MySQL/PostgreSQL: Multi-database support with native JSON field handling
Eloquent ORM: Advanced query scoping and relationship management
Inertia.js: Server-side rendering with SPA-like user experience
Model Context Protocol: Native MCP server integration for AI agent communication

Frontend Stack

React 19: Latest React with concurrent features and improved performance
TypeScript 5.7: Full type safety with advanced type inference
Shadcn/ui: Premium component library built on Radix UI primitives
Tailwind CSS 4.0: Utility-first styling with advanced design system
Inertia.js React: Seamless server-client communication without API complexity
Web Audio API: Native browser audio notifications for real-time feedback

📦 Installation & Setup

Prerequisites

PHP 8.2+ with extensions: pdo, json, mbstring, tokenizer, xml, ctype
Node.js 18+ with npm or yarn
Composer 2.x for PHP dependency management
Git for version control integration
SQLite/MySQL/PostgreSQL (SQLite included for quick start)

Quick Start

# Clone the repository
git clone [repository-url] ai-manager
cd ai-manager

# Install backend dependencies
composer install

# Install frontend dependencies
npm install

# Environment setup
cp .env.example .env
php artisan key:generate

# Database setup (SQLite - no additional config needed)
touch database/database.sqlite
php artisan migrate

# Build frontend assets
npm run build

# Start development server with all services
composer run dev

Development Environment

The composer run dev command starts multiple services concurrently:

Laravel Server: http://localhost:8000
Queue Worker: Background job processing
Log Monitoring: Real-time log viewing with Pail
Vite Dev Server: Hot module replacement for frontend assets

MCP Server Setup

# Navigate to MCP server directory
cd mcp-server

# Install MCP server dependencies
npm install

# Build the MCP server
npm run build

# Configure Claude Desktop (see mcp-server/README.md for details)

🎯 Usage Guide

Web Interface Usage

Creating Projects

Navigate to /projects in your browser
Click "Nuovo Progetto" (New Project)
Fill in the project form:
- Name: Project identifier (required)
- Directory: Working directory path (auto-detected)
- Git Branch: Current branch (auto-detected)
- Request Description: Detailed project requirements
- Todo List: Structured task list in JSON format
- Status: In Progress / Completed toggle

Advanced Todo List Formats

Simple Format (String Array):

[
  "Setup development environment",
  "Implement user authentication",
  "Create project dashboard",
  "Deploy to production"
]

Advanced Format (Object Array with Metadata):

[
  {
    "title": "Setup development environment",
    "description": "Install dependencies and configure local environment",
    "completed": true,
    "timestamp": "2024-01-15T10:30:00Z",
    "status": "completed",
    "priority": "high",
    "assigned_to": "development_team"
  },
  {
    "title": "Implement user authentication",
    "description": "JWT-based authentication with refresh tokens",
    "completed": false,
    "status": "in_progress",
    "priority": "high",
    "progress": "60%",
    "blockers": ["Waiting for security review"]
  }
]

AI Agent Integration

MCP Tools Usage

// Update or create project via MCP
await mcpTools.project_upsert({
  name: "E-commerce Platform Development",
  todo: [
    {"title": "Database schema design", "completed": true},
    {"title": "API endpoint implementation", "completed": false, "status": "in_progress"}
  ],
  request: "Building scalable e-commerce platform - CURRENTLY: Implementing payment gateway",
  in_progress: true
});

// Send completion notification
await mcpTools.project_ding({message: "Payment gateway integration completed"});

Direct API Usage

# Create/Update project via API (no authentication required)
curl -X POST http://localhost:8000/api/projects/upsert \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Assistant Integration",
    "directory": "/path/to/project",
    "git_branch": "feature/ai-integration",
    "todo": [
      {"title": "Model integration", "completed": true},
      {"title": "Response optimization", "completed": false}
    ],
    "request": "Integrating AI assistant - CURRENTLY: Optimizing response times",
    "in_progress": true
  }'

# Trigger completion notification
curl -X POST http://localhost:8000/api/ding

🔗 API Reference

Public API Endpoints (No Authentication)

Designed for AI agents and automated systems

Method	Endpoint	Description	Status
`POST`	`/api/projects/upsert`	Smart Create/Update - Primary agent endpoint	⭐ Recommended
`POST`	`/api/projects`	Create new project	✅ Available
`PUT`	`/api/projects/{id}`	Update existing project	✅ Available
`DELETE`	`/api/projects/{id}`	Delete project	✅ Available
`POST`	`/api/ding`	Trigger audio notification	🔔 Notification

Web Interface Endpoints (Authentication Required)

For browser-based user interactions

Method	Endpoint	Description	Auth Required
`GET`	`/projects`	List all projects (web view)	✅ Session
`GET`	`/projects/create`	Create project form	✅ Session
`GET`	`/projects/{id}`	Project details view	✅ Session
`GET`	`/projects/{id}/edit`	Edit project form	✅ Session
`POST`	`/projects`	Create project (web)	✅ Session + CSRF
`PUT`	`/projects/{id}`	Update project (web)	✅ Session + CSRF
`DELETE`	`/projects/{id}`	Delete project (web)	✅ Session + CSRF
`POST`	`/ding`	Notification (web)	✅ Session + CSRF

Key API Features

Upsert Logic: The /api/projects/upsert endpoint intelligently creates new projects or updates existing ones based on the project name
Auto-Detection: Directory and git branch information is automatically detected when not provided
JSON Validation: Robust validation for todo list JSON structures with detailed error reporting
No Authentication: Public API endpoints require no authentication for seamless agent integration
Real-time Updates: Changes are immediately reflected in the web interface

📚 Documentation

Core Documentation

Document	Description	Target Audience
Architecture Guide	Sistema architetturale completo, pattern design e flusso dati	Technical Teams, System Architects
API Documentation	Riferimento completo REST API con esempi pratici	Developers, AI Agents
Deployment Guide	Guida completa deployment produzione e configurazione server	DevOps, System Administrators
Development Guide	Setup ambiente sviluppo, testing e workflow contributori	Frontend/Backend Developers
MCP Integration	Configurazione e utilizzo Model Context Protocol per AI agents	AI Developers, Automation Engineers
Security Guide	Documentazione sicurezza, best practices e audit checklist	Security Teams, DevOps
Troubleshooting	Risoluzione problemi comuni e guida diagnostica	All Users, Support Teams

Quick Reference

🌐 Web Interface: http://localhost:8000 (Authentication required)
🔗 API Base URL: http://localhost:8000/api (Public access, no auth)
🤖 MCP Server: Integrated via /mcp-server directory
⚡ Development: composer run dev (starts all services concurrently)
🎯 Primary Use Case: AI agent project tracking and management

Technical Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web Interface │    │   Public APIs   │    │   MCP Server    │
│                 │────│                 │────│                 │
│ • Authentication│    │ • No Auth       │    │ • Local Access │
│ • CRUD Interface│    │ • AI Optimized  │    │ • Claude Desktop│
│ • Real-time UI  │    │ • JSON Schema   │    │ • Tool Registry │
└─────────────────┘    └─────────────────┘    └─────────────────┘

External Resources

Laravel Documentation - Backend framework reference
React Documentation - Frontend library guide
Inertia.js Guide - Full-stack framework documentation
Shadcn/ui Components - UI component library
Model Context Protocol - AI agent integration standard
TypeScript Handbook - Type system reference

🗂️ Project Structure

ai-manager/
├── 🚀 Core Application
│   ├── app/
│   │   ├── Http/Controllers/
│   │   │   └── ProjectController.php      # Main API controller with CRUD + upsert
│   │   ├── Models/
│   │   │   └── Project.php                # Eloquent model with advanced scopes
│   │   └── Providers/
│   │       └── AppServiceProvider.php     # Service container configuration
│   ├── database/
│   │   ├── migrations/
│   │   │   ├── *_create_projects_table.php
│   │   │   └── *_add_directory_git_branch.php
│   │   └── database.sqlite                # SQLite database (development)
│   └── routes/
│       ├── web.php                        # Web interface routes (auth required)
│       └── api.php                        # Public API routes (no auth)
│
├── 🎨 Frontend Application
│   └── resources/js/
│       ├── components/
│       │   ├── project-card.tsx           # Project display component
│       │   ├── project-form.tsx           # Unified create/edit form
│       │   └── ui/                        # Shadcn/ui component library
│       ├── pages/Projects/
│       │   ├── Index.tsx                  # Project listing with search/filter
│       │   ├── Create.tsx                 # Project creation page
│       │   ├── Edit.tsx                   # Project editing page
│       │   └── Show.tsx                   # Project detail view
│       ├── hooks/
│       │   ├── use-ding.tsx              # Audio notification hook
│       │   └── use-mobile.tsx            # Responsive design utilities
│       ├── types/
│       │   └── index.d.ts                # TypeScript type definitions
│       └── layouts/
│           └── app-layout.tsx            # Main application layout
│
├── 🤖 MCP Server Integration
│   └── mcp-server/
│       ├── src/
│       │   └── index.ts                  # MCP server implementation
│       ├── dist/                         # Compiled JavaScript
│       ├── package.json                  # Node.js dependencies
│       └── claude_desktop_config.example.json
│
├── 📖 Documentation
│   ├── README.md                         # This comprehensive guide
│   ├── API_DOCUMENTATION.md              # Complete API reference
│   ├── ARCHITECTURE.md                   # System architecture guide
│   └── MCP_INTEGRATION.md                # MCP setup and usage
│
└── ⚙️ Configuration
    ├── composer.json                     # PHP dependencies and scripts
    ├── package.json                      # Node.js dependencies and scripts
    ├── vite.config.ts                    # Frontend build configuration
    ├── tailwind.config.js               # Tailwind CSS configuration
    └── tsconfig.json                     # TypeScript configuration

🛠️ Development

Development Workflow

Fork & Clone
```
git clone [your-fork-url]
cd ai-manager
```

Environment Setup

composer install
npm install
cp .env.example .env
php artisan key:generate
php artisan migrate

Start Development

composer run dev  # Starts all services concurrently

Testing

php artisan test        # Run PHP tests
npm run test           # Run JavaScript tests  
npm run lint           # Check code style
npm run types          # Verify TypeScript

Contributing Guidelines

Feature Development

git checkout -b feature/descriptive-name
# Make your changes
git commit -m "feat: add descriptive commit message"
git push origin feature/descriptive-name

Code Standards
- Follow PSR-12 for PHP code
- Use ESLint + Prettier for TypeScript/React
- Write comprehensive tests for new features
- Update documentation for API changes
Commit Convention
- feat: New features
- fix: Bug fixes
- docs: Documentation updates
- refactor: Code refactoring
- test: Test additions or updates

🚀 Deployment

Production Setup

# Install dependencies
composer install --no-dev --optimize-autoloader
npm ci

# Build assets
npm run build

# Configure environment
cp .env.example .env
# Edit .env with production settings

# Setup database
php artisan migrate --force

# Optimize Laravel
php artisan config:cache
php artisan route:cache
php artisan view:cache

Environment Variables

# Application
APP_NAME="AI Manager"
APP_ENV=production
APP_URL=https://your-domain.com

# Database
DB_CONNECTION=mysql
DB_DATABASE=ai_manager
DB_USERNAME=your_user
DB_PASSWORD=your_password

# MCP Server
AIMANAGER_API_URL=https://your-domain.com/api

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Laravel Team - Robust PHP framework foundation
React Team - Powerful UI library
Tailwind Labs - Exceptional styling system
Shadcn - Beautiful component library
Anthropic - Model Context Protocol specification
Open Source Community - Continuous inspiration and support

Built with ❤️ using Laravel, React, and TypeScript

Empowering AI agents with intelligent project management

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.claude/agents		.claude/agents
.github/workflows		.github/workflows
app		app
bootstrap		bootstrap
config		config
database		database
mcp-server		mcp-server
public		public
resources		resources
routes		routes
storage		storage
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
AGENT_INSTRUCTIONS.md		AGENT_INSTRUCTIONS.md
AGENT_SYSTEM_PROMPT.md		AGENT_SYSTEM_PROMPT.md
API_DOCUMENTATION.md		API_DOCUMENTATION.md
ARCHITECTURE.md		ARCHITECTURE.md
DEPLOYMENT.md		DEPLOYMENT.md
DEVELOPMENT.md		DEVELOPMENT.md
MCP_INTEGRATION.md		MCP_INTEGRATION.md
README.md		README.md
SECURITY.md		SECURITY.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
artisan		artisan
components.json		components.json
composer.json		composer.json
composer.lock		composer.lock
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
phpunit.xml		phpunit.xml
test_cookies.txt		test_cookies.txt
todo.md		todo.md
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

AI Manager - Advanced Project Management System

🚀 Key Features

Core Project Management

AI Agent Integration

Modern User Experience

🏗️ Architecture Overview

Backend Stack

Frontend Stack

📦 Installation & Setup

Prerequisites

Quick Start

Development Environment

MCP Server Setup

🎯 Usage Guide

Web Interface Usage

Creating Projects

Advanced Todo List Formats

AI Agent Integration

MCP Tools Usage

Direct API Usage

🔗 API Reference

Public API Endpoints (No Authentication)

Web Interface Endpoints (Authentication Required)

Key API Features

📚 Documentation

Core Documentation

Quick Reference

Technical Architecture

External Resources

🗂️ Project Structure

🛠️ Development

Development Workflow

Contributing Guidelines

🚀 Deployment

Production Setup

Environment Variables

📄 License

🙏 Acknowledgments

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages