CURSOR_SETUP.md

Setting Up MCP Server with Cursor Editor

This guide shows you how to integrate your custom MCP server with Cursor editor for enhanced AI assistance.

🚀 Quick Setup

1. Build the MCP Server

npm run build

2. Test the Server

# Test with the example Cursor-optimized server
node dist/cli.js start --config examples/cursor-config.json

3. Configure Cursor

Option A: Using the Built Example Server

Add this to your Cursor MCP configuration file:

{
  "mcpServers": {
    "cursor-dev-server": {
      "command": "node",
      "args": [
        "/absolute/path/to/your/mcp-server/examples/cursor-mcp-server.js"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Option B: Using the CLI

{
  "mcpServers": {
    "cursor-dev-server": {
      "command": "node",
      "args": [
        "/absolute/path/to/your/mcp-server/dist/cli.js",
        "start",
        "--config",
        "/absolute/path/to/your/mcp-server/examples/cursor-config.json"
      ]
    }
  }
}

🛠 Available Tools in Cursor

Once configured, you'll have access to these tools in Cursor:

File Operations

• read_file: Read file contents
• write_file: Write content to files
• list_directory: Browse directory contents

Development Tools

• run_command: Execute shell commands
• search_files: Search text within files
• git_status: Check git repository status

Example Usage in Cursor

You: "Read the package.json file"
AI: Uses read_file tool to show package.json contents

You: "List all TypeScript files in the src directory"
AI: Uses list_directory and search_files tools

You: "Run npm test"
AI: Uses run_command tool to execute tests

You: "What's the git status?"
AI: Uses git_status tool to show repository state

📁 Configuration File Locations

Windows

%APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp_servers.json

macOS

~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp_servers.json

Linux

~/.config/Cursor/User/globalStorage/cursor.mcp/mcp_servers.json

🔧 Custom Configuration

Creating Your Own Tools

1. Extend the example server:

import { MCPServer, ToolDefinition } from 'mcp-server-dev';

const myCustomTool: ToolDefinition = {
  name: 'my_tool',
  description: 'My custom tool for Cursor',
  inputSchema: {
    type: 'object',
    properties: {
      input: { type: 'string' }
    },
    required: ['input']
  },
  handler: async (args) => {
    // Your tool logic here
    return {
      content: [{
        type: 'text',
        text: `Processed: ${args.input}`
      }]
    };
  }
};

server.getToolRegistry().registerTool(myCustomTool);

2. Add project-specific resources:

server.getResourceManager().registerResource({
  uri: 'project://config',
  name: 'Project Configuration',
  description: 'Current project settings',
  provider: async () => {
    // Return project-specific data
  }
});

🐛 Troubleshooting

Server Not Starting

1. Check the absolute paths in your configuration
2. Ensure the server builds successfully: npm run build
3. Test manually: node dist/cli.js start --config examples/cursor-config.json

Tools Not Available in Cursor

1. Restart Cursor after configuration changes
2. Check Cursor's MCP logs for connection errors
3. Verify the configuration file syntax

Permission Issues

1. Ensure the MCP server has necessary file system permissions
2. For shell commands, verify the user has appropriate access

📊 Monitoring and Debugging

Enable Debug Logging

{
  "mcpServers": {
    "cursor-dev-server": {
      "command": "node",
      "args": [
        "/path/to/dist/cli.js",
        "start",
        "--debug",
        "--config",
        "/path/to/cursor-config.json"
      ]
    }
  }
}

Check Server Status

# Test connection manually
node dist/cli.js test-connection --config examples/cursor-config.json

🌟 Advanced Features

HTTP Mode for Web Integration

If you want to use HTTP mode (not typical for Cursor):

{
  "mcpServers": {
    "cursor-http-server": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "x-api-key": "your-api-key"
      }
    }
  }
}

Custom Prompts

The server includes code review prompts that Cursor can use:

You: "Review this file for security issues"
AI: Uses the code_review prompt with security focus

🎯 Best Practices

1. Keep tools focused: Each tool should do one thing well
2. Validate inputs: Always validate tool parameters
3. Handle errors gracefully: Return meaningful error messages
4. Use appropriate timeouts: Prevent long-running operations from hanging
5. Log appropriately: Use structured logging for debugging

📚 Next Steps

1. Customize the example server for your specific needs
2. Add project-specific tools and resources
3. Create custom prompts for your workflow
4. Share your configuration with your team

For more advanced usage, see the main README.md and API documentation.