# MCP Simple Server

A simple Model Context Protocol (MCP) server with three basic tools: echo, add numbers, and get timestamp.

Supports both **stdio** and **HTTP/WebSocket** transport modes for flexible deployment options.

## Features

- **echo**: Echoes back any message you provide
- **add**: Adds two numbers together
- **get_timestamp**: Returns the current timestamp in ISO 8601 format
- **Dual Mode Support**: Run in stdio mode (local) or HTTP/WebSocket mode (remote)
- **HTTP REST API**: Health checks and server info endpoints
- **WebSocket Support**: Real-time MCP protocol communication

## Installation

```bash
npm install
```

## Building

```bash
npm run build
```

## Running the Server

### stdio Mode (Default - Local Development)

```bash
npm start
# or
MCP_MODE=stdio node dist/index.js
```

### HTTP/WebSocket Mode (Remote Access)

```bash
MCP_MODE=http PORT=3000 node dist/index.js
```

Once running in HTTP mode, access:
- Health check: `http://localhost:3000/health`
- Server info: `http://localhost:3000/`
- WebSocket: `ws://localhost:3000/`

## Tools

### echo
Echoes back the provided message.

**Arguments:**
- `message` (string, required): The message to echo back

**Example:**
```json
{
  "message": "Hello, World!"
}
```

### add
Adds two numbers together.

**Arguments:**
- `a` (number, required): The first number
- `b` (number, required): The second number

**Example:**
```json
{
  "a": 5,
  "b": 3
}
```

### get_timestamp
Returns the current timestamp in ISO 8601 format.

**Arguments:** None

## Deployment

### AWS EC2 Deployment

Deploy to AWS EC2 with automated setup using AWS CloudShell. See [AWS_DEPLOYMENT.md](AWS_DEPLOYMENT.md) for detailed instructions.

**Quick Start:**
```bash
# From AWS CloudShell
curl -O https://raw.githubusercontent.com/joeleesuh/mcp-simple-server/main/scripts/deploy-to-ec2.sh
chmod +x deploy-to-ec2.sh
./deploy-to-ec2.sh
```

Includes:
- Automated EC2 instance provisioning (t3.micro - Free Tier eligible)
- Auto-install Node.js and dependencies
- **Runs in HTTP mode** on port 3000 with WebSocket support
- Security group configured for port 3000 access
- Systemd service setup with environment variables
- AWS Session Manager access (no SSH keys required)

After deployment, access the server at:
- `http://<PUBLIC_IP>:3000/health` - Health check
- `http://<PUBLIC_IP>:3000/` - Server info
- `ws://<PUBLIC_IP>:3000/` - WebSocket endpoint

### Deployment to smithery.ai

This project is configured for deployment on Smithery.ai with:
- `Dockerfile` - Multi-stage Docker build for optimized container image
- `smithery.yaml` - Smithery configuration for stdio-based MCP server
- `.dockerignore` - Excludes unnecessary files from Docker build

### Prerequisites

1. Create a GitHub repository for this project
2. Push your code to GitHub (including Dockerfile and smithery.yaml)
3. Create an account on [smithery.ai](https://smithery.ai)
4. (Optional) Test Docker build locally: `docker build -t mcp-simple-server .`

### Steps to Deploy

1. **Push to GitHub** (if not already done):
   ```bash
   git add .
   git commit -m "Add Smithery deployment configuration"
   git push
   ```

2. **Deploy on smithery.ai**:
   - Go to [smithery.ai](https://smithery.ai)
   - Sign in with your GitHub account
   - Click "New Server" or "Deploy Server"
   - Connect your GitHub repository
   - Select the `mcp-simple-server` repository
   - Smithery will automatically detect `Dockerfile` and `smithery.yaml`
   - Click "Deploy"

3. **Use Your Server**:
   - Once deployed, Smithery will provide installation instructions
   - You can install it with: `npx @smithery/cli install <your-server-name>`
   - Or use it directly in Claude Desktop or other MCP clients

### Example Claude Desktop Configuration

After deployment, add this to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "simple-server": {
      "command": "npx",
      "args": ["-y", "@smithery/mcp-simple-server"]
    }
  }
}
```

Or if testing locally:

```json
{
  "mcpServers": {
    "simple-server": {
      "command": "node",
      "args": ["C:/Users/User/mcp-simple-server/dist/index.js"]
    }
  }
}
```

## Development

### Project Structure

```
mcp-simple-server/
├── src/
│   └── index.ts              # Main server implementation
├── scripts/
│   ├── deploy-to-ec2.sh      # AWS CloudShell deployment script
│   └── user-data.sh          # EC2 instance initialization script
├── dist/                     # Compiled JavaScript (generated)
├── Dockerfile                # Docker container configuration
├── smithery.yaml             # Smithery deployment configuration
├── .dockerignore             # Docker build exclusions
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── README.md                # This file
└── AWS_DEPLOYMENT.md        # AWS EC2 deployment guide
```

### Adding New Tools

To add new tools, modify `src/index.ts`:

1. Add the tool definition to the `TOOLS` array
2. Add a new case in the `CallToolRequestSchema` handler switch statement
3. Rebuild the project: `npm run build`

## License

MIT