# 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:**
```bash
npm install
```
2. **Run the automated setup:**
```bash
npm run setup
```
This will:
- Create environment configuration
- Set up Redis (Docker) if available
- Start the development server automatically
3. **Manual start (alternative):**
```bash
npm run dev
```
The server will be available at `http://localhost:3000`
## 🧪 Testing
### Quick Tests
```bash
# 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:
```bash
# 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:
```env
# 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
```bash
# 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](https://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`):
```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):
```json
{
"mcpServers": {
"custom-mcp": {
"url": "http://localhost:3000/sse"
}
}
}
```
For older Cursor versions:
```json
{
"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`:
```typescript
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**:
```typescript
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
```bash
# 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:
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
```
### Tools/Call
Call a specific tool:
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "tool-name",
"arguments": {
"param": "value"
}
}
}
```
## 🚀 Deployment
### Vercel (Recommended)
1. **Deploy to Vercel:**
```bash
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:
```bash
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
