# 📘 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! 🚀**
