modelcontextprotocol/docs
Watch
1
0
Fork
You've already forked docs
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #16 from modelcontextprotocol/justin/fixes-2

Browse source 
Update "Development Tools"
This commit is contained in:
Justin Spahr-Summers 2024-11-21 14:48:20 +00:00 • committed by GitHub
commit 0854b8e900
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 79 additions and 176 deletions
Download patch file Download diff file Expand all files Collapse all files

99
docs/tools/debugging.mdx
View file

@ -1,10 +1,14 @@
--- ---
title: Debugging MCP servers title: Debugging
description: A comprehensive guide to debugging Model Context Protocol (MCP) servers and integrations description: A comprehensive guide to debugging Model Context Protocol (MCP) 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. 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.
<Info>
This guide is for macOS. Guides for other platforms are coming soon.
</Info>
## Debugging tools overview ## Debugging tools overview
MCP provides several tools for debugging at different levels: MCP provides several tools for debugging at different levels:
@ -12,9 +16,9 @@ MCP provides several tools for debugging at different levels:
1. **MCP Inspector** 1. **MCP Inspector**
- Interactive debugging interface - Interactive debugging interface
- Direct server testing - Direct server testing
- See the [Inspector Guide](docs/tools/inspector) for details - See the [Inspector guide](/docs/tools/inspector) for details
2. **Claude.app Developer Tools** 2. **Claude Desktop Developer Tools**
- Integration testing - Integration testing
- Log collection - Log collection
- Chrome DevTools integration - Chrome DevTools integration
@ -24,7 +28,7 @@ MCP provides several tools for debugging at different levels:
- Error tracking - Error tracking
- Performance monitoring - Performance monitoring
## Debugging in Claude.app ## Debugging in Claude Desktop
### Checking server status ### Checking server status
@ -32,20 +36,18 @@ The Claude.app interface provides basic server status information:
1. Click the 🔌 icon to view: 1. Click the 🔌 icon to view:
- Connected servers - Connected servers
- Available prompts - Available prompts and resources
- Accessible resources
- Supported tools
### Enabling logging 2. Click the 🔨 icon to view:
- Tools made available to the model
Get detailed logs from Claude.app: ### Viewing logs
Review detailed MCP logs from Claude Desktop:
```bash ```bash
# Launch with logging enabled
open /Applications/Claude.app --stdout ~/Claude.log --stderr ~/Claude.log
# Follow logs in real-time # Follow logs in real-time
tail -n 100 -f ~/Claude.log tail -n 20 -f ~/Logs/Claude/mcp*.log
``` ```
The logs capture: The logs capture:
@ -56,7 +58,7 @@ The logs capture:
### Using Chrome DevTools ### Using Chrome DevTools
Access Chrome's developer tools for deeper inspection: Access Chrome's developer tools inside Claude Desktop to investigate client-side errors:
1. Enable DevTools: 1. Enable DevTools:
```bash ```bash
@ -70,9 +72,9 @@ Note: You'll see two DevTools windows:
- Main content window - Main content window
- App title bar window - App title bar window
Use the Console panel to inspect client-side errors.
Use the Network panel to inspect: Use the Network panel to inspect:
- WebSocket connections
- Server-sent events
- Message payloads - Message payloads
- Connection timing - Connection timing
@ -80,15 +82,16 @@ Use the Network panel to inspect:
### Environment variables ### Environment variables
MCP servers don't inherit environment variables automatically. Configure them in `claude_desktop_config.json`: MCP servers inherit only a subset of environment variables automatically, like `USER`, `HOME`, and `PATH`.
To override the default variables or provide your own, you can specify an `env` key in `claude_desktop_config.json`:
```json ```json
{ {
"myserver": { "myserver": {
"command": "mcp-server-myapp", "command": "mcp-server-myapp",
"env": { "env": {
"HOME": "/Users/username", "MYAPP_API_KEY": "some_key",
"PATH": "/usr/local/bin:/usr/bin:/bin"
} }
} }
} }
@ -117,23 +120,41 @@ Common initialization problems:
When servers fail to connect: When servers fail to connect:
1. Check Claude.app logs 1. Check Claude Desktop logs
2. Verify server process is running 2. Verify server process is running
3. Test standalone with Inspector 3. Test standalone with [Inspector](/docs/tools/inspector)
4. Check network connectivity 4. Verify protocol compatibility
5. Verify protocol compatibility
## Implementing logging ## Implementing logging
### Server-side logging ### Server-side logging
Implement custom logging in your server: When building a server that uses the local stdio [transport](/docs/concepts/transports), all messages logged to stderr (standard error) will be captured by the client (e.g., Claude Desktop) automatically.
```typescript <Warning>
server.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => { Local MCP servers should not log messages to stdout (standard out), as this will interfere with protocol operation.
console.log(`[${notification.params.level}] ${notification.params.data}`); </Warning>
});
``` For all [transports](/docs/concepts/transports), you can also provide logging to the client by sending a log message notification:
<Tabs>
<Tab title="Python">
```python
server.request_context.session.send_log_message(
level="info",
data="Server started successfully",
)
```
</Tab>
<Tab title="TypeScript">
```typescript
server.sendLoggingMessage({
level: "info",
data: "Server started successfully",
});
```
</Tab>
</Tabs>
Important events to log: Important events to log:
- Initialization steps - Initialization steps
@ -156,27 +177,22 @@ In client applications:
### Development cycle ### Development cycle
1. Initial Development 1. Initial Development
- Use Inspector for basic testing - Use [Inspector](/docs/tools/inspector) for basic testing
- Implement core functionality - Implement core functionality
- Add logging points - Add logging points
2. Integration Testing 2. Integration Testing
- Test in Claude.app - Test in Claude Desktop
- Monitor logs - Monitor logs
- Check error handling - Check error handling
3. Production Deployment
- Verify logging
- Monitor performance
- Track errors
### Testing changes ### Testing changes
To test changes efficiently: To test changes efficiently:
- **Configuration changes**: Restart Claude.app - **Configuration changes**: Restart Claude Desktop
- **Server code changes**: Use Command-R to reload - **Server code changes**: Use Command-R to reload
- **Quick iteration**: Use Inspector during development - **Quick iteration**: Use [Inspector](/docs/tools/inspector) during development
## Best practices ## Best practices
@ -220,14 +236,13 @@ When encountering issues:
1. **First Steps** 1. **First Steps**
- Check server logs - Check server logs
- Test with Inspector - Test with [Inspector](/docs/tools/inspector)
- Review configuration - Review configuration
- Verify environment - Verify environment
2. **Support Channels** 2. **Support Channels**
- #mcp-sig channel
- GitHub issues - GitHub issues
- MCP Asana project - GitHub discussions
3. **Providing Information** 3. **Providing Information**
- Log excerpts - Log excerpts

150
docs/tools/inspector.mdx
View file

@ -1,9 +1,9 @@
--- ---
title: MCP Inspector title: Inspector
description: In-depth guide to using the MCP Inspector for testing and debugging Model Context Protocol servers 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. 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 ## Getting started
@ -20,111 +20,35 @@ Pass arguments to your server after the path:
npx @modelcontextprotocol/inspector path/to/server.js arg1 arg2 npx @modelcontextprotocol/inspector path/to/server.js arg1 arg2
``` ```
## Interface overview ## Feature overview
The Inspector provides several key panels for interacting with your MCP server: The Inspector provides several features for interacting with your MCP server:
### Server info panel ### Server connection pane
- Displays server name and version - Allows selecting the [transport](/docs/concepts/transports) for connecting to the server
- Shows negotiated protocol version - For local servers, supports customizing the command-line arguments and environment
- Lists supported capabilities
- Indicates connection status
### Resources browser ### Resources tab
- Lists all available resources - Lists all available resources
- Shows resource metadata (MIME types, descriptions) - Shows resource metadata (MIME types, descriptions)
- Allows resource content inspection - Allows resource content inspection
- Supports subscription testing - Supports subscription testing
### Prompts panel ### Prompts tab
- Displays available prompt templates - Displays available prompt templates
- Shows prompt arguments and descriptions - Shows prompt arguments and descriptions
- Enables prompt testing with custom arguments - Enables prompt testing with custom arguments
- Previews generated messages - Previews generated messages
### Tools panel ### Tools tab
- Lists available tools - Lists available tools
- Shows tool schemas and descriptions - Shows tool schemas and descriptions
- Provides input validation - Enables tool testing with custom inputs
- Displays tool execution results - Displays tool execution results
## Testing features ### Notifications pane
- Presents all logs recorded from the server
### Resource testing - Shows notifications received from the server
```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 ## Best practices
@ -137,52 +61,16 @@ Verify server capabilities:
2. Iterative testing 2. Iterative testing
- Make server changes - Make server changes
- Restart Inspector - Rebuild the server
- Reconnect the Inspector
- Test affected features - Test affected features
- Monitor messages - Monitor messages
3. Error testing 3. Test edge cases
- Test invalid inputs - 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 - Missing prompt arguments
- Concurrent operations - Concurrent operations
- Verify error handling and error responses
## 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 ## Next steps