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
2. Key Capabilities
3. Architecture
4. Integrations & Required Credentials
5. Installation & Setup
6. Running the Server & UI
7. Available MCP Tools
8. Submission Checklist
9. Project Structure
10. Troubleshooting
11. 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

   git clone <repo-url>
   cd MCP\ server

2. Create & activate a Python environment

   python3 -m venv .venv
   source .venv/bin/activate            # Windows: .venv\Scripts\activate

3. Install dependencies

   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)

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.