Custom MCP Server 🤖

A Model Context Protocol (MCP) server built with Next.js, providing useful tools and utilities through both HTTP and Server-Sent Events (SSE) transports.

🚀 Features

🔧 Available Tools

• echo - Echo any message back (perfect for testing)
• get-current-time - Get the current timestamp and ISO date
• calculate - Perform basic mathematical calculations safely

🌐 Transport Methods

• HTTP Transport (/mcp) - Stateless HTTP requests (works without Redis)
• SSE Transport (/sse) - Server-Sent Events with Redis for state management

🔒 Security Features

• Rate limiting (100 requests per minute)
• Safe mathematical expression evaluation
• Input sanitization and validation

🏃‍♂️ Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• Docker (optional, for local Redis)

Setup

1. Clone and install dependencies:

   npm install
   

2. Run the automated setup:

   npm run setup
   

   This will:

   • Create environment configuration
   • Set up Redis (Docker) if available
   • Start the development server automatically

3. Manual start (alternative):

   npm run dev
   

The server will be available at http://localhost:3000

🧪 Testing

Quick Tests

# Test HTTP transport
npm run test:http

# Test SSE transport (requires Redis)
npm run test:sse

# Test with Claude Desktop protocol
npm run test:stdio

# Comprehensive tool testing
npm run test:tools

Manual Testing

You can test the MCP server manually using curl:

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Call the echo tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "echo",
      "arguments": {
        "message": "Hello World!"
      }
    }
  }'

# Calculate an expression
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "calculate",
      "arguments": {
        "expression": "15 * 4 + 10"
      }
    }
  }'

🔧 Configuration

Environment Variables

Create a .env.local file:

# Local Redis (Docker)
REDIS_URL=redis://localhost:6379

# Upstash Redis (Production)
UPSTASH_REDIS_REST_URL=your-upstash-url
UPSTASH_REDIS_REST_TOKEN=your-upstash-token

Redis Setup

The server automatically detects and uses Redis in this priority order:

1. Upstash Redis (if UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are set)
2. Local Redis (if REDIS_URL is set)
3. No Redis (HTTP transport only)

Local Redis with Docker

# The setup script handles this automatically, but you can also run manually:
docker run -d --name redis-mcp -p 6379:6379 redis:alpine

Upstash Redis (Recommended for Production)

1. Create an Upstash Redis database at upstash.com
2. Add the connection details to your .env.local
3. The server will automatically detect and use it

🖥️ Integration with AI Tools

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "custom-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/mcp"
      ]
    }
  }
}

Configuration file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor IDE

For Cursor 0.48.0 or later (direct SSE support):

{
  "mcpServers": {
    "custom-mcp": {
      "url": "http://localhost:3000/sse"
    }
  }
}

For older Cursor versions:

{
  "mcpServers": {
    "custom-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/mcp"
      ]
    }
  }
}

🛠️ Development

Project Structure

custom-mcp-server/
├── app/
│   ├── [transport]/
│   │   └── route.ts          # Main MCP server logic
│   ├── layout.tsx            # Root layout
│   └── page.tsx              # Home page
├── lib/
│   └── redis.ts              # Redis utilities
├── scripts/
│   ├── setup.mjs             # Automated setup
│   ├── test-http-client.mjs  # HTTP transport tests
│   ├── test-sse-client.mjs   # SSE transport tests
│   └── test-tools.mjs        # Comprehensive tool tests
├── package.json
├── next.config.ts
└── README.md

Adding New Tools

1. Define the tool in app/[transport]/route.ts:

const tools = {
  // ... existing tools
  myNewTool: {
    name: "my-new-tool",
    description: "Description of what your tool does",
    inputSchema: {
      type: "object",
      properties: {
        param1: {
          type: "string",
          description: "Description of parameter"
        }
      },
      required: ["param1"]
    }
  }
};

2. Add the handler:

const toolHandlers = {
  // ... existing handlers
  "my-new-tool": async ({ param1 }: { param1: string }) => {
    // Your tool logic here
    return {
      content: [
        {
          type: "text",
          text: `Result: ${param1}`
        }
      ]
    };
  }
};

Testing Your Changes

# Run all tests
npm run test:tools

# Test specific functionality
npm run test:http
npm run test:sse

📝 API Reference

Tools/List

Get all available tools:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Tools/Call

Call a specific tool:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "tool-name",
    "arguments": {
      "param": "value"
    }
  }
}

🚀 Deployment

Vercel (Recommended)

1. Deploy to Vercel:

   vercel
   

2. Add environment variables in Vercel dashboard:

   • UPSTASH_REDIS_REST_URL
   • UPSTASH_REDIS_REST_TOKEN

3. Update your AI tool configurations to use the deployed URL:

   https://your-app.vercel.app/mcp
   https://your-app.vercel.app/sse
   

Other Platforms

The server is a standard Next.js application and can be deployed to any platform that supports Node.js:

• Netlify
• Railway
• Render
• DigitalOcean App Platform

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-new-feature
3. Make your changes and add tests
4. Run the test suite: npm run test:tools
5. Commit your changes: git commit -am 'Add some feature'
6. Push to the branch: git push origin feature/my-new-feature
7. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Troubleshooting

Common Issues

Server not starting:

• Check if port 3000 is available
• Ensure all dependencies are installed: npm install

Redis connection issues:

• Verify Docker is running: docker ps
• Check Redis container status: docker ps -a | grep redis-mcp
• Restart Redis: docker restart redis-mcp

AI tool not detecting server:

• Ensure the server is running and accessible
• Check the configuration file syntax (valid JSON)
• Restart your AI tool after configuration changes
• Verify the server URL is correct

Tool calls failing:

• Check server logs for error messages
• Test tools manually with npm run test:tools
• Verify the tool parameters match the expected schema

Debug Mode

Enable debug logging by setting the environment variable:

DEBUG=1 npm run dev

📞 Support

• Create an issue on GitHub for bug reports
• Check existing issues for common problems
• Review the test scripts for usage examples