Initial commit

skills/mcp-server-creator/reference/troubleshooting.md

@@ -0,0 +1,103 @@
+# MCP Server Troubleshooting
+
+## Error Handling Patterns
+
+### Validation Errors
+
+```typescript
+if (!isValid(input)) {
+  throw new Error("Invalid input: expected format X, got Y");
+}
+```
+
+### API Errors
+
+```typescript
+try {
+  const result = await externalAPI.call();
+  return result;
+} catch (error) {
+  console.error("API error:", error);
+  return {
+    content: [{
+      type: "text",
+      text: `Error: ${error.message}. Please try again.`
+    }]
+  };
+}
+```
+
+### Resource Not Found
+
+```typescript
+if (!resource) {
+  throw new Error(`Resource not found: ${uri}`);
+}
+```
+
+---
+
+## Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Server not detected | Invalid path | Use absolute path, verify file exists |
+| Tools don't appear | Build not run | Run `npm run build` |
+| "Server error" | stdout logging | Remove console.log, use console.error |
+| Connection timeout | Server crash | Check mcp-server-NAME.log for errors |
+| Invalid config | JSON syntax | Validate JSON, check quotes/commas |
+
+---
+
+## Quick Reference Commands
+
+### Check Claude Desktop Logs
+
+```bash
+tail -f ~/Library/Logs/Claude/mcp.log
+tail -f ~/Library/Logs/Claude/mcp-server-[name].log
+```
+
+### Validate Config JSON
+
+```bash
+python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
+```
+
+### Test with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector [command] [args]
+```
+
+### Restart Claude Desktop
+
+```bash
+# macOS
+osascript -e 'quit app "Claude"'
+open -a Claude
+```
+
+---
+
+## Transport-Specific Issues
+
+### STDIO Transport
+
+**Problem**: Server crashes with no error
+**Cause**: Using console.log() which corrupts JSON-RPC
+**Solution**: Use console.error() only
+
+**Problem**: Server not responding
+**Cause**: Blocking synchronous operation
+**Solution**: Use async/await for all I/O
+
+### HTTP Transport
+
+**Problem**: Connection refused
+**Cause**: Wrong port or server not running
+**Solution**: Check PORT env var, verify server started
+
+**Problem**: Authentication errors
+**Cause**: Missing or invalid credentials
+**Solution**: Configure auth headers/tokens