# Calculator MCP Server

A Model Context Protocol (MCP) server that provides mathematical calculation tools for AI assistants.

## Features

This MCP server provides three core mathematical operations:
- **Add** - Add two numbers together with calculation history tracking
- **Multiply** - Multiply two numbers with optimized performance
- **Divide** - Divide numbers with comprehensive zero-division protection

The server maintains a calculation history and provides robust error handling for all mathematical operations.

## Prerequisites

- Node.js (version 14 or higher)
- npm or yarn package manager

## Installation

1. Clone or download this repository
2. Navigate to the project directory:
   ```bash
   cd my-first-mcp-server
   ```

3. Install dependencies:
   ```bash
   npm install
   ```

4. Build the TypeScript code:
   ```bash
   npm run build
   ```

## Running the Server

### Development Mode
For development and testing:
```bash
npm run dev
```

### Production Mode
For production use:
```bash
npm run start
```

## Testing the Server

You can test if the server is working by sending an MCP request:

```bash
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/server.js
```

This should return a JSON response listing the available tools.

## Integration with AI Clients

### Cursor IDE

1. Create a `.cursor/mcp.json` file in your project root:
   ```json
   {
     "mcpServers": {
       "calculator": {
         "command": "node",
         "args": [
           "/absolute/path/to/my-first-mcp-server/dist/server.js"
         ],
         "env": {}
       }
     }
   }
   ```

2. Replace `/absolute/path/to/my-first-mcp-server/` with the actual path to this directory

3. Restart Cursor IDE

4. The calculator tools will be available to the AI assistant

### Claude Desktop

1. Create or edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
   ```json
   {
     "mcpServers": {
       "calculator": {
         "command": "node",
         "args": ["/absolute/path/to/my-first-mcp-server/dist/server.js"]
       }
     }
   }
   ```

2. Replace the path with your actual directory path

3. Restart Claude Desktop

## Development

To modify or extend the calculator functionality:

1. Edit the source files in the `src/` directory
2. Rebuild the project: `npm run build`
3. Test your changes: `npm run dev`

## Configuration

The server can be configured using environment variables. Copy `.env.example` to `.env` and modify as needed.

Available configuration options:
- `NODE_ENV`: Environment mode (development/production)
- `PORT`: Server port (default: 3000)
- `LOG_LEVEL`: Logging verbosity
- `DB_*`: Database connection settings

## Docker Support

You can run the entire stack using Docker Compose:

```bash
docker-compose up -d
```

This will start:
- Calculator MCP Server
- PostgreSQL database (for calculation history)
- Redis cache
- Database administration interface

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

## License

This project is licensed under the ISC License.

## Available Tools

### add
Adds two numbers together.

**Parameters:**
- `a` (number): First number
- `b` (number): Second number

**Example:** `add(25, 17)` returns `42`

### multiply
Multiplies two numbers.

**Parameters:**
- `a` (number): First number
- `b` (number): Second number

**Example:** `multiply(6, 7)` returns `42`

### divide
Divides the first number by the second number.

**Parameters:**
- `a` (number): Dividend (number to divide)
- `b` (number): Divisor (divide by this)

**Example:** `divide(84, 2)` returns `42`

**Note:** Division by zero will return an error.

## Using in Other Projects

### Option 1: Absolute Path Reference
In any project where you want to use this calculator:

1. Create `.cursor/mcp.json` in that project's root
2. Reference the absolute path to this server's `dist/server.js`
3. Restart your IDE

### Option 2: Copy to Project
```bash
# Copy the entire MCP server to your project
cp -r /path/to/my-first-mcp-server /path/to/your-project/mcp-servers/calculator

# Update .cursor/mcp.json to use relative path:
{
  "mcpServers": {
    "calculator": {
      "command": "node",
      "args": ["./mcp-servers/calculator/dist/server.js"],
      "env": {}
    }
  }
}
```

### Option 3: NPM Package (Advanced)
You can publish this as an npm package for easier distribution:

1. Update `package.json` with your package details
2. Run `npm publish`
3. In other projects: `npm install your-calculator-mcp`
4. Use `npx your-calculator-mcp` in MCP configuration

## Development

### Scripts
- `npm run build` - Compile TypeScript to JavaScript
- `npm run dev` - Run in development mode with tsx
- `npm run start` - Run the compiled server

### File Structure
```
my-first-mcp-server/
├── src/
│   └── server.ts          # Main server implementation
├── dist/
│   └── server.js          # Compiled JavaScript (generated)
├── .cursor/
│   └── mcp.json          # Local MCP configuration
├── package.json          # Node.js dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file
```

## Troubleshooting

### Server Not Connecting
1. Ensure the path in `.cursor/mcp.json` is correct and absolute
2. Verify the server builds successfully: `npm run build`
3. Test the server manually: `echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/server.js`
4. Restart your IDE after configuration changes

### Tools Not Available
1. Check that `.cursor/mcp.json` is in the root of your working project
2. Ensure you're opening the correct project in your IDE
3. Wait a few seconds after opening for MCP to initialize
4. Check IDE developer console for MCP-related errors

### Permission Issues
```bash
# Make sure the server file is executable
chmod +x dist/server.js
```

## Server Details

- **Protocol**: Model Context Protocol (MCP)
- **Transport**: Standard I/O (stdio)
- **Language**: TypeScript/Node.js
- **Framework**: @modelcontextprotocol/sdk

## License

ISC

## Contributing

Feel free to extend this server with additional mathematical operations or features!