添加 README.md

2025-04-17 00:44:09 +08:00
parent bab06c4c2a
commit 12f2c38db7
1 changed files with 138 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,138 @@
+# Maya MCP (Model Context Protocol)
+
+Maya integration through the Model Context Protocol for Windsurf connectivity.
+
+## Installation
+
+1. Drag `install.mel` into Maya viewport
+2. Click "Install" in the dialog
+3. **Important**: Restart Maya after installation
+4. The plugin should now be loaded automatically and the MCP menu should appear in Maya's menu bar
+
+## Uninstallation
+
+1. Drag `install.mel` into Maya viewport
+2. Click "Uninstall" in the dialog
+3. The plugin will be unloaded and removed from auto-load
+
+## Manual Loading
+
+If the plugin doesn't load automatically, you can load it manually in the Script Editor:
+
+```python
+import sys
+sys.path.append(r"D:/Dev/Tools/MayaMCP")
+import maya.cmds as cmds
+cmds.loadPlugin("D:/Dev/Tools/MayaMCP/maya_mcp_plugin.py")
+```
+
+If the MCP menu doesn't appear, you can create it manually:
+
+```mel
+source "D:/Dev/Tools/MayaMCP/install.mel";
+forceMCPMenu();
+```
+
+## Troubleshooting
+
+- If you encounter any issues after installation, try restarting Maya
+- Make sure the plugin directory is correctly set in your system
+- Check Maya's Script Editor for any error messages
+- Verify that all required files are present in the plugin directory
+- If the menu doesn't appear, use the `forceMCPMenu()` function as described above
+- If you get connection errors in Windsurf, check the configuration in `mcp_config.json`
+
+## Windsurf Configuration
+
+The Windsurf configuration file is located at:
+```
+C:\Users\<username>\.codeium\windsurf\mcp_config.json
+```
+
+Make sure it has the following settings:
+```json
+{
+  "mcpServers": {
+    "MayaMCP": {
+      "serverUrl": "http://127.0.0.1:4550/",
+      "sseEndpoint": "http://127.0.0.1:4550/",
+      "timeout": 10000,
+      "retryInterval": 1000,
+      "maxRetries": 10,
+      "debug": true,
+      "autoConnect": true
+    }
+  }
+}
+```
+
+## Testing
+
+You can test the server connection using the provided test scripts:
+
+```bash
+# Test the server binding address
+python Debug/check_server_binding.py
+
+# Test the SSE connection
+python Debug/test_sse_connection.py
+```
+
+These tests will help verify that the server is correctly bound to 127.0.0.1 and that SSE events are being properly transmitted.
+
+## Features
+
+- Windsurf connectivity via SSE
+- Scene information retrieval
+- Maya integration
+- FastAPI or HTTP server modes (automatic fallback)
+
+## Server Modes
+
+The MCP server can run in two modes:
+
+1. **FastAPI Mode** (Default): Uses FastAPI and UVicorn for better performance and stability
+2. **HTTP Mode** (Fallback): Uses Python's built-in HTTP server if FastAPI is not available
+
+The server automatically selects the best available mode. If FastAPI is installed, it will use that; otherwise, it will fall back to the HTTP server.
+
+## Configuration
+
+The MCP server runs on port 4550 by default. Make sure this port is available and not blocked by a firewall.
+
+## Advanced: Using UVicorn and FastAPI
+
+FastAPI and UVicorn are now the recommended server backend. They have been successfully tested with Maya 2025 and provide better performance and stability.
+
+### Installing with Maya's Python (mayapy)
+
+You can install FastAPI and UVicorn directly using Maya's Python interpreter:
+
+```bash
+# For Windows
+"C:\Program Files\Autodesk\Maya2025\bin\mayapy.exe" -m pip install fastapi uvicorn
+
+# For macOS
+/Applications/Autodesk/maya2025/Maya.app/Contents/bin/mayapy -m pip install fastapi uvicorn
+
+# For Linux
+/usr/autodesk/maya2025/bin/mayapy -m pip install fastapi uvicorn
+```
+
+This will install the packages directly into Maya's Python environment, ensuring they are available when running the MCP server from within Maya.
+
+### Offline Installation
+
+If you want to install FastAPI and UVicorn in an environment without internet access:
+
+```bash
+# In an environment with internet access, download dependencies
+pip download uvicorn fastapi -d ./packages
+
+# In the target environment, install
+pip install --no-index --find-links=./packages uvicorn fastapi
+```
+
+## License
+
+Copyright (c) Jeffrey Tsai