From 9a8fcf76cb9bf31b2ea299a9b043e6b684942bcc Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 24 Oct 2025 14:45:06 +0000 Subject: [PATCH] docs: add MCP Server setup guide for Claude Desktop integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added comprehensive MCP Server configuration guide to enable direct file access between Claude Desktop and the Wan2.1 PWA project. Features: - Step-by-step installation for macOS, Windows, Linux - Configuration examples with actual paths - Verification and testing instructions - Troubleshooting common issues - Security best practices - Advanced configuration options - Comparison with current session workflow This will help developers and collaborators set up persistent file access for seamless development with Claude Desktop. ๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- wan-pwa/MCP_SERVER_SETUP.md | 519 ++++++++++++++++++++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 wan-pwa/MCP_SERVER_SETUP.md diff --git a/wan-pwa/MCP_SERVER_SETUP.md b/wan-pwa/MCP_SERVER_SETUP.md new file mode 100644 index 0000000..30c6b61 --- /dev/null +++ b/wan-pwa/MCP_SERVER_SETUP.md @@ -0,0 +1,519 @@ +# MCP Server Setup for Wan2.1 PWA + +## Overview +This guide shows how to connect Claude Desktop to your local Wan2.1 PWA project directory for persistent file access and seamless development workflow. + +## What is MCP? + +**Model Context Protocol (MCP)** allows Claude Desktop to directly access and manipulate files in your local project directory, eliminating the need to copy files back and forth. + +### Benefits +- ๐Ÿ”„ **Direct File Access** - Claude can read and write files directly in your project +- ๐Ÿ’พ **Persistent Changes** - All edits are saved to your local filesystem +- ๐Ÿš€ **Faster Workflow** - No manual copying of code between sessions +- ๐Ÿ”’ **Secure** - Runs locally on your machine, you control access + +--- + +## Prerequisites + +- **Claude Desktop** installed ([download here](https://claude.ai/download)) +- **Node.js 18+** installed +- **Your Wan2.1 PWA project** cloned locally + +--- + +## Installation & Setup + +### Step 1: Install MCP SDK + +Choose one of these methods: + +#### Global Installation (Recommended) +```bash +npm install -g @modelcontextprotocol/sdk +``` + +#### Or Use npx (No global install needed) +```bash +npx @modelcontextprotocol/sdk --version +``` + +--- + +### Step 2: Get Your Project Path + +You need the **absolute path** to your wan-pwa directory. + +#### macOS/Linux +```bash +cd /path/to/Wan2.1/wan-pwa +pwd +# Example output: /Users/yourname/projects/Wan2.1/wan-pwa +``` + +#### Windows +```powershell +cd C:\path\to\Wan2.1\wan-pwa +cd +# Example output: C:\Users\yourname\projects\Wan2.1\wan-pwa +``` + +**Copy this path** - you'll need it in the next step. + +--- + +### Step 3: Configure Claude Desktop + +#### macOS + +1. **Open Claude Desktop Settings** + - Click **Claude** in menu bar โ†’ **Settings** (or `Cmd + ,`) + - Navigate to **Developer** tab + - Click **Edit Config** + +2. **Add MCP Server Configuration** + + Paste this JSON (replace `YOUR_ABSOLUTE_PATH`): + + ```json + { + "mcpServers": { + "wan-pwa": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "YOUR_ABSOLUTE_PATH" + ] + } + } + } + ``` + + **Example (macOS):** + ```json + { + "mcpServers": { + "wan-pwa": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "/Users/johnsmith/projects/Wan2.1/wan-pwa" + ] + } + } + } + ``` + +3. **Save and Restart** + - Save the file (`Cmd + S`) + - Quit Claude Desktop (`Cmd + Q`) + - Reopen Claude Desktop + +#### Windows + +1. **Open Claude Desktop Settings** + - Click **Settings** icon โ†’ **Developer** tab + - Click **Edit Config** + +2. **Add MCP Server Configuration** + + Paste this JSON (replace `YOUR_ABSOLUTE_PATH`): + + ```json + { + "mcpServers": { + "wan-pwa": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "YOUR_ABSOLUTE_PATH" + ] + } + } + } + ``` + + **Example (Windows):** + ```json + { + "mcpServers": { + "wan-pwa": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "C:\\Users\\johnsmith\\projects\\Wan2.1\\wan-pwa" + ] + } + } + } + ``` + + **Note:** Use double backslashes (`\\`) in Windows paths. + +3. **Save and Restart** + - Save the file + - Close and reopen Claude Desktop + +#### Linux + +1. **Open Claude Desktop Settings** + - Open Settings โ†’ Developer tab + - Click **Edit Config** + +2. **Add MCP Server Configuration** + + Paste this JSON (replace `YOUR_ABSOLUTE_PATH`): + + ```json + { + "mcpServers": { + "wan-pwa": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "YOUR_ABSOLUTE_PATH" + ] + } + } + } + ``` + + **Example (Linux):** + ```json + { + "mcpServers": { + "wan-pwa": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "/home/johnsmith/projects/Wan2.1/wan-pwa" + ] + } + } + } + ``` + +3. **Save and Restart** + - Save the file + - Restart Claude Desktop + +--- + +### Step 4: Verify Connection + +Open a new conversation in Claude Desktop and ask: + +``` +Can you list the files in my wan-pwa project? +``` + +**Expected Response:** +``` +wan-pwa/ +โ”œโ”€โ”€ apps/ +โ”‚ โ”œโ”€โ”€ web/ +โ”‚ โ””โ”€โ”€ api/ +โ”œโ”€โ”€ packages/ +โ”‚ โ”œโ”€โ”€ db/ +โ”‚ โ””โ”€โ”€ types/ +โ”œโ”€โ”€ README.md +โ”œโ”€โ”€ SETUP.md +โ”œโ”€โ”€ package.json +... +``` + +If you see the file structure, **you're connected!** ๐ŸŽ‰ + +--- + +## Using MCP with Your Project + +### Common Tasks + +#### View a File +``` +Show me the content of apps/web/src/app/page.tsx +``` + +#### Edit a File +``` +Update the Button component in apps/web/src/components/ui/button.tsx to add a loading state +``` + +#### Create New Files +``` +Create a new API endpoint for video analytics in apps/api/routes/analytics.py +``` + +#### Run Commands +``` +Run npm install in the web app directory +``` + +#### Database Migrations +``` +Create a new migration to add a 'favorites' table +``` + +### Example Workflow + +1. **Ask for Code Review** + ``` + Review the generation.py file and suggest improvements + ``` + +2. **Request New Features** + ``` + Add a retry button to failed generations in the history page + ``` + +3. **Debug Issues** + ``` + Why is the credit deduction not working? Check the database functions + ``` + +4. **Refactor Code** + ``` + Extract the image upload logic into a reusable hook + ``` + +--- + +## Alternative: Claude Code CLI + +For terminal-based workflows: + +```bash +# Install CLI +npm install -g claude-code + +# Navigate to project +cd /path/to/Wan2.1/wan-pwa + +# Start session +claude-code + +# In the CLI +> connect /path/to/Wan2.1/wan-pwa +> list files +> edit apps/web/src/app/page.tsx +``` + +--- + +## Troubleshooting + +### Issue: "MCP server not found" + +**Solution:** +1. Verify `@modelcontextprotocol/sdk` is installed: + ```bash + npm list -g @modelcontextprotocol/sdk + ``` + +2. Check your config path is absolute (not relative): + ```bash + # โœ… Correct + "/Users/john/projects/Wan2.1/wan-pwa" + + # โŒ Wrong + "~/projects/Wan2.1/wan-pwa" + "./wan-pwa" + ``` + +3. Restart Claude Desktop completely + +--- + +### Issue: "Permission denied" + +**Solution:** +1. Check directory permissions: + ```bash + ls -la /path/to/Wan2.1/wan-pwa + ``` + +2. Ensure you have read/write access: + ```bash + chmod -R u+rw /path/to/Wan2.1/wan-pwa + ``` + +3. Don't run Claude Desktop with `sudo` + +--- + +### Issue: "Files not updating" + +**Solution:** +1. MCP servers don't auto-reload on file changes +2. Ask Claude to "refresh" or "reload" the file +3. Restart the MCP server: + - Quit Claude Desktop + - Reopen and start new conversation + +--- + +### Issue: "command not found: npx" + +**Solution:** +1. Install Node.js 18+ from [nodejs.org](https://nodejs.org) +2. Verify installation: + ```bash + node --version + npm --version + npx --version + ``` + +3. Restart terminal and Claude Desktop + +--- + +### Issue: Windows Path with Spaces + +**Solution:** +Use double backslashes and quotes: + +```json +{ + "mcpServers": { + "wan-pwa": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "C:\\Users\\John Smith\\projects\\Wan2.1\\wan-pwa" + ] + } + } +} +``` + +--- + +## Security Best Practices + +### โœ… DO: +- Only grant access to your project directory +- Use `.gitignore` for secrets and credentials +- Keep `.env` files out of version control +- Review MCP config before saving + +### โŒ DON'T: +- Grant access to root directory (`/` or `C:\`) +- Share your Claude Desktop config publicly +- Commit API keys or secrets to git +- Run with elevated permissions unnecessarily + +--- + +## Advanced Configuration + +### Multiple Projects + +You can configure multiple MCP servers: + +```json +{ + "mcpServers": { + "wan-pwa": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/wan-pwa"] + }, + "other-project": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/other-project"] + } + } +} +``` + +### Read-Only Access + +For code review without edit permissions: + +```json +{ + "mcpServers": { + "wan-pwa-readonly": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "/path/to/wan-pwa", + "--readonly" + ] + } + } +} +``` + +--- + +## Comparison: MCP vs Current Session + +| Feature | Current Session | With MCP Server | +|---------|----------------|-----------------| +| File Access | Temporary | Persistent | +| Edits | Need manual copy | Direct to files | +| Git Integration | Manual commands | Direct access | +| Multiple Projects | One at a time | Multiple servers | +| Setup Time | None | 5 minutes | +| Best For | Quick tasks | Deep development | + +--- + +## Next Steps + +1. โœ… Complete MCP setup using steps above +2. ๐Ÿงช Test connection with simple file operations +3. ๐Ÿš€ Start using Claude for development tasks +4. ๐Ÿ“š Explore [MCP Documentation](https://modelcontextprotocol.io/docs) for advanced features + +--- + +## Resources + +- **MCP Protocol Documentation**: https://modelcontextprotocol.io/docs +- **Claude Desktop Download**: https://claude.ai/download +- **Filesystem Server**: https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem +- **Claude Code Guide**: https://docs.claude.com/en/docs/claude-code +- **Wan2.1 PWA Docs**: See README.md, SETUP.md, DEPLOYMENT.md + +--- + +## Support + +### Getting Help + +1. Check this documentation +2. Review troubleshooting section +3. Check [MCP GitHub Issues](https://github.com/modelcontextprotocol/typescript-sdk/issues) +4. Ask in Claude Desktop (once connected!) + +### Common Questions + +**Q: Do I need MCP for development?** +A: No, but it significantly improves the workflow for active development. + +**Q: Does MCP work with claude.ai (web)?** +A: No, MCP is currently desktop-only. Use file uploads for web. + +**Q: Can I use MCP with VS Code?** +A: MCP is for Claude Desktop. For VS Code, use the Claude Code extension. + +**Q: Is my code sent to Anthropic?** +A: Only the files you discuss in conversations. MCP runs locally. + +**Q: Can multiple people share an MCP config?** +A: Yes, but each person needs their own absolute path configured. + +--- + +**Setup Complete?** Start building with Phase 4 features! ๐ŸŽ‰