sandraschi/notepadpp-mcp

Notepad++ MCP Server

MCP server for Notepad++ automation with portmanteau tool consolidation. FastMCP 2.14.1 compliant with structured logging and Windows API integration.

Installation

MCPB Package Installation

Download and install the MCPB package from Releases.

Python Installation

# Install from PyPI
pip install notepadpp-mcp

# Or install from source
git clone https://github.com/sandraschi/notepadpp-mcp.git
cd notepadpp-mcp
pip install -e .

⚙️ Claude Desktop Configuration

Add to your Claude Desktop configuration:

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

🔧 Manual Configuration (if needed)

{
  "mcpServers": {
    "notepadpp-mcp": {
      "command": "python",
      "args": ["-m", "notepadpp_mcp.tools.server"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src"
      }
    }
  }
}

📋 Requirements

🖥️ System Requirements

• Windows 10/11 (64-bit)
• Notepad++ 8.0+ installed and accessible
• Python 3.10+ with pip
• pywin32 for Windows API integration

Dependencies

• FastMCP 2.14.1+ - MCP framework
• structlog 23.0.0+ - Structured JSON logging
• pywin32 - Windows API bindings
• psutil - System monitoring

🚨 Important Notes

• Notepad++ must be installed on the system
• Server requires Windows API access (pywin32)
• First run may require Notepad++ to be started manually

Tool Organization

The server uses portmanteau tools following FastMCP 2.14.1+ standards. Each tool consolidates related operations to prevent tool explosion while maintaining functionality.

Usage Examples

# File operations
file_ops("open", file_path="document.txt")
file_ops("save")
file_ops("info")

# Text operations
text_ops("insert", text="Hello World")
text_ops("find", text="search term")

# Status operations
status_ops("help")
status_ops("system_status")
status_ops("health_check")

📁 Project Structure

notepadpp-mcp/
├── src/notepadpp_mcp/
│   ├── tools/          # MCP server implementation
│   ├── docs/           # Documentation and examples
│   ├── tests/          # Test suite
│   └── dxt/            # DXT packaging configuration
├── pyproject.toml      # Package configuration
├── README.md           # This file
└── LICENSE             # MIT license

Documentation

• - Tool reference and usage examples
• - System design and implementation details

Tools Overview (8 Portmanteau Tools)

All tools follow FastMCP 2.14.1+ portmanteau pattern with enhanced response patterns.

Portmanteau Tools

file_ops

Consolidates file operations: open, new, save, info

• Open files in Notepad++
• Create new files
• Save current file
• Get file metadata

text_ops

Consolidates text operations: insert, find

• Insert text at cursor position
• Search text with options

status_ops

Consolidates status operations: help, system_status, health_check

• Hierarchical help system
• System diagnostics
• Health checks

tab_ops

Consolidates tab operations: list, switch, close

• List open tabs with metadata
• Switch between tabs by index
• Close tabs by index

session_ops

Consolidates session operations: save, load, list

• Save workspace sessions
• Load saved sessions
• List available sessions

linting_ops

Consolidates linting operations: python, javascript, json, markdown, tools

• Python analysis (ruff/flake8)
• JavaScript validation (ESLint)
• JSON syntax checking
• Markdown style validation

display_ops

Consolidates display operations: fix_invisible_text, fix_display_issue

• Fix invisible text issues
• Fix display problems

plugin_ops

Consolidates plugin operations: discover, install, list, execute

• Discover plugins from official list
• Install plugins via Plugin Admin
• List installed plugins
• Execute plugin commands

Core Capabilities

• Windows API integration with pywin32
• FastMCP 2.14.1+ compliance with portmanteau pattern
• Structured JSON logging to stderr
• 64 tests covering all portmanteau tools
• Enhanced response patterns (summary, next_steps, recovery_options)
• Multi-linter support with fallback options
• Code quality analysis for multiple languages
• Plugin ecosystem integration

🛠️ Development

# Clone and install
git clone https://github.com/sandraschi/notepadpp-mcp.git
cd notepadpp-mcp
pip install -e .[dev]

# Run comprehensive tests
pytest src/notepadpp_mcp/tests/

# Run with coverage
pytest src/notepadpp_mcp/tests/ --cov=src/notepadpp_mcp --cov-report=html

# Format code
ruff format src/ tests/

# Lint code
ruff check src/ tests/

# Via Makefile
make test
make test-coverage
make lint
make format
make check  # Run all checks

# Test real Notepad++ integration
python demonstration_test.py

# Development helper
python dev.py test|format|build|validate-dxt

🧪 Testing

• 64 comprehensive tests covering all tools including linting and plugin functionality
• Real Windows API testing with actual Notepad++ integration
• Demonstration script (demonstration_test.py) tests live functionality
• CI/CD ready with automated testing pipeline
• Multi-linter testing with ruff, flake8, and ESLint integration
• Plugin ecosystem testing with GitHub API mocking

🏗️ Architecture

🎯 Core Components

• NotepadPPController - Windows API integration layer
• FastMCP Server - MCP protocol implementation
• Tool Decorators - Automatic tool registration
• Structured Logging - Professional error handling

🔧 Integration Flow

1. MCP Client (Claude Desktop) → FastMCP Server
2. Server → NotepadPPController → Windows API
3. Windows API → Notepad++ Application → User Interface

📁 File Structure

src/notepadpp_mcp/
├── tools/server.py     # Main MCP server (2424 lines)
├── tests/              # Comprehensive test suite (64 tests)
├── docs/               # Documentation and examples
│   ├── README.md       # API documentation
│   ├── PRD.md          # Product requirements
│   └── PLUGIN_ECOSYSTEM.md  # Plugin integration guide
└── dxt/                # DXT packaging configuration

🐛 Troubleshooting

❌ Common Issues

"Notepad++ not found"

# Check if Notepad++ is installed
python demonstration_test.py

# Install Notepad++
# Download from: https://notepad-plus-plus.org/downloads/
# Or via Chocolatey: choco install notepadplusplus

"Windows API not available"

# Install pywin32
pip install pywin32

# Restart Python environment
# Try running demonstration script again
python demonstration_test.py

"Server not connecting"

{
  "mcpServers": {
    "notepadpp-mcp": {
      "command": "python",
      "args": ["-m", "notepadpp_mcp.tools.server"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src"
      }
    }
  }
}

"Tools not appearing in Claude"

1. Restart Claude Desktop after configuration
2. Check logs in Claude developer console
3. Verify Notepad++ is running on the system
4. Run demonstration script to test functionality

🆘 Getting Help

Run Diagnostics

# Test all functionality
python demonstration_test.py

# Check tool availability
python -c "from notepadpp_mcp.tools.server import app; print('Tools:', len(app._tools))"

Debug Mode

# Enable debug logging
import logging
logging.basicConfig(level=logging.DEBUG)

# Run server with debug output
python -m notepadpp_mcp.tools.server

Manual Testing

# Test portmanteau tools
from notepadpp_mcp.tools.server import file_ops, status_ops

# Get file info
info = await file_ops("info")
print("File info:", info)

# Get help
help_info = await status_ops("help")
print("Help:", help_info)

🤝 Contributing

📝 Development Setup

# Clone repository
git clone https://github.com/sandraschi/notepadpp-mcp.git
cd notepadpp-mcp

# Install development dependencies
pip install -e .[dev]

# Run tests
python -m pytest

# Format code
ruff format src/

# Build MCPB package
python dev.py build

🐛 Reporting Issues

1. Run demonstration script first: python demonstration_test.py
2. Check existing issues on GitHub
3. Include error logs and system information
4. Test with different Notepad++ versions if possible

Feature Requests

• Check existing portmanteau tools before proposing new ones
• Consider Windows API limitations
• Test with real Notepad++ workflows
• Follow FastMCP 2.14.1+ portmanteau patterns

Changelog

v1.2.0 - SOTA Compliance & Portmanteau Consolidation

• Portmanteau tool consolidation (26 → 8 tools)
• FastMCP 2.14.1+ compliance with enhanced response patterns
• Plugin ecosystem integration
• Display fix tools
• Updated MCPB packaging

v1.1.0 - Linting Tools

• Multi-language linting support
• Code quality analysis tools
• Enhanced testing coverage

v1.0.0 - Core Release

• Initial Notepad++ automation tools
• Windows API integration
• MCP server implementation

Planned Features

• Multi-instance support for multiple Notepad++ windows
• Advanced plugin workflows with multiple plugin coordination
• Plugin analytics and usage monitoring
• Custom plugin support for user-developed plugins
• HTML/CSS linting tools for web development
• Configuration files for custom settings
• Batch operations for multiple file processing

📄 License

MIT - see