内容
<div align="center">
<h1>İTÜ MCP</h1>
<p><em>将您的 İTÜ Ninova 和 OBS 账户连接到 Claude、Cursor、Codex 等 MCP 客户端</em></p>
<p>
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/%E7%89%88%E6%9C%AC-v0.2.0-blue?style=flat-square" alt="版本: v0.2.0" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/%E6%89%88%E6%9C%AC-MIT-green?style=flat-square" alt="许可证: MIT" /></a>
<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>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-%E6%9C%8C%E6%9F%B5%E9%BB%91-black?style=flat-square" alt="MCP 服务器" /></a>
</p>
<br />
<table>
<tr>
<td align="center"><strong>Ninova</strong><br/><code>LMS</code></td>
<td align="center"><strong>OBS</strong><br/><code>学生门户</code></td>
<td align="center"><strong>MCP</strong><br/><code>Claude · Cursor · Codex</code></td>
</tr>
<tr>
<td align="center">课程 · 文件 · 作业<br/>公告 · 提交截止日期</td>
<td align="center">注册 · 成绩<br/>成绩单 · 导师 · 实习</td>
<td align="center">自然语言提问<br/>(中文 / 英文)</td>
</tr>
</table>
</div>
<br />
---
## İTÜ MCP 是什么？
**İTÜ MCP** 在您的计算机上运行，并将您的 İTÜ 账户连接到人工智能助手。您可以使用您的凭证（通常为 `姓名@itu.edu.tr`）登录，**Ninova** 和 **OBS** 读取数据，并通过 [Model Context Protocol](https://modelcontextprotocol.io) 提供结构化的工具。
| 您的需求 | İTÜ MCP 回答 |
|:---|---|
| "本周有哪些作业的截止日期？" | Ninova 作业和截止日期工具 |
| "X 课程的成绩 / 出勤记录？" | OBS 中间成绩、字母成绩和出勤记录 |
| "成绩单 / 导师 / 实习？" | OBS 个人资料、导师、实习、成绩单 PDF |
| "总结 PDF" | 下载 + `read_resource_text` （PDF/DOCX） |
| "上传作业" | 可选上传，`confirm=true` 条件 |
> **本地优先。** 密码存储在设备上；仅发送到 İTÜ 登录 / Ninova / OBS 地址。不会在第三方服务器上存储凭证。
>
> **与 İTÜ 无官方关联。** 仅限您自己的账户使用。
---
## 示例
通过 Claude Desktop 进行自然语言提问示例：
<p align="center">
<img src="docs/bu_dönem_hangi_dersler.png" alt="本学期我选了哪些课程" width="720" />
<br />
<em>OBS：本学期注册课程和计划</em>
</p>
<p align="center">
<img src="docs/son_duyurular.png" alt="最近的公告和消息" width="720" />
<br />
<em>Ninova：最近的公告和消息板摘要</em>
</p>
---
## 架构
```
┌──────────────┐ stdio / HTTP ┌─────────────────────┐
│ Claude │ ◄──────────────────► │ itu-mcp │
│ Cursor │ MCP 工具 │ （Python 3.11+） │
│ Codex · … │ └──────────┬──────────┘
└──────────────┘ │
│ SSO + JWT
┌───────────────────────────┼───────────────────────────┐
▼ ▼ ▼
ninova.itu.edu.tr girisv3.itu.edu.tr obs.itu.edu.tr
（LMS HTML） （İTÜ 登录） （JSON API）
```
| 层 | 角色 |
|---|---|
| **MCP 服务器** | 工具列表，简单响应，CLI（`--check-auth`，`--list-tools`） |
| **Ninova 客户端** | 会话 + HTML 解析（公告，文件，作业，上传表单） |
| **OBS 客户端** | SSO → `/ogrenci/auth/jwt` → `/api/ogrenci/...` |
| **状态** | 可选 cookie 缓存，跟踪快照，下载（`~/.ninova_state`） |
---
## 快速开始
### 1. 安装
```bash
pipx install itu-mcp
# 或：pip install --user itu-mcp
# 从源代码：
# git clone https://github.com/yatuk/itu-mcp.git
# cd itu-mcp && pip install -e .
```
### 2. 凭证
```bash
cp .env.example .env
# NINOVA_USERNAME=姓名.姓氏@itu.edu.tr
# NINOVA_PASSWORD=********
```
用户名通常是 **İTÜ 电子邮件** 地址；不仅仅是本地部分。
### 3. 烟雾测试
```bash
itu-mcp --version
itu-mcp --check-auth
itu-mcp --list-tools
```
### 4. 连接 MCP 客户端
**Claude Code**
```bash
claude mcp add itu itu-mcp \
-e NINOVA_USERNAME=姓名.姓氏@itu.edu.tr \
-e NINOVA_PASSWORD=密码
```
**Codex CLI**
```bash
codex mcp add itu \
--env NINOVA_USERNAME=姓名.姓氏@itu.edu.tr \
--env NINOVA_PASSWORD=密码 \
-- itu-mcp
```
**Claude Desktop / Cursor:** [docs/installation.md](docs/installation.md) 和 `examples/` 目录。
> **完成。** 重新启动客户端并提问： *"列出 Ninova 上的课程"* 或 *"OBS 上本学期我注册了哪些课程？*"
---
## 你可以问什么？
- *"本周有哪些作业的截止日期？"*
- *"阅读 EEF 211E 课程文件中的 PDF。*"
- *"OBS 上 2025-2026 春季学期我注册了哪些课程？*"
- *"我的 CEN 354E 中间成绩是多少？*"
- *"我的导师是谁？显示我的实习信息。*"
- *"下载成绩单 PDF。*"
---
## 工具地图
<table>
<tr>
<td align="center" width="50%"><strong>Ninova （LMS）</strong></td>
<td align="center" width="50%"><strong>OBS （门户）</strong></td>
</tr>
<tr>
<td>
<code>auth_status</code> · <code>list_courses</code><br/>
<code>get_course_*</code> · <code>sync_all_courses</code><br/>
<code>get_upcoming_deadlines</code><br/>
<code>read_resource_text</code> · <code>submit_assignment</code>
</td>
<td>
<code>obs_auth_status</code> · <code>obs_get_profile</code><br/>
<code>obs_list_registered_courses</code><br/>
<code>obs_get_course_grades</code> · <code>obs_get_attendance</code><br/>
<code>obs_get_advisor</code> · <code>obs_download_transcript</code>
</td>
</tr>
</table>
完整的工具列表、Docker、远程 HTTP、环境变量： **[docs/advanced.md](docs/advanced.md)**。
---
## 安全
| 做 | 不要 |
|---|---|
| 仅使用您自己的 **İTÜ 账户** | 在 `.env` 或 cookie 中提交 |
| **本地 stdio** 优先使用 MCP | 共享远程 MCP URL / API 密钥 |
| 仅在 **`confirm=true`** 的情况下使用 `submit_assignment` | 在未阅读预览的情况下上传作业 |
| 在远程安装中使用 `NINOVA_REMOTE_API_KEY` | 在没有安全路径和密钥的情况下公开 |
详情： [docs/security.md](docs/security.md)。
OBS 配置文件工具 **默认隐藏** TCKN / 电话号码（使用 `include_sensitive=true` 打开）。
---
## 配置（可选）
```bash
export NINOVA_COURSE_CACHE_TTL_SECONDS=60
export NINOVA_REQUEST_DELAY_MS=120
export NINOVA_SESSION_PERSIST=1
export NINOVA_COMPACT_DEFAULT=0
export NINOVA_ALLOW_UPLOADS=1
export NINOVA_OBS_BASE_URL=https://obs.itu.edu.tr
```
参见 `.env.example` 和 [docs/advanced.md](docs/advanced.md)。
---
## 开发
```bash
git clone https://github.com/yatuk/itu-mcp.git
cd itu-mcp
python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate
pip install -e ".[playwright]"
python -m unittest discover -s tests -v
```
---
## 链接
| 资源 | URL |
|---|---|
| **安装** | [docs/installation.md](docs/installation.md) |
| **高级 / 工具** | [docs/advanced.md](docs/advanced.md) |
| **安全** | [docs/security.md](docs/security.md) |
| **变更日志** | [CHANGELOG.md](CHANGELOG.md) |
| **问题** | [github.com/yatuk/itu-mcp/issues](https://github.com/yatuk/itu-mcp/issues) |
---
## 致谢
本项目建立在 [**Hikmet Gultekin**](https://github.com/hikmedit) 编写的原始 **[ninova-mcp](https://github.com/hikmedit/ninova-mcp)** 工作基础上。第一个开源、基于凭证的 İTÜ Ninova MCP 服务器（LMS 登录、HTML 解析、跟踪、 `.mcpb` 打包）。
İTÜ MCP 扩展了这个基础：OBS 学生门户 API、PDF 文本读取、安全作业上传、会话持久性、远程 API 密钥和在该存储库下重新打包。
---
## 许可证
[MIT](LICENSE)。与伊斯坦布尔技术大学（İstanbul Teknik Üniversitesi）没有官方关联。
<br />
<div align="center">
<sub><a href="https://github.com/yatuk">yatuk</a> 由 · <a href="https://github.com/yatuk/itu-mcp">GitHub</a></sub>
</div>
