Skip to main content
Glama
MCP IT Help Desk
by minasenel

πŸ€– MCP IT Help Desk

Python MCP Protocol Fast Agent License: MIT

AI-powered IT support: understands issues (TR/EN), suggests fixes, and routes to the right experts. Experts are stored in Django DB.


✨ Features

  • AI-Powered Classification (100% LLM): Turkish + English via Gemini; no heuristics

  • Auto-Solutions: Common hardware/software/network fixes for non-critical cases

  • Smart Expert Assignment: Availability + expertise + load consideration

  • Modern Web UI: Real-time chat via Flask + Socket.IO + Tailwind

  • MCP Tools: Add/process issues, AI try-solve, assign experts

Related MCP server: Freshservice MCP server

🧭 Table of Contents

  • πŸ”§ MCP Tools

  • πŸš€ Quick Start

  • 🧱 Architecture

  • πŸ—‚οΈ File Structure

  • πŸ“– Comprehensive Documentation

  • βš™οΈ Advanced Configuration

  • πŸ§ͺ Usage Examples

  • 🧠 Design Philosophy

  • 🀝 Contributing & Support

πŸ”§ MCP Tools

Tool

Purpose

Inputs

Output

add_issue

Create a new ticket with normalized fields and timestamps

employee_id, description, category, subcategory, priority

Issue created: ISSnnn

ai_try_solve

Attempt auto-resolution for common issues (non-critical)

description, category, subcategory, priority

Solution text or suggestion to assign expert

assign_expert

Classify description and pick best available expert

description

Assigned expert: T00x - Name (category/subcategory)

process_issues

Batch normalize + auto-solve + assign/queue

none

Summary: closed_by_ai, assigned/queued, skipped

πŸ‘©β€πŸ’» Expert Data Format (Django DB)

Field

Type

Example

Notes

id

string (pk)

T001

Human-friendly ID

name

string

Elif Hanım, Ağ Uzmanı

Display name

expertise

JSON/list

["network","vpn"]

Tags matched by classifier

contact

string

elif@example.com

Optional

availability

boolean

true

Considered for assignment

current_load

integer

0

Incremented on assignment

πŸš€ Quick Start

Prerequisites

  • Python 3.11+

  • uv (recommended)

  • Gemini API key (required): set GEMINI_API_KEY or GOOGLE_API_KEY

Install dependencies

uv sync

πŸ”₯ Most Important: Start Project (2 terminals)

Terminal 1 β€” start Django API (port 8000):

cd django_api_service
python3 manage.py runserver 8000

Terminal 2 β€” start Web UI (Flask + Socket.IO):

cd ..  # back to project root (mcp-it-helpdesk)
uv run python start_web_agent.py

Set up Django (migrations + import experts)

cd django_api_service
uv run python manage.py makemigrations
uv run python manage.py migrate
uv run python import_experts.py  # imports tech_experts.json into DB

Run services

# MCP (via Fast Agent)
uv run fast-agent go --stdio "uv run python main.py"

# Django API (serves at http://localhost:8000; root "/" returns 404 by design)
uv run python django_api_service/manage.py runserver
# health check: http://localhost:8000/api/health/

# Web UI (Flask, serves at http://localhost:5001)
uv run python web_agent.py
# open http://localhost:5001

Notes:

  • API routes live under /api/ (e.g., /api/health/, /api/issues/). The root / returns 404 by design.

  • The web frontend at http://localhost:5001 calls the API at http://localhost:8000 by default.

🧱 Architecture

Web UI (Flask/Socket.IO)         Django API (REST + ORM)         MCP Server (main.py)
         β”‚                                β”‚                               β”‚
         β”‚  create/assign issues (HTTP)   β”‚                               β”‚
         └──────────────► /api/issues/ ───┼──────────┐                    β”‚
                                          β”‚          β”‚                    β”‚
                                          β–Ό          β”‚                    β”‚
                                  SQLite (Issues, Experts)                β”‚
                                                     β–²                    β”‚
                                                     └── load experts β—„β”€β”€β”€β”˜

πŸ—‚οΈ File Structure

mcp-it-helpdesk/
β”œβ”€ main.py                     # MCP server with tools
β”œβ”€ problems.txt                # Legacy issue store (MCP-only)
β”œβ”€ tech_experts.json           # Legacy sample; data is stored in Django DB
β”œβ”€ web_agent.py                # Flask web chat
β”œβ”€ templates/index.html        # Web UI
β”œβ”€ django_api_service/
β”‚  β”œβ”€ api/settings.py          # Django settings
β”‚  β”œβ”€ manage.py
β”‚  └─ issues/
β”‚     β”œβ”€ models.py             # Issue, Expert models
β”‚     β”œβ”€ serializers.py        # Validation + Gemini integration
β”‚     β”œβ”€ views.py              # REST endpoints and actions
β”‚     └─ migrations/           # Django migrations
└─ docs/images/                # (add your screenshots/diagrams here)

πŸ“– Comprehensive Documentation

Detailed Features and Benefits

  • Bilingual understanding (TR/EN): Reduces back-and-forth with users

  • AI-first classification: Requires Gemini key; ensures consistent, accurate categorization

  • Human-in-the-loop: Assign experts for high/critical cases or when AI can’t resolve

Installation Guide (Step-by-Step)

  1. Install dependencies with uv sync

  2. Run Django migrations and import experts (see Quick Start)

  3. Launch MCP, Django API, and the Web UI

  4. Test with the usage examples below

Practical Usage Examples

Inside Fast Agent:

/tools
/call main-add_issue {"employee_id":"E001","description":"VPN bağlantı sorunu","category":"network","subcategory":"vpn","priority":"medium"}
/call main-ai_try_solve {"description":"VPN bağlantı sorunu","category":"network","subcategory":"vpn","priority":"medium"}
/call main-process_issues

βš™οΈ Advanced Configuration

  • Gemini model: Set GEMINI_MODEL env (default: gemini-1.5-flash)

  • API Keys (required): Provide GEMINI_API_KEY or GOOGLE_API_KEY. The app maps GEMINI_API_KEY to GOOGLE_API_KEY automatically.

  • CORS: settings.py allows http://localhost:5001 for the web UI; adjust for production

  • Secrets & DB: .gitignore excludes local DBs and secrets; use .env files locally (don’t commit)

🧠 Design Philosophy

  • LLM-first: Classification and validation are fully AI-driven

  • Single Source of Truth for Experts: Experts live in Django DB (no runtime JSON fallback)

πŸ§ͺ Testing Ideas

  • Unit test serializers and classification (LLM prompts and outputs)

  • Integration test Django actions that shell into MCP (assign_expert, ai_solve)

  • E2E test via Web UI: create issue β†’ assign expert β†’ verify DB state

🐳 Docker

Official Image

  • Pull and run:

docker pull minasenel/mcp-it-helpdesk:latest
docker run --rm --name mcp_api -p 8000:8000 \
  -e GEMINI_API_KEY="<your_key>" \
  minasenel/mcp-it-helpdesk:latest
# open http://localhost:8000/api/health/
  • If port 8000 is busy on your host, map another host port:

docker run --rm --name mcp_api -p 8001:8000 \
  -e GEMINI_API_KEY="<your_key>" \
  minasenel/mcp-it-helpdesk:latest
# then use http://localhost:8001

Notes:

  • API routes live under /api/. The root / returns 404 by design.

  • The frontend typically runs at http://localhost:5001 and talks to the API at http://localhost:8000.

Environment Variables

  • GEMINI_API_KEY or GOOGLE_API_KEY (required)

  • SECRET_KEY (recommended for production; generated if missing in dev)

  • DJANGO_ALLOWED_HOSTS (set domains for production)

Examples:

docker run --rm -p 8000:8000 \
  -e GEMINI_API_KEY="<your_key>" \
  -e DJANGO_ALLOWED_HOSTS="localhost,127.0.0.1" \
  -e SECRET_KEY="change-me" \
  minasenel/mcp-it-helpdesk:latest

Data Persistence

  • The image uses SQLite by default inside the container. Data will be ephemeral unless you mount a volume:

# Persist the Django project folder (including db.sqlite3)
docker run --rm -p 8000:8000 \
  -e GEMINI_API_KEY="<your_key>" \
  -v "$PWD/django_data":/app/django_api_service \
  minasenel/mcp-it-helpdesk:latest

Build locally (optional)

If you prefer to build from source:

# from repo root
docker build -t YOUR_USERNAME/mcp-it-helpdesk:latest .
docker run --rm -p 8000:8000 \
  -e GEMINI_API_KEY="<your_key>" \
  YOUR_USERNAME/mcp-it-helpdesk:latest

Licensed under MIT.

Available Tools

4 tools
add_issueD

Inputs: category (required), priority (required), description (required), employee_id (required), +1 more. Returns: result

ai_try_solveC

This tool is used to try to solve the issue with AI first @param description: The description of the issue @param category: The category of the issue @param subcategory: The subcategory of the issue @param priority: The priority of the issue @return: The solution for the issue if it is solved, otherwise "ÇâzΓΌm ΓΆnerisi bulunamadΔ±: uzman atamasΔ± ΓΆnerilir."

Inputs: category (required), priority (required), description (required), subcategory (required). Returns: result

assign_expertC

Analyze the problem description, classify into standard categories, and choose the most suitable available expert.

Inputs: description (required). Returns: result

process_issuesC

This tool is used to process the issues @return: The summary of the issues

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.1/5.0

    Scored across 4 tools

    Disambiguation3/5

    Tools appear distinct but 'add_issue' lacks description, causing ambiguity about its exact role relative to 'ai_try_solve' and 'assign_expert'.

    Naming Consistency3/5

    Most tools use verb_noun pattern, but 'ai_try_solve' deviates with an awkward structure mixing AI and action verb.

    Tool Count4/5

    Four tools are reasonable for a simple help desk server, covering core steps without being excessive.

    Completeness2/5

    Missing essential operations like listing, updating, or deleting issues, and lacks a tool for viewing a single issue's details.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      This server provides a comprehensive integration with Zendesk. Retrieving and managing tickets and comments. Ticket analyzes and response drafting. Access to help center articles as knowledge base.
      7
      126
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Integration server that connects AI assistants to Atlassian products (Confluence & Jira), enabling natural language interactions for searching content, managing issues, creating documents, and updating project information.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An AI-powered code consultation server that routes programming queries to specific AI models based on requested expertise levels. It enables users to receive structured feedback on debugging, architectural decisions, and code reviews from Gemini, Claude, or GPT.
      -