# Salaxy MCP

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes a Finnish payroll (palkanlaskenta) API as MCP tools. Built with the official TypeScript MCP SDK.

## Tools

### `get_income_types`

Returns all Finnish payroll income types (*tulolajit*) supported by the server.

**Parameters:** none

**Returns:** JSON array of income types, each with:

| Field | Description |
|---|---|
| `code` | Incomes Register (*tulorekisteri*) code, e.g. `"101"` |
| `name_fi` | Finnish name, e.g. `"Aikapalkka"` |
| `name_en` | English translation, e.g. `"Time-based wage"` |
| `indicative_tax_rate_pct` | Flat withholding rate used in demo calculations |
| `description` | Plain-language description of the income type |

Supported codes include time-based wages (101), piece-rate wages (102), overtime (201), shift supplements (210), holiday compensation (301), holiday bonus (302), sick pay (401), fringe benefits (501, 502), and commission pay (601).

---

### `calculate_salary`

Calculates gross and net salary by applying Finnish statutory deductions:

- **Income tax** — based on the income type's indicative withholding rate
- **TyEL pension** — 7.45 % employee contribution (2024 rate)
- **Unemployment insurance** — 0.79 % employee share (2024 rate)

**Parameters:**

| Parameter | Type | Description |
|---|---|---|
| `base_salary` | `number` | Hourly rate (€) when `hours_worked > 0`; monthly salary (€) when `hours_worked = 0` |
| `income_type_code` | `string` | Income type code from `get_income_types`, e.g. `"101"` |
| `hours_worked` | `number` | Hours in the pay period; pass `0` for a fixed monthly salary |

**Returns:**

```json
{
  "income_type": { "code": "101", "name_fi": "Aikapalkka", "name_en": "Time-based wage" },
  "currency": "EUR",
  "deduction_rates": {
    "income_tax_pct": 25,
    "pension_pct": 7.45,
    "unemployment_pct": 0.79
  },
  "gross_salary": 3080.00,
  "income_tax": 750.03,
  "pension_deduction": 229.46,
  "unemployment_deduction": 24.33,
  "net_salary": 2076.18,
  "hours_worked": 80,
  "effective_hourly_rate": 38.50
}
```

---

### `get_employee`

Returns mock employee master data by ID.

**Parameters:**

| Parameter | Type | Description |
|---|---|---|
| `employee_id` | `string` | Employee identifier (case-insensitive). Available: `EMP001`, `EMP002`, `EMP003`, `EMP004` |

**Returns:**

```json
{
  "employee": {
    "id": "EMP001",
    "first_name": "Mikael",
    "last_name": "Virtanen",
    "ssn_masked": "150385-****",
    "employment_type": "Toistaiseksi voimassa oleva / Permanent",
    "department": "Ohjelmistokehitys / Software Development",
    "hourly_rate": 38.5,
    "monthly_salary": 6160,
    "tax_card_rate": 28,
    "municipality": "Helsinki",
    "iban": "FI21 1234 5600 0007 85"
  }
}
```

---

## Getting started

```bash
npm install
npm run build
npm start
```

The server communicates over **stdio** (standard MCP transport). To integrate with Claude Desktop, add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "salaxy": {
      "command": "node",
      "args": ["/absolute/path/to/salaxy-mcp/dist/index.js"]
    }
  }
}
```

## Project structure

```
salaxy-mcp/
├── src/
│   ├── index.ts   # MCP server, tool definitions, salary calculation logic
│   └── data.ts    # Income types and mock employee data
├── package.json
├── tsconfig.json
└── README.md
```

## Notes

- Tax rates and statutory deduction percentages are illustrative 2024 values for demonstration purposes and should not be used for real payroll.
- SSNs in mock data are masked; IBANs are synthetic.