Notepad++ MCP 服务器

用于 Windows 上 Notepad++ 的 MCP 服务器。使用 FastMCP 3.1.0，包含组合工具（更少的工具，相同的覆盖范围）、可选的 HTTP 网桥、采样（兼容 Ollama 的 HTTP 或客户端 LLM）、提示词、skill:// 资源以及 Agentic（代理） 工作流。

编辑器与本仓库的区别： Notepad++ 自身的优势（Scintilla、插件、宏、会话等）与本 MCP 暴露的功能是分开的。请参阅 docs/EDITOR_AND_MCP_SCOPE.md 以获取清晰的划分和更全面的编辑器端概述。

要求

安装

推荐： uv。

从本仓库克隆：

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

或者以可编辑模式安装该包：

uv pip install -e ".[dev]"

当包发布到 PyPI 后，你可以运行：

uvx notepadpp-mcp

使用

服务器运行方式

发布的控制台脚本为 notepadpp-mcp (pyproject.toml 中的 notepadpp_mcp.server:run)。

• 默认 stdio： 大多数 MCP 宿主（Claude Desktop, Cursor 等）使用的方式。无需额外标志。

• 可选 HTTP 网桥： 在 127.0.0.1 上运行 FastAPI + uvicorn，MCP HTTP 位于 /mcp。

notepadpp-mcp --http --port 10815

如果 10815 端口被占用，请更改 --port（如果你使用一组 MCP Web 应用，请参阅中央端口注册表）。

MCP 客户端配置

Claude Desktop (claude_desktop_config.json)：将 command/args 指向你的安装路径。以下是使用固定仓库路径下的 uv 的示例：

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

如果 notepadpp-mcp 在 PATH 中：

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

旧版： 旧文档引用了 python -m notepadpp_mcp.tools.server。除非你在调试该模块，否则请优先使用 notepadpp-mcp。

调用工具（概念）

助手通过名称调用 MCP 工具；你不需要在 PowerShell 中运行这些工具。以下是组合工具中 操作 的示例：

此外：suggest_notepad_plan，agentic_notepad_workflow（编排），具体取决于构建版本。

会话快照 (session_ops)

• save：复制 Notepad++ 的实时 session.xml（通常为 %APPDATA%\Notepad++\session.xml，其中列出了 所有打开的缓冲区），并将其保存为 %APPDATA%\Notepad++\notepadpp-mcp-sessions\ 下的命名文件。格式与 Notepad++ 用于 加载会话 / -openSession 的格式一致。如果实时文件丢失或未列出任何文件，服务器将回退到由 活动标签页 路径构建的 最小会话（前提是该路径在磁盘上存在）。

• load：运行 notepad++.exe -openSession "<saved.xml>"。是打开 新实例 还是 现有实例 取决于你在 Notepad++ 中的 多实例 设置。

• 覆盖项：NOTEPADPP_SESSION_STORAGE_DIR（存储命名 *.xml 的位置），NOTEPADPP_LIVE_SESSION_XML（覆盖实时 session.xml 的路径，例如便携版或 -settingsDir 布局）。

采样（用于工作流的 LLM）

可选。按照服务器 / NotepadSamplingHandler 中的文档设置环境变量，例如：

• NOTEPADPP_SAMPLING_BASE_URL：兼容 OpenAI 的基础 URL（例如 Ollama http://127.0.0.1:11434/v1）

• NOTEPADPP_SAMPLING_MODEL

• NOTEPADPP_SAMPLING_USE_CLIENT_LLM：在支持的情况下让 MCP 宿主运行采样

工具概述（组合工具）

响应使用一致的字典结构：success，message 或 summary，以及相关的 error / recovery_options。

仓库中的文档

• docs/EDITOR_AND_MCP_SCOPE.md：Notepad++ (编辑器) 与本服务器：编辑器的优势，MCP 网桥的边界

• docs/NOTEPADPP_MACROS.md：宏（人们的使用场景，shortcuts.xml，精选集 / 未来工具构想）

• src/notepadpp_mcp/docs/：API 说明，示例，PRD（如有）

• src/notepadpp_mcp/docs_manifest.py：Web 网桥的 REST/MCP 概述（启用时）

开发

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

可选：如果存在 demonstration_test.py 或项目 dev.py，可用于集成冒烟测试。

路线图 / 待办事项 (扩展)

已计划或开放的工作，欢迎贡献者参与：

• [ ] 多实例 / 多窗口：当打开多个 Notepad++ 时，针对特定的 HWND

• [ ] 更丰富的插件流：协调的多插件步骤，来自插件管理器的更好错误界面

• [ ] Linting：HTML/CSS，可选的 linter 配置文件

• [ ] 配置档案：服务器端默认值（路径、超时、自动启动）

• [ ] 批处理：具有进度报告的一流批处理文件操作

• [ ] Web UI：使文档与实际仪表板包（例如 web_sota/）和端口保持一致

• [ ] 测试 / 覆盖率：提高覆盖率；保持 Windows 运行器上的 CI 绿色

• [ ] 宏：仓库内的精选 XML 片段；可选的 %APPDATA%\Notepad++\shortcuts.xml 读取/列出/合并（参见 docs/NOTEPADPP_MACROS.md）

旧的变更日志要点（多实例、插件分析等）在仍然适用的情况下已合并到上述列表中。

故障排除

• 找不到 Notepad++：安装 Notepad++，启动一次，或者如果你的构建版本支持，启用自动启动行为。

• Windows API 不可用：使用 Windows；在与服务器相同的环境中安装 pywin32。

• 客户端中缺少工具：重启宿主，检查 MCP 日志，确认 notepadpp-mcp 在终端中运行且无错误。

• 会话保存为空 / 失败：Notepad++ 可能在打开已保存文件或 重启 编辑器之前不会刷新 session.xml；确保 设置 > 首选项 > 备份 中的会话行为符合你的预期。对于便携版安装，请将 NOTEPADPP_LIVE_SESSION_XML 设置为正确的 session.xml。

变更日志 (简要)

• 0.2.x：session_ops 持久化命名会话：复制实时 session.xml，通过 -openSession 加载（参见 README 中的 会话快照 部分）。

• 0.2.0：FastMCP 3.1.0，采样，技能，提示词，代理工作流，HTTP 网桥 + server.py 中实现的 Web 钩子。

• 更早版本：组合工具整合，Linting 和插件工具。

🛡️ 工业级技术栈

本项目遵循 SOTA 14.1 工业标准，用于高保真代理编排：

• Python (核心)：使用 Ruff 进行 Linting 和格式化。核心处理程序中对 print 语句零容忍 (T201)。

• Webapp (UI)：使用 Biome 进行亚毫秒级 Linting。严格执行 noConsoleLog。

• 协议合规性：强化 stdout/stderr 隔离，确保抗崩溃的 JSON-RPC 通信。

• 自动化：所有舰队操作的 Justfile 配方（just lint, just fix, just dev）。

• 安全性：通过 bandit 和 safety 进行自动化审计。

许可证

MIT - 参见 LICENSE。