project-agent-mcp

JasonCoate/project-agent-mcp

3.1

If you are the rightful owner of project-agent-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Project Agent is an AI-powered project management tool that integrates with MCP servers and N8N automation to provide intelligent project steering and task automation.

Tools
5
Resources
0
Prompts
0

Project Agent

AI-powered project management with MCP server integration and N8N automation

A self-hosted project management system that integrates with AI assistants through the Model Context Protocol (MCP). Manage specifications, track progress, and automate workflows locally.

Quick Start

🚀 Recommended Installation

One installation, use for all projects:

  1. Clone and setup:

    git clone <this-repo> ~/tools/project-agent
cd ~/tools/project-agent
./scripts/setup-shared.sh  # Installs dependencies

  2. Start the MCP server:

    cd ~/tools/project-agent/mcp-server
npm run build
npm start  # Keep running in background

  3. Configure your AI assistant to use ~/tools/project-agent/mcp-server

    • See for detailed setup

  4. Create projects anywhere:

    mkdir my-awesome-app && cd my-awesome-app
# Then in your AI assistant:
"Create a new project called 'my-awesome-app' for a React web application"

Alternative: Manual Setup

git clone <this-repo> ~/tools/project-agent
cd ~/tools/project-agent/mcp-server
npm install
npm run build
npm start  # Keep running in background

The agent automatically creates:

  • .specs/ folder with project specifications
  • Feature directories with conventional commit prefixes (e.g., 1-feat-authentication/)
  • Project-specific organization under .specs/project-name/
  • Task lists and workflow phases
  • Progress tracking and checkpoints

📚 Documentation

  • 🚀 - Get running in 5 minutes
  • 📋 - Complete setup options and workflows
  • 💡 - Step-by-step walkthrough
  • 🔄 - Planning-first workflow system with conversational interface
  • 🧠 - Context storage for LLMs
  • 📝 - Quick reference for memory tools
  • 🔗 - Workflow automation
  • 🧪 - Comprehensive testing documentation
  • 📊 - Coverage setup and GitHub integration

Features

  • Enhanced Workflow System - Planning-first approach with conversational tool interactions and real-time progress tracking
  • Project Management - Create and manage projects with specifications and tasks
  • Progress Tracking - Real-time monitoring with plain English summaries and intelligent steering recommendations
  • Task Synchronization - Bidirectional sync between markdown files and database with automated progress updates
  • Conversational Interface - Plain English announcements and formatted output for all MCP tool calls
  • Memory Management - Persistent context storage for LLMs with session continuity and knowledge snapshots
  • MCP Integration - Works with Cursor, Claude Desktop, Continue.dev, and other MCP-compatible tools
  • N8N Automation - Automated workflows for monitoring and notifications
  • Local Deployment - Self-hosted with SQLite database

Documentation

  • - Detailed setup guide
  • - Complete implementation guide
  • - Planning-first workflow system with conversational interface
  • - Context storage for LLMs
  • - Quick reference for memory tools
  • - Installation and configuration
  • - Workflows and examples
  • - Comprehensive testing documentation

Development & Testing

Quick Commands

# Setup and build
npm run setup          # Run setup script
npm run build          # Build TypeScript
npm run build:watch    # Build in watch mode
npm run clean          # Clean build artifacts

# Development
npm start              # Start MCP server
npm run dev            # Start in development mode
npm run start:watch    # Start with auto-restart

# Testing
npm test               # Run basic tests
npm run test:all       # Run all test suites
npm run test:coverage  # Run tests with coverage
npm run test:watch     # Run tests in watch mode
npm run test:unit      # Run unit tests only
npm run test:integration # Run integration tests
npm run test:mcp-tools # Run MCP tools tests
npm run test:mcp-server # Run MCP server tests

# Code Quality
npm run lint           # Run ESLint
npm run lint:check     # Check linting without fixing
npm run format         # Format code with Prettier
npm run format:check   # Check formatting
npm run type-check     # TypeScript type checking

# Documentation
npm run docs:serve     # Serve documentation locally

# Deployment
npm run deploy         # Deploy with Docker
npm run docker:build   # Build Docker image
npm run docker:run     # Run Docker container

Code Coverage

The project includes comprehensive code coverage tracking:

  • GitHub Integration: Automatic coverage reporting on PRs
  • Coverage Services: Codecov and Coveralls integration
  • Coverage Badge: Real-time coverage status
  • HTML Reports: Interactive coverage analysis

See for setup and usage.

Testing Suite

Comprehensive testing organized in the tests/ directory:

# Legacy commands (still supported)
cd tests/mcp-tools && node test-all-tools-comprehensive.js
cd tests/integration && npx ts-node test-comprehensive.ts

See for complete testing documentation.

How It Works

The system provides project context to AI assistants through MCP, enabling them to:

  • Create planning-first workflows with conversational interfaces
  • Track project specifications and requirements with real-time synchronization
  • Monitor task progress with plain English summaries and automated updates
  • Maintain project history and decisions with checkpoint validation
  • Store session context and retrieve relevant information
  • Create knowledge snapshots for complex projects
  • Query project knowledge with natural language
  • Validate specification consistency and phase completion
  • Provide bidirectional sync between markdown files and database

Compatible Tools

  • Cursor AI - MCP integration with project context
  • Claude Desktop - Native MCP server support
  • Continue.dev - VS Code extension with MCP tools
  • Trae IDE - Built-in MCP server integration
  • Gemini CLI - Command-line AI with MCP support
  • Universal CLI Client - Included interface (clients/universal-mcp-client.ts)

N8N Workflows

  • Project Monitor - Automated project health monitoring
  • Progress Tracker - Real-time task progress tracking via webhooks
  • Spec Validator - Specification consistency validation
  • MCP Integration - Direct MCP server tool integration

Architecture

[AI Assistants] ↔ [MCP Server] ↔ [SQLite Database]
                      ↕              ↕
              [N8N Workflows] → [Intelligent Steering]

Components:

  • MCP Server (mcp-server/) - Core project management engine
  • SQLite Database - Project data persistence
  • N8N Workflows (n8n-workflows/) - Automation and monitoring
  • Universal Client (clients/) - Command-line interface

Usage

# Start MCP server
cd mcp-server && npm run build && npm start

# Test with Universal CLI (new terminal)
npm run test:clients

# Or run the integration demo
npm run test:integration

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Test your changes with npm run test:integration
  4. Submit a pull request

License

MIT License - see LICENSE file for details.