kasra-mcp-server 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. kasra_mcp_server-1.0.0/LICENSE +21 -0
  2. kasra_mcp_server-1.0.0/PKG-INFO +238 -0
  3. kasra_mcp_server-1.0.0/README.md +219 -0
  4. kasra_mcp_server-1.0.0/kasra_client.py +872 -0
  5. kasra_mcp_server-1.0.0/kasra_mcp_server.egg-info/PKG-INFO +238 -0
  6. kasra_mcp_server-1.0.0/kasra_mcp_server.egg-info/SOURCES.txt +12 -0
  7. kasra_mcp_server-1.0.0/kasra_mcp_server.egg-info/dependency_links.txt +1 -0
  8. kasra_mcp_server-1.0.0/kasra_mcp_server.egg-info/entry_points.txt +2 -0
  9. kasra_mcp_server-1.0.0/kasra_mcp_server.egg-info/requires.txt +5 -0
  10. kasra_mcp_server-1.0.0/kasra_mcp_server.egg-info/top_level.txt +3 -0
  11. kasra_mcp_server-1.0.0/main.py +15 -0
  12. kasra_mcp_server-1.0.0/pyproject.toml +30 -0
  13. kasra_mcp_server-1.0.0/server.py +293 -0
  14. kasra_mcp_server-1.0.0/setup.cfg +4 -0
kasra_mcp_server-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Emad Razavi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
kasra_mcp_server-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,238 @@
1
+ Metadata-Version: 2.4
2
+ Name: kasra-mcp-server
3
+ Version: 1.0.0
4
+ Summary: Model Context Protocol (MCP) server for Kasra Lite Attendance and Personnel Management System
5
+ Author-email: Emad Razavi <razavioo@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/razavioo/kasra-mcp-server
8
+ Project-URL: Repository, https://github.com/razavioo/kasra-mcp-server
9
+ Keywords: mcp,model-context-protocol,kasra,attendance,fastmcp
10
+ Requires-Python: >=3.10
11
+ Description-Content-Type: text/markdown
12
+ License-File: LICENSE
13
+ Requires-Dist: fastmcp>=2.0.0
14
+ Requires-Dist: httpx>=0.25.0
15
+ Requires-Dist: beautifulsoup4>=4.12.0
16
+ Requires-Dist: pycryptodome>=3.18.0
17
+ Requires-Dist: python-dotenv>=1.0.0
18
+ Dynamic: license-file
19
+
20
+ # Kasra Lite Attendance & Personnel MCP Server
21
+
22
+ [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
23
+ [![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-FastMCP-brightgreen.svg)](https://modelcontextprotocol.io/)
24
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
25
+
26
+ A Model Context Protocol (MCP) server for the **Kasra Lite Attendance, Personnel, Cartable, and Leave Management System** ([app.kasralite.com](https://app.kasralite.com)).
27
+
28
+ Connect your AI agents (Claude Desktop, OpenCode, Cursor, Windsurf, etc.) directly to Kasra Lite to view attendance, punches, leaves, cardex, cartable requests, work periods, and submit leave/mission requests autonomously.
29
+
30
+ > ๐Ÿš€ **100% Pure HTTP & Async API โ€” No Headless Browser Required!**
31
+ > Runs via standard HTTP/2 APIs and AES-128-CBC encryption without downloading Chromium or running Playwright/Puppeteer. Works in any environment including headless Linux servers, Docker containers, macOS, and Windows.
32
+
33
+ ---
34
+
35
+ ## ๐ŸŒŸ Available MCP Tools (17 Tools)
36
+
37
+ ### 1. Personnel Profile & Dashboard
38
+ - **`kasra_get_profile`**: Retrieve user identity, personnel code, system ID, role, department, and recent login IP history.
39
+ - **`kasra_get_dashboard_summary`**: Real-time summary:
40
+ - Last registered punch of today (time & status)
41
+ - Cardex leave balance (hours)
42
+ - Total presence & worked hours in current period
43
+ - Permissions needed (incomplete punches, overtime, deficit)
44
+ - Request approval counters (in progress, confirmed, rejected)
45
+ - Pending cartable documents count
46
+ - **`kasra_get_desktop_shortcuts`**: Get user's pinned/favorite desktop bookmarks.
47
+ - **`kasra_get_messages`**: Retrieve broadcast announcements and system messages.
48
+
49
+ ### 2. Attendance & Reports
50
+ - **`kasra_get_daily_report`**: Day-by-day detailed breakdown of punches, hours, shift, structure, surplus presence, and deficit presence with date filtering.
51
+ - **`kasra_get_monthly_report`**: Aggregate monthly attendance report with period selection.
52
+ - **`kasra_get_work_periods`**: List of all available financial and attendance work periods (e.g., Shahrivar 1405, Mordad 1405, ...).
53
+ - **`kasra_export_daily_report_excel`**: Generate and download daily attendance reports directly as an Excel (`.xls`) file.
54
+
55
+ ### 3. Permissions, Leaves & Missions
56
+ - **`kasra_get_credit_types`**: List all permission types with codes:
57
+ - Hourly deficit: Hourly leave (`11001`), Hourly sick leave (`11011`), Hourly mission (`11021`), Hourly remote work (`14087`), etc.
58
+ - Daily deficit: Daily leave (`11002`), Daily sick leave (`11012`), Daily mission (`11022`), Daily remote work (`14084`), etc.
59
+ - Surplus presence: Regular overtime (`11101`), Remote overtime (`14088`), Friday overtime (`60023`), etc.
60
+ - **`kasra_submit_credit_request`**: Submit a new hourly or daily leave, mission, remote work, or overtime request with automated security tokens.
61
+ - **`kasra_get_submitted_requests`**: View all submitted permission requests and their approval/rejection status.
62
+ - **`kasra_delete_credit_request`**: Cancel/delete a submitted permission request.
63
+
64
+ ### 4. Cartable & Workflow
65
+ - **`kasra_get_cartable_items`**: View workflow documents in cartable by tab:
66
+ - `in_wait`: Requests awaiting your approval
67
+ - `confirmed`: Approved documents
68
+ - `rejected`: Rejected documents
69
+ - `refer`: Referred documents
70
+
71
+ ### 5. System Base Information
72
+ - **`kasra_get_system_shifts`**: Retrieve all defined organizational shifts (Administrative shift, Remote work shift, etc.).
73
+ - **`kasra_get_personnel_groups`**: Retrieve all organizational personnel groups and permission categories.
74
+ - **`kasra_get_holidays`**: Official holiday calendar defined in the system.
75
+ - **`kasra_get_user_menu`**: Complete hierarchy of accessible system menus and subsystems.
76
+
77
+ ---
78
+
79
+ ## ๐Ÿ“ฆ Installation
80
+
81
+ ```bash
82
+ git clone https://github.com/razavioo/kasra-mcp-server.git
83
+ cd kasra-mcp-server
84
+ pip install -r requirements.txt
85
+ ```
86
+
87
+ ---
88
+
89
+ ## โš™๏ธ Configuration
90
+
91
+ Copy the example environment file:
92
+ ```bash
93
+ cp .env.example .env
94
+ ```
95
+
96
+ Edit `.env`:
97
+ ```env
98
+ KASRA_BASE_URL=https://app.kasralite.com
99
+ KASRA_USERNAME=your_national_id_or_username
100
+ KASRA_PASSWORD=your_password
101
+ ```
102
+
103
+ ---
104
+
105
+ ## ๐Ÿ”Œ Agent Integration
106
+
107
+ You can run this MCP server either **directly without cloning** using `uvx`, via **`pip`**, or from a **local clone**.
108
+
109
+ ### Option A: Zero-Install with `uvx` (Recommended)
110
+
111
+ No need to clone the repo or manage python environments!
112
+
113
+ #### Claude Desktop (`claude_desktop_config.json`)
114
+ ```json
115
+ {
116
+ "mcpServers": {
117
+ "kasra": {
118
+ "command": "uvx",
119
+ "args": [
120
+ "--from",
121
+ "git+https://github.com/razavioo/kasra-mcp-server.git",
122
+ "kasra-mcp-server"
123
+ ],
124
+ "env": {
125
+ "KASRA_BASE_URL": "https://app.kasralite.com",
126
+ "KASRA_USERNAME": "your_username",
127
+ "KASRA_PASSWORD": "your_password"
128
+ }
129
+ }
130
+ }
131
+ }
132
+ ```
133
+
134
+ #### OpenCode (`~/.config/opencode/opencode.jsonc` or `opencode.json`)
135
+ ```json
136
+ {
137
+ "mcp": {
138
+ "kasra": {
139
+ "type": "local",
140
+ "command": [
141
+ "uvx",
142
+ "--from",
143
+ "git+https://github.com/razavioo/kasra-mcp-server.git",
144
+ "kasra-mcp-server"
145
+ ],
146
+ "environment": {
147
+ "KASRA_BASE_URL": "https://app.kasralite.com",
148
+ "KASRA_USERNAME": "your_username",
149
+ "KASRA_PASSWORD": "your_password"
150
+ },
151
+ "enabled": true
152
+ }
153
+ }
154
+ }
155
+ ```
156
+
157
+ #### Cursor (`.cursor/mcp.json`)
158
+ ```json
159
+ {
160
+ "mcpServers": {
161
+ "kasra": {
162
+ "command": "uvx --from git+https://github.com/razavioo/kasra-mcp-server.git kasra-mcp-server",
163
+ "env": {
164
+ "KASRA_BASE_URL": "https://app.kasralite.com",
165
+ "KASRA_USERNAME": "your_username",
166
+ "KASRA_PASSWORD": "your_password"
167
+ }
168
+ }
169
+ }
170
+ }
171
+ ```
172
+
173
+ ---
174
+
175
+ ### Option B: Installed via `pip`
176
+
177
+ ```bash
178
+ pip install git+https://github.com/razavioo/kasra-mcp-server.git
179
+ ```
180
+
181
+ Then in your MCP configuration:
182
+ ```json
183
+ {
184
+ "mcpServers": {
185
+ "kasra": {
186
+ "command": "kasra-mcp-server",
187
+ "env": {
188
+ "KASRA_BASE_URL": "https://app.kasralite.com",
189
+ "KASRA_USERNAME": "your_username",
190
+ "KASRA_PASSWORD": "your_password"
191
+ }
192
+ }
193
+ }
194
+ }
195
+ ```
196
+
197
+ ---
198
+
199
+ ### Option C: From Local Source
200
+
201
+ ```bash
202
+ git clone https://github.com/razavioo/kasra-mcp-server.git
203
+ cd kasra-mcp-server
204
+ pip install -r requirements.txt
205
+ ```
206
+
207
+ ```json
208
+ {
209
+ "mcpServers": {
210
+ "kasra": {
211
+ "command": "python3",
212
+ "args": [
213
+ "/path/to/kasra-mcp-server/main.py"
214
+ ],
215
+ "env": {
216
+ "KASRA_BASE_URL": "https://app.kasralite.com",
217
+ "KASRA_USERNAME": "your_username",
218
+ "KASRA_PASSWORD": "your_password"
219
+ }
220
+ }
221
+ }
222
+ }
223
+ ```
224
+
225
+ ---
226
+
227
+ ## ๐Ÿงช Testing
228
+
229
+ Test all tools directly in python:
230
+ ```bash
231
+ python3 test_tools.py
232
+ ```
233
+
234
+ ---
235
+
236
+ ## ๐Ÿ“„ License
237
+
238
+ This project is licensed under the [MIT License](LICENSE).
kasra_mcp_server-1.0.0/README.md ADDED
@@ -0,0 +1,219 @@
1
+ # Kasra Lite Attendance & Personnel MCP Server
2
+
3
+ [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
4
+ [![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-FastMCP-brightgreen.svg)](https://modelcontextprotocol.io/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+
7
+ A Model Context Protocol (MCP) server for the **Kasra Lite Attendance, Personnel, Cartable, and Leave Management System** ([app.kasralite.com](https://app.kasralite.com)).
8
+
9
+ Connect your AI agents (Claude Desktop, OpenCode, Cursor, Windsurf, etc.) directly to Kasra Lite to view attendance, punches, leaves, cardex, cartable requests, work periods, and submit leave/mission requests autonomously.
10
+
11
+ > ๐Ÿš€ **100% Pure HTTP & Async API โ€” No Headless Browser Required!**
12
+ > Runs via standard HTTP/2 APIs and AES-128-CBC encryption without downloading Chromium or running Playwright/Puppeteer. Works in any environment including headless Linux servers, Docker containers, macOS, and Windows.
13
+
14
+ ---
15
+
16
+ ## ๐ŸŒŸ Available MCP Tools (17 Tools)
17
+
18
+ ### 1. Personnel Profile & Dashboard
19
+ - **`kasra_get_profile`**: Retrieve user identity, personnel code, system ID, role, department, and recent login IP history.
20
+ - **`kasra_get_dashboard_summary`**: Real-time summary:
21
+ - Last registered punch of today (time & status)
22
+ - Cardex leave balance (hours)
23
+ - Total presence & worked hours in current period
24
+ - Permissions needed (incomplete punches, overtime, deficit)
25
+ - Request approval counters (in progress, confirmed, rejected)
26
+ - Pending cartable documents count
27
+ - **`kasra_get_desktop_shortcuts`**: Get user's pinned/favorite desktop bookmarks.
28
+ - **`kasra_get_messages`**: Retrieve broadcast announcements and system messages.
29
+
30
+ ### 2. Attendance & Reports
31
+ - **`kasra_get_daily_report`**: Day-by-day detailed breakdown of punches, hours, shift, structure, surplus presence, and deficit presence with date filtering.
32
+ - **`kasra_get_monthly_report`**: Aggregate monthly attendance report with period selection.
33
+ - **`kasra_get_work_periods`**: List of all available financial and attendance work periods (e.g., Shahrivar 1405, Mordad 1405, ...).
34
+ - **`kasra_export_daily_report_excel`**: Generate and download daily attendance reports directly as an Excel (`.xls`) file.
35
+
36
+ ### 3. Permissions, Leaves & Missions
37
+ - **`kasra_get_credit_types`**: List all permission types with codes:
38
+ - Hourly deficit: Hourly leave (`11001`), Hourly sick leave (`11011`), Hourly mission (`11021`), Hourly remote work (`14087`), etc.
39
+ - Daily deficit: Daily leave (`11002`), Daily sick leave (`11012`), Daily mission (`11022`), Daily remote work (`14084`), etc.
40
+ - Surplus presence: Regular overtime (`11101`), Remote overtime (`14088`), Friday overtime (`60023`), etc.
41
+ - **`kasra_submit_credit_request`**: Submit a new hourly or daily leave, mission, remote work, or overtime request with automated security tokens.
42
+ - **`kasra_get_submitted_requests`**: View all submitted permission requests and their approval/rejection status.
43
+ - **`kasra_delete_credit_request`**: Cancel/delete a submitted permission request.
44
+
45
+ ### 4. Cartable & Workflow
46
+ - **`kasra_get_cartable_items`**: View workflow documents in cartable by tab:
47
+ - `in_wait`: Requests awaiting your approval
48
+ - `confirmed`: Approved documents
49
+ - `rejected`: Rejected documents
50
+ - `refer`: Referred documents
51
+
52
+ ### 5. System Base Information
53
+ - **`kasra_get_system_shifts`**: Retrieve all defined organizational shifts (Administrative shift, Remote work shift, etc.).
54
+ - **`kasra_get_personnel_groups`**: Retrieve all organizational personnel groups and permission categories.
55
+ - **`kasra_get_holidays`**: Official holiday calendar defined in the system.
56
+ - **`kasra_get_user_menu`**: Complete hierarchy of accessible system menus and subsystems.
57
+
58
+ ---
59
+
60
+ ## ๐Ÿ“ฆ Installation
61
+
62
+ ```bash
63
+ git clone https://github.com/razavioo/kasra-mcp-server.git
64
+ cd kasra-mcp-server
65
+ pip install -r requirements.txt
66
+ ```
67
+
68
+ ---
69
+
70
+ ## โš™๏ธ Configuration
71
+
72
+ Copy the example environment file:
73
+ ```bash
74
+ cp .env.example .env
75
+ ```
76
+
77
+ Edit `.env`:
78
+ ```env
79
+ KASRA_BASE_URL=https://app.kasralite.com
80
+ KASRA_USERNAME=your_national_id_or_username
81
+ KASRA_PASSWORD=your_password
82
+ ```
83
+
84
+ ---
85
+
86
+ ## ๐Ÿ”Œ Agent Integration
87
+
88
+ You can run this MCP server either **directly without cloning** using `uvx`, via **`pip`**, or from a **local clone**.
89
+
90
+ ### Option A: Zero-Install with `uvx` (Recommended)
91
+
92
+ No need to clone the repo or manage python environments!
93
+
94
+ #### Claude Desktop (`claude_desktop_config.json`)
95
+ ```json
96
+ {
97
+ "mcpServers": {
98
+ "kasra": {
99
+ "command": "uvx",
100
+ "args": [
101
+ "--from",
102
+ "git+https://github.com/razavioo/kasra-mcp-server.git",
103
+ "kasra-mcp-server"
104
+ ],
105
+ "env": {
106
+ "KASRA_BASE_URL": "https://app.kasralite.com",
107
+ "KASRA_USERNAME": "your_username",
108
+ "KASRA_PASSWORD": "your_password"
109
+ }
110
+ }
111
+ }
112
+ }
113
+ ```
114
+
115
+ #### OpenCode (`~/.config/opencode/opencode.jsonc` or `opencode.json`)
116
+ ```json
117
+ {
118
+ "mcp": {
119
+ "kasra": {
120
+ "type": "local",
121
+ "command": [
122
+ "uvx",
123
+ "--from",
124
+ "git+https://github.com/razavioo/kasra-mcp-server.git",
125
+ "kasra-mcp-server"
126
+ ],
127
+ "environment": {
128
+ "KASRA_BASE_URL": "https://app.kasralite.com",
129
+ "KASRA_USERNAME": "your_username",
130
+ "KASRA_PASSWORD": "your_password"
131
+ },
132
+ "enabled": true
133
+ }
134
+ }
135
+ }
136
+ ```
137
+
138
+ #### Cursor (`.cursor/mcp.json`)
139
+ ```json
140
+ {
141
+ "mcpServers": {
142
+ "kasra": {
143
+ "command": "uvx --from git+https://github.com/razavioo/kasra-mcp-server.git kasra-mcp-server",
144
+ "env": {
145
+ "KASRA_BASE_URL": "https://app.kasralite.com",
146
+ "KASRA_USERNAME": "your_username",
147
+ "KASRA_PASSWORD": "your_password"
148
+ }
149
+ }
150
+ }
151
+ }
152
+ ```
153
+
154
+ ---
155
+
156
+ ### Option B: Installed via `pip`
157
+
158
+ ```bash
159
+ pip install git+https://github.com/razavioo/kasra-mcp-server.git
160
+ ```
161
+
162
+ Then in your MCP configuration:
163
+ ```json
164
+ {
165
+ "mcpServers": {
166
+ "kasra": {
167
+ "command": "kasra-mcp-server",
168
+ "env": {
169
+ "KASRA_BASE_URL": "https://app.kasralite.com",
170
+ "KASRA_USERNAME": "your_username",
171
+ "KASRA_PASSWORD": "your_password"
172
+ }
173
+ }
174
+ }
175
+ }
176
+ ```
177
+
178
+ ---
179
+
180
+ ### Option C: From Local Source
181
+
182
+ ```bash
183
+ git clone https://github.com/razavioo/kasra-mcp-server.git
184
+ cd kasra-mcp-server
185
+ pip install -r requirements.txt
186
+ ```
187
+
188
+ ```json
189
+ {
190
+ "mcpServers": {
191
+ "kasra": {
192
+ "command": "python3",
193
+ "args": [
194
+ "/path/to/kasra-mcp-server/main.py"
195
+ ],
196
+ "env": {
197
+ "KASRA_BASE_URL": "https://app.kasralite.com",
198
+ "KASRA_USERNAME": "your_username",
199
+ "KASRA_PASSWORD": "your_password"
200
+ }
201
+ }
202
+ }
203
+ }
204
+ ```
205
+
206
+ ---
207
+
208
+ ## ๐Ÿงช Testing
209
+
210
+ Test all tools directly in python:
211
+ ```bash
212
+ python3 test_tools.py
213
+ ```
214
+
215
+ ---
216
+
217
+ ## ๐Ÿ“„ License
218
+
219
+ This project is licensed under the [MIT License](LICENSE).