@reneturcios/fiscocheck 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rene Turcios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# fiscocheck
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+fiscocheck is a small local bridge to the hosted
+imperioutils fisco-it MCP server, a collection of
+Italian tax utilities. Through it an agent can check
+and generate a codice fiscale, validate a partita
+IVA, an IBAN or a PEC address, look up a CAP or an
+ATECO code, run the common calculations (regime
+forfettario, IVA, reverse charge, split payment,
+IMU), parse a FatturaPA document, compose the rows
+of an F24 form from amounts the caller has already
+calculated, work through Intrastat periodicity and
+composition, read NIS2 reference data, verify a
+payee, and run the guardian supplier checks. The
+tool descriptions upstream are in Italian and this
+bridge serves them exactly as captured, untranslated.
+
+The bridge holds no tax tables of its own. It
+answers the tool list locally, exactly as captured
+from the live endpoint, and forwards each tool call
+upstream, returning whatever comes back untouched.
+No tool in this surface submits a filing or executes
+a payment: the F24 and Intrastat composers assemble
+documents from caller-supplied rows, and the
+guardian tools check caller-supplied supplier data
+(IBAN, partita IVA and codice fiscale checksums, and
+the EU VIES public register).
+
+## Tools
+
+28 tools, grouped by area:
+
+- Identifiers: `validate_codice_fiscale`,
+  `generate_codice_fiscale`, `validate_partita_iva`,
+  `validate_iban`, `validate_pec`.
+- Lookups: `lookup_cap`, `lookup_ateco`,
+  `search_ateco`.
+- Calculations: `calc_forfettario`, `calc_iva`,
+  `calc_reverse_charge`, `calc_split_payment`,
+  `calc_imu`.
+- Documents: `parse_fatturapa`,
+  `parse_verify_fatturapa`, `compose_f24`.
+- Intrastat: `intrastat_periodicity`,
+  `intrastat_compose`, `intrastat_reference`.
+- NIS2: `nis2_tipologie`, `nis2_ambito`,
+  `nis2_reference`.
+- Payee and guardian: `verify_payee`,
+  `guardian_list_suppliers`,
+  `guardian_supplier_ledger`,
+  `guardian_supplier_status`, `guardian_check_iban`,
+  `guardian_watch_supplier`.
+
+Five tools (`calc_imu`, `intrastat_reference`,
+`nis2_tipologie`, `nis2_reference`, `verify_payee`)
+were captured with an empty `required: []` list, and
+three guardian tools (`guardian_list_suppliers`,
+`guardian_supplier_ledger`,
+`guardian_supplier_status`) were captured with no
+`required` key at all; both shapes are served
+verbatim. Per the original registry record, 23 tools
+are free and the 5 guardian tools are the keyed set.
+
+## Configuration
+
+- `IMPERIOUTILS_MCP_URL` (optional) — override the
+  upstream endpoint. Defaults to
+  `https://imperioutils.com/api/mcp`. (The override
+  hook is this rebuild's own labelled reconstruction.)
+- `IMPERIOUTILS_API_KEY` (optional) — when set, every
+  upstream request carries an `X-API-Key: <key>`
+  header, for the caller's own imperioutils API key.
+  When it is not set, no key header is sent. (The
+  header name is pinned by the original's registry
+  record; the record pins no package env name, so
+  forwarding the key from this env var is a labelled
+  reconstruction — the original surface was captured
+  keyless.)
+
+### Forwarding mechanics
+
+On the first tool call the client opens a streamable
+HTTP session upstream: a JSON-RPC `initialize`
+request (protocolVersion `2025-03-26`, clientInfo
+name `fiscocheck`), then a
+`notifications/initialized` notification, then the
+`tools/call` request carrying the caller's arguments
+unchanged. When the upstream answers `initialize`
+with an `Mcp-Session-Id` header, that value rides on
+every later request of the session, which is reused
+for the life of the process. Replies may arrive as
+plain JSON or as server-sent events; both are read.
+
+Successful upstream results pass through verbatim,
+including any `isError` flag the upstream sets.
+Failures — a JSON-RPC error, a non-2xx status, an
+unreadable response, or a request that cannot be
+completed — come back as an `isError` result whose
+text starts with `fiscocheck error:` (this rendering
+is this rebuild's own labelled reconstruction).
+
+## CLI
+
+Each tool is also a subcommand taking one JSON
+argument string:
+
+```bash
+npx @reneturcios/fiscocheck validate_iban '{"iban":"IT60X0542811101000000123456"}'
+npx @reneturcios/fiscocheck validate_codice_fiscale '{"codice_fiscale":"RSSMRA80A01H501U"}'
+npx @reneturcios/fiscocheck calc_imu '{}'
+npx @reneturcios/fiscocheck --version
+```
+
+Exit codes: `0` on success, `1` on an `isError`
+result, `2` on a usage error.
+
+## MCP server
+
+```bash
+npx -y @reneturcios/fiscocheck mcp
+```
+
+MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "fiscocheck": {
+      "command": "npx",
+      "args": ["-y", "@reneturcios/fiscocheck", "mcp"]
+    }
+  }
+}
+```
+
+## Docker
+
+```bash
+docker run -i ghcr.io/cloudcorprecords/fiscocheck
+docker run --rm ghcr.io/cloudcorprecords/fiscocheck --version
+```
+
+The container's default command is `mcp`, so the first
+form is a stdio MCP server; any other arguments reach
+the CLI normally.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run dev
+```
+
+The test suite runs entirely against a stubbed
+JSON-RPC upstream — no live network calls.
+
+## License
+
+MIT — see `LICENSE`.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * fiscocheck CLI.
+ *
+ *   fiscocheck <tool> '<json-args>'
+ *   fiscocheck mcp
+ *   fiscocheck --version
+ *
+ * <tool> is one of the 28 forwarded tools. Each tool
+ * subcommand takes a single JSON argument string holding
+ * that tool's arguments, forwards the call the same way
+ * the MCP path does, and prints the forwarded result
+ * content. Exit codes: 0 success, 1 on an isError
+ * result, 2 usage error.
+ */
+import { callTool, TOOL_NAMES, VERSION } from "./forward.js";
+function usage() {
+    console.error(`Usage:
+  fiscocheck <tool> '<json-args>'     one of: ${TOOL_NAMES.join(", ")}
+  fiscocheck mcp
+  fiscocheck --version`);
+    process.exit(2);
+}
+function firstText(result) {
+    const content = result.content;
+    if (Array.isArray(content)) {
+        for (const item of content) {
+            if (item !== null &&
+                typeof item === "object" &&
+                item.type === "text" &&
+                typeof item.text === "string") {
+                return item.text;
+            }
+        }
+    }
+    return typeof content === "string" ? content : JSON.stringify(content);
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    if (cmd === "--version" || cmd === "-v") {
+        console.log(VERSION);
+        return;
+    }
+    if (cmd === "mcp") {
+        if (rest.length !== 0)
+            usage();
+        const { startMcpServer } = await import("./mcp.js");
+        await startMcpServer();
+        return;
+    }
+    if (!TOOL_NAMES.includes(cmd ?? ""))
+        usage();
+    if (rest.length > 1)
+        usage();
+    let args = {};
+    if (rest.length === 1) {
+        try {
+            const parsed = JSON.parse(rest[0]);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                usage();
+            }
+            args = parsed;
+        }
+        catch {
+            console.error("error: argument must be a JSON object string");
+            process.exit(2);
+        }
+    }
+    const result = await callTool(cmd, args);
+    if (result.isError) {
+        console.error(`error: ${firstText(result)}`);
+        process.exit(1);
+    }
+    console.log(typeof result.content === "string"
+        ? result.content
+        : JSON.stringify(result.content, null, 2));
+}
+void main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG7D,SAAS,KAAK;IACZ,OAAO,CAAC,KAAK,CAAC;gDACgC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;;uBAE9C,CAAC,CAAC;IACvB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,SAAS,SAAS,CAAC,MAAkB;IACnC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,IACE,IAAI,KAAK,IAAI;gBACb,OAAO,IAAI,KAAK,QAAQ;gBACvB,IAA2B,CAAC,IAAI,KAAK,MAAM;gBAC5C,OAAQ,IAA2B,CAAC,IAAI,KAAK,QAAQ,EACrD,CAAC;gBACD,OAAQ,IAAyB,CAAC,IAAI,CAAC;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;AACzE,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7C,IAAI,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;QAClB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,KAAK,EAAE,CAAC;QAC/B,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QACpD,MAAM,cAAc,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,IAAI,EAAE,CAAC;QAAE,KAAK,EAAE,CAAC;IAC7C,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,EAAE,CAAC;IAC7B,IAAI,IAAI,GAA4B,EAAE,CAAC;IACvC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3E,KAAK,EAAE,CAAC;YACV,CAAC;YACD,IAAI,GAAG,MAAiC,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;YAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACzC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,CAAC,KAAK,CAAC,UAAU,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC7C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,CACT,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;QAChC,CAAC,CAAC,MAAM,CAAC,OAAO;QAChB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAC5C,CAAC;AACJ,CAAC;AAED,KAAK,IAAI,EAAE,CAAC"}

package/dist/forward.d.ts

@@ -0,0 +1,83 @@
+/**
+ * fiscocheck core: a forwarding client for the hosted
+ * imperioutils fisco-it MCP server (Italian tax tools).
+ *
+ * Nothing is computed locally. tools/list is answered
+ * from the literal definitions below, taken verbatim
+ * from a live capture of the upstream server (name,
+ * title, description and inputSchema exactly as
+ * captured, title key included; descriptions are in
+ * Italian and are served verbatim, not translated).
+ * A tools/call travels upstream over a streamable-HTTP
+ * JSON-RPC session: an initialize POST, a
+ * notifications/initialized POST, then the tools/call
+ * POST, carrying the Mcp-Session-Id response header on
+ * later requests when the upstream issues one. The
+ * session opens lazily on the first forwarded call and
+ * is reused for the client's life.
+ *
+ * The endpoint is pinned to
+ * https://imperioutils.com/api/mcp and may be replaced
+ * with the IMPERIOUTILS_MCP_URL environment variable
+ * (that override is a labelled reconstruction). When
+ * IMPERIOUTILS_API_KEY is set, every upstream request
+ * carries an `X-API-Key: <key>` header (header name
+ * pinned by the registry record's remote declaration;
+ * forwarding the key from this env var is a labelled
+ * reconstruction, as the capture was taken keyless and
+ * the record pins no package env name). When it is
+ * unset, no key header goes out.
+ *
+ * A successful upstream result is returned exactly as
+ * received, isError flag and extra fields included.
+ * Failures — an upstream JSON-RPC error, a non-2xx
+ * status, a body that cannot be parsed, or a fetch that
+ * throws or times out — become an isError result whose
+ * text begins with `fiscocheck error:` (that rendering
+ * is a labelled reconstruction). Replies may be plain
+ * JSON or SSE (`data:` lines); the JSON-RPC message
+ * whose id matches the request wins.
+ */
+import type { ForwardDeps, ToolArgs, ToolDef, ToolResult } from "./types.js";
+export declare const VERSION = "0.1.0";
+export declare const DEFAULT_ENDPOINT_URL = "https://imperioutils.com/api/mcp";
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const PROTOCOL_VERSION = "2025-03-26";
+export declare const TOOL_DEFS: ToolDef[];
+export declare const TOOL_NAMES: string[];
+/** Whether `name` belongs to the captured surface. */
+export declare function isKnownTool(name: string): boolean;
+/**
+ * Read a JSON-RPC response body, tolerating SSE framing.
+ * Returns the message whose id matches `expectedId` when
+ * present, otherwise the last parseable message, otherwise
+ * null when nothing in the body parses.
+ */
+export declare function parseRpcBody(text: string, expectedId?: number): Record<string, unknown> | null;
+/**
+ * A forwarding client that holds a single upstream
+ * session, opened lazily on first use and reused from
+ * then on (for the process lifetime in the MCP server,
+ * or for a single invocation in the CLI).
+ */
+export declare class FiscocheckClient {
+    private readonly deps;
+    private sessionId;
+    private ready;
+    private sessionPromise;
+    private idCounter;
+    constructor(deps?: ForwardDeps);
+    private fetchFn;
+    private endpointUrl;
+    private apiKey;
+    private timeoutMs;
+    private nextId;
+    private post;
+    private ensureSession;
+    /** Forward one tool call; upstream failures come back as isError results. */
+    callTool(name: string, args: ToolArgs): Promise<ToolResult>;
+}
+/** Build a forwarding client; tests inject a fake fetch and env through deps. */
+export declare function createClient(deps?: ForwardDeps): FiscocheckClient;
+/** One-shot helper: a fresh client for a single call (the CLI path). */
+export declare function callTool(name: string, args: ToolArgs, deps?: ForwardDeps): Promise<ToolResult>;