cyprusscope
README.md
# cyprusscope
Cyprus company and tax questions, answered from a reviewed fact base. cyprusscope is a local forwarding client for the hosted Doviandi MCP service: it answers `tools/list` locally from the captured tool definitions and forwards every lookup to Doviandi, returning the answers exactly as the service sends them back.
The surface covers a reviewed fact lookup, statutory tests for tax residence, the IP Box, audit substitution and VAT registration, a proposed company-name screen, the recurring compliance obligations of a Cyprus company, a public-register company lookup, the Doviandi service catalogue, late-filing charges, payroll contributions, a glossary, and a scoping-call booking link. Nothing is cached, stored or computed locally — the package is a pipe, not an adviser.
## The tools
- **`cyprus_fact_lookup`** — Search the reviewed Cyprus corporate and tax fact base. `query` is required.
- **`cyprus_tax_residency_test`** — Apply the 183-day test and the 60-day rule. `days_in_cyprus` is required.
- **`cyprus_ip_box_nexus`** — Compute the IP Box nexus fraction and effective rate. `qualifying_expenditure` and `overall_expenditure` are required.
- **`cyprus_audit_or_review_test`** — Test whether a review may replace a full audit. `net_turnover` and `gross_assets` are required.
- **`cyprus_company_name_check`** — Screen a proposed company name against naming criteria and the public register. `proposed_name` is required.
- **`cyprus_vat_registration_test`** — Test whether VAT registration is required. `taxable_supplies_last_12_months` is required.
- **`cyprus_compliance_obligations`** — List the recurring obligations of a Cyprus company. No parameters are required.
- **`cyprus_company_lookup`** — Search the Registrar of Companies public register by name or registration number. No parameters are required by the schema.
- **`doviandi_services`** — The Doviandi service catalogue, optionally narrowed with `filter`.
- **`cyprus_late_filing_charge`** — Calculate the charge for filing or paying late. No parameters are required by the schema.
- **`cyprus_payroll_contributions`** — Break a salary into employer cost and employee deductions. `gross_annual_salary` is required.
- **`cyprus_glossary_lookup`** — Expand and define a Cyprus tax or corporate term. `term` is required.
- **`request_scoping_call`** — Return a booking link for a scoping call. `what_are_you_trying_to_do` is required.
## Install and run
As an MCP server via npm:
```bash
npx -y @reneturcios/cyprusscope mcp
```
MCP client configuration:
```json
{
"mcpServers": {
"cyprusscope": {
"command": "npx",
"args": ["-y", "@reneturcios/cyprusscope", "mcp"]
}
}
}
```
As a container:
```bash
docker run -i ghcr.io/cloudcorprecords/cyprusscope
docker run --rm ghcr.io/cloudcorprecords/cyprusscope cyprus_glossary_lookup '{"term":"SDC"}'
```
## CLI
One binary serves both the command line and the MCP server. Each tool is a subcommand taking a single JSON string with that tool's arguments:
```bash
cyprusscope cyprus_fact_lookup '{"query":"60 day rule conditions"}'
cyprusscope cyprus_glossary_lookup '{"term":"VIES"}'
cyprusscope cyprus_compliance_obligations '{}'
cyprusscope --version
```
Exit codes: `0` when the forwarded call succeeds, `1` when the upstream result is an error, and `2` for usage problems such as an unknown subcommand or a malformed JSON argument.
## Configuration
- `CYPRUS_MCP_URL` — Overrides the upstream endpoint. The default is the pinned hosted endpoint, `https://doviandi.com/api/mcp`. (The override variable is a reconstruction added by this rebuild.)
The upstream registry record declares no headers, so no authentication header is ever sent; the tool surface was captured keyless.
Upstream failures — a JSON-RPC error from the service, a non-2xx response, an unreadable body, or a request that fails outright — are reported to the caller as an error result whose text starts with `cyprusscope error:`.
## How forwarding works
The first forwarded call opens a session: an `initialize` request (protocol version `2025-03-26`), followed by a `notifications/initialized` notification, then the `tools/call` itself. If the service answers the initialize request with an `Mcp-Session-Id` header, that value is carried on every later request, and the open session is reused for the rest of the process. Replies are accepted either as plain JSON or as server-sent events. Successful results pass through verbatim, including any `isError` flag and any extra fields the service includes.
## Development
```bash
npm install
npm run build # tsc -> dist/ (dist/cli.js is the bin)
npm test # tsx --test test/*.test.ts — stubbed upstream, no network
npm run dev # run the CLI from source
```
The test suite checks the served tool list against the captured surface, exercises the session handshake and its reuse, verifies that no `Authorization` header is ever sent, and verifies that arguments go upstream untouched and results come back untouched.
## License
MIT — see `LICENSE`. Copyright (c) 2026 Rene Turcios.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues