---
description:
globs:
alwaysApply: true
---
## MCP Best Practices
1. **Standardized Tool Naming**
- Use descriptive, lowercase names with underscores
- Follow the pattern: `[service]_[action]_[object]`
- Example: `github_create_repository`, `todoist_update_task`
2. **Parameter Validation**
- Always validate input parameters before processing
- Return clear error messages for invalid inputs
- Include parameter type specifications in tool definitions
3. **Error Handling**
- Implement proper try/catch blocks for all API calls
- Return structured error objects with code and description
- Log errors for debugging but sanitize sensitive information
4. **Authentication Management**
- Use environment variables for API keys and tokens
- Never hardcode credentials in server code
- Implement token refresh mechanisms where applicable
5. **Performance Optimization**
- Cache repetitive API calls when appropriate
- Implement request throttling to avoid rate limits
- Split complex operations into smaller tools for better reusability
## Smithery-Specific Rules
1. **Configuration Schema**
- Define complete `configSchema` in `smithery.yaml`
- Document all configuration options thoroughly
- Mark required parameters appropriately
2. **Command Generation**
- Use the correct environment variable mapping in `commandFunction`
- Ensure proper escaping of special characters in config strings
- Follow the Smithery startup protocol for proper initialization
3. **Server Structure**
- Implement required MCP protocol methods
- Use the latest `@modelcontextprotocol/sdk` version
- Structure projects with clear separation of concerns
4. **Deployment Best Practices**
- Include proper Dockerfile configuration
- Specify all dependencies in package.json
- Set appropriate NODE_ENV for production deployments
5. **Versioning**
- Use semantic versioning for all MCP servers
- Document breaking changes between versions
- Provide upgrade paths for major version changes
## Cursor IDE Integration
1. **MCP Server Registration**
- Use consistent naming in `mcp.json`
- Follow the standard command structure:
```json
"command": "npx",
"args": [
"-y",
"@smithery/cli@latest",
"run",
"[package-name]",
"--config",
"[escaped-json-config]"
]
```
2. **Tool Discovery**
- Refresh tools after configuration changes
- Verify green dot status for enabled servers
- Check console for connection errors
3. **Configuration Management**
- Escape quotes correctly in config strings (use `\"` for quotes inside config)
- Use environment-specific configurations for different environments
- Document required API keys and tokens
4. **Troubleshooting**
- Check "No resources available" warnings in Cursor IDE
- Verify network connectivity to API endpoints
- Monitor token usage and rate limits
5. **Performance**
- Order servers by frequency of use for faster tool discovery
- Configure timeout settings appropriately
- Use local servers for development when possible
