added debugging

2024-11-20 14:55:31 -05:00 · 2024-11-20 14:55:31 -05:00 · 4ff95a730c
commit 4ff95a730c
parent a6595252ce
2 changed files with 478 additions and 2542 deletions
--- a/docs/tools/debugging.mdx
+++ b/docs/tools/debugging.mdx
@ -0,0 +1,242 @@
+---
+title: Debugging MCP servers
+description: A comprehensive guide to debugging Model Context Protocol (MCP) servers and integrations
+---
+
+Effective debugging is essential when developing MCP servers or integrating them with applications. This guide covers the debugging tools and approaches available in the MCP ecosystem.
+
+## Debugging tools overview
+
+MCP provides several tools for debugging at different levels:
+
+1. **MCP Inspector**
+   - Interactive debugging interface
+   - Direct server testing
+   - See the [Inspector Guide](docs/tools/inspector) for details
+
+2. **Claude.app Developer Tools**
+   - Integration testing
+   - Log collection
+   - Chrome DevTools integration
+
+3. **Server Logging**
+   - Custom logging implementations
+   - Error tracking
+   - Performance monitoring
+
+## Debugging in Claude.app
+
+### Checking server status
+
+The Claude.app interface provides basic server status information:
+
+1. Click the 🔌 icon to view:
+   - Connected servers
+   - Available prompts
+   - Accessible resources
+   - Supported tools
+
+### Enabling logging
+
+Get detailed logs from Claude.app:
+
+```bash
+# Launch with logging enabled
+open /Applications/Claude.app --stdout ~/Claude.log --stderr ~/Claude.log
+
+# Follow logs in real-time
+tail -n 100 -f ~/Claude.log
+```
+
+The logs capture:
+- Server connection events
+- Configuration issues
+- Runtime errors
+- Message exchanges
+
+### Using Chrome DevTools
+
+Access Chrome's developer tools for deeper inspection:
+
+1. Enable DevTools:
+```bash
+jq '.allowDevTools = true' ~/Library/Application\ Support/Claude/developer_settings.json > tmp.json \
+  && mv tmp.json ~/Library/Application\ Support/Claude/developer_settings.json
+```
+
+2. Open DevTools: `Command-Option-Shift-i`
+
+Note: You'll see two DevTools windows:
+- Main content window
+- App title bar window
+
+Use the Network panel to inspect:
+- WebSocket connections
+- Server-sent events
+- Message payloads
+- Connection timing
+
+## Common issues
+
+### Environment variables
+
+MCP servers don't inherit environment variables automatically. Configure them in `claude_desktop_config.json`:
+
+```json
+{
+  "myserver": {
+    "command": "mcp-server-myapp",
+    "env": {
+      "HOME": "/Users/username",
+      "PATH": "/usr/local/bin:/usr/bin:/bin"
+    }
+  }
+}
+```
+
+### Server initialization
+
+Common initialization problems:
+
+1. **Path Issues**
+   - Incorrect server executable path
+   - Missing required files
+   - Permission problems
+
+2. **Configuration Errors**
+   - Invalid JSON syntax
+   - Missing required fields
+   - Type mismatches
+
+3. **Environment Problems**
+   - Missing environment variables
+   - Incorrect variable values
+   - Permission restrictions
+
+### Connection problems
+
+When servers fail to connect:
+
+1. Check Claude.app logs
+2. Verify server process is running
+3. Test standalone with Inspector
+4. Check network connectivity
+5. Verify protocol compatibility
+
+## Implementing logging
+
+### Server-side logging
+
+Implement custom logging in your server:
+
+```typescript
+server.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => {
+  console.log(`[${notification.params.level}] ${notification.params.data}`);
+});
+```
+
+Important events to log:
+- Initialization steps
+- Resource access
+- Tool execution
+- Error conditions
+- Performance metrics
+
+### Client-side logging
+
+In client applications:
+
+1. Enable debug logging
+2. Monitor network traffic
+3. Track message exchanges
+4. Record error states
+
+## Debugging workflow
+
+### Development cycle
+
+1. Initial Development
+   - Use Inspector for basic testing
+   - Implement core functionality
+   - Add logging points
+
+2. Integration Testing
+   - Test in Claude.app
+   - Monitor logs
+   - Check error handling
+
+3. Production Deployment
+   - Verify logging
+   - Monitor performance
+   - Track errors
+
+### Testing changes
+
+To test changes efficiently:
+
+- **Configuration changes**: Restart Claude.app
+- **Server code changes**: Use Command-R to reload
+- **Quick iteration**: Use Inspector during development
+
+## Best practices
+
+### Logging strategy
+
+1. **Structured Logging**
+   - Use consistent formats
+   - Include context
+   - Add timestamps
+   - Track request IDs
+
+2. **Error Handling**
+   - Log stack traces
+   - Include error context
+   - Track error patterns
+   - Monitor recovery
+
+3. **Performance Tracking**
+   - Log operation timing
+   - Monitor resource usage
+   - Track message sizes
+   - Measure latency
+
+### Security considerations
+
+When debugging:
+
+1. **Sensitive Data**
+   - Sanitize logs
+   - Protect credentials
+   - Mask personal information
+
+2. **Access Control**
+   - Verify permissions
+   - Check authentication
+   - Monitor access patterns
+
+## Getting help
+
+When encountering issues:
+
+1. **First Steps**
+   - Check server logs
+   - Test with Inspector
+   - Review configuration
+   - Verify environment
+
+2. **Support Channels**
+   - #mcp-sig channel
+   - GitHub issues
+   - MCP Asana project
+
+3. **Providing Information**
+   - Log excerpts
+   - Configuration files
+   - Steps to reproduce
+   - Environment details
+
+## Next steps
+
+- Learn to use the [MCP Inspector](/docs/tools/inspector)
+- Review [Protocol Overview](/api-reference/protocol-overview)
+- Study [Error Handling](/api-reference/error-handling)
--- a/docs/tools/inspector.mdx
+++ b/docs/tools/inspector.mdx
@ -0,0 +1,232 @@
+---
+title: MCP Inspector
+description: In-depth guide to using the MCP Inspector for testing and debugging Model Context Protocol servers
+---
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive developer tool for testing and debugging MCP servers. While the [Debugging Guide](docs/tools/debugging) covers the Inspector as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector's features and capabilities.
+
+## Getting started
+
+### Installation and basic usage
+
+The Inspector runs directly through `npx` without requiring installation:
+
+```bash
+npx @modelcontextprotocol/inspector path/to/server.js
+```
+
+Pass arguments to your server after the path:
+```bash
+npx @modelcontextprotocol/inspector path/to/server.js arg1 arg2
+```
+
+## Interface overview
+
+The Inspector provides several key panels for interacting with your MCP server:
+
+### Server info panel
+- Displays server name and version
+- Shows negotiated protocol version
+- Lists supported capabilities
+- Indicates connection status
+
+### Resources browser
+- Lists all available resources
+- Shows resource metadata (MIME types, descriptions)
+- Allows resource content inspection
+- Supports subscription testing
+
+### Prompts panel
+- Displays available prompt templates
+- Shows prompt arguments and descriptions
+- Enables prompt testing with custom arguments
+- Previews generated messages
+
+### Tools panel
+- Lists available tools
+- Shows tool schemas and descriptions
+- Provides input validation
+- Displays tool execution results
+
+## Testing features
+
+### Resource testing
+```typescript
+// Example resource URI to test
+resource://myapp/data/123
+```
+
+1. View resource metadata
+2. Inspect content representations
+3. Test subscription updates
+4. Monitor resource changes
+
+### Prompt testing
+
+Test prompts with different arguments:
+```json
+{
+  "temperature": 0.7,
+  "style": "concise"
+}
+```
+
+1. Validate argument constraints
+2. Preview generated messages
+3. Test error conditions
+4. Check template rendering
+
+### Tool testing
+
+Test tool execution with various inputs:
+```json
+{
+  "query": "SELECT * FROM users",
+  "limit": 10
+}
+```
+
+1. Validate input schemas
+2. Test error handling
+3. Monitor execution progress
+4. Inspect tool results
+
+## Advanced usage
+
+### Message inspector
+
+The Message inspector panel shows all communication between the client and server:
+
+1. Request/response pairs
+2. Notifications
+3. Progress updates
+4. Error messages
+
+This helps debug:
+- Protocol conformance
+- Message formatting
+- Error conditions
+- State transitions
+
+### Subscription testing
+
+Test resource subscriptions:
+
+1. Subscribe to resources
+2. Monitor update notifications
+3. Test unsubscribe behavior
+4. Verify update patterns
+
+### Capability testing
+
+Verify server capabilities:
+
+1. Check supported features
+2. Test capability negotiation
+3. Verify feature availability
+4. Monitor initialization flow
+
+## Best practices
+
+### Development workflow
+
+1. Start Development
+   - Launch Inspector with your server
+   - Verify basic connectivity
+   - Check capability negotiation
+
+2. Iterative testing
+   - Make server changes
+   - Restart Inspector
+   - Test affected features
+   - Monitor messages
+
+3. Error testing
+   - Test invalid inputs
+   - Check error responses
+   - Verify error handling
+   - Test recovery flows
+
+### Tips and tricks
+
+1. Keep Inspector Running
+   - Monitor changes in real-time
+   - Quick iteration cycle
+   - Immediate feedback
+
+2. Use Message Filtering
+   - Filter by message type
+   - Focus on specific features
+   - Debug targeted behaviors
+
+3. Test Edge Cases
+   - Invalid resource URIs
+   - Malformed tool inputs
+   - Missing prompt arguments
+   - Concurrent operations
+
+## Keyboard shortcuts
+
+The Inspector supports several keyboard shortcuts for efficient testing:
+
+| Shortcut | Action |
+|----------|---------|
+| `Cmd/Ctrl + R` | Reload connection |
+| `Cmd/Ctrl + K` | Clear message log |
+| `Cmd/Ctrl + F` | Filter messages |
+| `Cmd/Ctrl + S` | Save message log |
+
+## Common patterns
+
+### Development loop
+
+1. Start server development
+2. Launch Inspector
+3. Implement feature
+4. Test in Inspector
+5. Refine implementation
+6. Repeat
+
+### Integration testing
+
+1. Test basic functionality
+2. Verify error handling
+3. Check performance
+4. Validate protocols
+5. Test user flows
+
+## Next steps
+
+<CardGroup cols={2}>
+    <Card
+        title="MCP Inspector"
+        icon="github"
+        href="https://github.com/modelcontextprotocol/inspector"
+    >
+        Check out the MCP Inspector source code
+    </Card>
+
+    <Card
+        title="Debugging Guide"
+        icon="bug"
+        href="/docs/tools/debugging"
+    >
+        Learn about broader debugging strategies
+    </Card>
+
+    <Card
+        title="Server APIs"
+        icon="server"
+        href="/api-reference/server-api/resource-management"
+    >
+        Explore implementation details
+    </Card>
+
+    <Card
+        title="Protocol Overview"
+        icon="book"
+        href="/api-reference/protocol-overview"
+    >
+        Review message specifications
+    </Card>
+</CardGroup>