# 📘 CodePilot MCP - Intelligent Automation Platform

## 🎯 Overview

**CodePilot MCP** is an intelligent automation platform built on the Model Context Protocol (MCP) framework. It acts as a bridge between Large Language Models (LLMs) and real-world tools like GitHub, Notion, and Google Calendar. Designed for software engineers, team coordinators, and AI researchers, CodePilot enables smart task execution, personalized agent memory, and Slack integration through a modular, secure, and scalable microservices architecture.

---

## 🚀 Key Features

### 1. 🔄 Multi-Tool MCP Agent Server

* Automates workflows across **GitHub**, **Notion**, and **Google Calendar**
* Complies with the open **MCP Protocol** for tool interoperability
* Containerized with real-time event streaming (SSE)

### 2. 🤖 Slack Bot Integration

* Use the command `/codepilot` in Slack to automate:
  * Bug triage in GitHub
  * Meeting rescheduling in Calendar
  * Task syncing in Notion
* Internally triggers: **Planner → Reasoner → Validator → Executor → Memory Store**

### 3. 🧠 LLM Memory Store

* Tracks previous commands, feedback, and tool interactions
* Personalizes responses based on user history
* Powered by **MongoDB** with RBAC for secure storage

### 4. 📊 MCP Eval Dashboard

* Built using **Next.js**, **TailwindCSS**, and **ShadCN**
* Features:
  * ✅ Success/failure rate of agent tasks
  * 🧠 LLM memory usage and impact
  * 🔍 API call history
  * 📄 Error logs and response times

---

## 🧠 Architecture

```
User (Slack/Frontend)
   │
   ▼
/codepilot Command or Dashboard UI
   │
   ▼
Planner Agent  ──▶ Reasoner (LLM) ──▶ Validator (Zod)
   │                                  │
   ▼                                  ▼
Executor ──▶ GitHub / Notion / Calendar API
   │
   ▼
Memory Store (Mongo) + Eval Logger (Postgres)
   │
   ▼
Eval Dashboard (Next.js)
```

---

## 🧱 Tech Stack Breakdown

| Layer         | Tech                                                                |
| ------------- | ------------------------------------------------------------------- |
| Frontend      | Next.js, Tailwind, ShadCN (for MCP Eval Dashboard)                  |
| Backend       | Node.js + TypeScript (Express or Next.js API Routes)                |
| Databases     | PostgreSQL (main data), Redis (caching), MongoDB (LLM Memory Store) |
| LLMs          | GPT-4o (OpenAI), Relevance AI, Hugging Face                         |
| Infra         | Docker, Google Cloud Run, GitHub Actions, Secret Manager            |
| Slack Bot     | Bolt SDK (Slack API) + Webhook Trigger to MCP Server                |
| Auth & ACL    | OAuth 2.1, RBAC, JWT                                                |
| Observability | Sentry, Google Cloud Logging, UptimeRobot                           |
| Validation    | Zod, CSP headers, Prompt Injection Filters                          |

---

## 📦 Available Tools

### GitHub Integration
- `github_create_issue` - Create issues with labels and assignees
- `github_list_issues` - Query issues with filters
- `github_create_pr` - Create pull requests with automation

### Notion Integration
- `notion_create_page` - Create structured documentation
- `notion_update_page` - Update existing pages
- `notion_query_database` - Search and filter databases

### Google Calendar Integration
- `calendar_create_event` - Schedule meetings with attendees
- `calendar_list_events` - Query calendar events
- `calendar_update_event` - Modify existing events

### Workflow Automation
- `workflow_project_setup` - End-to-end project initialization
- `workflow_bug_triage` - Automated bug analysis and assignment
- `workflow_meeting_scheduler` - Smart meeting coordination

---

## 🚀 Quick Start

### Prerequisites

- Node.js 18+
- MongoDB instance
- API tokens for GitHub, Notion, and Google Calendar

### Installation

1. **Clone and Install Dependencies**
```bash
git clone <repository-url>
cd CodePilot-MCP
npm install
```

2. **Environment Setup**
```bash
cp .env.example .env
# Edit .env with your API tokens and database URLs
```

3. **Build the Project**
```bash
npm run build
```

4. **Start the MCP Server**
```bash
npm start
```

### Testing with Claude Desktop

1. **Configure Claude Desktop**
```json
{
  "mcpServers": {
    "codepilot-mcp": {
      "command": "node",
      "args": ["C:\\path\\to\\CodePilot-MCP\\dist\\index.js"]
    }
  }
}
```

2. **Test Commands in Claude**
- "Create a GitHub issue for bug tracking"
- "Set up a new project with GitHub repo and Notion workspace"
- "Schedule a team standup meeting"

---

## 🔧 Development

### Scripts

```bash
npm run dev          # Development server with hot reload
npm run build        # Build TypeScript to JavaScript
npm run test         # Run test suite
npm run lint         # ESLint code checking
npm run format       # Prettier code formatting
```

### Project Structure

```
src/
├── index.ts                 # Main MCP server entry point
├── agents/                  # AI agent system
│   ├── planner.ts          # Workflow planning agent
│   ├── reasoner.ts         # LLM-powered reasoning agent
│   ├── executor.ts         # Task execution agent
│   └── eval.ts             # Evaluation and metrics agent
├── services/               # External service integrations
│   ├── github/             # GitHub API service
│   ├── notion/             # Notion API service
│   ├── calendar/           # Google Calendar service
│   ├── auth/               # Authentication service
│   └── memory/             # MongoDB memory store
└── utils/                  # Shared utilities
    ├── logger.ts           # Winston logging
    └── validation.ts       # Zod schemas
```

---

## 🤖 Slack Bot Integration

The MCP server includes a comprehensive Slack bot for workflow management and notifications.

### Features
- **Interactive Commands**: Slash commands and mention handlers
- **Workflow Control**: Start, stop, and monitor workflows directly from Slack
- **Real-time Notifications**: Get updates on workflow status changes
- **Webhook Integration**: Receive notifications from GitHub, Notion, and Calendar events

### Setup
1. Create a Slack app at https://api.slack.com/apps
2. Configure the following scopes:
   - `app_mentions:read`
   - `chat:write`
   - `commands`
   - `users:read`
3. Add environment variables:
   ```bash
   SLACK_BOT_TOKEN=xoxb-your-bot-token
   SLACK_SIGNING_SECRET=your-signing-secret
   SLACK_APP_TOKEN=xapp-your-app-token # For Socket Mode
   ```

### Commands
- `/codepilot workflows` - List your workflows
- `/codepilot create [name]` - Create a new workflow
- `/codepilot help` - Show help message
- `@CodePilot start workflow [name]` - Start a workflow
- `@CodePilot status workflow [id]` - Check workflow status
- `@CodePilot stop workflow [id]` - Stop a workflow

## 📊 MCP Eval Dashboard

A modern Next.js dashboard for monitoring and managing your CodePilot MCP workflows.

### Features
- **Real-time Monitoring**: Live workflow status and system health
- **Performance Metrics**: Charts and analytics for workflow performance
- **Activity Feed**: Recent activity and notifications
- **System Health**: Monitor API services and resource usage
- **Quick Actions**: Start workflows and manage tasks

### Setup
```bash
cd dashboard
npm install
npm run dev
```

The dashboard will be available at http://localhost:3000

### Environment Variables
```bash
NEXT_PUBLIC_API_URL=http://localhost:3000
NEXT_PUBLIC_WS_URL=ws://localhost:3001
```

### Components
- **Dashboard Layout**: Responsive sidebar navigation
- **Workflow Overview**: Active workflows and progress tracking
- **System Health**: Service status and resource monitoring
- **Metrics Charts**: Performance visualization with Recharts
- **Recent Activity**: Timeline of recent events
- **Quick Actions**: One-click workflow management

## 🌐 Webhook Service

The webhook service handles incoming events from external services and routes them appropriately.

### Supported Webhooks
- **GitHub**: PR creation, issue updates, repository events
- **Slack**: Event API notifications
- **Notion**: Page updates, database changes
- **Google Calendar**: Event creation, updates
- **Custom**: Generic webhook endpoint for other integrations

### Endpoints
```
POST /webhooks/github      - GitHub webhook events
POST /webhooks/slack       - Slack event subscriptions
POST /webhooks/notion      - Notion API webhooks
POST /webhooks/calendar    - Google Calendar notifications
POST /webhooks/custom/:source - Custom webhook endpoint
GET  /webhooks/events      - Webhook event history
GET  /health              - Health check
```

### Security
- Signature verification for GitHub, Slack, and Notion
- CORS support
- Request logging and error handling
- Rate limiting (configurable)

## 🛠 Development Workflow

### Adding New Integrations

1. **Create Service Module**:
   ```typescript
   // src/services/newservice/index.ts
   export class NewService {
     async performAction(params: any) {
       // Implementation
     }
   }
   ```

2. **Add Validation Schema**:
   ```typescript
   // src/utils/validation.ts
   export const NewServiceSchema = z.object({
     // Define schema
   });
   ```

3. **Register Tool in MCP Server**:
   ```typescript
   // src/index.ts
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (request.params.name === 'new_service_action') {
       // Handle the tool
     }
   });
   ```

4. **Add to Webhook Handler** (if needed):
   ```typescript
   // src/services/webhook/index.ts
   private async handleNewServiceWebhook(payload: any): Promise<void> {
     // Handle webhook
   }
   ```

### Testing

```bash
# Run main server tests
npm test

# Run dashboard tests
cd dashboard
npm test

# Type checking
npm run type-check

# Linting
npm run lint
```

### Deployment Options

#### Local Development
```bash
npm run dev
```

#### Docker
```bash
docker build -t codepilot-mcp .
docker run -p 3000:3000 -p 3001:3001 codepilot-mcp
```

#### Google Cloud Run
```bash
gcloud run deploy codepilot-mcp \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated
```

### Performance Optimization

- **Caching**: Redis for session and workflow state
- **Database**: MongoDB with indexes for fast queries  
- **Rate Limiting**: Configurable per-service rate limits
- **Connection Pooling**: Reuse API connections
- **Background Jobs**: Queue system for long-running tasks

## 🏗 Architecture Decisions

### Why This Stack?
- **TypeScript**: Type safety and better developer experience
- **Zod**: Runtime validation and type inference
- **Express**: Webhook handling and API endpoints
- **Next.js**: Modern React framework for dashboard
- **MongoDB**: Flexible document storage for workflows
- **Tailwind CSS**: Utility-first styling

### Design Patterns
- **Service Layer**: Separation of concerns for each integration
- **Agent Pattern**: Specialized agents for planning, reasoning, execution
- **Event-Driven**: Webhook-based real-time updates
- **Validation Layer**: Centralized input validation with Zod
- **Error Handling**: Comprehensive error boundaries and logging

### Security Best Practices
- Input validation on all endpoints
- Webhook signature verification
- Rate limiting and CORS
- Environment variable configuration
- JWT-based authentication (extendable)
- SQL injection prevention (NoSQL with validation)

## 📈 Monitoring and Analytics

### Metrics Collected
- Workflow execution times
- API response times
- Error rates by service
- Resource usage (CPU, memory)
- User activity patterns

### Logging
```typescript
import { logger } from './utils/logger';

logger.info('Operation completed', { 
  workflowId, 
  duration, 
  status 
});
```

### Health Checks
- Service availability monitoring
- Database connection status
- External API health
- Resource usage alerts

## 🤝 Contributing

### Development Setup
1. Clone the repository
2. Install dependencies: `npm install`
3. Copy `.env.example` to `.env` and configure
4. Start development server: `npm run dev`
5. Start dashboard: `cd dashboard && npm run dev`

### Code Style
- Use TypeScript for all new code
- Follow ESLint configuration
- Write tests for new features
- Document public APIs
- Use conventional commits

### Pull Request Process
1. Create feature branch from `main`
2. Make changes with tests
3. Update documentation
4. Submit PR with description
5. Address review feedback

## 📋 Roadmap

### Version 1.1
- [ ] Discord integration
- [ ] Advanced workflow templates
- [ ] Workflow marketplace
- [ ] Mobile dashboard app

### Version 1.2
- [ ] AI-powered workflow suggestions
- [ ] Multi-tenant support
- [ ] Advanced analytics
- [ ] Plugin system

### Version 2.0
- [ ] Visual workflow builder
- [ ] Enterprise features
- [ ] Advanced security
- [ ] Workflow marketplace

## 📞 Support

- **Documentation**: Check this README and inline code comments
- **Issues**: Use GitHub Issues for bug reports
- **Discussions**: Use GitHub Discussions for questions
- **Email**: Contact [bathinibathinanna1432@gmail.com] for enterprise support

## 🙏 Acknowledgments

- **Model Context Protocol**: For the foundational framework
- **Anthropic**: For MCP development and Claude integration
- **Open Source Community**: For the excellent libraries and tools
- **Contributors**: Thank you to all who help improve this project

---

**Happy Automating! 🚀**