# hilan-mcp [Health: Active] **Category:** ๐Ÿ’ป Developer Tools **Repository:** https://github.com/udah1/hilan-mcp **GitHub Stars:** 6 **npm Downloads (last month):** 295 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/hilan-mcp ## Description Pull Hilan (Hilanet / ื—ื™ืœืŸ, ื—ื™ืœื ื˜) payslips and Form 106 into any AI assistant. ## Tools Capabilities this server exposes over MCP: - **listTenants** โ€” List configured tenants โ€” no secrets. - **syncPayslips** โ€” Fetch structured payslip data + PDFs for the last N months. - **resyncPayslipMonth** โ€” Re-fetch one specific month, overwriting what's stored. - **syncForm106** โ€” Download the Form 106 PDF for a given year. - **downloadCombinedPayslipsPdf** โ€” One PDF covering a whole month range. - **getSalaryTrends** โ€” Yearly averages, YoY %, CAGR, and notable raises โ€” computed locally. - **listTables** โ€” Inspect the queryable local schema. - **query** โ€” Run read-only SQL against local payslip/Form106 data. - **getPersonalDetails** โ€” Live lookup of personal details (not persisted). - **dismissUpdateNotice** โ€” Suppress a specific version's update notice. - **debugCallAsmx** โ€” Raw API exploration โ€” off by default. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "hilan-mcp": { "command": "npx", "args": ["-y","hilan-mcp"] } } ``` ## Documentation & README
# hilan-mcp **An MCP server for [Hilan](https://net.hilan.co.il) (Hilanet / ื—ื™ืœืŸ, ื—ื™ืœื ื˜)** โ€” pull your payslips and Form 106 into any AI assistant, for any Hilan tenant. [![npm version](https://img.shields.io/npm/v/hilan-mcp.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/hilan-mcp) [![npm downloads](https://img.shields.io/npm/dm/hilan-mcp.svg?color=blue)](https://www.npmjs.com/package/hilan-mcp) [![license](https://img.shields.io/npm/l/hilan-mcp.svg?color=green)](https://github.com/udah1/hilan-mcp/blob/master/LICENSE) [![node](https://img.shields.io/node/v/hilan-mcp.svg)](https://www.npmjs.com/package/hilan-mcp)
--- There's no official Hilan API. `hilan-mcp` drives a real (headless) Chromium browser via [Playwright](https://playwright.dev) to log in, then reuses that same authenticated session to call Hilan's internal endpoints and download PDFs โ€” no fragile hand-rolled cookie replay, and no plaintext secrets stored anywhere. ## Table of contents - [Features](#features) - [How it works](#how-it-works) - [Setup](#setup) - [0. If you're on npm 12 or newer](#0-if-youre-on-npm-12-or-newer) - [1. Register a tenant and enter credentials](#1-register-a-tenant-and-enter-credentials) - [2. Add the server to your MCP client config](#2-add-the-server-to-your-mcp-client-config) - [3. Use it](#3-use-it) - [For AI agents setting this up on a user's behalf](#for-ai-agents-eg-claude-setting-this-up-on-a-users-behalf) - [MCP tools](#mcp-tools) - [Scope](#scope-v1) - [Reliability notes](#reliability-notes-learned-from-a-real-end-to-end-run) - [Security model](#security-model) - [Development](#development) - [License](#license) ## Features - ๐Ÿ“„ **Payslips** โ€” structured Bruto/Neto/salary-parts data, plus the PDF, for any month in the tenant's history. - ๐Ÿงพ **Form 106** โ€” annual tax summary PDFs, per year. - ๐Ÿ” **Encrypted local storage** โ€” SQLCipher-encrypted SQLite, key never written to disk in plaintext; OS-native credential store (Keychain/DPAPI/Secret Service) support. - ๐Ÿข **Any Hilan tenant** โ€” login form fields are detected per-tenant instead of hardcoded to one employer. - ๐Ÿ’ฌ **Answers, not raw JSON** โ€” tools like `query` answer "how much did I earn in June?" straight from local data, no network round-trip. - ๐Ÿ”„ **Self-updating awareness** โ€” the server checks for newer versions and lets your AI agent offer to update you, without needing its own UI. ## How it works This server drives a real (headless) Chromium browser via [Playwright](https://playwright.dev) to log in, then reuses that same authenticated browser context's HTTP client (`context.request`) to call Hilan's internal `.asmx` JSON endpoints and download PDFs โ€” so it automatically inherits whatever cookies/headers a real page load would have set up, instead of a fragile hand-rolled cookie replay. Login form fields differ per Hilan tenant (some have 2 fields, some 3), so the login form is inspected fresh for each tenant the first time you ingest credentials, rather than hardcoded to one company. ## Setup ### 0. If you're on npm 12 or newer npm 12 blocks dependency install scripts unless you allow them, and one of this package's dependencies (`better-sqlite3-multiple-ciphers`, the encrypted SQLite engine) needs its install script to compile a native binding. Without it, setup appears to succeed and then every tool that touches the database fails. Allow it once, for all future `npx` and global installs: ```bash npm config set allow-scripts=better-sqlite3-multiple-ciphers --location=user ``` Or per install, if you'd rather not set it globally: ```bash npm install -g --allow-scripts=better-sqlite3-multiple-ciphers hilan-mcp ``` On npm 11 and older this isn't needed โ€” install scripts still run by default. Check with `npm --version`. ### 1. Register a tenant and enter credentials Run this **yourself**, directly in your own terminal โ€” never paste real credentials into an AI chat. It installs the Chromium browser Playwright needs (one-time), launches a headless browser, detects your tenant's actual login fields, and prompts you for each one (passwords are masked). No local clone or `npm install` needed โ€” `npx` fetches the package on the fly: ```bash npx hilan-mcp setup --tenant amdocs # tenant subdomain # or npx hilan-mcp setup --tenant 5227 # numeric org code, resolved automatically ``` > If you already have the package installed some other way, the equivalent > lower-level command is `npx hilan-mcp ingest-creds --tenant <...>` โ€” > `setup` just also handles the one-time Chromium install first. The first time you run this you'll be asked to set an **encryption key** for the local database (min 6 characters) โ€” this key is never written to disk in plaintext. For the MCP server to open the database on its own (without a human present to respond to a prompt every time), it looks for the key in this order: 1. **OS credential store** (recommended) โ€” run `npx hilan-mcp setup-key` once, yourself, in your own terminal. You'll be asked to type a key (or press Enter to generate a strong random one), and it's stored in your OS's native secure storage: **macOS Keychain** (verified โ€” same file that holds your Wi-Fi/browser passwords, silent, no dialogs), **Windows** (DPAPI, tied to your Windows user account), or **Linux** (Secret Service / `secret-tool`, needs a keyring daemon like GNOME Keyring or KWallet). Nothing ends up in any config file at all. 2. **`HILAN_DB_KEY` env var** โ€” set it in the server's `env` block (see step 2). Same trust model as any other API key/secret configured for an MCP server in `mcp.json` (local file, not committed to git). 3. **Desktop notification** (last resort) โ€” the server falls back to asking via a system notification (with a plain terminal prompt as a further fallback), but that requires a human to respond within ~30s of every tool call that needs the database, so it's not recommended for normal use. ### 2. Add the server to your MCP client config Running the package with **no arguments** starts the MCP server itself (stdio transport) โ€” that's what your MCP client's config actually invokes: ```json { "mcpServers": { "hilan": { "command": "npx", "args": ["-y", "hilan-mcp"] } } } ```
Single-employer setup โ€” skip passing tenant on every tool call If you only ever use this for **one** employer, you can set a default tenant in the server's `env` block. Only the **first** of these that's set is used, in this order โ€” `COMPANY_URL` โ†’ `COMPANY_TENANT` โ†’ `COMPANY_CODE`: ```json { "mcpServers": { "hilan": { "command": "npx", "args": ["-y", "hilan-mcp"], "env": { "COMPANY_TENANT": "amdocs", "HILAN_DB_KEY": "the-encryption-key-you-set-during-ingest-creds", "NODE_EXTRA_CA_CERTS": "/path/to/your-corporate-ca-bundle.pem" } } } } ``` `HILAN_DB_KEY` is only needed if you didn't run `npx hilan-mcp setup-key` (see step 1) โ€” the OS credential store takes priority when both are present. `NODE_EXTRA_CA_CERTS` is only needed on networks with a TLS-intercepting corporate proxy (see [Reliability notes](#reliability-notes-learned-from-a-real-end-to-end-run)) โ€” omit it otherwise. | Env var | Example | Notes | |---|---|---| | `COMPANY_URL` | `https://amdocs.net.hilan.co.il` | Highest priority. | | `COMPANY_TENANT` | `amdocs` | Bare subdomain. Used only if `COMPANY_URL` isn't set. | | `COMPANY_CODE` | `5227` | Numeric org code. Used only if neither above is set โ€” requires an extra lookup round-trip. | This same fallback also applies to `npx hilan-mcp ingest-creds` โ€” `--tenant` is optional if one of these env vars is set. An explicit `tenant` argument (or `--tenant` flag) always overrides the env vars.
Running from a local clone instead of the published package Use `"command": "node", "args": ["/absolute/path/to/hilan-mcp/dist/cli/index.js"]` (after `npm install && npm run build` in that clone) instead of the `npx` form above.
### 3. Use it Ask your assistant things like "sync my last 3 payslips from Hilan", "download my Form 106 for 2025", or "how much net/gross did I earn in June 2026?" (answered instantly from the local database via the `query` tool, no network round-trip, once that month has been synced at least once) โ€” see the full [tool list](#mcp-tools) below. ## For AI agents (e.g. Claude) setting this up on a user's behalf If a user asks you to set up `hilan-mcp` for them: 1. **You must not** run `ingest-creds`/`setup`/`setup-key` yourself via a shell tool โ€” they prompt for a password and/or an encryption key interactively, and your shell tool's transcript could capture what the user types. Tell the user to open their **own** terminal and run `npx hilan-mcp setup --tenant ` themselves, then (recommended) `npx hilan-mcp setup-key`. Check their `npm --version` first: on npm 12+ they also need [step 0](#0-if-youre-on-npm-12-or-newer) or the database will fail to open later, in a way that doesn't look related to installation. 2. Once that's done, **you** can safely add the MCP server entry to the client's config file (the JSON blocks above) โ€” that part has no secrets in it as long as the user used `setup-key` (OS credential store) rather than the `HILAN_DB_KEY` env var fallback. 3. After the config is added, the user (or their client) needs to reload/ restart the MCP connection for the new tools to appear. 4. Don't enable `HILAN_ENABLE_DEBUG_TOOLS` unless the user explicitly asks for the raw `.asmx`/PDF exploration tools โ€” they're an intentional escape hatch (see [Security model](#security-model)), not needed for normal use. 5. If a tool response includes an `_updateNotice` field, tell the user and ask if they'd like to update; if they decline, call `dismissUpdateNotice` with that version (see [MCP tools](#mcp-tools)). ## MCP tools | Tool | Summary | |---|---| | `listTenants` | List configured tenants โ€” no secrets. | | `syncPayslips` | Fetch structured payslip data + PDFs for the last N months. | | `resyncPayslipMonth` | Re-fetch one specific month, overwriting what's stored. | | `syncForm106` | Download the Form 106 PDF for a given year. | | `downloadCombinedPayslipsPdf` | One PDF covering a whole month range. | | `getSalaryTrends` | Yearly averages, YoY %, CAGR, and notable raises โ€” computed locally. | | `listTables` / `describeTable` | Inspect the queryable local schema. | | `query` | Run read-only SQL against local payslip/Form106 data. | | `getPersonalDetails` | Live lookup of personal details (not persisted). | | `dismissUpdateNotice` | Suppress a specific version's update notice. | | `debugCallAsmx` / `debugDownloadPdf` | Raw API exploration โ€” off by default. |
Full tool reference (arguments, behavior, notes) #### `listTenants()` Configured tenants (subdomain, capability, whether login has succeeded before) โ€” no secrets. #### `syncPayslips(tenant?, monthsBack?, skipPdf?)` Logs in (reusing a saved session if it still works), fetches structured Bruto/Neto/salary-parts data for the last N months (default 3), and downloads each payslip PDF. Set `skipPdf: true` for a much faster numbers-only sync (e.g. "what did I earn this year"). `tenant` is optional if `COMPANY_URL`/`COMPANY_TENANT`/`COMPANY_CODE` is set. The tenant's own archive length caps how far back this can actually go โ€” no need to guess a start date. #### `resyncPayslipMonth(tenant?, period, skipPdf?)` Re-fetches **one specific month** (e.g. `"10_2019"` or `"10/2019"`), overwriting whatever's stored. Use this instead of re-running `syncPayslips` over the whole history just to retry one bad/truncated PDF or to answer a one-off "how much did I make in month X" question. #### `syncForm106(tenant?, year?)` Logs in and downloads the Form 106 PDF for a given year (or the tenant's default year). Same `tenant` fallback as above. #### `downloadCombinedPayslipsPdf(tenant?, fromMonth, toMonth, destDir?)` Downloads **one PDF covering a whole month range** (e.g. all of 2015โ€“2024) instead of one file per month. Automatically splits into multiple files if the range would otherwise exceed the server's URL length limit (see [Reliability notes](#reliability-notes-learned-from-a-real-end-to-end-run)) โ€” practical ceiling is roughly 10โ€“15 years per chunk. #### `getSalaryTrends(tenant?, fromYear?, toYear?)` Computes salary growth trends **from locally-synced payslips only** โ€” no live login, no network call. Returns yearly average Bruto/Neto, year-over-year % change between adjacent years, CAGR between the first and last full (12-month) calendar year, overall growth (first vs. last synced month), and "notable jumps" (โ‰ฅ10% YoY change in Bruto). Optional `fromYear`/`toYear` scope the calendar years considered. Prefer this over hand-rolling aggregation with `query` โ€” grouping/sorting by plain `period` text gets cross-year chronology wrong (e.g. `"01_2011"` sorts before `"02_2010"`); this tool sorts by actual calendar month internally. #### `listTables()` / `describeTable(table)` Lists queryable tables (`payslips`, `form106` only) and their columns/indexes. #### `query(sql)` SELECT-only SQL against `payslips`/`form106`. **`credentials`, `sessions`, and `tenants` are hard-blocked** โ€” see [Security model](#security-model). Good for quick questions like "how much net/gross did I earn in June 2026" without touching the network at all. #### `getPersonalDetails(tenant?)` Logs in and returns personal details (name, national ID, birthdate, address, phone, email, work start date, job type). Live lookup only โ€” **not persisted** to the local database. #### `dismissUpdateNotice(version)` Call this if the user declines an update you offered them (see below), so that exact version isn't mentioned again. #### `debugCallAsmx(tenant?, servicePath, body?)` / `debugDownloadPdf(tenant?, relativeUrl, fileName)` **Debug/exploration only, disabled by default** โ€” raw pass-through to any `.asmx` endpoint, or download of an arbitrary relative PDF URL, on a logged-in session. Requires `HILAN_ENABLE_DEBUG_TOOLS=1` in the server's `env` block; not registered otherwise. Filenames are sanitized (no path traversal) and URLs are restricted to the tenant's own origin (no SSRF).
**Update notifications**: this server has no UI of its own, so update checks piggyback on whatever tool the agent happens to call next. At most once a day, a successful tool response may include an extra `_updateNotice` field with a message like *"A new hilan-mcp version is available: 0.1.0 -> 0.2.0..."* โ€” if you're the AI agent reading this, tell the user and ask if they'd like to update; if they say no, call `dismissUpdateNotice` with that version so it isn't raised again (a newer version will still be announced later). The check itself hits the npm registry with a 3s timeout and silently no-ops if it's unreachable (e.g. offline, corporate proxy) โ€” it never fails a tool call. **Concurrency note**: every tool call for a given tenant is automatically queued and run one-at-a-time internally (see `TenantService.runExclusive`) โ€” Hilan's site (and/or the network path to it) doesn't handle concurrent requests from one session well and everything times out otherwise. You don't need to serialize calls yourself; different tenants still run fully in parallel. ## Scope (v1) - โœ… Payslips (list, structured Bruto/Neto/parts, PDF) - โœ… Form 106 (PDF, per year) - โ›” General file archive, Form 101 โ€” not built (v1.1+) - โ›” One-time-code / 2FA login โ€” tenants that require it return a clear "unsupported" error instead of hanging Tenants whose internal API response doesn't match the structured shape seen on the reference tenant (Amdocs) are marked `pdf_only`: payslip syncs still work and still save a PDF, just without the parsed Bruto/Neto numbers. ## Reliability notes (learned from a real end-to-end run)
Corporate TLS-intercepting proxies, PDF URL quirks, truncation retries, URL-length limits, and OTP false positives - **Corporate TLS-intercepting proxies** (e.g. Amdocs's network) break Playwright's Node-side `context.request` for the internal API/PDF calls with `self-signed certificate in certificate chain`. Set `NODE_EXTRA_CA_CERTS` to your organization's exported CA bundle in the server's `env` block if you hit this. - **Direct PDF download URLs are relative to `/Hilannetv2`**, not the domain root โ€” a URL returned by the JSON API like `PersonalFile/PdfPaySlip.aspx/...` actually lives at `/Hilannetv2/PersonalFile/PdfPaySlip.aspx/...`. Confirmed via a live browser network capture. - PDF downloads go through an **in-page `fetch()`** (same-origin, raw URL) rather than `context.request`, which silently re-encodes literal `/` in query strings to `%2F` and gets 404'd by some endpoints. - The same corporate proxy occasionally **truncates a PDF response mid-stream** (observed: suspiciously round 32768-byte cutoffs) without the fetch itself erroring. `downloadPdf` checks the whole buffer for the standard `%%EOF` PDF trailer (not just the tail โ€” some genuine Hilan PDFs have tens/hundreds of KB of trailing null-byte padding *after* a valid `%%EOF`) and retries up to 3 times before giving up. - Combined multi-month PDFs (`PaySlipApiapi.asmx/GetMultiplePaySlipData`, one file covering a date range instead of one per month) hit a hard **HTTP 404 once the URL exceeds ~2048 characters** โ€” that's IIS's default `requestFiltering maxQueryString` limit, not a Hilan-specific cap (each month adds ~11 chars to the URL). Verified working at 120 months (10 years, ~1.4KB URL); verified failing at 194 months (~16 years, 2.2KB URL) โ€” so a ~15-year request is the realistic practical ceiling per combined PDF. Not an issue for per-month syncing (`syncPayslips`), which never builds one huge URL. - A tenant's *regular* login page can unconditionally show a "log in with a one-time code" button/link even when normal username+password login is fully supported and working โ€” don't treat that text alone as proof OTP is required. Only genuinely new OTP-input fields (or navigating to an OTP-specific route) after a failed login count as OTP being required.
## Security model - The whole SQLite database (`~/Library/Application Support/HilanMcp/hilan.db` on macOS, XDG/AppData equivalents elsewhere) is encrypted at rest via SQLCipher (`better-sqlite3-multiple-ciphers`), keyed by a passphrase you choose that is **never persisted to disk**. PDFs live alongside it under `.../HilanMcp/pdfs//`, and rolling log files under `.../HilanMcp/logs/` (redacted โ€” see below). App-data, PDF, and log directories are created with `0700` permissions; the DB and PDF files themselves with `0600`. - `credentials` (your login fields) and `sessions` (saved browser cookies) are ordinary tables *inside* that encrypted database, but they are **never reachable through the `query`/`listTables`/`describeTable` tools** โ€” those are hard-allowlisted to `payslips` and `form106` only, validated via a full SQL AST parse (not a regex) so `JOIN`s, subqueries, and quoted identifiers can't be used to sneak past the allowlist (see `src/utils/sqlValidation.ts` and `src/tests/sqlValidation.test.ts`). - Cookies and auth headers are redacted from log files and from any error message a tool call returns, so a Playwright error can't leak your session into your chat history (see `src/utils/redact.ts`). - Credential entry (`ingest-creds`) must be run directly by you in your own terminal โ€” never through an assistant's shell tool, whose transcript could capture what you typed. - `debugCallAsmx` is an intentional escape hatch: it lets a logged-in session call **any** `.asmx` endpoint with **any** body, bypassing the curated tools above. It was added for API exploration during development and is one-employee-scoped (same session, same permissions you already have on the site) โ€” it can't reach other employees' data or other tenants โ€” but it could in principle call a write endpoint (Hilan generally gates writes behind approval flows, but this hasn't been audited). Off by default (`HILAN_ENABLE_DEBUG_TOOLS`); treat it like `query`'s SQL escape hatch โ€” fine for an AI assistant you trust to explore with, not something to expose to untrusted input. ## Development Clone this repo to work on the code itself (not needed just to *use* the server โ€” see [Setup](#setup) above for that): ```bash npm install npm run typecheck npm test # unit tests (SQL allowlist, path-traversal, redaction, update checks, ...) npm run build # compile TypeScript -> dist/ npm run start:mcp # run the server directly from source (stdio transport) npm run setup # local equivalent of `npx hilan-mcp setup` npm run ingest-creds # register a tenant + credentials (interactive, run yourself) npm run setup-key # store the DB encryption key in your OS credential store (interactive, run yourself) ``` `npm publish` ships only `dist/`, `README.md`, and `LICENSE` (see the `files` field in `package.json`) โ€” source, tests, and local research artifacts are excluded. `prepublishOnly` runs typecheck + tests + build first, so a broken build can't be published. The published `bin` entry (`dist/cli/index.js`) is what `npx hilan-mcp` and `npx hilan-mcp ` both invoke. ## License [MIT](https://github.com/udah1/hilan-mcp/blob/HEAD/LICENSE)