BIT101 MCP

Локальный сервис Model Context Protocol (MCP) только для чтения для студентов Пекинского технологического института. Он преобразует контент сообщества BIT101, отзывы о курсах, личное расписание, оценки и календарь Lexue в структурированные данные, понятные агенту, позволяя задавать вопросы на естественном языке напрямую.

[!IMPORTANT] Этот проект является неофициальным общественным проектом и не имеет отношения к Пекинскому технологическому институту или официальному BIT101. Windows прошёл основные проверки на реальном оборудовании, Fedora 43 + niri подтверждён как работающий; проект всё ещё находится на стадии MVP. Перед использованием прочтите Аутентификация, безопасность и конфиденциальность.

Возможности

• Сводка сегодняшних постов BIT101 или поиск исторических обсуждений по ключевым словам

• Поиск курсов, преподавателей и отзывов студентов за прошлые годы

• Получение расписания на сегодня, эту неделю, следующую неделю или указанный семестр

• Запрос оценок, кредитов, среднего балла и максимального балла по группе (если предоставлено вышестоящей системой)

• Запрос событий календаря Lexue на будущий период

• Комбинирование данных из разных источников для ответа на вопросы, например: «Как студенты оценивают преподавателей моих курсов на следующий семестр?»

Все инструменты доступны только для чтения. Проект не может публиковать посты, ставить лайки, комментировать, сдавать задания, изменять оценки или модифицировать любые данные университета.

Related MCP server: MCP-Server-CollageAI

Демонстрация на реальном оборудовании

Следующие скриншоты сделаны при реальных вызовах OpenCode cli на Windows. Конкретные ответы генерируются используемой моделью на основе данных, возвращаемых MCP, не отражают мнение автора проекта и могут меняться вместе с обновлениями моделей и данных.

Сводка сегодняшних постов

Агент вызывает list_today_posts для получения постов за день, затем формирует краткую сводку на основе заголовков, содержимого и активности.

Отзывы о преподавателях и курсах

Агент сначала ищет курсы, соответствующие преподавателю, затем вызывает get_course_reviews для агрегации метаданных курса, оценок, отзывов и исторической информации.

Обсуждение профессиональных направлений

Когда в каталоге курсов нет точного совпадения, агент может продолжить поиск постов BIT101 и прочитать соответствующие обсуждения, демонстрируя совместное использование нескольких инструментов MCP.

Календарь Lexue

Агент может запрашивать события Lexue за 7–90 дней. Если в действующем календаре нет ближайших задач, корректно возвращается пустой список, а не ошибочная интерпретация «нет задач» как сбоя интерфейса.

Подготовка перед использованием

Рекомендуемое окружение:

• Windows 10/11 или Linux с настольным браузером и доступным системным keyring (Fedora 43 + niri проверены)

• Python 3.11 или новее

• uv

• Клиент с поддержкой локального stdio MCP, например Codex, OpenCode, Cursor или Claude Code

• Учётная запись BIT101

• Для запроса расписания и оценок также требуется учётная запись единой аутентификации Пекинского технологического института; для некоторых входов может потребоваться SMS-подтверждение

• Для запроса Lexue необходимо один раз экспортировать адрес подписки на личный календарь из Lexue

Установка

Расскажите своему агенту (рекомендуется)

Если ваш агент может выполнять команды терминала и изменять собственную конфигурацию MCP, вы можете напрямую отправить ему следующий текст:

请帮我安装并配置 BIT101 MCP：
https://github.com/tiny-paris/BIT101-mcp

要求：
1. 先阅读仓库 README，尤其是“认证、安全与隐私”部分，并告诉我它会访问哪些服务。
2. 检查本机是否安装 Python 3.11+、Git 和 uv；缺少时说明后再安装。
3. 优先使用以下命令安装为用户级工具：
   uv tool install "git+https://github.com/tiny-paris/BIT101-mcp.git"
4. 识别我当前使用的 MCP 客户端，将 bit101-mcp 配置为用户级/全局 stdio MCP，
   名称使用 bit101，单次工具执行超时至少设置为 360 秒。
5. 如果找不到命令，运行 uv tool dir --bin，并在 MCP 配置中使用
   bit101-mcp（Windows 为 bit101-mcp.exe）的绝对路径。
6. 重启或重新加载 MCP，验证服务器已连接并能列出工具。
7. 不要在聊天、命令行参数、配置文件或环境变量中向我索要或写入账号、密码、
   短信验证码、Cookie、token 或乐学订阅 URL。需要认证时，只让我在 MCP 自动打开的
   127.0.0.1 临时页面中操作。
8. 不要修改默认上游地址。完成后告诉我修改了哪些配置文件以及验证结果。

После завершения установки агентом просто задайте в новом диалоге вопрос «Суммируй сегодняшние посты BIT101», чтобы запустить первую аутентификацию по требованию.

Установка из исходного кода

После публикации репозитория можно выполнить:

git clone https://github.com/tiny-paris/BIT101-mcp.git
cd BIT101-mcp
uv sync --all-groups
uv tool install .

uv tool install . установит bit101-mcp как пользовательскую команду. Просмотреть каталог исполняемых файлов uv можно следующей командой:

uv tool dir --bin

Если MCP-клиент не находит bit101-mcp, перезапустите клиент или укажите в конфигурации абсолютный путь к bit101-mcp.exe в этом каталоге.

Запуск только в каталоге исходного кода

Для разработки или тестирования можно не устанавливать команду:

uv sync --all-groups
uv run bit101-mcp

После нормального запуска stdio MCP молча ожидает сообщения протокола — «зависание» — это нормально. Не используйте его как обычную интерактивную команду и не вводите в его терминал учётные данные.

[!NOTE] Простой uvx bit101-mcp станет доступен только после публикации проекта на PyPI. Текущий README не предполагает, что пакет PyPI уже существует.

Описание зависимостей

Проект объявляет 7 прямых зависимостей времени выполнения. Не все они «обязательны по протоколу MCP», а являются компонентами, необходимыми для текущей полной функциональности:

Таким образом, для текущей однопакетной версии все 7 являются зависимостями времени выполнения; но с функциональной точки зрения icalendar и python-dateutil обслуживают только Lexue, и в будущем при разделении на опциональные функции их можно сделать дополнительными зависимостями. Сейчас разделение усложнит установку и обработку ошибок, а экономия объёма будет незначительной.

В uv.lock также будут видны косвенные зависимости, такие как anyio, httpcore, certifi — они автоматически подтягиваются указанными библиотеками, не являются верхнеуровневыми компонентами, вызываемыми проектом напрямую, и не должны устанавливаться или удаляться вручную по отдельности.

Следующие зависимости используются только для разработки и публикации и не устанавливаются как обычные зависимости времени выполнения:

Настройка MCP-клиента

Первая аутентификация в университете может занять до нескольких минут, поэтому рекомендуется установить тайм-аут одного вызова инструмента в 360 секунд. После настройки необходимо перезапустить MCP-клиент, чтобы он запустил новый процесс сервиса.

Codex

Codex CLI, расширение Codex IDE и хост Codex в настольном ChatGPT используют общую конфигурацию MCP в config.toml. Официальная документация: Codex MCP docs.

Сначала добавьте через CLI:

codex mcp add bit101 -- bit101-mcp
codex mcp list

Затем проверьте пользовательский %USERPROFILE%\.codex\config.toml и добавьте тайм-аут инструментов:

[mcp_servers.bit101]
command = "bit101-mcp"
tool_timeout_sec = 360

Если нужно включить только в доверенном проекте, поместите ту же конфигурацию в .codex/config.toml этого проекта. Пользовательская конфигурация доступна в любом каталоге и в новых диалогах.

Если команда не в PATH Codex, можно указать абсолютный путь:

[mcp_servers.bit101]
command = 'C:\path\to\bit101-mcp.exe'
tool_timeout_sec = 360

OpenCode

Проект протестирован на реальном оборудовании Windows со следующей традиционной конфигурацией OpenCode. opencode.json в корне проекта действует только для этого проекта; для использования в любом каталоге поместите его в пользовательский ~/.config/opencode/opencode.json (на Windows обычно %USERPROFILE%\.config\opencode\opencode.json).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bit101": {
      "type": "local",
      "command": ["bit101-mcp"],
      "enabled": true,
      "timeout": 360000
    }
  }
}

Проверка подключения:

opencode mcp list

Если запуск возможен только в каталоге исходного кода, обычно это означает, что в конфигурации используется относительная команда и нет глобальной установки. Установите bit101-mcp или измените command на абсолютный путь .venv\Scripts\bit101-mcp.exe.

Структура конфигурации OpenCode V2 отличается: сервисы находятся в mcp.servers, тайм-аут выполнения — в mcp.timeout.execution. Следуйте официальной документации OpenCode MCP:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "timeout": {
      "execution": 360000
    },
    "servers": {
      "bit101": {
        "type": "local",
        "command": ["bit101-mcp"]
      }
    }
  }
}

Cursor

Согласно документации Cursor MCP, глобальная конфигурация находится в ~/.cursor/mcp.json, конфигурация проекта — в .cursor/mcp.json:

{
  "mcpServers": {
    "bit101": {
      "command": "bit101-mcp",
      "args": []
    }
  }
}

После сохранения перезапустите Cursor и убедитесь, что bit101 включён в списке доступных инструментов агента.

Claude Code

Следуя документации Claude Code MCP, добавьте пользовательский stdio-сервис:

claude mcp add --scope user bit101 -- bit101-mcp
claude mcp list

Общая конфигурация stdio

Другим MCP-клиентам достаточно настроить один локальный stdio-процесс:

{
  "command": "bit101-mcp",
  "args": []
}

Не записывайте учётные данные, пароли, cookie, токены или URL Lexue в конфигурацию MCP, переменные окружения или параметры инструментов.

Начало работы

После настройки просто задавайте вопросы в диалоге с агентом — запускать фоновый сервис вручную не нужно. Например:

Сообщество и курсы BIT101

总结一下今天 BIT101 都有哪些帖子。
查找最近关于“数据结构”的讨论。
如何评价某某老师的某门课？请区分普遍评价和少数意见。
查找“特立自动化”相关讨论，并列出信息来源。

Расписание и оценки

我今天有什么课？
我下周有什么课？按实际日期和开始时间排序。
列出本学期完整课表。
列出我的所有成绩，包括课程、学期、学分、成绩、班级平均分和最高分。

При запросе «эта/следующая неделя» сервер вычисляет точный номер недели на основе текущей даты и возвращает полное время starts_at, ends_at и т.д.; агенту не нужно самостоятельно угадывать учебные недели или время занятий.

Lexue

未来 14 天有哪些乐学任务？按截止时间排序。
看看未来 30 天的乐学日历。

Доступные инструменты

Успешные результаты единообразно имеют вид:

{
  "ok": true,
  "data": {}
}

Результаты ошибок не содержат стеков вызовов вышестоящих систем или информацию об аутентификации:

{
  "ok": false,
  "error": {
    "code": "UPSTREAM_UNAVAILABLE",
    "service": "bit101",
    "message": "BIT101 is temporarily unavailable.",
    "retryable": true
  }
}

Технические принципы

Ядро состоит из четырёх уровней:

1. Уровень инструментов MCP: предоставляет только пользовательские концепции — посты, курсы, расписание, оценки и задачи; не раскрывает cookie, токены вызова или внутренние идентификаторы сервисов.

2. Уровень клиентов: отдельно обрабатывает API BIT101 и шлюз данных университета; при сбое запроса определяет, истекла ли сессия, и выполняет только одну восстанавливаемую повторную попытку.

3. Уровень стандартизации: преобразует форматы разных вышестоящих систем в стабильные, JSON-совместимые поля; отвечает за разбор дат в часовом поясе Шанхая, учебных недель, времени занятий, оценок и событий ICS.

4. Уровень аутентификации и хранения: открывает локальную страницу только при необходимости; пароли не попадают в параметры MCP; после успеха сохраняется только переиспользуемая сессия.

MCP использует stdio transport. Стандартный вывод отправляет только данные протокола MCP, журналы записываются только в стандартный поток ошибок, чтобы логи не нарушали протокольную связь.

Процесс аутентификации

Почему нельзя напрямую переиспользовать вход BIT101 в браузере?

Cookie браузера принадлежат его собственному защищённому пространству; MCP — это отдельный локальный процесс. Проект намеренно не читает базы cookie Chrome/Edge и не требует установки расширений браузера. Это добавляет одну лишнюю первичную аутентификацию, но позволяет избежать сканирования MCP всех учётных данных браузера пользователя.

Открытие нового диалога с агентом само по себе не очищает состояние входа. При запуске MCP считывает и проверяет сохранённые сессии; повторный вход выполняется только если сессия отсутствует, вышестоящая система признала её недействительной, временный вызов аутентификационного шлюза истёк или хранилище учётных данных системы недоступно.

BIT101

При первом вызове инструмента сообщества:

1. MCP запускает временную страницу на случайном порту 127.0.0.1.

2. Пользователь вводит номер студенческого билета и пароль BIT101 на локальной странице.

3. Локальный процесс обрабатывает пароль по существующему протоколу входа BIT101 и отправляет HTTPS-запрос к API BIT101.

4. После успешного входа в хранилище учётных данных системы сохраняется только возвращённая сессия BIT101; исходный пароль не сохраняется.

5. Временная страница закрывается, исходный вызов инструмента продолжает выполнение.

Расписание и оценки университета

Расписание и оценки поступают из персонального сервиса данных университета и не используют тот же «ключ», что и сессия сообщества BIT101. При первом вызове локальная страница собирает учётные данные единой аутентификации, пароль и, при необходимости, SMS-код, и отправляет их по HTTPS существующему REST-шлюзу BIT-Login. MCP сохраняет краткосрочную сессию вызова, возвращённую шлюзом, но не сохраняет пароль университета.

Календарь Lexue

Текущий REST-шлюз BIT-Login не предоставляет интерфейс календаря Lexue, который можно было бы вызывать из этого проекта, и проект не перереализует CAS/SSO университета. Поэтому в MVP пользователю необходимо один раз сгенерировать частный адрес подписки на странице Календарь → Экспорт календаря в Lexue и вставить его на локальной странице подключения.

Страница подключения фактически загружает и проверяет содержимое iCalendar; только действующая подписка отображает Connected; обычные страницы calendar/view.php отклоняются. Адрес подписки не попадает в результаты агента или инструментов MCP и сохраняется в хранилище учётных данных системы. Действительный календарь без ближайших событий возвращает пустой список.

Аутентификация, безопасность и конфиденциальность

Краткий вывод

Этот проект снижает риск попадания паролей в агента, историю чата и журналы, но не может гарантировать «нулевой риск». Установка локального MCP эквивалентна установке локальной программы с доступом в сеть; пользователь должен доверять исходному коду проекта, установочным пакетам, зависимостям и настроенным удалённым сервисам аутентификации.

Особенно важно различать два утверждения:

• Пароли не отправляются агенту/LLM: это явно реализованная граница проекта.

• Пароли существуют только на этом компьютере: это не так. Пароль единой аутентификации университета должен быть отправлен локальным MCP по HTTPS настроенному удалённому шлюзу BIT-Login для завершения аутентификации.

Какая информация куда попадает?

Адреса вышестоящих систем по умолчанию:

• API BIT101: https://bit101.flwfdd.xyz

• REST BIT-Login: https://login.bit101.flwfdd.xyz

HTTPS защищает от обычного перехвата в сети, но не заменяет доверие к оператору сервера. Пользователи, которых беспокоит прохождение пароля университета через удалённый шлюз, не должны включать инструменты расписания и оценок.

Реализованные меры защиты

• Временный HTTP-сервис привязан только к 127.0.0.1 и использует случайный порт, назначенный ОС.

• Каждая аутентификация использует 256-битный случайный state с сравнением за постоянное время для защиты от поддельных отправок.

• Страница отключает кэширование, внешний контент, iframe, referrer и угадывание MIME-типов.

• Страница прекращает прослушивание после успеха, отмены или тайм-аута.

• Пароли и коды подтверждения не записываются в файлы; код очищает ссылки на соответствующие переменные как можно скорее после запроса.

• Сессии записываются через Python keyring в хранилище учётных данных ОС (Windows Credential Manager или Secret Service/keyring на Linux); при недоступности хранятся только в памяти текущего процесса, без отката к файлам в открытом виде.

• Журналы маскируют пароли, коды подтверждения, cookie, Bearer-токены и заголовки Authorization.

• Адрес Lexue должен использовать HTTPS в домене bit.edu.cn и возвращать действительный iCalendar.

• Все инструменты помечены как доступные только для чтения и не предоставляют возможности изменять данные университета или сообщества.

На что следует обратить внимание пользователю

• Устанавливайте только из доверенных репозиториев или доверенных страниц релизов и по возможности проверяйте исходный код и хеши релизов.

• Адрес локальной страницы аутентификации должен начинаться с http://127.0.0.1:<случайный порт>/connect.

• Никогда не отправляйте пароли, коды подтверждения, cookie, токены или URL Lexue в поле чата агента, параметры MCP, Issues или журналы.

• Не используйте личные учётные данные университета на ненадёжных общедоступных компьютерах.

• URL подписки Lexue — это частная ссылка «получил — значит можешь читать», её нужно защищать как пароль; при подозрении на утечку перегенерируйте её в Lexue.

• При запросе оценок и расписания соответствующие данные предоставляются текущему агенту. Самостоятельно решайте, включать ли эти функции, исходя из политики данных используемой модели и клиента.

Очистка локальных сессий

На Windows откройте Панель управления → Диспетчер учётных данных → Учётные данные Windows; на Linux откройте инструмент управления Secret Service текущего окружения рабочего стола (обычно GNOME Keyring или KDE Wallet). Удалите следующие записи с именем сервиса bit101-mcp:

• bit101-session

• school-session

• lexue-calendar-url

После удаления следующий вызов соответствующего инструмента потребует повторной аутентификации. Удаление Python-пакета не удаляет эти системные учётные данные автоматически. Если на Linux нет доступного бэкенда keyring, сессии хранятся только в памяти текущего процесса, и после перезапуска MCP потребуется повторный вход.

Параметры конфигурации

Неконфиденциальные параметры настраиваются только через переменные окружения:

Учётные данные и сессии нельзя настраивать через параметры инструментов или переменные окружения. Изменение адресов вышестоящих систем означает доверие новому оператору сервиса — используйте с осторожностью.

Часто задаваемые вопросы

Нужно ли запускать агента в каталоге проекта?

Нет. После установки команды через uv tool install . и записи MCP в пользовательскую конфигурацию клиента можно использовать из любого каталога. opencode.json, .cursor/mcp.json или .codex/config.toml в корне проекта действуют только для соответствующего проекта.

Почему при первом использовании открывается браузер?

Аутентификация запускается по требованию. Первый запрос постов требует сессию BIT101; первый запрос расписания/оценок требует сессию университета; первый запрос Lexue также требует частную подписку на календарь. Пароли и адрес подписки не могут проходить через чат, поэтому используется временная локальная страница.

Почему MCP всё равно требует вход, если веб-страница BIT101 уже авторизована?

Сессия веб-страницы хранится в cookie браузера. MCP не читает cookie браузера, поэтому ему нужно создать собственную минимальную сессию. Это жертвует удобством первого входа, но избегает прямого доступа ко всем данным входа браузера.

Почему в новом диалоге иногда снова требуется вход?

Новый диалог не очищает сессии активно, но MCP проверяет сессии вышестоящих систем. Повторный вход происходит при истечении сессии, её отзыве сервером, недействительности вызова аутентификационного шлюза или недоступности хранилища учётных данных системы. Если сразу после успешного входа и перезапуска снова появляется запрос, проверьте наличие записей bit101-mcp в хранилище учётных данных системы.

Lexue показывает Connected, но задач нет — почему?

Если адрес подписки прошёл проверку iCalendar, пустой список обычно означает, что в выбранном диапазоне времени действительно нет событий. Можно расширить диапазон запроса с 7 до 30 дней для проверки.

Почему университетские инструменты работают медленно?

Первая аутентификация университета, SMS-подтверждение и получение деталей оценок могут занять много времени. Установите тайм-аут инструментов MCP в 360 секунд и дождитесь завершения текущего вызова; не запускайте несколько университетских инструментов одновременно.

Что делать, если команда bit101-mcp не найдена?

Выполните uv tool dir --bin, чтобы найти каталог установки, добавьте его в PATH или укажите абсолютный путь к bit101-mcp.exe в конфигурации MCP. После изменения перезапустите клиент.

Коды ошибок

Все ошибки проходят очистку и не возвращают пароли, cookie, токены, заголовки Authorization, исходные стеки вызовов или полные чувствительные запросы.

Разработка

Структура проекта:

src/bit101_mcp/
├── server.py           # MCP 入口、工具注册和服务器说明
├── tools/              # Agent 可见的只读工具
├── clients/            # BIT101 与学校上游客户端
├── auth/               # 本地浏览器认证、状态机和凭据存储
├── models/             # 数据标准化、周次和 ICS 解析
└── logging_utils.py    # stderr 日志和秘密脱敏

Установка зависимостей для разработки и запуск проверок:

uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv build

Перед релизом мейнтейнеры проверяют стандартизацию данных, состояние аутентификации, маскирование секретов и процесс повторных попыток с помощью мок-тестов, не распространяемых с публичным репозиторием; эти тесты не требуют реальных учётных записей. Интеграционные тесты с реальными аккаунтами остаются ручными и опциональными; тестовые учётные данные не должны попадать в репозиторий или CI.

Благодарности

Спасибо проекту BIT101 и всем его контрибьюторам. Долгосрочно поддерживаемые сообщество, отзывы о курсах, интерфейсы данных кампуса и инструменты аутентификации, созданные старшими товарищами, значительно облегчили студенческую жизнь и заложили важную основу для этого проекта.

Этот проект особенно ссылается на или использует интерфейсы и документацию следующих проектов:

• BIT101

• BIT101-GO

• BIT101-Android

• BIT-Login

BIT101 MCP — это независимо разработанный неофициальный MCP-клиент, взаимодействующий с соответствующими сервисами через сетевые интерфейсы. Лицензия MIT этого репозитория применяется только к оригинальному коду этого проекта и не заменяет и не изменяет лицензии каких-либо вышестоящих проектов.

Текущие ограничения

• Windows прошёл основные проверки на реальном оборудовании; Fedora 43 + niri подтверждён как работающий, другие окружения рабочего стола Linux ещё не проверены по отдельности.

• Lexue по-прежнему требует однократной ручной вставки экспортированного частного адреса подписки на календарь.

• Срок действия сессии университета определяется вышестоящим шлюзом и не может гарантировать долгосрочный вход без повторной аутентификации.

• Средний и максимальный баллы зависят от того, предоставляет ли вышестоящая система детали по каждому курсу.

• Пакет PyPI и отдельный исполняемый файл для Windows пока не опубликованы.

• Никаких операций записи не предоставляется.

Лицензия

Данный проект использует MIT License. Приветствуется использование, изменение, распространение и отправка улучшений при условии сохранения уведомлений об авторских правах и лицензии.

Вклад

Приветствуются Issue и Pull Request. При сообщении о проблеме, пожалуйста, укажите:

• Версии операционной системы, Python, uv и MCP-клиента

• Используемые названия инструментов и обезличенные коды ошибок

• Появляется ли локальная страница аутентификации

• Шаги для воспроизведения

Пожалуйста, не отправляйте номера студенческих билетов, пароли, коды подтверждения, Cookie, токены, полные заголовки запросов, URL 乐学 или другую личную информацию.