Content
# IT Helpdesk Assistant MCP
A portfolio-ready [Model Context Protocol](https://modelcontextprotocol.io/)
server that gives an AI client read-only helpdesk context, controlled repair
operations, a consistent support prompt, and optional external integrations.
The project runs locally with no API keys. On first start it creates a SQLite
database with demo customers, devices, tickets, and inventory. Local manuals are
discovered dynamically from `documents/`.
## Documentation
Start with the [documentation index](docs/index.md), or go directly to:
| Guide | Contents |
|---|---|
| [Getting started](docs/getting-started.md) | Installation, first run, Inspector, client configuration |
| [Configuration](docs/configuration.md) | Paths, driver API, SMTP, timeout, and secrets |
| [MCP reference](docs/mcp-reference.md) | Every resource, tool, prompt, argument, output, and error |
| [Data model](docs/data-model.md) | SQLite tables, relationships, lifecycle, numbering, and seed data |
| [Workflows](docs/workflows.md) | Diagnosis, ticket lifecycle, inventory, email, and reports |
| [Operations](docs/operations.md) | Transports, backups, restore, knowledge files, and health checks |
| [Development](docs/development.md) | Modules, tests, packaging, and extension procedures |
| [Security](docs/security.md) | Trust boundaries, secrets, data protection, and hardening |
| [Troubleshooting](docs/troubleshooting.md) | Startup, MCP, database, PDF, search, API, and SMTP failures |
| [Architecture](docs/architecture.md) | Component, sequence, and data-model diagrams |
## What is included
| Phase | Delivered capability |
|---|---|
| 1. Foundation | FastMCP server over stdio, SSE, or Streamable HTTP |
| 2. Files | Dynamic `docs://` resources for `.pdf`, `.txt`, and `.md` |
| 3. Database | SQLite customers, repair tickets, devices, inventory, and timelines |
| 4. Search | One tool searches manuals and historical tickets |
| 5. External APIs | Vendor support, configurable driver API, SMTP, Open-Meteo demo |
| 6. Tools | Customer, ticket, inventory, search, and report operations |
| 7. Prompt | `helpdesk_assistant` safety and workflow prompt |
| 8. Workflow | Search → diagnose → check parts → create/update/close → notify |
| 9. User features | `HD-YYYYMM-NNNN` numbers, timelines, dashboard, Markdown reports |
| 10. Polish | Modular code, tests, architecture docs, setup and client examples |
## Quick start
Python 3.11 or newer is required. The dependency constraint intentionally stays
on MCP Python SDK v1 while v2 is pre-release.
### Windows PowerShell
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python server.py
```
### macOS or Linux
```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python server.py
```
The default transport is stdio. For a local HTTP endpoint:
```powershell
python server.py --transport streamable-http
```
The endpoint is `http://127.0.0.1:8000/mcp`.
## Open in MCP Inspector
The official Inspector runs through `npx`. From this repository:
```powershell
npx -y @modelcontextprotocol/inspector .\.venv\Scripts\python.exe server.py
```
On macOS or Linux, replace the Python path with `.venv/bin/python`. In the
Inspector, verify the Resources, Tools, and Prompts tabs. The Inspector can also
connect to `http://127.0.0.1:8000/mcp` when the server runs with
`--transport streamable-http`.
## Connect an MCP client
Use absolute paths because desktop clients may start the process from another
working directory.
```json
{
"mcpServers": {
"it-helpdesk": {
"command": "D:\\absolute\\path\\to\\it-helpdesk\\.venv\\Scripts\\python.exe",
"args": ["D:\\absolute\\path\\to\\it-helpdesk\\server.py"]
}
}
}
```
Use `/absolute/path/to/.../.venv/bin/python` on macOS or Linux.
## MCP surface
### Resources
| URI | Purpose |
|---|---|
| `docs://list` | Discover manuals and their generated IDs |
| `docs://{document_id}` | Read a discovered PDF, text, or Markdown manual |
| `db://customers` | Customer directory |
| `db://tickets` | Ticket queue |
| `db://tickets/{ticket_number}` | Full ticket, customer/device context, timeline |
| `db://devices` | Registered customer devices |
| `db://inventory` | Parts and supplies |
| `db://dashboard` | Live operations totals and recent tickets |
### Tools
| Tool | Effect |
|---|---|
| `search_helpdesk` | Search manuals and ticket history together |
| `add_customer` | Create a customer after validation |
| `create_ticket` | Open a numbered repair ticket |
| `update_ticket_status` | Add a timeline event and change active status |
| `close_ticket` | Record a resolution and close a ticket |
| `search_inventory` | Match SKU, part, vendor, category, or compatible model |
| `generate_report` | Return or save summary, ticket, or inventory Markdown |
| `lookup_manufacturer_support` | Return official vendor support locations |
| `lookup_driver` | Call a configured catalog or return the official driver page |
| `send_ticket_email` | Send a status update through configured SMTP |
| `get_weather_demo` | Demonstrate a keyless Open-Meteo API lookup |
Mutating, read-only, destructive, and open-world tools carry MCP tool
annotations so compatible clients can present appropriate confirmation UI.
### Prompt
`helpdesk_assistant(issue)` provides an evidence-led support workflow. The same
core behavior is also supplied as server instructions during MCP initialization:
inspect local context first, prefer reversible actions, protect secrets, require
approval before mutations, and never fabricate tool results.
## Configuration
Copy `.env.example` to `.env` when using `mcp dev`, or set the variables in the
environment that launches your client.
| Variable | Purpose |
|---|---|
| `HELPDESK_DOCUMENTS_DIR` | Override the manuals directory |
| `HELPDESK_DATABASE_PATH` | Override the SQLite database path |
| `HELPDESK_REPORTS_DIR` | Override saved report output |
| `HELPDESK_DRIVER_API_URL` | Optional JSON driver catalog endpoint |
| `HELPDESK_DRIVER_API_KEY` | Optional bearer token for that endpoint |
| `HELPDESK_SMTP_*` | SMTP host, port, credentials, and From address |
| `HELPDESK_EXTERNAL_TIMEOUT_SECONDS` | Network timeout; default `10` |
Without a driver API, `lookup_driver` returns an official manufacturer page.
Without SMTP configuration, email fails safely with setup guidance. Weather is
the only built-in live HTTP call and uses
[Open-Meteo](https://open-meteo.com/en/docs).
## Test and verify
Tests exercise the public FastMCP surface with temporary files and a real
temporary SQLite database. Only external HTTP/email adapters are replaced.
```powershell
python -m unittest discover -s tests -v
python -m compileall -q it_helpdesk server.py
python -m mypy --check-untyped-defs it_helpdesk server.py
```
For a manual protocol check, use the Inspector and:
1. Read `docs://list` and `db://dashboard`.
2. Call `search_helpdesk` with `printer`.
3. Add a customer and create a ticket with the returned customer ID.
4. Read `db://tickets/{ticket_number}` to inspect its timeline.
5. Update, report, and close the ticket.
## Architecture
```mermaid
flowchart LR
Client["MCP client / Inspector"] -->|"stdio, SSE, or HTTP"| Server["FastMCP server"]
Server --> Prompt["Helpdesk instructions + prompt"]
Server --> Resources["Resource handlers"]
Server --> Tools["Tool handlers"]
Resources --> Docs["DocumentStore"]
Docs --> Files["PDF / TXT / Markdown"]
Resources --> Repo["HelpdeskRepository"]
Tools --> Repo
Repo --> SQLite[("SQLite")]
Tools --> Reports["Markdown reports"]
Tools --> Integrations["External integrations"]
Integrations --> Vendor["Vendor / driver API"]
Integrations --> SMTP["SMTP"]
Integrations --> Weather["Open-Meteo"]
```
See [docs/architecture.md](docs/architecture.md) for boundaries, workflow, and
design decisions.
## Project structure
```text
it-helpdesk/
├── documents/ # Auto-discovered local knowledge base
├── database/ # Runtime SQLite database (ignored)
├── reports/ # Optional generated reports (ignored)
├── docs/ # Full project and API documentation
├── it_helpdesk/
│ ├── cli.py # Installed command entrypoint
│ ├── config.py # Environment-backed settings
│ ├── database.py # Schema, seed data, queries, ticket lifecycle
│ ├── documents.py # File discovery, PDF extraction, search
│ ├── integrations.py # HTTP/vendor/weather and SMTP adapters
│ ├── mcp_server.py # Resources, tools, prompt registration
│ └── reports.py # Markdown report generation
├── tests/test_mcp_server.py # Public MCP integration tests
├── server.py # Simple local entrypoint
├── pyproject.toml
└── requirements.txt
```
## Design notes
- SQL uses bound parameters, foreign keys, validation, and an atomic monthly
sequence for collision-resistant ticket numbers.
- Document IDs come only from discovered files; callers cannot use the resource
template for arbitrary path access.
- Database connections are short-lived, making server construction and tests
deterministic without global mutable connections.
- External services are explicit boundaries with timeouts and actionable errors.
- Demo seed data is inserted only when the customer table is empty.
