Hilan Mcp

There's no official Hilan API. hilan-mcp drives a real (headless) Chromium browser via Playwright 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
• How it works
• Setup
  • 0. If you're on npm 12 or newer
  • 1. Register a tenant and enter credentials
  • 2. Add the server to your MCP client config
  • 3. Use it
• For AI agents setting this up on a user's behalf
• MCP tools
• Scope
• Reliability notes
• Security model
• Development
• 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 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:

npm config set allow-scripts=better-sqlite3-multiple-ciphers --location=user

Or per install, if you'd rather not set it globally:

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:

npx hilan-mcp setup --tenant amdocs        # tenant subdomain# ornpx 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:

{  "mcpServers": {    "hilan": {      "command": "npx",      "args": ["-y", "hilan-mcp"]    }  }}

{  "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"      }    }  }}

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 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 <their-org-code-or-subdomain> themselves, then (recommended) npx hilan-mcp setup-key. Check their npm --version first: on npm 12+ they also need step 0 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), 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

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)

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/<tenant>/, 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 JOINs, 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 above for that):

npm installnpm run typechecknpm 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 <subcommand> both invoke.

License

MIT