Skip to main content
Glama
Sign In
ti-nspire-mcp

ti-nspire-mcp

by reliasdomi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

📟 ti-nspire-mcp (v0.2.0 - MCP 2.0)

CI License: MIT Python 3.13+ MCP 2.0

Servidor Model Context Protocol (MCP 2.0) de código abierto para integrar calculadoras Texas Instruments (TI-Nspire CX II / CX II CAS / CX) con agentes de Inteligencia Artificial (Claude Desktop, Cursor, Antigravity, Gemini CLI).

🚀 Características Principales

1. Comunicación USB Nativa a Bajo Nivel (Protocolo NavNet / DocLink / NNSE)

  • Protocolo de Paquetes Completo (0x54FD / NNSE): Comunicación directa sobre Bulk Endpoints (IN 0x81 / OUT 0x01, 512 bytes) para dispositivos 0x0451:0xE022 (CX II) y 0x0451:0xE012 (CX).

  • direct_upload_tns: Transfiere archivos .tns directamente al almacenamiento interno de la calculadora (servicio 0x4060) sin depender de un navegador web externo.

  • capture_screen_live: Solicita el framebuffer en vivo (320x240, servicio 0x4024 RLE / 0x4021 Raw), decodifica píxeles RGB565 (16 bits) con Pillow y expone la imagen en PNG / Base64 para modelos multimodales.

  • list_remote_filesystem: Explora el árbol de directorios interno de la memoria Flash (/, /PyLib, /MyLib).

2. Motor Avanzado de Generación y Parseo de .tns

  • Soporte Multipágina y Multiaplicación: Crea documentos .tns combinando páginas de Python (<py-app>), Notas Matemáticas (<notes-app>), Hojas de Cálculo (<lists-and-spreadsheet-app>) y Calculadora CAS (<calculator-app>).

  • Conversor Matemático LaTeX $\rightarrow$ XML Nativo (<expr>): Transforma expresiones en LaTeX (\frac, \sqrt[n], \int, \sum, matrices \begin{pmatrix}, letras griegas) a etiquetas matemáticas nativas <expr> de TI-Nspire OS.

  • Soporte para Lua y Ndless: Empaqueta scripts en Lua (<script-app type="lua">) y binarios nativos de Ndless (PRG\x00), además de incluir un inspector/parser de archivos .tns existentes (inspect_tns_document).

3. Implementación Completa de MCP 2.0

  • MCP Resources:

    • ti://calculator/screenshot: Recurso dinámico con la captura actual en PNG Base64 para que la IA "vea" la pantalla de la calculadora en tiempo real.

    • ti://calculator/storage: Estado en tiempo real de la memoria Flash, SDRAM, batería y directorio raíz.

  • MCP Tools con Pydantic V2 y Linter MicroPython:

    • Validación estricta de esquemas, telemetría enriquecida de errores (ErrorTelemetry) y analizador estático AST (validate_micropython_code) que detecta módulos restringidos y coordenadas fuera del lienzo 320x240 antes de subir el código.

  • MCP Prompts Guiados:

    • crear-solucionador-paso-a-paso

    • generar-chuleta-formulas-tns

    • diagnosticar-bootloop

4. Integración del Puente Inalámbrico ESP32 (Wi-Fi / Hotspot / iPhone)

  • Modo "Pantalla Remota desde iPhone": Canal bidireccional por WebSockets (ws://192.168.4.1:81/ws) y UART (ti_hub) con interfaz web progresiva para visualizar la pantalla 320x240 y enviar teclas desde Safari en iOS.

  • Generador de Firmware (generate_esp32_firmware): Genera sketches .ino de Arduino, CMakeLists.txt para ESP-IDF, el script compañero en MicroPython y los comandos listos para compilar con arduino-cli.

5. Calidad de Software, Mocks CI/CD y Tipado Estricto

  • Modo Mock (TI_NSPIRE_MOCK=1): Simula el hardware USB (0x0451:0xE022), el framebuffer RGB565 y el sistema de archivos interno para ejecución determinista en GitHub Actions y pruebas sin calculadora física.

  • Verificación Continua: Cobertura completa con pytest, tipado estricto con mypy --strict y linting/formateo con ruff.

Related MCP server: pico-bay

📁 Estructura del Proyecto

ti-nspire-mcp/
├── .github/workflows/ci.yml        # Pipeline CI/CD en GitHub Actions (Ruff, Mypy, Pytest)
├── pyproject.toml                  # Configuración de paquete, uv, ruff, mypy y pytest
├── README.md                       # Documentación principal
├── CONTRIBUTING.md                 # Guía para colaboradores
├── LICENSE                         # Licencia MIT
├── src/
│   └── ti_nspire_mcp/
│       ├── __init__.py             # Exportaciones públicas
│       ├── __main__.py             # Punto de entrada CLI
│       ├── models.py               # Modelos Pydantic V2 y telemetría de errores
│       ├── usb_protocol.py         # Protocolo de paquetes NavNet (0x54FD), NNSE y RGB565/RLE
│       ├── usb_driver.py           # Driver USB Bulk IN/OUT y dispositivo Mock para CI/CD
│       ├── latex_converter.py      # Conversor de LaTeX a XML matemático nativo <expr>
│       ├── tns_builder.py          # Generador y parser multipágina .tns (Python, Notas, Lua, Ndless)
│       ├── micropython_linter.py   # Analizador AST y validador de módulos MicroPython TI
│       ├── esp32_bridge.py         # Puente Wi-Fi/WebSockets ESP32 y generador arduino-cli
│       └── server.py               # Servidor MCP 2.0 (Resources, Tools y Prompts)
├── scripts/
│   └── test_device.py              # Script de diagnóstico integral por consola
└── tests/
    ├── test_usb_protocol.py        # Tests de tramas NavNet/NNSE, RGB565 y driver USB
    ├── test_tns_and_latex.py       # Tests de LaTeX <expr>, multipágina, Lua y Ndless
    ├── test_linter_and_esp32.py    # Tests de linter MicroPython y puente ESP32
    └── test_server.py              # Tests de integración MCP 2.0

🛠️ Instalación y Diagnóstico Rápido

Requisitos Previos

  • macOS / Linux / Windows con libusb instalado (en macOS: brew install libusb).

  • Python >=3.13 y uv.

git clone https://github.com/reliasdomi/ti-nspire-mcp.git
cd ti-nspire-mcp
uv sync --dev
uv run python scripts/test_device.py

🔌 Configuración en Clientes de IA

1. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "ti-nspire": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/relias/Desktop/ti-nspire-mcp",
        "ti-nspire-mcp"
      ]
    }
  }
}

2. Antigravity / Gemini CLI

agy mcp add ti-nspire -- uv run --directory /Users/relias/Desktop/ti-nspire-mcp ti-nspire-mcp

🧰 Catálogo MCP 2.0

Recursos (Resources)

URI

MIME Type

Descripción

ti://calculator/screenshot

application/json

Framebuffer en vivo 320x240 convertido de RGB565 a PNG Base64.

ti://calculator/storage

application/json

Estado en tiempo real de Flash, RAM, batería y directorio raíz /.

Herramientas (Tools)

Herramienta

Descripción

get_calculator_status

Detecta la calculadora por USB y reporta descriptores, endpoints y memoria.

direct_upload_tns

Sube un archivo .tns directamente por USB Bulk (protocolo NavNet 0x4060).

capture_screen_live

Captura la pantalla de la TI-Nspire (RGB565 $\rightarrow$ PNG Base64).

list_remote_filesystem

Lista los archivos y carpetas de la memoria interna de la calculadora.

create_python_tns_document

Empaqueta código Python validado en un documento .tns.

create_multipage_tns_document

Genera documentos .tns multipágina (Notas LaTeX, Hojas de Cálculo, Python, Lua, Ndless).

convert_latex_to_nspire_xml

Convierte expresiones en LaTeX a etiquetas matemáticas <expr> de TI-Nspire.

create_lua_or_ndless_tns

Empaqueta scripts Lua o aplicaciones nativas Ndless (PRG\x00).

inspect_tns_document

Analiza e inspecciona las páginas y scripts dentro de cualquier archivo .tns.

validate_micropython_code

Depura sintaxis AST, módulos restringidos y límites 320x240 antes del envío.

generate_esp32_firmware

Genera sketches de Arduino/ESP-IDF listos para compilar con arduino-cli.

sync_esp32_remote_screen

Sincroniza frames y comandos bidireccionales con el visor de iPhone vía ESP32.

convert_script_to_tns

Convierte un archivo .py local a .tns.

get_device_specs

Devuelve especificaciones de pantalla, procesador y librerías de la TI-Nspire CX II.

generate_python_template

Genera plantillas base para solucionadores, gráficos 2D y enlace serie.

Prompts Guiados (Prompts)

  • crear-solucionador-paso-a-paso: Diseña, valida y sube un solucionador interactivo con notas LaTeX y Python.

  • generar-chuleta-formulas-tns: Crea un formulario multipágina con expresiones <expr>, hojas de cálculo y visor.

  • diagnosticar-bootloop: Guía interactiva de recuperación de arranque y diagnóstico de memoria por USB.

🧪 Ejecución de Tests y Calidad de Código

uv run pytest
uv run ruff check .
uv run mypy

📄 Licencia

Distribuido bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.

Available Tools

15 tools
capture_screen_liveA

Envía el paquete NavNet de solicitud de captura de framebuffer (0x4024 / 0x4021) a la TI-Nspire, recibe los píxeles en formato RGB565 (16 bits, 320x240), los convierte con Pillow a PNG y los devuelve codificados en Base64 para análisis visual por la IA.

:param save_path: Ruta opcional en disco donde guardar también el archivo .png.

Inputs: save_path. Returns: object

convert_latex_to_nspire_xmlB

Convierte expresiones matemáticas en LaTeX a etiquetas XML matemáticas nativas de TI-Nspire () y a notación simbólica interna de TI-Nspire OS.

:param latex_expression: Expresión en LaTeX (ej. '\frac{-b \pm \sqrt{b^{2}-4ac}}{2a}'). :param evaluate: Si es True, marca la etiqueta para evaluación automática.

Inputs: latex_expression (required), evaluate. Returns: object

convert_script_to_tnsC

Convierte un archivo .py existente en tu computadora a formato .tns de TI-Nspire.

:param python_script_path: Ruta absoluta al archivo .py a convertir.

Inputs: python_script_path (required). Returns: object

create_lua_or_ndless_tnsA

Empaqueta un script de Lua (motor TI-Nspire Script App) o una aplicación nativa de Ndless (cabecera PRG\x00) en un archivo .tns ejecutable.

:param filename: Nombre del archivo .tns a generar. :param mode: 'lua' para scripts Lua o 'ndless' para aplicaciones nativas Ndless. :param code_or_payload: Código fuente Lua o payload para Ndless. :param output_directory: Carpeta de salida opcional.

Inputs: filename (required), mode, code_or_payload, output_directory. Returns: object

create_multipage_tns_documentB

Genera un documento .tns avanzado con soporte multipágina y multiaplicación: hojas de cálculo ('spreadsheet'), notas matemáticas formateadas con LaTeX ('notes'), scripts de Python ('python'), scripts de Lua ('lua'), calculadoras CAS ('calculator') y binarios nativos de Ndless ('ndless').

:param filename: Nombre del archivo .tns a crear. :param pages: Lista de especificaciones de página (TNSPageSpec: page_type, title, content, formulas_latex, spreadsheet_columns). :param document_title: Título global del documento. :param output_directory: Directorio donde guardar el archivo .tns.

Inputs: pages (required), filename (required), document_title, output_directory. Returns: object

create_python_tns_documentA

Empaqueta código Python en un archivo de documento .tns listo para transferir y ejecutar directamente en la TI-Nspire CX II. Incluye verificación preventiva de MicroPython.

:param filename: Nombre del archivo (ejemplo: 'solucionador.tns' o 'app') :param python_code: Código fuente en Python para la calculadora. :param output_directory: Carpeta de destino (por defecto el Escritorio del usuario).

Inputs: filename (required), python_code (required), output_directory. Returns: object

direct_upload_tnsA

Sube un archivo .tns directamente al almacenamiento interno de la calculadora TI-Nspire por USB mediante el protocolo de paquetes NavNet/DocLink (servicio 0x4060, Bulk Endpoints IN/OUT) sin depender de ningún navegador web externo.

:param filename: Nombre de destino del archivo (ej. 'solucionador.tns'). :param python_code: Código Python opcional para empaquetar al vuelo antes de subir. :param local_tns_path: Ruta local opcional a un archivo .tns ya existente en disco. :param remote_directory: Carpeta de destino en la memoria de la calculadora (por defecto '/PyLib').

Inputs: filename (required), python_code, local_tns_path, remote_directory. Returns: object

generate_esp32_firmwareB

Genera sketches de Arduino (.ino), configuración ESP-IDF, cliente MicroPython para TI-Nspire y comandos listos para compilar con arduino-cli para el puente inalámbrico ESP32.

:param mode: 'iphone_remote_screen', 'serial_wifi_bridge' o 'ai_assistant_proxy'. :param ssid: Nombre de la red Wi-Fi / Hotspot creada por el ESP32. :param password: Contraseña WPA2 (mínimo 8 caracteres). :param baud_rate: Velocidad de puerto serie UART entre ESP32 y TI-Nspire. :param output_directory: Directorio opcional donde guardar los archivos listos para compilar.

Inputs: mode, ssid, password, baud_rate, +1 more. Returns: object

generate_python_templateB

Genera plantillas de código listas y optimizadas para el entorno Python de la TI-Nspire CX II.

:param template_type: 'math_solver', 'graphics', 'serial_receiver' o 'notes_viewer'

Inputs: template_type. Returns: object

get_calculator_statusA

Verifica el estado de conexión USB de la calculadora Texas Instruments en el ordenador. Detecta modelos como TI-Nspire CX II, TI-Nspire CX, TI-84 Plus CE, etc.

Inputs: no named parameters. Returns: object

get_device_specsB

Proporciona especificaciones técnicas completas, módulos de Python soportados y restricciones de hardware de la calculadora Texas Instruments.

Inputs: model. Returns: object

inspect_tns_documentB

Parsea e inspecciona un archivo .tns existente, devolviendo sus páginas, tipos de aplicación (Python, Notas, Hoja de Cálculo, Lua, Ndless), código fuente embebido y fórmulas .

:param tns_path: Ruta al archivo .tns que se desea analizar.

Inputs: tns_path (required). Returns: object

list_remote_filesystemA

Lee el árbol de directorios interno de la memoria Flash de la calculadora TI-Nspire mediante el servicio NavNet 0x4060.

:param directory: Directorio remoto a consultar (ej. '/', '/PyLib', '/MyLib').

Inputs: directory. Returns: object

sync_esp32_remote_screenC

Sincroniza en tiempo real la captura de pantalla de la TI-Nspire CX II y comandos bidireccionales con la placa ESP32 para el modo "Pantalla Remota desde iPhone" (WebSockets / Serial).

:param status_text: Texto de estado a mostrar en el visor remoto de iPhone. :param command: Comando o evento de tecla opcional a transmitir de forma bidireccional.

Inputs: command, status_text. Returns: object

validate_micropython_codeA

Herramienta de depuración preventiva de código MicroPython antes del envío a la TI-Nspire CX II. Verifica sintaxis AST, módulos restringidos, coordenadas fuera de pantalla (320x240), rangos de color RGB (0-255) y huella de RAM.

:param python_code: Código Python a validar.

Inputs: python_code (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    B3.3/5.0

    Scored across 15 tools

    Disambiguation3/5

    Four separate tools produce .tns files (create_python_tns_document, convert_script_to_tns, create_multipage_tns_document, create_lua_or_ndless_tns) and the multipage tool explicitly supports Python and Lua pages, so its boundary with the single-purpose variants is genuinely fuzzy. The descriptions help somewhat, but an agent must read carefully to pick the right document generator.

    Naming Consistency4/5

    Nearly all names follow a snake_case verb_noun pattern (get_calculator_status, list_remote_filesystem, create_multipage_tns_document, inspect_tns_document). The only real deviation is direct_upload_tns with an adverb prefix, a minor inconsistency.

    Tool Count4/5

    15 tools sits at the upper end of a reasonable range and the core USB/.tns workflow justifies most of them. However, generate_esp32_firmware and sync_esp32_remote_screen expand into a separate hardware domain, suggesting mild scope creep.

    Completeness3/5

    The surface is heavy on authoring (.tns creation, LaTeX conversion, validation) and covers status, upload, listing, and screen capture, but there is no tool to download a file off the calculator or delete remote files, which are notable gaps for a USB file-transfer server. Creating and reading documents is covered, but the remote storage lifecycle is not.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers