Notepad++ MCP 서버

Windows용 **Notepad++**를 위한 MCP 서버입니다. FastMCP 3.1.0을 사용하여 포트만토(portmanteau) 도구(더 적은 도구로 동일한 범위 지원), 선택적 HTTP 브리지, 샘플링(Ollama 호환 HTTP 또는 클라이언트 LLM), 프롬프트, skill:// 리소스 및 에이전트 워크플로우를 지원합니다.

편집기 vs 이 저장소: 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에서 MCP HTTP 지원.

notepadpp-mcp --http --port 10815

10815 포트가 사용 중인 경우 --port를 변경하십시오(MCP 웹앱 군을 사용하는 경우 중앙 포트 레지스트리 참조).

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++의 다중 인스턴스(Multi-instance) 설정에 따라 다릅니다.

• 재정의: NOTEPADPP_SESSION_STORAGE_DIR(명명된 *.xml이 저장되는 위치), NOTEPADPP_LIVE_SESSION_XML(실시간 session.xml에 대한 재정의 경로, 예: 포터블 또는 -settingsDir 레이아웃).

샘플링 (워크플로우용 LLM)

선택 사항입니다. 서버 / NotepadSamplingHandler에 문서화된 대로 환경 변수를 설정하십시오. 예:

• NOTEPADPP_SAMPLING_BASE_URL: OpenAI 호환 베이스 (예: 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++ (편집기) vs 이 서버: 편집기의 강점, MCP 브리지의 경계

• docs/NOTEPADPP_MACROS.md: 매크로 (사용 용도, shortcuts.xml, 큐레이션 세트 / 향후 도구 아이디어)

• src/notepadpp_mcp/docs/: API 노트, 예시, PRD(있는 경우)

• src/notepadpp_mcp/docs_manifest.py: 웹 브리지용 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

선택 사항: 통합 스모크 테스트를 위해 python demonstration_test.py 또는 프로젝트 dev.py(있는 경우)를 실행하십시오.

로드맵 / 할 일 (확장)

계획 중이거나 열려 있는 작업 - 기여자를 위한 좋은 첫 번째 이슈:

• [ ] 다중 인스턴스 / 다중 창: 여러 Notepad++가 열려 있을 때 특정 HWND를 대상으로 지정

• [ ] 더 풍부한 플러그인 흐름: 조정된 다중 플러그인 단계, 플러그인 관리자로부터의 더 나은 오류 표면

• [ ] 린팅: HTML/CSS, 린터를 위한 선택적 구성 파일

• [ ] 구성 프로필: 서버 측 기본값 (경로, 타임아웃, 자동 시작)

• [ ] 배치: 진행 상황 보고가 포함된 일류 배치 파일 작업

• [ ] 웹 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, 샘플링, 스킬, 프롬프트, 에이전트 워크플로우, server.py에 구현된 HTTP 브리지 + 웹 훅.

• 이전: 포트만토 도구 통합, 린팅 및 플러그인 도구.

🛡️ 산업 품질 스택

이 프로젝트는 고충실도 에이전트 오케스트레이션을 위한 SOTA 14.1 산업 표준을 준수합니다:

• Python (코어): 린팅 및 포맷팅을 위한 Ruff. 코어 핸들러에서 print 문에 대한 무관용 원칙 (T201).

• 웹앱 (UI): 밀리초 미만의 린팅을 위한 Biome. 엄격한 noConsoleLog 적용.

• 프로토콜 준수: 충돌 방지 JSON-RPC 통신을 보장하기 위한 강화된 stdout/stderr 격리.

• 자동화: 모든 플릿 작업을 위한 Justfile 레시피 (just lint, just fix, just dev).

• 보안: bandit 및 safety를 통한 자동 감사.

라이선스

MIT - LICENSE를 참조하십시오.