itu-mcp 0.2.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 (43) hide show
  1. itu_mcp-0.2.0/LICENSE +21 -0
  2. itu_mcp-0.2.0/PKG-INFO +341 -0
  3. itu_mcp-0.2.0/README.md +304 -0
  4. itu_mcp-0.2.0/pyproject.toml +61 -0
  5. itu_mcp-0.2.0/setup.cfg +4 -0
  6. itu_mcp-0.2.0/src/itu_mcp.egg-info/PKG-INFO +341 -0
  7. itu_mcp-0.2.0/src/itu_mcp.egg-info/SOURCES.txt +41 -0
  8. itu_mcp-0.2.0/src/itu_mcp.egg-info/dependency_links.txt +1 -0
  9. itu_mcp-0.2.0/src/itu_mcp.egg-info/entry_points.txt +5 -0
  10. itu_mcp-0.2.0/src/itu_mcp.egg-info/requires.txt +11 -0
  11. itu_mcp-0.2.0/src/itu_mcp.egg-info/top_level.txt +1 -0
  12. itu_mcp-0.2.0/src/ninova_mcp/__init__.py +5 -0
  13. itu_mcp-0.2.0/src/ninova_mcp/__main__.py +4 -0
  14. itu_mcp-0.2.0/src/ninova_mcp/attendance_summary.py +189 -0
  15. itu_mcp-0.2.0/src/ninova_mcp/cache.py +57 -0
  16. itu_mcp-0.2.0/src/ninova_mcp/client.py +472 -0
  17. itu_mcp-0.2.0/src/ninova_mcp/compact.py +140 -0
  18. itu_mcp-0.2.0/src/ninova_mcp/env.py +79 -0
  19. itu_mcp-0.2.0/src/ninova_mcp/gpa.py +143 -0
  20. itu_mcp-0.2.0/src/ninova_mcp/obs_client.py +872 -0
  21. itu_mcp-0.2.0/src/ninova_mcp/parsing.py +2018 -0
  22. itu_mcp-0.2.0/src/ninova_mcp/remote.py +212 -0
  23. itu_mcp-0.2.0/src/ninova_mcp/remote_security.py +183 -0
  24. itu_mcp-0.2.0/src/ninova_mcp/schedule_utils.py +95 -0
  25. itu_mcp-0.2.0/src/ninova_mcp/server.py +3217 -0
  26. itu_mcp-0.2.0/src/ninova_mcp/session_store.py +153 -0
  27. itu_mcp-0.2.0/src/ninova_mcp/text_extract.py +185 -0
  28. itu_mcp-0.2.0/src/ninova_mcp/tracking.py +214 -0
  29. itu_mcp-0.2.0/tests/test_cache.py +40 -0
  30. itu_mcp-0.2.0/tests/test_cli.py +77 -0
  31. itu_mcp-0.2.0/tests/test_compact.py +43 -0
  32. itu_mcp-0.2.0/tests/test_env.py +133 -0
  33. itu_mcp-0.2.0/tests/test_gpa_schedule.py +128 -0
  34. itu_mcp-0.2.0/tests/test_mcpb_bootstrap.py +54 -0
  35. itu_mcp-0.2.0/tests/test_obs.py +575 -0
  36. itu_mcp-0.2.0/tests/test_parsing.py +480 -0
  37. itu_mcp-0.2.0/tests/test_remote_security.py +106 -0
  38. itu_mcp-0.2.0/tests/test_server_cache.py +123 -0
  39. itu_mcp-0.2.0/tests/test_server_protocol.py +79 -0
  40. itu_mcp-0.2.0/tests/test_session_store.py +121 -0
  41. itu_mcp-0.2.0/tests/test_text_extract.py +90 -0
  42. itu_mcp-0.2.0/tests/test_tracking.py +84 -0
  43. itu_mcp-0.2.0/tests/test_upload.py +155 -0
itu_mcp-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hikmet Gultekin
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.
itu_mcp-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,341 @@
1
+ Metadata-Version: 2.4
2
+ Name: itu-mcp
3
+ Version: 0.2.0
4
+ Summary: MCP server for İTÜ Ninova (LMS) and OBS (student portal): courses, grades, deadlines, transcript, and more for Claude, Cursor, Codex.
5
+ Author: yatuk
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/yatuk/itu-mcp
8
+ Project-URL: Repository, https://github.com/yatuk/itu-mcp
9
+ Project-URL: Issues, https://github.com/yatuk/itu-mcp/issues
10
+ Keywords: mcp,model-context-protocol,ninova,obs,itu,claude,cursor
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Education
14
+ Classifier: Intended Audience :: End Users/Desktop
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Education
21
+ Classifier: Topic :: Internet :: WWW/HTTP
22
+ Classifier: Typing :: Typed
23
+ Requires-Python: >=3.11
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Requires-Dist: beautifulsoup4>=4.12.0
27
+ Requires-Dist: lxml>=5.0.0
28
+ Requires-Dist: mcp<2,>=1.27.0
29
+ Requires-Dist: pypdf>=4.0.0
30
+ Requires-Dist: python-docx>=1.1.0
31
+ Requires-Dist: requests>=2.31.0
32
+ Requires-Dist: starlette>=0.37.2
33
+ Requires-Dist: uvicorn>=0.30.0
34
+ Provides-Extra: playwright
35
+ Requires-Dist: playwright>=1.40; extra == "playwright"
36
+ Dynamic: license-file
37
+
38
+ <div align="center">
39
+
40
+ <p>
41
+ <img src="docs/logo.png" alt="İTÜ MCP" width="120" />
42
+ </p>
43
+
44
+ <h1>İTÜ MCP</h1>
45
+
46
+ <p><em>İTÜ Ninova ve OBS hesabını Claude, Cursor, Codex ve diğer MCP istemcilerine bağla</em></p>
47
+
48
+ <p>
49
+ <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/sürüm-v0.2.0-blue?style=flat-square" alt="Sürüm: v0.2.0" /></a>
50
+ <a href="LICENSE"><img src="https://img.shields.io/badge/lisans-MIT-green?style=flat-square" alt="Lisans: MIT" /></a>
51
+ <a href="https://github.com/yatuk/itu-mcp"><img src="https://img.shields.io/badge/python-3.11+-3776AB?logo=python&logoColor=white&style=flat-square" alt="Python 3.11+" /></a>
52
+ <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-sunucu-black?style=flat-square" alt="MCP Sunucu" /></a>
53
+ </p>
54
+
55
+ <br />
56
+
57
+ <table>
58
+ <tr>
59
+ <td align="center"><strong>Ninova</strong><br/><code>LMS</code></td>
60
+ <td align="center"><strong>OBS</strong><br/><code>Öğrenci portalı</code></td>
61
+ <td align="center"><strong>MCP</strong><br/><code>Claude · Cursor · Codex</code></td>
62
+ </tr>
63
+ <tr>
64
+ <td align="center">Dersler · dosyalar · ödevler<br/>duyurular · teslim tarihleri</td>
65
+ <td align="center">Kayıt · notlar<br/>transkript · danışman · staj</td>
66
+ <td align="center">Doğal dilde sor<br/>(TR / EN)</td>
67
+ </tr>
68
+ </table>
69
+ </div>
70
+
71
+ <br />
72
+
73
+ ---
74
+
75
+ ## İTÜ MCP nedir?
76
+
77
+ **İTÜ MCP** bilgisayarında çalışır ve kendi İTÜ hesabını yapay zeka asistanlarına bağlar. Kimlik bilgilerinle (genelde `ad@itu.edu.tr`) giriş yapar, **Ninova** ve **OBS** üzerinden veri okur, [Model Context Protocol](https://modelcontextprotocol.io) üzerinden yapılandırılmış araçlar sunar.
78
+
79
+ | İhtiyacın | İTÜ MCP cevabı |
80
+ |:---|---|
81
+ | "Bu hafta hangi ödevlerin teslimi var?" | Ninova ödev ve teslim tarihi araçları |
82
+ | "X dersinin notları / yoklaması?" | OBS ara not, harf notu ve yoklama |
83
+ | "Transkript / danışman / staj?" | OBS profil, danışman, staj, transkript PDF |
84
+ | "PDF özetle" | İndirme + `read_resource_text` (PDF/DOCX) |
85
+ | "Ödev yükle" | İsteğe bağlı yükleme, `confirm=true` şart |
86
+
87
+ > **Önce yerel.** Şifren cihazda kalır; yalnızca İTÜ giriş / Ninova / OBS adreslerine gönderilir. Üçüncü taraf bir sunucuya kimlik bilgisi depolanmaz.
88
+ >
89
+ > **İTÜ ile resmi bağlantısı yoktur.** Yalnızca kendi hesabınla kullan.
90
+
91
+ ---
92
+
93
+ ## Örnekler
94
+
95
+ Claude Desktop üzerinden doğal dilde soru sorma örnekleri:
96
+
97
+ <p align="center">
98
+ <img src="docs/bu_dönem_hangi_dersler.png" alt="Bu dönem hangi dersleri aldım" width="720" />
99
+ <br />
100
+ <em>OBS: dönem kayıtlı dersler ve program</em>
101
+ </p>
102
+
103
+ <p align="center">
104
+ <img src="docs/son_duyurular.png" alt="Son duyurular ve mesajlar" width="720" />
105
+ <br />
106
+ <em>Ninova: son duyurular ve mesaj panosu özeti</em>
107
+ </p>
108
+
109
+ ---
110
+
111
+ ## Mimari
112
+
113
+ ```mermaid
114
+ flowchart LR
115
+ subgraph istemciler["MCP İstemcileri"]
116
+ claude["Claude Desktop"]
117
+ claude_code["Claude Code"]
118
+ cursor["Cursor"]
119
+ codex["Codex"]
120
+ end
121
+
122
+ subgraph sunucu["itu-mcp (Python 3.11+)"]
123
+ mcp["MCP Sunucu<br/>(FastMCP · stdio / HTTP)"]
124
+ ninova_client["NinovaClient<br/>SSO · HTML parse"]
125
+ obs_client["ObsClient<br/>JWT · JSON API"]
126
+ obs_public["ObsPublicClient<br/>kimliksiz · HTML/JSON"]
127
+ state["Durum<br/>çerez · anlık görüntü · indirme"]
128
+ end
129
+
130
+ subgraph itu["İTÜ Sunucuları"]
131
+ ninova["ninova.itu.edu.tr<br/>(LMS · HTML)"]
132
+ giris["girisv3.itu.edu.tr<br/>(İTÜ SSO giriş)"]
133
+ obs["obs.itu.edu.tr<br/>(öğrenci JSON API)"]
134
+ obs_pub["obs.itu.edu.tr/public<br/>(açık katalog · program)"]
135
+ end
136
+
137
+ istemciler -->|"MCP araçları"| mcp
138
+ mcp --> ninova_client
139
+ mcp --> obs_client
140
+ mcp --> obs_public
141
+ ninova_client --> giris
142
+ ninova_client --> ninova
143
+ obs_client --> giris
144
+ obs_client --> obs
145
+ obs_public --> obs_pub
146
+ ninova_client --> state
147
+ obs_client --> state
148
+ obs_public --> state
149
+ ```
150
+
151
+
152
+ | Katman | Rol |
153
+ |---|---|
154
+ | **MCP sunucu** | Araç listesi, sade yanıtlar, CLI (`--check-auth`, `--list-tools`) |
155
+ | **Ninova istemcisi** | Oturum + HTML ayrıştırma (duyuru, dosya, ödev, yükleme formu) |
156
+ | **OBS istemcisi** | SSO → `/ogrenci/auth/jwt` → `/api/ogrenci/...` |
157
+ | **OBS public istemcisi** | Kimliksiz → `/public/DersProgram`, `/public/DersBilgi`, `/public/GenelTanimlamalar/...` |
158
+ | **Durum** | İsteğe bağlı çerez önbelleği, izleme anlık görüntüleri, indirmeler (`~/.ninova_state`) |
159
+
160
+ ---
161
+
162
+ ## Hızlı başlangıç
163
+
164
+ ### 1. Kurulum
165
+
166
+ ```bash
167
+ pipx install itu-mcp
168
+ # veya: pip install --user itu-mcp
169
+ # kaynaktan:
170
+ # git clone https://github.com/yatuk/itu-mcp.git
171
+ # cd itu-mcp && pip install -e .
172
+ ```
173
+
174
+ ### 2. Kimlik bilgileri
175
+
176
+ ```bash
177
+ cp .env.example .env
178
+ # NINOVA_USERNAME=ad.soyad@itu.edu.tr
179
+ # NINOVA_PASSWORD=********
180
+ ```
181
+
182
+ Kullanıcı adı genelde **İTÜ e-posta** adresindir; yalnızca yerel kısım değil.
183
+
184
+ ### 3. Duman testi
185
+
186
+ ```bash
187
+ itu-mcp --version
188
+ itu-mcp --check-auth
189
+ itu-mcp --list-tools
190
+ ```
191
+
192
+ ### 4. MCP istemcisini bağla
193
+
194
+ **Claude Code**
195
+
196
+ ```bash
197
+ claude mcp add itu itu-mcp \
198
+ -e NINOVA_USERNAME=ad.soyad@itu.edu.tr \
199
+ -e NINOVA_PASSWORD=sifren
200
+ ```
201
+
202
+ **Codex CLI**
203
+
204
+ ```bash
205
+ codex mcp add itu \
206
+ --env NINOVA_USERNAME=ad.soyad@itu.edu.tr \
207
+ --env NINOVA_PASSWORD=sifren \
208
+ -- itu-mcp
209
+ ```
210
+
211
+ **Claude Desktop / Cursor:** [docs/installation.md](docs/installation.md) ve `examples/` klasörüne bak.
212
+
213
+ > **Bitti.** İstemciyi yeniden başlat ve sor: *"Ninova'daki derslerimi listele"* veya *"OBS'te bu dönem kayıtlı derslerim?"*
214
+
215
+ ---
216
+
217
+ ## Ne sorabilirsin?
218
+
219
+ - *"Bu hafta hangi ödevlerimin teslimi var?"*
220
+ - *"EEF 211E sınıf dosyalarındaki PDF'i oku."*
221
+ - *"OBS'te 2025-2026 Bahar kayıtlı derslerim neler?"*
222
+ - *"CEN 354E ara notlarım?"*
223
+ - *"Danışmanım kim? Staj bilgilerimi göster."*
224
+ - *"Transkript PDF indir."*
225
+ - *"BLG bölümünde bu dönem hangi dersler açılmış, kontenjan durumu ne?"*<sup>✨</sup>
226
+ - *"BLG 223E'yi almak için önce hangi dersleri almam lazım?"*<sup>✨</sup>
227
+
228
+ <sup>✨</sup> <sub>Kimlik gerektirmez — `.env` olmadan da çalışır.</sub>
229
+
230
+ ---
231
+
232
+ ## Araç haritası
233
+
234
+ <table>
235
+ <tr>
236
+ <td align="center" width="33%"><strong>Ninova (LMS)</strong><br/><sub>oturum gerekir</sub></td>
237
+ <td align="center" width="33%"><strong>OBS (portal)</strong><br/><sub>oturum gerekir</sub></td>
238
+ <td align="center" width="33%"><strong>OBS Public</strong><br/><sub>kimlik gerekmez ✨</sub></td>
239
+ </tr>
240
+ <tr>
241
+ <td>
242
+ <code>auth_status</code> · <code>list_courses</code><br/>
243
+ <code>get_course_*</code> · <code>sync_all_courses</code><br/>
244
+ <code>get_upcoming_deadlines</code><br/>
245
+ <code>read_resource_text</code> · <code>submit_assignment</code>
246
+ </td>
247
+ <td>
248
+ <code>obs_auth_status</code> · <code>obs_get_profile</code><br/>
249
+ <code>obs_list_registered_courses</code><br/>
250
+ <code>obs_get_course_grades</code> · <code>obs_get_attendance</code><br/>
251
+ <code>obs_get_advisor</code> · <code>obs_download_transcript</code><br/>
252
+ <code>obs_get_schedule</code> · <code>obs_get_internships</code>
253
+ </td>
254
+ <td>
255
+ <code>obs_search_courses</code><br/>
256
+ <code>obs_get_course_prerequisites</code><br/>
257
+ <code>get_public_course_schedule</code><br/>
258
+ <code>get_public_course_prerequisites</code>
259
+ </td>
260
+ </tr>
261
+ </table>
262
+
263
+ Tam araç listesi, Docker, uzak HTTP, ortam değişkenleri: **[docs/advanced.md](docs/advanced.md)**.
264
+
265
+ ---
266
+
267
+ ## Güvenlik
268
+
269
+ | Yap | Yapma |
270
+ |---|---|
271
+ | Yalnızca **kendi** İTÜ hesabını kullan | `.env` veya çerezleri commit etme |
272
+ | **Yerel stdio** MCP tercih et | Uzak MCP URL / API anahtarını paylaşma |
273
+ | `submit_assignment` yalnızca **`confirm=true`** ile | Önizlemeyi okumadan ödev yükleme |
274
+ | Uzak kurulumda `NINOVA_REMOTE_API_KEY` kullan | Gizli path ve anahtar olmadan public açma |
275
+
276
+ Ayrıntılar: [docs/security.md](docs/security.md).
277
+
278
+ OBS profil araçları TCKN / telefonu **varsayılan olarak gizler** (`include_sensitive=true` ile açılır).
279
+
280
+ ---
281
+
282
+ ## Yapılandırma (isteğe bağlı)
283
+
284
+ ```bash
285
+ export NINOVA_COURSE_CACHE_TTL_SECONDS=60
286
+ export NINOVA_REQUEST_DELAY_MS=120
287
+ export NINOVA_SESSION_PERSIST=1
288
+ export NINOVA_COMPACT_DEFAULT=0
289
+ export NINOVA_ALLOW_UPLOADS=1
290
+ export NINOVA_OBS_BASE_URL=https://obs.itu.edu.tr
291
+ export NINOVA_OBS_PUBLIC_CACHE_TTL_SECONDS=3600
292
+ export NINOVA_PUBLIC_SCHEDULE_CACHE_TTL_SECONDS=60
293
+ ```
294
+
295
+ `.env.example` ve [docs/advanced.md](docs/advanced.md) dosyalarına bak.
296
+
297
+ ---
298
+
299
+ ## Geliştirme
300
+
301
+ ```bash
302
+ git clone https://github.com/yatuk/itu-mcp.git
303
+ cd itu-mcp
304
+ python -m venv .venv
305
+ # Windows: .venv\Scripts\activate
306
+ source .venv/bin/activate
307
+ pip install -e ".[playwright]"
308
+ python -m unittest discover -s tests -v
309
+ ```
310
+
311
+ ---
312
+
313
+ ## Bağlantılar
314
+
315
+ | Kaynak | URL |
316
+ |---|---|
317
+ | **Kurulum** | [docs/installation.md](docs/installation.md) |
318
+ | **Gelişmiş / araçlar** | [docs/advanced.md](docs/advanced.md) |
319
+ | **Güvenlik** | [docs/security.md](docs/security.md) |
320
+ | **Değişiklik günlüğü** | [CHANGELOG.md](CHANGELOG.md) |
321
+ | **Sorunlar** | [github.com/yatuk/itu-mcp/issues](https://github.com/yatuk/itu-mcp/issues) |
322
+
323
+ ---
324
+
325
+ ## Teşekkür
326
+
327
+ Bu proje, [**Hikmet Gultekin**](https://github.com/hikmedit) tarafından yazılan orijinal **[ninova-mcp](https://github.com/hikmedit/ninova-mcp)** çalışmasının üzerine kurulmuştur. İlk açık kaynak, kimlik bilgisiyle çalışan İTÜ Ninova MCP sunucusudur (LMS giriş, HTML ayrıştırma, izleme, `.mcpb` paketleme).
328
+
329
+ İTÜ MCP bu temeli genişletir: OBS öğrenci portalı API'leri, PDF metin okuma, güvenli ödev yükleme, oturum kalıcılığı, uzak API anahtarı ve bu depo altında yeniden paketleme.
330
+
331
+ ---
332
+
333
+ ## Lisans
334
+
335
+ [MIT](LICENSE). İstanbul Teknik Üniversitesi ile resmi bağlantısı yoktur.
336
+
337
+ <br />
338
+
339
+ <div align="center">
340
+ <sub><a href="https://github.com/yatuk">yatuk</a> tarafından · <a href="https://github.com/yatuk/itu-mcp">GitHub</a></sub>
341
+ </div>
itu_mcp-0.2.0/README.md ADDED
@@ -0,0 +1,304 @@
1
+ <div align="center">
2
+
3
+ <p>
4
+ <img src="docs/logo.png" alt="İTÜ MCP" width="120" />
5
+ </p>
6
+
7
+ <h1>İTÜ MCP</h1>
8
+
9
+ <p><em>İTÜ Ninova ve OBS hesabını Claude, Cursor, Codex ve diğer MCP istemcilerine bağla</em></p>
10
+
11
+ <p>
12
+ <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/sürüm-v0.2.0-blue?style=flat-square" alt="Sürüm: v0.2.0" /></a>
13
+ <a href="LICENSE"><img src="https://img.shields.io/badge/lisans-MIT-green?style=flat-square" alt="Lisans: MIT" /></a>
14
+ <a href="https://github.com/yatuk/itu-mcp"><img src="https://img.shields.io/badge/python-3.11+-3776AB?logo=python&logoColor=white&style=flat-square" alt="Python 3.11+" /></a>
15
+ <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-sunucu-black?style=flat-square" alt="MCP Sunucu" /></a>
16
+ </p>
17
+
18
+ <br />
19
+
20
+ <table>
21
+ <tr>
22
+ <td align="center"><strong>Ninova</strong><br/><code>LMS</code></td>
23
+ <td align="center"><strong>OBS</strong><br/><code>Öğrenci portalı</code></td>
24
+ <td align="center"><strong>MCP</strong><br/><code>Claude · Cursor · Codex</code></td>
25
+ </tr>
26
+ <tr>
27
+ <td align="center">Dersler · dosyalar · ödevler<br/>duyurular · teslim tarihleri</td>
28
+ <td align="center">Kayıt · notlar<br/>transkript · danışman · staj</td>
29
+ <td align="center">Doğal dilde sor<br/>(TR / EN)</td>
30
+ </tr>
31
+ </table>
32
+ </div>
33
+
34
+ <br />
35
+
36
+ ---
37
+
38
+ ## İTÜ MCP nedir?
39
+
40
+ **İTÜ MCP** bilgisayarında çalışır ve kendi İTÜ hesabını yapay zeka asistanlarına bağlar. Kimlik bilgilerinle (genelde `ad@itu.edu.tr`) giriş yapar, **Ninova** ve **OBS** üzerinden veri okur, [Model Context Protocol](https://modelcontextprotocol.io) üzerinden yapılandırılmış araçlar sunar.
41
+
42
+ | İhtiyacın | İTÜ MCP cevabı |
43
+ |:---|---|
44
+ | "Bu hafta hangi ödevlerin teslimi var?" | Ninova ödev ve teslim tarihi araçları |
45
+ | "X dersinin notları / yoklaması?" | OBS ara not, harf notu ve yoklama |
46
+ | "Transkript / danışman / staj?" | OBS profil, danışman, staj, transkript PDF |
47
+ | "PDF özetle" | İndirme + `read_resource_text` (PDF/DOCX) |
48
+ | "Ödev yükle" | İsteğe bağlı yükleme, `confirm=true` şart |
49
+
50
+ > **Önce yerel.** Şifren cihazda kalır; yalnızca İTÜ giriş / Ninova / OBS adreslerine gönderilir. Üçüncü taraf bir sunucuya kimlik bilgisi depolanmaz.
51
+ >
52
+ > **İTÜ ile resmi bağlantısı yoktur.** Yalnızca kendi hesabınla kullan.
53
+
54
+ ---
55
+
56
+ ## Örnekler
57
+
58
+ Claude Desktop üzerinden doğal dilde soru sorma örnekleri:
59
+
60
+ <p align="center">
61
+ <img src="docs/bu_dönem_hangi_dersler.png" alt="Bu dönem hangi dersleri aldım" width="720" />
62
+ <br />
63
+ <em>OBS: dönem kayıtlı dersler ve program</em>
64
+ </p>
65
+
66
+ <p align="center">
67
+ <img src="docs/son_duyurular.png" alt="Son duyurular ve mesajlar" width="720" />
68
+ <br />
69
+ <em>Ninova: son duyurular ve mesaj panosu özeti</em>
70
+ </p>
71
+
72
+ ---
73
+
74
+ ## Mimari
75
+
76
+ ```mermaid
77
+ flowchart LR
78
+ subgraph istemciler["MCP İstemcileri"]
79
+ claude["Claude Desktop"]
80
+ claude_code["Claude Code"]
81
+ cursor["Cursor"]
82
+ codex["Codex"]
83
+ end
84
+
85
+ subgraph sunucu["itu-mcp (Python 3.11+)"]
86
+ mcp["MCP Sunucu<br/>(FastMCP · stdio / HTTP)"]
87
+ ninova_client["NinovaClient<br/>SSO · HTML parse"]
88
+ obs_client["ObsClient<br/>JWT · JSON API"]
89
+ obs_public["ObsPublicClient<br/>kimliksiz · HTML/JSON"]
90
+ state["Durum<br/>çerez · anlık görüntü · indirme"]
91
+ end
92
+
93
+ subgraph itu["İTÜ Sunucuları"]
94
+ ninova["ninova.itu.edu.tr<br/>(LMS · HTML)"]
95
+ giris["girisv3.itu.edu.tr<br/>(İTÜ SSO giriş)"]
96
+ obs["obs.itu.edu.tr<br/>(öğrenci JSON API)"]
97
+ obs_pub["obs.itu.edu.tr/public<br/>(açık katalog · program)"]
98
+ end
99
+
100
+ istemciler -->|"MCP araçları"| mcp
101
+ mcp --> ninova_client
102
+ mcp --> obs_client
103
+ mcp --> obs_public
104
+ ninova_client --> giris
105
+ ninova_client --> ninova
106
+ obs_client --> giris
107
+ obs_client --> obs
108
+ obs_public --> obs_pub
109
+ ninova_client --> state
110
+ obs_client --> state
111
+ obs_public --> state
112
+ ```
113
+
114
+
115
+ | Katman | Rol |
116
+ |---|---|
117
+ | **MCP sunucu** | Araç listesi, sade yanıtlar, CLI (`--check-auth`, `--list-tools`) |
118
+ | **Ninova istemcisi** | Oturum + HTML ayrıştırma (duyuru, dosya, ödev, yükleme formu) |
119
+ | **OBS istemcisi** | SSO → `/ogrenci/auth/jwt` → `/api/ogrenci/...` |
120
+ | **OBS public istemcisi** | Kimliksiz → `/public/DersProgram`, `/public/DersBilgi`, `/public/GenelTanimlamalar/...` |
121
+ | **Durum** | İsteğe bağlı çerez önbelleği, izleme anlık görüntüleri, indirmeler (`~/.ninova_state`) |
122
+
123
+ ---
124
+
125
+ ## Hızlı başlangıç
126
+
127
+ ### 1. Kurulum
128
+
129
+ ```bash
130
+ pipx install itu-mcp
131
+ # veya: pip install --user itu-mcp
132
+ # kaynaktan:
133
+ # git clone https://github.com/yatuk/itu-mcp.git
134
+ # cd itu-mcp && pip install -e .
135
+ ```
136
+
137
+ ### 2. Kimlik bilgileri
138
+
139
+ ```bash
140
+ cp .env.example .env
141
+ # NINOVA_USERNAME=ad.soyad@itu.edu.tr
142
+ # NINOVA_PASSWORD=********
143
+ ```
144
+
145
+ Kullanıcı adı genelde **İTÜ e-posta** adresindir; yalnızca yerel kısım değil.
146
+
147
+ ### 3. Duman testi
148
+
149
+ ```bash
150
+ itu-mcp --version
151
+ itu-mcp --check-auth
152
+ itu-mcp --list-tools
153
+ ```
154
+
155
+ ### 4. MCP istemcisini bağla
156
+
157
+ **Claude Code**
158
+
159
+ ```bash
160
+ claude mcp add itu itu-mcp \
161
+ -e NINOVA_USERNAME=ad.soyad@itu.edu.tr \
162
+ -e NINOVA_PASSWORD=sifren
163
+ ```
164
+
165
+ **Codex CLI**
166
+
167
+ ```bash
168
+ codex mcp add itu \
169
+ --env NINOVA_USERNAME=ad.soyad@itu.edu.tr \
170
+ --env NINOVA_PASSWORD=sifren \
171
+ -- itu-mcp
172
+ ```
173
+
174
+ **Claude Desktop / Cursor:** [docs/installation.md](docs/installation.md) ve `examples/` klasörüne bak.
175
+
176
+ > **Bitti.** İstemciyi yeniden başlat ve sor: *"Ninova'daki derslerimi listele"* veya *"OBS'te bu dönem kayıtlı derslerim?"*
177
+
178
+ ---
179
+
180
+ ## Ne sorabilirsin?
181
+
182
+ - *"Bu hafta hangi ödevlerimin teslimi var?"*
183
+ - *"EEF 211E sınıf dosyalarındaki PDF'i oku."*
184
+ - *"OBS'te 2025-2026 Bahar kayıtlı derslerim neler?"*
185
+ - *"CEN 354E ara notlarım?"*
186
+ - *"Danışmanım kim? Staj bilgilerimi göster."*
187
+ - *"Transkript PDF indir."*
188
+ - *"BLG bölümünde bu dönem hangi dersler açılmış, kontenjan durumu ne?"*<sup>✨</sup>
189
+ - *"BLG 223E'yi almak için önce hangi dersleri almam lazım?"*<sup>✨</sup>
190
+
191
+ <sup>✨</sup> <sub>Kimlik gerektirmez — `.env` olmadan da çalışır.</sub>
192
+
193
+ ---
194
+
195
+ ## Araç haritası
196
+
197
+ <table>
198
+ <tr>
199
+ <td align="center" width="33%"><strong>Ninova (LMS)</strong><br/><sub>oturum gerekir</sub></td>
200
+ <td align="center" width="33%"><strong>OBS (portal)</strong><br/><sub>oturum gerekir</sub></td>
201
+ <td align="center" width="33%"><strong>OBS Public</strong><br/><sub>kimlik gerekmez ✨</sub></td>
202
+ </tr>
203
+ <tr>
204
+ <td>
205
+ <code>auth_status</code> · <code>list_courses</code><br/>
206
+ <code>get_course_*</code> · <code>sync_all_courses</code><br/>
207
+ <code>get_upcoming_deadlines</code><br/>
208
+ <code>read_resource_text</code> · <code>submit_assignment</code>
209
+ </td>
210
+ <td>
211
+ <code>obs_auth_status</code> · <code>obs_get_profile</code><br/>
212
+ <code>obs_list_registered_courses</code><br/>
213
+ <code>obs_get_course_grades</code> · <code>obs_get_attendance</code><br/>
214
+ <code>obs_get_advisor</code> · <code>obs_download_transcript</code><br/>
215
+ <code>obs_get_schedule</code> · <code>obs_get_internships</code>
216
+ </td>
217
+ <td>
218
+ <code>obs_search_courses</code><br/>
219
+ <code>obs_get_course_prerequisites</code><br/>
220
+ <code>get_public_course_schedule</code><br/>
221
+ <code>get_public_course_prerequisites</code>
222
+ </td>
223
+ </tr>
224
+ </table>
225
+
226
+ Tam araç listesi, Docker, uzak HTTP, ortam değişkenleri: **[docs/advanced.md](docs/advanced.md)**.
227
+
228
+ ---
229
+
230
+ ## Güvenlik
231
+
232
+ | Yap | Yapma |
233
+ |---|---|
234
+ | Yalnızca **kendi** İTÜ hesabını kullan | `.env` veya çerezleri commit etme |
235
+ | **Yerel stdio** MCP tercih et | Uzak MCP URL / API anahtarını paylaşma |
236
+ | `submit_assignment` yalnızca **`confirm=true`** ile | Önizlemeyi okumadan ödev yükleme |
237
+ | Uzak kurulumda `NINOVA_REMOTE_API_KEY` kullan | Gizli path ve anahtar olmadan public açma |
238
+
239
+ Ayrıntılar: [docs/security.md](docs/security.md).
240
+
241
+ OBS profil araçları TCKN / telefonu **varsayılan olarak gizler** (`include_sensitive=true` ile açılır).
242
+
243
+ ---
244
+
245
+ ## Yapılandırma (isteğe bağlı)
246
+
247
+ ```bash
248
+ export NINOVA_COURSE_CACHE_TTL_SECONDS=60
249
+ export NINOVA_REQUEST_DELAY_MS=120
250
+ export NINOVA_SESSION_PERSIST=1
251
+ export NINOVA_COMPACT_DEFAULT=0
252
+ export NINOVA_ALLOW_UPLOADS=1
253
+ export NINOVA_OBS_BASE_URL=https://obs.itu.edu.tr
254
+ export NINOVA_OBS_PUBLIC_CACHE_TTL_SECONDS=3600
255
+ export NINOVA_PUBLIC_SCHEDULE_CACHE_TTL_SECONDS=60
256
+ ```
257
+
258
+ `.env.example` ve [docs/advanced.md](docs/advanced.md) dosyalarına bak.
259
+
260
+ ---
261
+
262
+ ## Geliştirme
263
+
264
+ ```bash
265
+ git clone https://github.com/yatuk/itu-mcp.git
266
+ cd itu-mcp
267
+ python -m venv .venv
268
+ # Windows: .venv\Scripts\activate
269
+ source .venv/bin/activate
270
+ pip install -e ".[playwright]"
271
+ python -m unittest discover -s tests -v
272
+ ```
273
+
274
+ ---
275
+
276
+ ## Bağlantılar
277
+
278
+ | Kaynak | URL |
279
+ |---|---|
280
+ | **Kurulum** | [docs/installation.md](docs/installation.md) |
281
+ | **Gelişmiş / araçlar** | [docs/advanced.md](docs/advanced.md) |
282
+ | **Güvenlik** | [docs/security.md](docs/security.md) |
283
+ | **Değişiklik günlüğü** | [CHANGELOG.md](CHANGELOG.md) |
284
+ | **Sorunlar** | [github.com/yatuk/itu-mcp/issues](https://github.com/yatuk/itu-mcp/issues) |
285
+
286
+ ---
287
+
288
+ ## Teşekkür
289
+
290
+ Bu proje, [**Hikmet Gultekin**](https://github.com/hikmedit) tarafından yazılan orijinal **[ninova-mcp](https://github.com/hikmedit/ninova-mcp)** çalışmasının üzerine kurulmuştur. İlk açık kaynak, kimlik bilgisiyle çalışan İTÜ Ninova MCP sunucusudur (LMS giriş, HTML ayrıştırma, izleme, `.mcpb` paketleme).
291
+
292
+ İTÜ MCP bu temeli genişletir: OBS öğrenci portalı API'leri, PDF metin okuma, güvenli ödev yükleme, oturum kalıcılığı, uzak API anahtarı ve bu depo altında yeniden paketleme.
293
+
294
+ ---
295
+
296
+ ## Lisans
297
+
298
+ [MIT](LICENSE). İstanbul Teknik Üniversitesi ile resmi bağlantısı yoktur.
299
+
300
+ <br />
301
+
302
+ <div align="center">
303
+ <sub><a href="https://github.com/yatuk">yatuk</a> tarafından · <a href="https://github.com/yatuk/itu-mcp">GitHub</a></sub>
304
+ </div>