Repository avatar
Developer Tools
v0.1.0
active

cyprusscope

io.github.CloudCorpRecords/cyprusscope

Cyprus corporate and tax facts, statutory tests, register search and payroll calculations.

Documentation

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:

npx -y @reneturcios/cyprusscope mcp

MCP client configuration:

{
  "mcpServers": {
    "cyprusscope": {
      "command": "npx",
      "args": ["-y", "@reneturcios/cyprusscope", "mcp"]
    }
  }
}

As a container:

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:

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

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.

NPM
@reneturcios/cyprusscope
Install Command
npm install @reneturcios/cyprusscope
Runtime: npx
OCI
ghcr.io/cloudcorprecords/cyprusscope:0.1.0
Install Command
docker pull ghcr.io/cloudcorprecords/cyprusscope:0.1.0:undefined
Runtime: docker