chore: add type hints and suppress Pylance Blender import warnings

- Add # type: ignore to all bpy, bmesh, addon_utils, mathutils imports
- Fix Optional type hints to use X | None syntax (Python 3.10+)
- Add type guards for socket.socket | None in server.py
- Add dict isinstance checks before attribute access
- Fix mixed-in method calls with # type: ignore in modeling operators
- Fix tuple attribute access (.z -> [2]) for Pylance compatibility
- Update integration_tests.md with all four scenarios (grid, arch, print, filament_tag)
- Update unit_tests.md to use [PASS] instead of emoji
- Simplify mushroom keychain to red cap, update README
- Delete outdated MULTICOLOR_3MF_GUIDE.md

All type checking now passes with no false positives on Blender APIs.

Author: seehiong

README.md

@@ -356,7 +356,7 @@ Set environment variables in `.env`:
 
 ```
 BLENDER_MCP_HOST=127.0.0.1
-BLENDER_MCP_PORT=8888
+BLENDER_MCP_PORT=8585
 BLENDER_ASSETS_DIR=C:/path/to/your/assets
 
 ```

blender_mcp_addon/__init__.py

@@ -1,6 +1,9 @@
-import bpy
+# blender_mcp_addon/__init__.py
+
+import bpy  # type: ignore
 
 from .server import BlenderMCPServer
+from .utils import DEFAULT_PORT
 
 bl_info = {
     "name": "Blender MCP for n8n",
@@ -69,7 +72,7 @@ def draw(self, context):
         layout.operator("blendermcp.start_server")
         layout.operator("blendermcp.stop_server")
         layout.separator()
-        layout.label(text="Port: 8888")
+        layout.label(text=f"Port: {DEFAULT_PORT}")
         layout.label(text="45+ Structured Tools")
 
 

blender_mcp_addon/server.py

@@ -1,10 +1,12 @@
+# blender_mcp_addon/server.py
+
 import json
 import queue
 import socket
 import threading
 import traceback
 
-import bpy
+import bpy  # type: ignore
 
 from .tools.animation import AnimationTools
 from .tools.camera import CameraTools
@@ -17,6 +19,7 @@
 from .tools.rendering import RenderingTools
 from .tools.scene import SceneTools
 from .tools.sculpting import SculptingTools
+from .utils import DEFAULT_HOST, DEFAULT_PORT
 
 
 class BlenderMCPServer(
@@ -35,7 +38,7 @@ class BlenderMCPServer(
     """Blender MCP Server for n8n with componentized tools"""
 
     def __init__(self):
-        self.server_socket = None
+        self.server_socket: socket.socket | None = None
         self.running = False
         self.server_thread = None
         self.command_queue = queue.Queue()
@@ -85,10 +88,11 @@ def import_and_analyze_reference(self, filepath=None):
             "bound_box": bound_box,
         }
 
-    def start_server(self, host="0.0.0.0", port=8888):
+    def start_server(self, host=DEFAULT_HOST, port=DEFAULT_PORT):
         if self.running:
             return
         try:
+            self.addon_log("Attempting to start MCP Server...")
             self.server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
             self.server_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
             self.server_socket.bind((host, port))
@@ -97,10 +101,14 @@ def start_server(self, host="0.0.0.0", port=8888):
             self.server_thread = threading.Thread(target=self._server_loop, daemon=True)
             self.server_thread.start()
             self._register_timer()
+            self.addon_log(f"MCP Server successfully started on {host}:{port}")
             print(f"MCP Server started on {host}:{port}")
         except Exception as e:
-            print(f"Failed to start server: {e}")
-            traceback.print_exc()
+            import traceback
+
+            error_msg = f"Failed to start server: {e}\n{traceback.format_exc()}"
+            print(error_msg)
+            self.addon_log(error_msg)
 
     def _register_timer(self):
         if self.timer_handle:
@@ -129,6 +137,8 @@ def stop_server(self):
     def _server_loop(self):
         while self.running:
             try:
+                if not self.server_socket:  # type: ignore
+                    break
                 self.server_socket.settimeout(1.0)
                 try:
                     client, _ = self.server_socket.accept()
@@ -263,6 +273,7 @@ def execute_command(self, command):
             "create_text": self.create_text,
             "create_plane": self.create_plane,
             "create_empty": self.create_empty,
+            "create_polygon": self.create_polygon,
             "duplicate_object": self.duplicate_object,
             "duplicate_selection": self.duplicate_selection,
             "create_and_array": self.create_and_array,
@@ -329,6 +340,7 @@ def execute_command(self, command):
             "repair_mesh": self.repair_mesh,
             "apply_voxel_remesh": self.apply_voxel_remesh,
             "export_model": self.export_model,
+            "import_model": self.import_model,
             # Sculpting
             "enter_sculpt_mode": self.enter_sculpt_mode,
             "exit_sculpt_mode": self.exit_sculpt_mode,

blender_mcp_addon/tools/animation.py

@@ -1,6 +1,8 @@
+# blender_mcp_addon/tools/animation.py
+
 import math
 
-import bpy
+import bpy  # type: ignore
 
 from ..utils import get_object
 

blender_mcp_addon/tools/camera.py

@@ -1,7 +1,9 @@
+# blender_mcp_addon/tools/camera.py
+
 import math
 
-import bpy
-from mathutils import Vector
+import bpy  # type: ignore
+from mathutils import Vector  # type: ignore
 
 from ..utils import get_object
 

blender_mcp_addon/tools/collections.py

@@ -1,4 +1,6 @@
-import bpy
+# blender_mcp_addon/tools/collections.py
+
+import bpy  # type: ignore
 
 from ..utils import get_collection, get_object
 

blender_mcp_addon/tools/history.py

@@ -1,4 +1,6 @@
-import bpy
+# blender_mcp_addon/tools/history.py
+
+import bpy  # type: ignore
 
 
 class HistoryTools:

blender_mcp_addon/tools/lighting.py

@@ -1,6 +1,8 @@
+# blender_mcp_addon/tools/lighting.py
+
 import math
 
-import bpy
+import bpy  # type: ignore
 
 from ..utils import get_object, hex_to_rgb
 

blender_mcp_addon/tools/materials.py

@@ -1,6 +1,8 @@
+# blender_mcp_addon/tools/materials.py
+
 import fnmatch
 
-import bpy
+import bpy  # type: ignore
 
 from ..utils import get_object, hex_to_rgb
 

blender_mcp_addon/tools/modeling/__init__.py

@@ -1,3 +1,5 @@
+# blender_mcp_addon/tools/modeling/__init__.py
+
 from .architectural import ModelingArchitectural
 from .modifiers import ModelingModifiers
 from .operators import ModelingOperators