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
- High-Level Workflow
- Key Capabilities
- Architecture
- Integrations & Required Credentials
- Installation & Setup
- Running the Server & UI
- Available MCP Tools
- Submission Checklist
- Project Structure
- Troubleshooting
- License & Contact
High-Level Workflow
- Intercept user queries (via MCP client, CLI, or Streamlit dashboard).
- Analyze intent with an NLP-powered
QueryAnalyzer(intent detection, entity extraction, domain classification, temporal parsing). - Fetch supplemental context from the relevant data sources.
- Assemble a ranked & summarized context package using caching, ranking, summarization, and correlation engines.
- 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(defaultconfig/credentials.json)GOOGLE_TOKEN_PATH(defaultconfig/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
-
Clone the repository
git clone <repo-url> cd MCP\ server -
Create & activate a Python environment
python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate -
Install dependencies
pip install -r requirements.txt -
Provide credentials
- Place Google OAuth desktop credentials at
config/credentials.json. - Create a
.envfile (copy.env.example) and populate the tokens/keys listed above.
- Place Google OAuth desktop credentials at
-
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)
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)
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.pyfor command-line chat testing.slack_test.py,jira_test.pyfor 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.