Keenetic NOC MCP

License: MIT Node.js 20+ Model Context Protocol

English

Keenetic NOC MCP is a security-first Model Context Protocol server for diagnosing and carefully managing Keenetic and Netcraze routers. It gives an AI client controlled access to a router on the LAN through RCI or remotely through a KeenDNS HTTPS Web Application, while treating passwords, keys, addresses, and router responses as sensitive data.

It is intended for operators who want useful network automation without handing an agent an unrestricted router session.

What it provides

Safe, bounded diagnostics for system state, internet, Wi-Fi, interfaces, routes, devices, DNS, VPN, segments, and logs.
Named router profiles for LAN and remote HTTPS RCI access; one MCP process serves one selected profile.
Remote transport with HTTPS-only endpoints, normal TLS certificate verification, and challenge-driven Digest or Basic authentication.
Read-only mode that omits mutation tools entirely.
Guarded changes: preview by default, explicit confirmation, backup before the first write, read-back verification, and separate persistence with save_config.
Centralized redaction in tool responses, errors, and audit records. Passwords are not accepted in command-line arguments.

Keenetic and Netcraze are trademarks of their respective owners. This independent project is not affiliated with or endorsed by either company.

Quick start

Requirements: Node.js 20 or newer and a router account with only the privileges it needs.

From a source checkout:

npm ci
npm run build
node dist/index.js router add
node dist/index.js router test home

After the package is published, the same profile setup can be started with:

npx -y keenetic-noc-mcp router add

Run the profile wizard in your own terminal. It validates the connection before saving and stores the password in the system keychain when available. Do not paste a password, endpoint credential, or secret-file path into an AI chat.

For an unattended deployment, configure a single process explicitly:

export KEENETIC_URL=https://rci.example.net/rci/
export KEENETIC_USER=router_operator
export KEENETIC_PASSWORD_FILE=/run/secrets/keenetic-router
node dist/index.js --read-only

For a LAN router, use KEENETIC_HOST instead of KEENETIC_URL. A remote endpoint must be HTTPS and end in /rci/. See Remote RCI for the required KeenDNS Web Application configuration.

Safety model

Start with --read-only. Mutation tools are not registered in that mode.
A real change requires dry_run=false and confirm=true.
Before the first real write, the server creates a startup-configuration backup. If the backup is unavailable, the write is blocked.
Each supported write is read back and verified. The server never calls save_config automatically.
Remote access to normal RCI does not imply access to auxiliary backup endpoints. Use a LAN profile when backup capability is unavailable remotely.
Router logs and all router-provided strings are untrusted data, never instructions.

Read the full safety model and security policy before enabling write access.

Development

npm ci
npm run typecheck
npm test
npm run build
git diff --check

The opt-in remote smoke check is read-only:

npm run smoke:remote
npm run smoke:remote -- --router <profile-id>

With no arguments it uses the default remote profile and its configured secret store; --router selects another remote profile. A complete set of KEENETIC_TEST_URL, KEENETIC_TEST_USER, and KEENETIC_TEST_PASSWORD overrides the profile registry for CI. Its summary contains only response shapes, statuses, and counts - never log lines, device aliases, addresses, or the endpoint. Never run a live mutation as part of a test or smoke check.

Documentation and contribution

Issues and pull requests are welcome. Please remove real IP addresses, MAC addresses, SSIDs, passwords, keys, cookies, and router configuration from reports and fixtures.

Licensed under the MIT License. This project contains adapted MIT-licensed work; the required notice is preserved in THIRD_PARTY_NOTICES.md.

Русский

Keenetic NOC MCP - ориентированный на безопасность сервер Model Context Protocol для диагностики и аккуратного управления роутерами Keenetic и Netcraze. Он даёт AI-клиенту контролируемый доступ к роутеру по LAN через RCI или удалённо через HTTPS Web Application KeenDNS, бережно обращаясь с паролями, ключами, адресами и ответами роутера.

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

Возможности

Безопасная диагностика с ограничением размера ответов: система, интернет, Wi-Fi, интерфейсы, маршруты, устройства, DNS, VPN, сегменты и журналы.
Именованные профили роутеров для LAN и удалённого HTTPS RCI; один процесс MCP обслуживает один выбранный профиль.
Удалённое подключение только по HTTPS, с обычной проверкой TLS-сертификата и аутентификацией Digest или Basic по запросу сервера.
Режим только для чтения, в котором инструменты изменения вообще не регистрируются.
Защищённые изменения: сначала предварительный просмотр, затем явное подтверждение, резервная копия перед первой записью, проверка чтением и отдельное сохранение конфигурации.
Централизованная маскировка секретов в ответах инструментов, ошибках и журнале аудита. Пароли не принимаются в аргументах командной строки.

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

Быстрый старт

Требуются Node.js 20+ и отдельная учётная запись роутера с минимально необходимыми правами.

Из исходного репозитория:

npm ci
npm run build
node dist/index.js router add
node dist/index.js router test home

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

npx -y keenetic-noc-mcp router add

Запускайте мастер профиля в собственном терминале. Он проверяет соединение до сохранения и при возможности помещает пароль в системное хранилище ключей. Не вставляйте пароль, учётные данные endpoint или путь к файлу секрета в AI-чат.

Для контейнера или другого неинтерактивного запуска укажите настройки одного процесса явно:

export KEENETIC_URL=https://rci.example.net/rci/
export KEENETIC_USER=router_operator
export KEENETIC_PASSWORD_FILE=/run/secrets/keenetic-router
node dist/index.js --read-only

Для LAN вместо KEENETIC_URL используйте KEENETIC_HOST. Удалённый endpoint должен работать по HTTPS и оканчиваться на /rci/. Настройка KeenDNS описана в Remote RCI.

Модель безопасности

Начинайте с --read-only: в этом режиме инструменты изменения не регистрируются.
Реальное изменение требует dry_run=false и confirm=true.
Перед первой реальной записью сервер создаёт резервную копию стартовой конфигурации. Если копия недоступна, изменение блокируется.
Каждое поддерживаемое изменение читается обратно и проверяется. Сервер никогда не вызывает save_config автоматически.
Удалённый доступ к RCI не гарантирует доступа к вспомогательному endpoint резервной копии. При такой недоступности используйте LAN-профиль.
Логи и любые строки, полученные от роутера, являются недоверенными данными, а не инструкциями.

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

Разработка

npm ci
npm run typecheck
npm test
npm run build
git diff --check

Необязательная удалённая smoke-проверка выполняется только на чтение:

npm run smoke:remote
npm run smoke:remote -- --router <profile-id>

Без аргументов используются default remote-профиль и его secret store; --router выбирает другой remote-профиль. Полный набор KEENETIC_TEST_URL, KEENETIC_TEST_USER и KEENETIC_TEST_PASSWORD имеет приоритет в CI. В итоге выводятся только формы ответов, статусы и счётчики - без строк лога, адресов, alias устройств и endpoint. Никогда не выполняйте реальные изменения роутера в тестах или smoke-проверках.

Документация и вклад

Приветствуются issue и pull request. Перед публикацией удаляйте из отчётов и фикстур реальные IP-адреса, MAC-адреса, SSID, пароли, ключи, cookies и конфигурацию роутера.

Проект распространяется по лицензии MIT. В нём используется адаптированный MIT-лицензированный код; обязательное уведомление сохранено в THIRD_PARTY_NOTICES.md.