arcade-mcp/libs/arcade-mcp-server/docs/clients/cursor.md

# Cursor IDE

Cursor is an AI-powered IDE that supports MCP servers. This guide will help you integrate your Arcade MCP server with Cursor for enhanced development capabilities.

## Prerequisites

- Cursor IDE installed
- Python 3.10+ installed
- `arcade-mcp` package installed (`pip install arcade-mcp`)

## Configuration

Cursor reads MCP server configurations from its settings. You can configure MCP servers through:

1. Cursor Settings UI
2. Configuration file
3. Workspace settings

## Basic Setup

### Method 1: Settings UI

1. Open Cursor Settings (`Cmd/Ctrl + Shift + J`)
2. Search for "MCP" or "Model Context Protocol"
3. Add a new server configuration:
   - **Name**: `arcade-tools`
   - **Command**: `python -m arcade_mcp stdio`
   - **Working Directory**: `/path/to/your/project`

### Method 2: Configuration File

Add to your Cursor configuration:

```json
{
  "mcp.servers": {
    "arcade-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  }
}
```

### Method 3: Workspace Settings

Create `.cursor/settings.json` in your workspace:

```json
{
  "mcp.servers": {
    "project-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio", "--debug"],
      "cwd": "${workspaceFolder}",
      "env": {
        "ARCADE_API_KEY": "${env:ARCADE_API_KEY}"
      }
    }
  }
}
```

## Development Workflow

### Hot Reload Setup

For active development with automatic reload:

```json
{
  "mcp.servers": {
    "dev-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "--reload", "--debug"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  }
}
```

### Virtual Environment

Use a project-specific virtual environment:

```json
{
  "mcp.servers": {
    "project-tools": {
      "command": "${workspaceFolder}/venv/bin/python",
      "args": ["-m", "arcade_mcp", "stdio"],
      "cwd": "${workspaceFolder}"
    }
  }
}
```

### Multiple Tool Sets

Configure different tool sets for different purposes:

```json
{
  "mcp.servers": {
    "github-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio", "--tool-package", "github"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    },
    "database-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio"],
      "cwd": "${workspaceFolder}/db_tools",
      "env": {
        "DATABASE_URL": "${env:DATABASE_URL}"
      }
    },
    "api-tools": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio"],
      "cwd": "${workspaceFolder}/api_tools"
    }
  }
}
```

## Integration Features

### Inline Tool Usage

Use tools directly in your code comments:

```python
# @mcp use arcade-tools.greet name="World"
# Result will appear here

def process_data(data):
    # @mcp use database-tools.query sql="SELECT * FROM users"
    pass
```

### Tool Discovery

View available tools in Cursor:

1. Open Command Palette (`Cmd/Ctrl + Shift + P`)
2. Type "MCP: List Tools"
3. Select your server to see available tools

### Tool Documentation

Access tool documentation:

1. Hover over tool usage in code
2. Use `Cmd/Ctrl + Click` on tool names
3. View in the MCP panel

## Advanced Configuration

### Environment-Specific Settings

Use different configurations per environment:

```json
{
  "mcp.servers": {
    "tools-dev": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio", "--env-file", ".env.dev"],
      "cwd": "${workspaceFolder}",
      "when": "${config:environment} == 'development'"
    },
    "tools-prod": {
      "command": "python",
      "args": ["-m", "arcade_mcp", "stdio", "--env-file", ".env.prod"],
      "cwd": "${workspaceFolder}",
      "when": "${config:environment} == 'production'"
    }
  }
}
```

### Task Integration

Create tasks for MCP server management:

```json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start MCP Server",
      "type": "shell",
      "command": "python -m arcade_mcp --reload --debug",
      "problemMatcher": [],
      "isBackground": true
    },
    {
      "label": "Test Tools",
      "type": "shell",
      "command": "python -m arcade_mcp --tool-package ${input:package} --debug",
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "package",
      "type": "promptString",
      "description": "Tool package name"
    }
  ]
}
```

### Debugging Tools

Debug your tools with Cursor's debugger:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug MCP Tools",
      "type": "python",
      "request": "launch",
      "module": "arcade_mcp",
      "args": ["--debug", "--reload"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  ]
}
```

## Best Practices

### Project Structure

Organize your MCP tools effectively:

```
my-project/
 .cursor/
    settings.json    # Cursor-specific settings
 .env                 # Environment variables
 .env.example         # Example environment file
 tools/
    __init__.py
    data_tools.py    # Data processing tools
    api_tools.py     # API interaction tools
    utils.py         # Utility tools
 requirements.txt
 README.md
```

### Tool Development Tips

1. **Use Type Hints**: Enable better IDE support
   ```python
   from typing import Annotated

   @tool
   def process(
       data: Annotated[str, "Input data to process"],
       format: Annotated[str, "Output format"] = "json"
   ) -> Annotated[dict, "Processed data"]:
       """Process data in the specified format."""
       pass
   ```

2. **Provide Clear Descriptions**: Help Cursor understand tool usage
3. **Handle Errors Gracefully**: Return helpful error messages
4. **Use Logging**: Enable debug mode for troubleshooting
5. **Test Incrementally**: Use Cursor's integrated terminal

### Performance Optimization

1. **Lazy Loading**: Import heavy dependencies inside tools
2. **Cache Results**: Use caching for expensive operations
3. **Async Support**: Use async tools for I/O operations
4. **Resource Management**: Clean up resources properly

## Troubleshooting

### Common Issues

#### Tools Not Loading

1. Check Python path and virtual environment
2. Verify `arcade-mcp` installation
3. Enable debug logging to see errors
4. Check for import errors in tool files

#### Permission Errors

1. Ensure proper file permissions
2. Check working directory access
3. Verify environment variable access

#### Connection Issues

1. Restart Cursor after configuration changes
2. Check for conflicting MCP servers
3. Verify stdio transport is working

### Debugging Steps

1. Enable debug mode in your configuration
2. Check Cursor's output panel for MCP logs
3. Test tools using the command line first
4. Use Cursor's Developer Tools for detailed logs

## Example: Complete Setup

Here's a full example of setting up a Cursor workspace with MCP:

1. **Create workspace structure**:
   ```
   my-workspace/
    .cursor/
       settings.json
    .vscode/
       tasks.json
    tools/
       my_tools.py
    pyproject.toml
   ```

2. **Configure `.cursor/settings.json`**:
   ```json
   {
     "mcp.servers": {
       "workspace-tools": {
         "command": "python",
         "args": ["-m", "arcade_mcp", "stdio", "--debug"],
         "cwd": "${workspaceFolder}",
         "env": {
           "PYTHONPATH": "${workspaceFolder}"
         }
       }
     }
   }
   ```

3. **Create `tools/my_tools.py`**:
   ```python
   from arcade_tdk import tool
   from typing import Annotated
   import json

   @tool
   async def format_json(
       data: Annotated[str, "JSON string to format"]
   ) -> Annotated[str, "Formatted JSON"]:
       """Format JSON data with proper indentation."""
       parsed = json.loads(data)
       return json.dumps(parsed, indent=2)

   @tool
   def analyze_code(
       file_path: Annotated[str, "Path to analyze"]
   ) -> Annotated[dict, "Analysis results"]:
       """Analyze Python code quality."""
       # Implementation here
       pass
   ```

4. **Restart Cursor and start using your tools!**