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.

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 (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

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 .env file (copy .env.example) and populate the tokens/keys listed above.
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.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.

Google Calendar MCP Server