# Calculator Investment MCP Server

Servidor MCP (Model Context Protocol) que proporciona herramientas de cálculo matemático y financiero para análisis de inversiones y préstamos.

## 🚀 Características

### Operaciones Matemáticas Básicas
- ✅ Suma, resta, multiplicación y división
- ✅ Potencias y raíces cuadradas
- ✅ Cálculo de porcentajes

### Análisis de Inversiones
- 📈 Cambio porcentual entre valores
- 💰 Cálculo de retorno de inversión (ROI)
- 📊 Coste medio ponderado de acciones
- 💼 Valoración de cartera de inversiones

### Análisis de Préstamos
- 🏦 Cálculo de cuota mensual
- 💳 Coste total del préstamo e intereses
- 🎯 Ahorro por amortización anticipada

## 📦 Instalación
```bash
# Clonar el repositorio
git clone https://github.com/TU-USUARIO/calculator-investment-mcp.git
cd calculator-investment-mcp

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build
```

## ⚙️ Configuración

### Configuración en Claude Desktop

Añade esto a tu archivo de configuración de Claude (`~/Library/Application Support/Claude/claude_desktop_config.json` en macOS):
```json
{
  "mcpServers": {
    "calculator-investment": {
      "command": "node",
      "args": ["/ruta/absoluta/a/calculator-investment/build/index.js"]
    }
  }
}
```

### Configuración en otros clientes MCP

Sigue las instrucciones del cliente MCP que estés utilizando para conectar servidores stdio.

## 📖 Uso

Una vez configurado, el servidor proporciona la herramienta `calculate` con múltiples operaciones.

### Ejemplos de Operaciones Matemáticas
```typescript
// Suma
{ operation: "add", values: [10, 20, 30] }
// Resultado: "60"

// Potencia
{ operation: "power", values: [2, 8] }
// Resultado: "256"

// Porcentaje (15% de 200)
{ operation: "percentage", values: [200, 15] }
// Resultado: "30"
```

### Ejemplos de Análisis de Inversiones
```typescript
// Cambio porcentual
{
  operation: "percentage_change",
  details: {
    initial_value: 1000,
    final_value: 1250
  }
}
// Resultado: "25.00"

// Retorno de inversión
{
  operation: "investment_return",
  details: {
    initial_value: 5000,
    shares: 100,
    price_per_share: 55,
    commission_sell: 10
  }
}
/* Resultado:
{
  "initial_cost": "5000.00",
  "current_value": "5500.00",
  "commission_sell": "10.00",
  "net_value": "5490.00",
  "profit": "490.00",
  "profit_percent": "9.80"
}
*/

// Coste medio de acciones
{
  operation: "average_cost",
  details: {
    holdings: [
      { shares: 100, price: 50 },
      { shares: 50, price: 60 },
      { shares: 75, price: 55 }
    ]
  }
}
/* Resultado:
{
  "total_shares": 225,
  "total_cost": "12125.00",
  "average_cost": "53.89"
}
*/

// Valor de cartera
{
  operation: "portfolio_value",
  details: {
    holdings: [
      { shares: 100, price: 52.50 },
      { shares: 50, price: 61.00 }
    ]
  }
}
/* Resultado:
{
  "total_value": "8300.00",
  "positions": [
    { "shares": 100, "price": 52.5, "value": "5250.00" },
    { "shares": 50, "price": 61, "value": "3050.00" }
  ]
}
*/
```

### Ejemplos de Análisis de Préstamos
```typescript
// Cuota mensual de préstamo
{
  operation: "loan_payment",
  details: {
    principal: 150000,
    annual_rate: 3.5,
    years: 25
  }
}
/* Resultado:
{
  "principal": "150000.00",
  "annual_rate": "3.50",
  "months": 300,
  "monthly_payment": "751.55",
  "total_paid": "225465.00",
  "total_interest": "75465.00"
}
*/

// Ahorro por amortización anticipada
{
  operation: "early_payment_savings",
  details: {
    principal: 150000,
    annual_rate: 3.5,
    years: 25,
    early_payment: 20000,
    early_payment_month: 12
  }
}
/* Resultado:
{
  "original_monthly_payment": "751.55",
  "original_total_interest": "75465.00",
  "early_payment_amount": "20000.00",
  "early_payment_month": 12,
  "new_monthly_payment": "653.35",
  "new_total_interest": "63318.77",
  "interest_savings": "12146.23",
  "percentage_saved": "16.09"
}
*/
```

## 🛠️ API Completa

### Operaciones Disponibles

| Operación | Descripción | Parámetros |
|-----------|-------------|------------|
| `add` | Suma múltiples valores | `values: number[]` |
| `subtract` | Resta valores en orden | `values: number[]` |
| `multiply` | Multiplica múltiples valores | `values: number[]` |
| `divide` | Divide valores en orden | `values: number[]` |
| `power` | Calcula potencia | `values: [base, exponente]` |
| `sqrt` | Raíz cuadrada | `values: [número]` |
| `percentage` | Porcentaje de un valor | `values: [cantidad, porcentaje]` |
| `percentage_change` | Cambio porcentual | `details: {initial_value, final_value}` |
| `investment_return` | Retorno de inversión | `details: {initial_value?, shares, price_per_share, commission_sell?}` |
| `average_cost` | Coste medio de acciones | `details: {holdings: [{shares, price}]}` |
| `portfolio_value` | Valor total de cartera | `details: {holdings: [{shares, price}]}` |
| `loan_payment` | Cuota mensual de préstamo | `details: {principal, annual_rate, years/months}` |
| `loan_total_cost` | Coste total del préstamo | `details: {principal, annual_rate, years/months}` |
| `early_payment_savings` | Ahorro por amortización | `details: {principal, annual_rate, years/months, early_payment, early_payment_month?}` |

### Parámetros de `details`

- **initial_value**: Valor inicial de la inversión
- **final_value**: Valor final para calcular cambio
- **shares**: Número de acciones
- **price_per_share**: Precio por acción
- **commission_buy**: Comisión de compra (cantidad fija)
- **commission_sell**: Comisión de venta (cantidad fija)
- **holdings**: Array de posiciones `{shares: number, price: number}`
- **principal**: Capital del préstamo
- **annual_rate**: Tasa anual de interés (TAE) en porcentaje
- **years**: Plazo del préstamo en años
- **months**: Plazo del préstamo en meses
- **early_payment**: Cantidad de amortización anticipada
- **early_payment_month**: Mes de la amortización (por defecto: 12)

## 🔧 Desarrollo
```bash
# Instalar dependencias de desarrollo
npm install

# Modo de desarrollo con watch
npm run watch

# Compilar
npm run build

# Ejecutar en modo desarrollo
npm run dev
```

## 📋 Scripts Disponibles
```json
{
  "build": "tsc",
  "watch": "tsc --watch",
  "dev": "node build/index.js"
}
```

## 🤝 Contribuir

Las contribuciones son bienvenidas. Por favor:

1. Haz fork del proyecto
2. Crea una rama para tu feature (`git checkout -b feature/nueva-funcionalidad`)
3. Commit tus cambios (`git commit -m 'Añadir nueva funcionalidad'`)
4. Push a la rama (`git push origin feature/nueva-funcionalidad`)
5. Abre un Pull Request

## 📝 Licencia

Este proyecto está bajo la licencia MIT. Ver el archivo `LICENSE` para más detalles.

## 👨‍💻 Autor

Daniel - Instructor de programación y desarrollador

## 🙏 Agradecimientos

- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocolo para integración con modelos de IA
- Anthropic - Por Claude y el ecosistema MCP

---

**Nota**: Este servidor MCP está diseñado para uso personal y educativo. Para cálculos financieros críticos, consulta siempre con un asesor financiero profesional.