Notepad++ MCP Server

# 🔥 Python Dependency Hell - The Great 3.13 Catastrophe of October 2025 **Date**: October 8, 2025 **Severity**: CRITICAL - All MCP servers broken **Status**: RESOLVED **Lesson**: Dependency hell was not invented on a whim! --- ## 🚨 **The Disaster** **What Happened**: - A server imported a tool incompatible with Python 3.13 - Cursor installed **Python 3.10** as a workaround (became default) - Config files (`pyproject.toml`) still demanded Python 3.13 - **RESULT**: All MCP servers broke with `TypeError: 'function' object is not subscriptable'` --- ## 📊 **Timeline** | Time | Event | Impact | |------|-------|--------| | ~1 week ago | Started using Python 3.13 | Seemed fine initially | | Early Oct 2025 | Installed incompatible tool | Broke one server | | Oct 7, 2025 | Cursor auto-installed Python 3.10 | All servers stopped working | | Oct 8, 2025 | Fixed with version constraints | ✅ Servers working again | --- ## 💥 **The Error** **Symptom**: ``` TypeError: 'function' object is not subscriptable File "...\mcp\server\session.py", line 96, in __init__ self._incoming_message_stream_writer, self._incoming_message_stream_reader = anyio.create_memory_object_stream[ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^ ServerRequestResponder ^^^^^^^^^^^^^^^^^^^^^^ ](0) ^ ``` **Affected servers**: - ❌ notepadpp-mcp - ❌ advanced-memory-mcp - ❌ rtorrent-mcp - ❌ Most other MCP servers **Servers that worked**: - ✅ basic-memory (already had fix) --- ## 🔍 **Root Cause Analysis** ### **Problem 1: MCP SDK 1.16.0 Breaking Change** **IMPORTANT CLARIFICATION**: - ✅ Python 3.13 worked fine for MONTHS with MCP 1.14.1 - ❌ MCP SDK 1.16.0 introduced Python 3.13 incompatibility - **It's not Python 3.13's fault - it's MCP 1.16.0!** **What happened**: - **Sept 2025**: Python 3.13 + MCP 1.14.1 + FastMCP 2.12.3 = ✅ Working - **Oct 7, 2025**: Package auto-updated to MCP 1.16.0 - **MCP 1.16.0** broke Python 3.13 compatibility - Generic type syntax `anyio.create_memory_object_stream[Type]` now fails **MCP ecosystem status** (Oct 2025): - `mcp` **1.14.1**: ✅ Python 3.13 compatible - `mcp` **1.16.0**: ❌ Python 3.13 broken - `fastmcp`: Works with either, depends on MCP version ### **Problem 2: Auto-Update to MCP 1.16.0** **What was working** (September 2025): ```toml # Python 3.13 + these packages worked perfectly: fastmcp==2.12.3 mcp==1.14.1 # ← This version was fine with 3.13! ``` **What broke** (October 2025): ```toml # Auto-update pulled new version: fastmcp>=2.12.0 # Pulled 2.12.4 # Which pulled: mcp==1.16.0 ← This broke 3.13! ``` **What happened**: 1. `fastmcp>=2.12.0` auto-upgraded to 2.12.4 2. FastMCP 2.12.4 pulled MCP 1.16.0 3. **MCP 1.16.0 broke Python 3.13 compatibility** 4. All servers using 3.13 crashed with `TypeError` 5. **BOOM!** 💥 --- ## ✅ **The Fix - THREE OPTIONS** ### **Option A: Downgrade MCP (Keep Python 3.13)** ⭐ **RECOMMENDED IF YOU LIKE 3.13** **Go back to the version that worked**: ```bash pip uninstall fastmcp mcp -y pip install fastmcp==2.12.3 mcp==1.14.1 ``` **Update your requirements.txt**: ```python fastmcp==2.12.3 mcp==1.14.1 ``` **Result**: ✅ Python 3.13 works again! --- ### **Option B: Downgrade Python (Keep MCP 1.16.0)** - Current Solution **Switch to Python 3.10**: ```toml requires-python = ">=3.10" ``` **Why**: Python 3.10 works with all MCP versions, including 1.16.0. --- ### **Option C: Wait for Fix** **Wait for**: - MCP 1.17.0 or later with Python 3.13 fix - Check https://github.com/modelcontextprotocol/python-sdk --- ### **Step 2: Constrain Package Versions** **Update `requirements.txt`**: ```python # Notepad++ MCP Server Requirements # Compatible with Python 3.10+ # Windows only fastmcp>=2.12.0 mcp>=1.0.0,<2.0.0 # ← CRITICAL: Pin to 1.x anyio>=4.0.0,<5.0.0 # ← CRITICAL: Prevent incompatible versions psutil>=5.9.0 pywin32==311; platform_system=='Windows' requests>=2.31.0 ``` **Update `pyproject.toml`**: ```toml [project] requires-python = ">=3.10" dependencies = [ "fastmcp>=2.12.0", "mcp>=1.0.0,<2.0.0", # ← CRITICAL "anyio>=4.0.0,<5.0.0", # ← CRITICAL "psutil>=5.9.0", "pywin32==311; platform_system=='Windows'", "requests>=2.31.0", ] ``` --- ### **Step 3: Reinstall Packages** ```bash # Remove broken packages pip uninstall fastmcp mcp anyio -y # Reinstall with constraints pip install "fastmcp>=2.12.0" "mcp>=1.0.0,<2.0.0" "anyio>=4.0.0,<5.0.0" # Or just reinstall from requirements.txt pip install -r requirements.txt ``` --- ### **Step 4: Verify** ```bash # Test server startup python -m notepadpp_mcp.tools.server # Should see: # ✅ FastMCP 2.12.4 # ✅ MCP SDK 1.16.0 # ✅ No TypeError! ``` --- ## 🎯 **The Fix - Quick Reference Card** **Copy-paste this into ANY broken MCP server:** ### **requirements.txt**: ```python fastmcp>=2.12.0 mcp>=1.0.0,<2.0.0 anyio>=4.0.0,<5.0.0 ``` ### **pyproject.toml**: ```toml requires-python = ">=3.10" dependencies = [ "fastmcp>=2.12.0", "mcp>=1.0.0,<2.0.0", "anyio>=4.0.0,<5.0.0", # ... other deps ] ``` ### **Then run**: ```bash pip uninstall fastmcp mcp anyio -y pip install -r requirements.txt ``` **DONE!** ✅ --- ## 📚 **Lessons Learned** ### **1. It Wasn't Python 3.13's Fault!** **What we THOUGHT**: - Python 3.13 is too new - Breaking changes in 3.13 caused issues - Should stick with 3.10 **What ACTUALLY happened**: - ✅ Python 3.13 worked perfectly for MONTHS - ❌ **MCP SDK 1.16.0 broke Python 3.13 compatibility** - The problem was the package update, not Python itself! **Rule**: **Pin your MCP version** or be ready for breakage --- ### **2. Always Pin Versions (ESPECIALLY MCP!)** **What broke us**: ```python fastmcp>=2.12.0 # Auto-pulled MCP 1.16.0 and broke everything! ``` **What worked**: ```python fastmcp==2.12.3 # Exact version mcp==1.14.1 # Exact version - worked with Python 3.13 ``` **Or use constraints**: ```python fastmcp>=2.12.0,<2.13.0 mcp>=1.14.0,<1.16.0 # Avoid 1.16.0! ``` **Why**: **MCP 1.16.0 specifically broke Python 3.13**. Pin to avoid surprises! --- ### **3. Dependency Hell is Real** **The term was not invented on a whim!** **What happened**: 1. We wanted Python 3.13 2. MCP required older `anyio` 3. But newer tools required newer packages 4. **Conflict!** Everything broke **Solution**: - Document known-good versions - Test before upgrading - Have rollback plan --- ## 🛠️ **Applying to Other Servers** ### **For advanced-memory-mcp**: ```bash cd D:\Dev\repos\advanced-memory-mcp # Edit requirements.txt - add: # mcp>=1.0.0,<2.0.0 # anyio>=4.0.0,<5.0.0 # Reinstall pip uninstall fastmcp mcp anyio -y pip install -r requirements.txt # Test python -m advanced_memory_mcp.server ``` --- ### **For rtorrent-mcp**: ```bash cd D:\Dev\repos\rtorrent-mcp # Same process # Edit requirements.txt # Reinstall packages # Test ``` --- ### **For ANY MCP Server**: **Universal fix**: 1. Set `requires-python = ">=3.10"` 2. Add `mcp>=1.0.0,<2.0.0` to dependencies 3. Add `anyio>=4.0.0,<5.0.0` to dependencies 4. Uninstall and reinstall packages 5. Test server startup --- ## 📊 **Version Compatibility Matrix** | Python | MCP | fastmcp | Status | Notes | |--------|-----|---------|--------|-------| | 3.10 | 1.14.1 | 2.12.3 | ✅ Works | Stable | | 3.10 | 1.16.0 | 2.12.4 | ✅ Works | Current fix | | 3.13 | 1.14.1 | 2.12.3 | ✅ Works | **Worked for months!** | | 3.13 | 1.16.0 | 2.12.4 | ❌ BREAKS | **MCP 1.16.0 broke 3.13!** | **Key finding**: MCP 1.14.1 works with Python 3.13, but MCP 1.16.0 doesn't! **As of**: October 2025 --- ## 🔮 **Can We Use Python 3.13 NOW?** **YES! Just use the old MCP version**: ```bash pip install fastmcp==2.12.3 mcp==1.14.1 ``` **This combination worked for months!** **Or wait for**: 1. MCP 1.17.0+ with Python 3.13 fix 2. Check release notes at https://github.com/modelcontextprotocol/python-sdk **Update**: You CAN use Python 3.13, just not with MCP 1.16.0 specifically! --- ## 💡 **Prevention - Future-Proofing** ### **1. Document Known-Good Versions** Create `TESTED_VERSIONS.md`: ```markdown # Last tested: October 8, 2025 - Python: 3.10.11 ✅ - fastmcp: 2.12.4 ✅ - mcp: 1.16.0 ✅ - anyio: 4.11.0 ✅ ``` --- ### **2. Use Virtual Environments** ```bash # Per-project isolation python -m venv .venv .venv\Scripts\activate pip install -r requirements.txt ``` **Why**: Prevents global package conflicts. --- ### **3. Lock Dependencies** Use `pip freeze` after confirming things work: ```bash # After successful install pip freeze > requirements-lock.txt # To reproduce exactly pip install -r requirements-lock.txt ``` --- ### **4. Add Pre-commit Hooks** ```yaml # .pre-commit-config.yaml - repo: local hooks: - id: check-python-version name: Check Python version entry: python -c "import sys; assert sys.version_info[:2] == (3, 10)" language: system ``` --- ## 🎓 **Wisdom from the Trenches** ### **Quote of the Day**: > "Dependency hell was not invented on a whim!" > *— Sandra, after fixing 10+ broken MCP servers* ### **Truths Discovered**: 1. **Newer ≠ Better** - Python 3.13 looks shiny - Python 3.10 actually works - Choose reliability over novelty 2. **Pin Everything** - `>=2.0.0` is an invitation to disaster - `>=2.0.0,<3.0.0` is sanity - Document WHY you pinned versions 3. **Test Incrementally** - Don't upgrade everything at once - Test one package at a time - Have a rollback plan 4. **Listen to Your Gut (But Investigate!)** - "3.13 seems like hassle" felt right - But turned out 3.13 worked fine for months! - The real issue was MCP 1.16.0 - Trust your instincts, but verify the root cause 5. **AI Isn't Always Right (Including Me!)** - I blamed Python 3.13 - Actually it was MCP 1.16.0 - Always check the timeline - Question assumptions (even from AI!) --- ## 📝 **Checklist: Fixing a Broken MCP Server** - [ ] Identify error: `TypeError: 'function' object is not subscriptable'` - [ ] Check Python version: `python --version` - [ ] Check if Python 3.13: If yes, that's likely the problem - [ ] Update `requirements.txt`: - [ ] Add `mcp>=1.0.0,<2.0.0` - [ ] Add `anyio>=4.0.0,<5.0.0` - [ ] Update `pyproject.toml`: - [ ] Set `requires-python = ">=3.10"` - [ ] Add same version constraints - [ ] Uninstall broken packages: `pip uninstall fastmcp mcp anyio -y` - [ ] Reinstall: `pip install -r requirements.txt` - [ ] Test: `python -m <server_module>` - [ ] Verify: Look for FastMCP banner, no errors - [ ] Document: Note the fix in your server's README --- ## 🎯 **Success Criteria** **Server is fixed when**: ✅ Server starts without errors ✅ FastMCP banner displays ✅ No `TypeError` about subscripting ✅ Appears in Claude Desktop MCP list ✅ Tools are callable --- ## 📞 **Still Broken?** **If this fix doesn't work**: 1. **Check other dependencies**: ```bash pip list | grep -E "mcp|fastmcp|anyio|pydantic" ``` 2. **Try clean install**: ```bash rm -rf .venv python -m venv .venv .venv\Scripts\activate pip install -r requirements.txt ``` 3. **Check for conflicts**: ```bash pip check ``` 4. **Verify Python version**: ```bash python --version # Should be 3.10.x or 3.11.x ``` 5. **Check server logs**: - Windows: `%APPDATA%\Claude\logs\mcp-server-<name>.log` - Look for detailed error messages --- ## 🏆 **The Moral of the Story** **Technology Stack Wisdom**: 1. **Stable > Shiny** - Use proven versions - Wait for ecosystem to catch up - Don't be an early adopter in production 2. **Pin Your Dependencies** - Explicit is better than implicit - Version ranges prevent surprises - Document why versions are pinned 3. **Test Before Upgrading** - One component at a time - In isolated environment first - Have rollback ready 4. **Trust Your Instincts** - "Not worth the hassle" was right - Experience matters - Question recommendations 5. **Document Everything** - Future you will thank you - Dependency hell will return - Solutions get forgotten --- **Remember**: When someone says "Just upgrade to the latest Python", show them this document! 📖 --- *Documented by: Claude Sonnet 4.5 (ironically, after recommending Python 3.13)* *Lesson learned: Even AI makes mistakes. Trust experienced developers.* *Date: October 8, 2025* *Status: Never forget the dependency hell of October 2025* **Dependency hell was not invented on a whim!** 🔥