harshwadhawe/MCP-server--datathon

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

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

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

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.