Servidor MCP de Notepad++

Servidor MCP para Notepad++ en Windows. Utiliza FastMCP 3.1.0 con herramientas combinadas (menos herramientas, misma cobertura), puente HTTP opcional, muestreo (HTTP compatible con Ollama o LLM del cliente), prompts, recursos skill:// y flujos de trabajo agénticos.

Editor vs este repositorio: Las fortalezas propias de Notepad++ (Scintilla, plugins, macros, sesiones) son independientes de lo que expone este MCP. Consulta docs/EDITOR_AND_MCP_SCOPE.md para ver una división clara y una visión general más completa del lado del editor.

Requisitos

Instalación

Recomendado: uv.

Desde un clon de este repositorio:

git clone https://github.com/sandraschi/notepadpp-mcp.git
Set-Location notepadpp-mcp
uv sync
uv run notepadpp-mcp --help

O instala el paquete en modo editable:

uv pip install -e ".[dev]"

Cuando el paquete se publique en PyPI, podrás ejecutarlo con:

uvx notepadpp-mcp

Uso

Cómo se ejecuta el servidor

El script de consola publicado es notepadpp-mcp (notepadpp_mcp.server:run en pyproject.toml).

• stdio predeterminado: lo que usan la mayoría de los hosts MCP (Claude Desktop, Cursor, etc.). Sin flags adicionales.

• Puente HTTP opcional: FastAPI + uvicorn en 127.0.0.1, MCP HTTP en /mcp.

notepadpp-mcp --http --port 10815

Cambia --port si el puerto 10815 está ocupado (consulta el registro central de puertos si utilizas un conjunto de aplicaciones web MCP).

Configuración del cliente MCP

Claude Desktop (claude_desktop_config.json): apunta command/args a tu instalación. Ejemplo usando uv desde una ruta de repositorio fija:

{
  "mcpServers": {
    "notepadpp-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "D:/Dev/repos/notepadpp-mcp", "notepadpp-mcp"]
    }
  }
}

Si notepadpp-mcp está en el PATH:

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

Legado: los documentos antiguos hacían referencia a python -m notepadpp_mcp.tools.server. Prefiere notepadpp-mcp a menos que estés depurando ese módulo.

Llamada a herramientas (conceptual)

El asistente llama a las herramientas MCP por su nombre; no las ejecutas en PowerShell. Ejemplos de operaciones dentro de las herramientas combinadas:

También: suggest_notepad_plan, agentic_notepad_workflow (orquestación), dependiendo de la compilación.

Instantáneas de sesión (session_ops)

• save: Copia el archivo session.xml activo de Notepad++ (normalmente %APPDATA%\Notepad++\session.xml), que enumera todos los búferes abiertos, en un archivo con nombre bajo %APPDATA%\Notepad++\notepadpp-mcp-sessions\. El formato coincide con lo que usa Notepad++ para Cargar sesión / -openSession. Si el archivo activo falta o no enumera archivos, el servidor recurre a una sesión mínima creada a partir de la ruta de la pestaña activa cuando esa ruta existe en el disco.

• load: Ejecuta notepad++.exe -openSession "<saved.xml>". Si una instancia nueva o existente abre los archivos depende de tu configuración de Instancia múltiple en Notepad++.

• Sobrescrituras: NOTEPADPP_SESSION_STORAGE_DIR (donde se almacenan los *.xml con nombre), NOTEPADPP_LIVE_SESSION_XML (ruta de sobrescritura al session.xml activo, p. ej., diseños portátiles o -settingsDir).

Muestreo (LLM para flujos de trabajo)

Opcional. Establece las variables de entorno como se documenta en el servidor / NotepadSamplingHandler, por ejemplo:

• NOTEPADPP_SAMPLING_BASE_URL: Base compatible con OpenAI (p. ej., Ollama http://127.0.0.1:11434/v1)

• NOTEPADPP_SAMPLING_MODEL

• NOTEPADPP_SAMPLING_USE_CLIENT_LLM: permite que el host MCP ejecute el muestreo cuando sea compatible

Descripción general de las herramientas (combinadas)

Las respuestas utilizan una forma de diccionario consistente: success, message o summary, además de error / recovery_options cuando sea relevante.

Documentación en el repositorio

• docs/EDITOR_AND_MCP_SCOPE.md: Notepad++ (editor) vs este servidor: fortalezas del editor, límites del puente MCP

• docs/NOTEPADPP_MACROS.md: Macros (para qué los usa la gente, shortcuts.xml, conjunto curado / ideas de herramientas futuras)

• src/notepadpp_mcp/docs/: Notas de API, ejemplos, PRD donde esté presente

• src/notepadpp_mcp/docs_manifest.py: Descripción general de REST/MCP para el puente web (cuando está habilitado)

Desarrollo

uv pip install -e ".[dev]"
uv run pytest src/notepadpp_mcp/tests/
uv run ruff check src/notepadpp_mcp tests
uv run ruff format src/notepadpp_mcp tests

Opcional: python demonstration_test.py o el proyecto dev.py si está presente para pruebas de humo de integración.

Hoja de ruta / TODO (extensiones)

Trabajo que está planificado o abierto: buenas primeras tareas para colaboradores:

• [ ] Instancia múltiple / ventana múltiple: apuntar a un HWND específico de Notepad++ cuando hay varios abiertos

• [ ] Flujos de plugins más ricos: pasos coordinados de múltiples plugins, mejores superficies de error desde el Administrador de Plugins

• [ ] Linting: HTML/CSS, archivos de configuración opcionales para linters

• [ ] Perfiles de configuración: valores predeterminados del lado del servidor (rutas, tiempos de espera, inicio automático)

• [ ] Lotes: operaciones de archivos por lotes de primera clase con informes de progreso

• [ ] Interfaz web: alinear los documentos con el paquete de panel real (p. ej., web_sota/) y puertos

• [ ] Pruebas / cobertura: aumentar la cobertura; mantener la CI verde en los ejecutores de Windows

• [ ] Macros: fragmentos XML curados en el repositorio; lectura/lista/fusión opcional para %APPDATA%\Notepad++\shortcuts.xml (ver docs/NOTEPADPP_MACROS.md)

Los puntos del registro de cambios anteriores (instancia múltiple, análisis de plugins, etc.) se incluyen en la lista anterior donde todavía se aplican.

Solución de problemas

• No se encuentra Notepad++: Instala Notepad++, inícialo una vez o habilita el comportamiento de inicio automático si tu compilación lo admite.

• API de Windows no disponible: Usa Windows; instala pywin32 en el mismo entorno que el servidor.

• Herramientas que faltan en el cliente: Reinicia el host, verifica los registros de MCP, confirma que notepadpp-mcp se ejecuta sin errores desde una terminal.

• El guardado de sesión está vacío / falla: Es posible que Notepad++ no actualice session.xml hasta que hayas abierto archivos guardados o reiniciado el editor; asegúrate de que el comportamiento de la sesión en Configuración > Preferencias > Copia de seguridad coincida con tus expectativas. Para instalaciones portátiles, establece NOTEPADPP_LIVE_SESSION_XML en el session.xml correcto.

Registro de cambios (corto)

• 0.2.x: session_ops persiste sesiones con nombre: copia el session.xml activo, carga mediante -openSession (ver la sección del README Instantáneas de sesión).

• 0.2.0: FastMCP 3.1.0, muestreo, habilidades, prompts, flujo de trabajo agéntico, puente HTTP + web hooks como se implementó en server.py.

• Anterior: Consolidación de herramientas combinadas, linting y herramientas de plugins.

🛡️ Pila de calidad industrial

Este proyecto se adhiere a los estándares industriales SOTA 14.1 para la orquestación agéntica de alta fidelidad:

• Python (Núcleo): Ruff para linting y formato. Tolerancia cero para declaraciones print en los controladores principales (T201).

• Aplicación web (UI): Biome para linting de sub-milisegundos. Aplicación estricta de noConsoleLog.

• Cumplimiento del protocolo: Aislamiento endurecido de stdout/stderr para garantizar una comunicación JSON-RPC resistente a fallos.

• Automatización: Recetas de Justfile para todas las operaciones de flota (just lint, just fix, just dev).

• Seguridad: Auditorías automatizadas mediante bandit y safety.

Licencia

MIT: ver LICENSE.