Project Nexus v2

Transform workflows with AI-powered reliability. Enterprise-grade workflow orchestration powered by Apache Pulsar, LLM routing, and MCP integration.

Overview

Project Nexus v2 is an enterprise-grade workflow orchestration platform that transforms how teams build mission-critical AI workflows. Built on Apache Pulsar for reliable messaging and powered by intelligent LLM routing, it enables you to:

• Route messages intelligently with AI-powered classification
• Process documents with AI vision to extract structured data from invoices, receipts, and handwritten notes
• Ensure zero task loss with individual message acknowledgment
• Scale securely with multi-tenant architecture and OAuth2 integration
• Monitor in real-time with Prometheus metrics and Grafana dashboards

Key Features

• Intelligent Message Routing: Automatically classifies and routes messages to vision, tool execution, or chat workers
• Modern AI Vision: Layout-aware OCR with table preservation for structured data extraction
• Pulsar Backbone: Individual message acknowledgment ensures no task is lost, even when workers fail
• Multi-Tenancy: OAuth2 integration with isolated Pulsar tenants and namespaces for enterprise-grade security
• MCP Integration: Execute tools via Model Context Protocol (Stripe payments, database operations, custom workflows)
• Real-Time Monitoring: Track worker status, consumer lag, and task completion with Prometheus and Grafana

Supported MCP Servers

Project Nexus v2 includes support for the following MCP servers:

Core Integration Servers

• ✅ Exa Search: Live web search using Exa MCP API (HTTP transport)
• ✅ Google Maps Grounding: Location search and mapping services (HTTP transport)
• ✅ Playwright: Browser automation and web scraping (stdio transport with headless mode)
• ✅ GitHub: GitHub repository and code management (stdio transport)
• ✅ LangChain Agent: Multi-step reasoning and tool orchestration via LangChain ReAct agents (HTTP transport)

Productivity & Automation Servers

• ✅ Google Workspace: Comprehensive GSuite integration (Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Chat) via stdio transport
• ✅ Notion: Notion workspace management, page search, database operations, and knowledge organization (stdio transport)
• ✅ n8n Automation: Visual workflow building, triggers, and integrations with thousands of services (stdio transport)

AI Reasoning Servers

• ✅ Sequential Thinking: Chain-of-thought reasoning and structured problem-solving for AI agents (stdio transport)

All system servers are pre-configured and can be enabled/disabled through the monitoring dashboard. Custom MCP servers can be added via the server management interface.

Note: Some servers require environment variables for authentication:

• Google Workspace: GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET
• Notion: NOTION_API_KEY
• GitHub: GitHub Personal Access Token (via settings or environment variable)
• Google Maps: GOOGLE_MAPS_GROUNDING_API_KEY

Tech Stack

• Framework: Next.js 16 (React 19)
• Language: TypeScript 5
• Styling: Tailwind CSS v4
• UI Components: Radix UI, shadcn/ui
• Package Manager: pnpm
• Database: Supabase (PostgreSQL)
• Backend: Supabase Edge Functions (Deno)
• Message Queue: Apache Pulsar
• Deployment: Vercel

Getting Started

Prerequisites

• Node.js 18+
• pnpm 10.x (or use corepack enable to manage it automatically)
• Supabase account (for database and authentication)
• Apache Pulsar instance (or use managed Pulsar service)

Installation

1. Clone the repository:

   git clone https://github.com/mcpmessenger/project-nexus-v2.git
   cd project-nexus-v2-main

2. Install dependencies:

   pnpm install

3. Set up environment variables:

   cp .env.example .env.local

   Edit .env.local with your configuration values (Supabase URL, API keys, Pulsar connection details, etc.).

4. Run database migrations:

   # Follow instructions in docs/STORAGE_SETUP.md

5. Run the development server:

   pnpm dev

6. Open http://localhost:3000 in your browser.

Development Commands

• pnpm dev - Start development server
• pnpm build - Build for production
• pnpm start - Start production server
• pnpm lint - Run ESLint

Project Structure

├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   ├── monitoring/        # Registry/MCP server management
│   └── workflows/         # Workflow orchestration UI
├── components/            # React components
│   ├── ui/               # Reusable UI components
│   └── workflow-diagram.tsx  # Visual workflow architecture
├── lib/                   # Utility functions and clients
├── public/                # Static assets
│   └── images/           # Server logos and images
├── supabase/              # Supabase configuration
│   ├── functions/        # Edge functions
│   └── migrations/       # Database migrations
└── docs/                  # Architecture and documentation

Deployment

This project is automatically deployed to Vercel when changes are pushed to the main branch.

• Repository: mcpmessenger/project-nexus-v2
• Branch: main
• Platform: Vercel

To trigger a manual rebuild, push a commit to main or trigger a redeploy from the Vercel dashboard.

Testing

Run the following commands to validate your setup:

pnpm lint    # Validate TypeScript and lint rules
pnpm build   # Ensure production bundle compiles

Documentation

Comprehensive documentation is available in the docs/ directory:

• Architecture: System design and component architecture
• Architecture v2: Updated architecture with improvements
• Implementation Roadmap: Planned features and milestones
• Operational Guide: Running and maintaining the system
• Storage Setup: Database and storage configuration
• Setup Guide: Detailed setup instructions

Contributing

We welcome contributions! Please see our Contributing Guide for detailed guidelines. Here's a quick overview:

Getting Started

1. Fork the repository
2. Create a feature branch from main:

   git checkout -b feature/your-feature-name

3. Make your changes
4. Test thoroughly:

   pnpm lint    # Check for linting errors
   pnpm build   # Ensure everything compiles

5. Commit your changes with a clear message:

   git commit -m "feat: Add your feature description"

6. Push to your fork:

   git push origin feature/your-feature-name

7. Open a pull request on GitHub

Contribution Guidelines

• Follow the existing code style and conventions
• Add tests for new features when applicable
• Update documentation if you change functionality
• Write clear, descriptive commit messages
• Ensure your code passes linting and builds successfully

Areas for Contribution

• MCP Server Adapters: Implement additional MCP server integrations
• UI/UX Improvements: Enhance the user interface and experience
• Documentation: Improve docs, add examples, or fix typos
• Testing: Add unit tests, integration tests, or E2E tests
• Performance: Optimize workflows, reduce latency, improve scalability
• Bug Fixes: Report and fix issues

For major changes, please open an issue first to discuss what you'd like to change.

License

See LICENSE file for details.

Legal

• Privacy Policy
• Terms of Service

Support

• Issues: Open an issue on GitHub
• Discussions: GitHub Discussions
• Documentation: Check the docs/ directory for detailed guides

---

Built with ❤️ by the Project Nexus team