Content
# Atbalsts MCP
MCP (Model Context Protocol) server for the NSIS.LV **Atbalsts** support /
ticketing platform (<https://atbalsts.nsis.lv>). Lets Claude and other MCP
clients manage tickets, attachments, and configuration directories through the
public REST API using natural language.
---
## Contents
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Running](#running)
- [Claude Desktop / MCP client integration](#claude-desktop--mcp-client-integration)
- [Available tools](#available-tools)
- [Role-based access](#role-based-access)
- [Project structure](#project-structure)
- [Data formats](#data-formats)
---
## Requirements
- Python 3.10+
- An active Atbalsts account (email + password)
- Network access to `https://atbalsts.nsis.lv`
---
## Installation
```bash
git clone https://github.com/nsislv/atbalsts-mcp.git
cd atbalsts-mcp
python -m venv venv
source venv/bin/activate # Linux / macOS
# venv\Scripts\activate.bat # Windows
pip install -r requirements.txt
```
---
## Configuration
Set the required environment variables before starting the server:
```bash
export ATBALSTS_EMAIL=user@example.com
export ATBALSTS_PASSWORD=your_password
```
Optional overrides (see `.env.example`):
| Variable | Default | Purpose |
|---|---|---|
| `ATBALSTS_BASE_URL` | `https://atbalsts.nsis.lv/rest` | REST base URL. |
| `ATBALSTS_TIMEOUT` | `30` | HTTP timeout (seconds). |
| `ATBALSTS_RATE_PER_SEC` | `2` | Token-bucket refill rate. |
| `ATBALSTS_RATE_BURST` | `5` | Token-bucket max burst. |
| `ATBALSTS_CLIENT_VERSION` | `mcp-1.0.0` | Version reported to `/rest/update`. |
The server performs a login against `/rest/login` on startup and exits with
a non-zero status if the credentials are rejected.
---
## Running
```bash
python server.py
```
The server speaks standard MCP over stdio. Use `mcp` CLI tooling or any MCP
client to interact with it.
---
## Claude Desktop / MCP client integration
Register the server with your MCP client. Example Claude Desktop config
(`claude_desktop_config.json`):
```json
{
"mcpServers": {
"atbalsts": {
"command": "/absolute/path/to/atbalsts-mcp/venv/bin/python",
"args": ["/absolute/path/to/atbalsts-mcp/server.py"],
"env": {
"ATBALSTS_EMAIL": "user@example.com",
"ATBALSTS_PASSWORD": "your_password"
}
}
}
}
```
---
## Available tools
### Auth & version
- `auth_whoami` — show cached session (role, legalname, company, regcode, server version).
- `auth_refresh` — force a fresh login and refresh the token.
- `check_for_updates` — call `/rest/update` to see if a newer Atbalsts client exists.
### Tickets
- `list_tickets` — list tickets for the current role, filterable by status and date range.
- `get_ticket` — full ticket record incl. posts, files, metadata.
- `create_ticket` — open a new ticket with optional attachments.
- `update_ticket` — patch title/status/priority/category/department/assignees.
- `post_ticket_reply` — add a reply (post) to a ticket with optional attachments.
- `close_ticket` — close a ticket with a date and total time spent (minutes).
- `delete_ticket` — permanently delete a ticket (admin/agent only, non-closed).
### Directories
- `list_companies` — all active companies (admin/agent only).
- `list_responsible` — users (filtered by regcode, or all for admin/agent).
- `list_agents` — consultants / support staff.
- `list_departaments` — departments configured for a company.
- `list_priority` — priority labels configured for a company.
- `list_category` — category labels configured for a company.
### Files
- `download_file` — fetch an attachment; optionally persist to a path, inline base64.
- `delete_file` — permanently delete an attachment (admin/agent only, non-closed ticket).
---
## Role-based access
Atbalsts enforces role-based visibility on every endpoint:
| Role | Scope |
|--------|-------|
| admin | Full access to everything. |
| agent | All tickets assigned to them or without an agent; browse users, companies. |
| owner | Own company's tickets and configuration. |
| user | Only own tickets and own configuration. |
Call `auth_whoami` to see the active role before calling tools that require
admin/agent (e.g. `list_companies`, `delete_ticket`, `delete_file`).
---
## Project structure
```
atbalsts-mcp/
├── server.py # MCP entry point (FastMCP)
├── atbalsts_client.py # HTTP client: login, token cache, rate limiter
├── tools/
│ ├── __init__.py
│ ├── auth.py # auth_whoami / auth_refresh / check_for_updates
│ ├── tickets.py # list/get/create/update/reply/close/delete
│ ├── directories.py # companies/users/agents/departments/priority/category
│ └── files.py # download/delete attachments
├── requirements.txt
├── .env.example
├── .gitignore
└── README.md
```
---
## Data formats
- **Dates** use `YYYY-MM-DD` in request payloads.
- **Ticket statuses**: `open`, `work`, `wait`, `close` (plus `notclose` for filtering).
- **Roles**: `admin`, `agent`, `owner`, `user`.
- **Identifiers**:
- `link` — opaque per-ticket or per-file id.
- `userlink` / `agentlink` — opaque per-user id.
- `regcode` — company registration code (e.g. `40001234567`).
- **Files**: request uploads as `multipart/form-data`; the server silently drops
files whose extension is not on the configured allow-list, so always confirm
the `files_saved` count in the response.
---
## Troubleshooting
- **`ERROR: Atbalsts login failed: Unauthorized`** — verify email/password; the
account must also be active.
- **Repeated 401 / `Forbidden`** — the current role is not allowed to call that
endpoint. Use `auth_whoami` to confirm the role.
- **Files attached but `files_saved: 0`** — the extension is blocked server-side.
- **Rate-limit pressure** — the client already applies a token-bucket limiter
(2 req/s avg, burst 5). Adjust via `ATBALSTS_RATE_PER_SEC` / `ATBALSTS_RATE_BURST`
if the server permits.
---
## License
MIT © NSIS.LV
