# Project Management MCP Server
A **Model Context Protocol (MCP)** server that acts as a context-aware middleware for AI assistants. It intercepts user queries, analyzes intent, fetches context from multiple productivity systems (Google Calendar, GitHub, Slack, and JIRA), assembles a structured context package, and delivers it alongside the original prompt to the Gemini AI model for hyper-relevant responses.
This repository (together with a Devpost demo video) forms the submission for the Build-Your-Own-MCP Challenge.
---
## Table of Contents
1. [High-Level Workflow](#high-level-workflow)
2. [Key Capabilities](#key-capabilities)
3. [Architecture](#architecture)
4. [Integrations & Required Credentials](#integrations--required-credentials)
5. [Installation & Setup](#installation--setup)
6. [Running the Server & UI](#running-the-server--ui)
7. [Available MCP Tools](#available-mcp-tools)
8. [Submission Checklist](#submission-checklist)
9. [Project Structure](#project-structure)
10. [Troubleshooting](#troubleshooting)
11. [License & Contact](#license--contact)
---
## High-Level Workflow
1. **Intercept** user queries (via MCP client, CLI, or Streamlit dashboard).
2. **Analyze** intent with an NLP-powered `QueryAnalyzer` (intent detection, entity extraction, domain classification, temporal parsing).
3. **Fetch** supplemental context from the relevant data sources.
4. **Assemble** a ranked & summarized context package using caching, ranking, summarization, and correlation engines.
5. **Deliver** the context bundle and original prompt to Gemini for the final response.
---
## Key Capabilities
### Intelligent Query Understanding
- Detects calendar, GitHub, Slack, and JIRA domains (or multi-domain queries).
- Extracts entities such as repositories, PR/issue counts, calendar dates, backlog keywords, etc.
- Supports relative and absolute time references via a time-aware analyzer.
### Multi-Source Context Gathering
- **Google Calendar:** Events, availability, conflicts, and multi-calendar aggregation.
- **GitHub:** Repositories, issues, PRs, commits, deployments, README summaries.
- **Slack:** Channels, mentions, unread messages, recent activity.
- **JIRA:** Boards, assigned issues, backlog items, sprint insights.
### Context Packaging
- **ContextCache:** TTL-based cache to minimize redundant API calls.
- **ContextRanker:** Prioritizes the most relevant events/issues per query.
- **ContextSummarizer:** Compresses context to stay within token budgets.
- **ContextCorrelator:** Cross-links signals across services (e.g., meetings vs. deployments vs. Slack alerts).
### Delivery via Gemini
- Aggregated context + user prompt → Gemini (primarily `gemini-2.5-flash`) to craft a tailored response.
---
## Architecture
```
┌──────────────────────────┐
│ User Request │
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ Query Analyzer │ ← intent detection, entities, time range
└────────────┬─────────────┘
│
┌──────────┼───────────┐
│ │ │
▼ ▼ ▼
Calendar GitHub Slack JIRA
Client Client Client Client
(fetch) (fetch) (fetch) (fetch)
│ │ │ │
└──────────┴───────────┴─────────┘
│
▼
┌──────────────────────────┐
│ Cache / Rank / Summarize │
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ Gemini Client (Chat) │ → context + prompt → AI answer
└──────────────────────────┘
```
---
## Integrations & Required Credentials
| Service | Credentials / Env Vars | Notes |
|------------------|----------------------------------------------------------|-------|
| Google Calendar | `config/credentials.json`, `config/token.json` (generated) | OAuth desktop credentials with Calendar scopes |
| GitHub | `.env` → `GITHUB_TOKEN` | Personal Access Token with repo scope |
| Slack | `.env` → `SLACK_USER_TOKEN` | User token with `channels:read`, `channels:history`, `groups:*`, `im:*`, `search:read`, `users:read` |
| JIRA | `.env` → `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` | Jira Cloud site, email, and API token |
| Gemini | `.env` → `GEMINI_API_KEY` | Google AI Studio API key |
Optional environment variables (with defaults in code):
- `GOOGLE_CREDENTIALS_PATH` (default `config/credentials.json`)
- `GOOGLE_TOKEN_PATH` (default `config/token.json`)
- `CALENDAR_TIMEZONE` (used for time parsing defaults)
Make sure sensitive files (credentials and tokens) stay out of version control. `.gitignore` already excludes them.
---
## Installation & Setup
1. **Clone the repository**
```bash
git clone <repo-url>
cd MCP\ server
```
2. **Create & activate a Python environment**
```bash
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
```
3. **Install dependencies**
```bash
pip install -r requirements.txt
```
4. **Provide credentials**
- Place Google OAuth desktop credentials at `config/credentials.json`.
- Create a `.env` file (copy `.env.example`) and populate the tokens/keys listed above.
5. **Authenticate Google Calendar (first run)**
Running the server for the first time will launch a browser window for Google OAuth and produce `config/token.json`.
---
## Running the Server & UI
### 1. MCP Server (JSON-RPC over stdio)
```bash
python main.py
```
This registers tools such as `chat`, `get_calendar_context`, `get_github_repositories`, `get_slack_mentions`, `get_jira_backlog`, etc.
### 2. Streamlit Dashboard (optional UI)
```bash
streamlit run streamlit_app.py
```
Features predefined queries, quick actions, and a custom prompt box for Calendar/GitHub/Slack/JIRA.
### 3. CLI Test Scripts (optional)
- `interactive_client.py` for command-line chat testing.
- `slack_test.py`, `jira_test.py` for quick credential and API verification.
---
## Available MCP Tools
| Tool | Description |
|------|-------------|
| `chat` | Main conversational endpoint; auto-fetches relevant context across all services. |
| **Calendar** |
| `get_calendar_context` | Analyze a query and return formatted calendar context. |
| `check_availability` | Check availability for a specific timeslot. |
| `get_upcoming_events` | List upcoming events. |
| `detect_conflicts` | Identify conflicts on a date. |
| **GitHub** |
| `get_github_repositories` | List repositories (with metadata). |
| `get_github_issues` | Fetch open issues. |
| `get_github_pull_requests` | Fetch PRs. |
| `get_github_deployments` | Retrieve deployments + status. |
| **Slack** |
| `get_slack_channels` | List channels. |
| `get_slack_unread` | Channels with unread messages. |
| `get_slack_mentions` | Recent mentions. |
| **JIRA** |
| `get_jira_boards` | List boards. |
| `get_jira_issues` | General issue retrieval (board/JQL). |
| `get_my_jira_issues` | Issues assigned to the authenticated user (with fallbacks). |
| `get_jira_backlog` | Backlog items (Agile API + JQL fallback). |
Each tool returns a formatted string suitable for direct inclusion in a context package.
---
## Submission Checklist
✅ **GitHub Repository** – contains the full MCP server implementation, connectors, UI, and test scripts.
✅ **Context-Aware Workflow** – intercept → analyze → fetch → assemble → deliver implemented across four services.
⚠️ **Devpost Video Demo** – still needed. Please record a short walkthrough showing:
- How a query flows through the system (e.g., via Streamlit UI).
- The resulting context assembly (logs/UI snippets).
- The Gemini-powered responses.
- Any unique 2.0 features (caching, correlation, summarization).
Upload the video to Devpost along with the repo link.
---
## Project Structure
```
MCP server/
├── main.py # Entry point for MCP server
├── streamlit_app.py # Optional Streamlit UI
├── interactive_client.py # Simple CLI client
├── slack_test.py / jira_test.py# Quick integration smoke tests
├── src/
│ ├── server.py # MCP tools & orchestration layer
│ ├── query_analyzer.py # NLP intent/time/entity detection
│ ├── context_cache.py # TTL cache for API responses
│ ├── context_ranker.py # Relevance scoring
│ ├── context_summarizer.py # Compression + summarization utilities
│ ├── context_correlator.py # Multi-source correlation engine
│ ├── context_formatter.py # Human-friendly context formatting
│ ├── gemini_client.py # Gemini chat integration
│ ├── calendar_client.py # Google Calendar wrapper
│ ├── github_client.py # GitHub REST wrapper
│ ├── slack_client.py # Slack WebClient wrapper
│ ├── jira_client.py # Jira REST (Agile + Core) wrapper
│ └── connectors/ # Connector facades per service
├── config/
│ ├── credentials.json # Google OAuth client (excluded from git)
│ └── token.json # Google OAuth token (excluded from git)
├── requirements.txt
├── .env.example
└── README.md (this file)
```
---
## Troubleshooting
| Issue | Resolution |
|-------|------------|
| Google Calendar auth loop | Delete `config/token.json` and rerun to reauthenticate. Ensure OAuth consent screen has you as a test user. |
| GitHub 401 | Regenerate `GITHUB_TOKEN` (classic PAT) with `repo` scope. |
| Slack `missing_scope` | Add required scopes under **User Token Scopes** and reinstall the app. |
| JIRA 410 errors | Confirm you have access to the Jira Cloud site and use valid API tokens. The client already falls back to board-based queries when search fails. |
| Gemini errors | Verify `GEMINI_API_KEY` is correct and the selected model is available in your region/account. |
Logging is configured to stderr to avoid interfering with MCP stdio responses.
---
## License & Contact
Created for the **Build-Your-Own-MCP Challenge**.
For questions, open an issue or reach out via the Devpost discussion board when submitting your demo.
