rs-mcp

MCP server + CLI for Georgia's Revenue Service (rs.ge). Exposes WayBill, Invoice, and TaxPayer SOAP APIs as AI-callable tools. Ships two interfaces from the same codebase:

• MCP server — 85 tools over stdio, works with any MCP-compatible client (Cursor, Claude Desktop, Windsurf, Continue, etc.)
• CLI (rs-cli) — same 85 operations as subcommands, JSON output, for scripts and AI agents
• Claude Skill — skills/rs-ge/ folder, upload to Claude.ai or Claude Code to teach Claude how to use the tools

Services covered:

| Service | Endpoint | Tools | |---------|----------|-------| | WayBill | services.rs.ge/WayBillService/WayBillService.asmx | 24 | | Invoice (NTOS) | revenue.mof.ge/ntosservice/ntosservice.asmx | 40 | | TaxPayer | services.rs.ge/taxservice/taxpayerservice.asmx | 20 | | Confirmation (HITL) | (internal) | 3 |

Key features:

• Read-only queries for waybills, invoices, taxpayer info, reference data
• Full CRUD for waybills and invoices (create, send, confirm, reject, close, delete)
• Human-in-the-Loop (HITL) safety for all destructive MCP operations
• CLI with interactive [y/N] confirmation for destructive commands (--yes to skip)
• Automatic SOAP envelope construction and XML response parsing

Prerequisites

• Node.js >= 18 (uses native fetch)
• npm
• An MCP-compatible client -- Cursor, Claude Desktop, Windsurf, Continue, or any agent/IDE that supports MCP
• rs.ge service user account (sub-user created through the rs.ge e-declaration portal)

Quick Start

1. Clone and install

git clone <your-repo-url> rs-mcp
cd rs-mcp
npm install

2. Configure environment

Copy the example file and fill in your credentials:

cp .env.example .env

Edit .env:

RS_SU=your_username:your_tin
RS_SP=your_password
RS_BASE_URL=https://services.rs.ge/WayBillService/WayBillService.asmx
RS_INVOICE_URL=https://www.revenue.mof.ge/ntosservice/ntosservice.asmx
RS_USER_ID=0
RS_TAX_URL=https://services.rs.ge/taxservice/taxpayerservice.asmx

See Environment Variables for details on each variable.

3. Build

npm run build

This compiles TypeScript from src/ into dist/.

4. Connect to your MCP client

The server uses stdio transport -- your MCP client spawns the process and communicates over stdin/stdout. Configuration varies by client:

Cursor -- create .cursor/mcp.json in the project root:

{
  "mcpServers": {
    "rs-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/rs-mcp"
    }
  }
}

Claude Desktop -- edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "rs-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/rs-mcp/dist/index.js"]
    }
  }
}

Other clients -- consult your client's MCP documentation. The server entry point is node dist/index.js with the working directory set to the project root.

Important: Do NOT run npm start manually during normal use. Your MCP client spawns the server process itself. After making changes, rebuild with npm run build and restart the MCP server from your client's settings.

CLI Quick Start

After building, use the rs-cli binary directly:

# Reference data (no auth needed for most)
node dist/cli.js reference waybill-types
node dist/cli.js reference units

# Waybill queries
node dist/cli.js waybill get 12345
node dist/cli.js waybill list --from 2025-01-01 --to 2025-03-31
node dist/cli.js waybill list --buyer-tin 123456789 --statuses 1

# Waybill actions (prompts [y/N] before executing)
node dist/cli.js waybill send 12345
node dist/cli.js waybill send 12345 --yes    # skip prompt

# Invoice
node dist/cli.js invoice seller-list --un-id 999 --from 2025-01-01 --to 2025-03-31
node dist/cli.js invoice get 456

# Taxpayer
node dist/cli.js taxpayer info 123456789
node dist/cli.js taxpayer dashboard

# Pretty-print JSON
node dist/cli.js waybill get 12345 --pretty

Or install globally and use rs-cli directly:

npm install -g .
rs-cli reference waybill-types

All commands output JSON. Use --pretty to force formatted output (auto-enabled on TTY).

Global flags:

| Flag | Short | Description | |------|-------|-------------| | --yes | -y | Skip [y/N] prompt on destructive operations | | --pretty | — | Force pretty-printed JSON |

For a full command reference, see skills/rs-ge/references/.

Claude Skill

The skills/rs-ge/ folder is a proper Claude Agent Skill. Upload it to teach Claude how to use both the MCP tools and CLI.

Install in Claude.ai:

1. Zip the skills/rs-ge/ folder
2. Go to Settings → Capabilities → Skills → Upload skill

Install in Claude Code: Place the skills/rs-ge/ folder in your Claude Code skills directory.

Environment Variables

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | RS_SU | Yes | Service username in username:TIN format | myuser:123456789 | | RS_SP | Yes | Service password | MyPassword123 | | RS_BASE_URL | No | WayBill SOAP endpoint (has default) | https://services.rs.ge/WayBillService/WayBillService.asmx | | RS_INVOICE_URL | No | Invoice/NTOS SOAP endpoint (has default) | https://www.revenue.mof.ge/ntosservice/ntosservice.asmx | | RS_USER_ID | Yes | Your e-declaration user ID (for invoice tools). Use ntos_get_un_id_from_user_id to find it. | 135184 | | RS_TAX_URL | No | TaxPayer SOAP endpoint (has default) | https://services.rs.ge/taxservice/taxpayerservice.asmx |

RS_SU and RS_SP are shared across all three services. The WayBill and Invoice services auto-inject them as su/sp. The TaxPayer service passes them explicitly per method (credential parameter names vary by method).

Project Structure

rs-mcp/
├── .env                        # Credentials (git-ignored)
├── .env.example                # Template for .env
├── package.json                # bin: { "rs-cli": "./dist/cli.js" }
├── tsconfig.json
├── skills/
│   └── rs-ge/                  # Claude Agent Skill (upload to Claude.ai / Claude Code)
│       ├── SKILL.md            # Skill definition with YAML frontmatter
│       └── references/         # Detailed command docs (loaded by Claude on demand)
│           ├── waybill.md
│           ├── invoice.md
│           └── taxpayer.md
└── src/
    ├── index.ts                # MCP entry point -- creates server, registers all tools
    ├── cli.ts                  # CLI entry point -- parseArgs router (rs-cli binary)
    ├── config.ts               # Loads environment variables
    ├── confirm.ts              # HITL pending-action store and execution logic
    ├── mcp-confirm.ts          # MCP wrapper: wraps queueAction with MCP content format
    ├── output.ts               # CLI JSON printer (pretty on TTY, compact when piped)
    ├── prompt.ts               # CLI readline [y/N] confirmation prompt
    ├── soap/
    │   ├── client.ts           # SOAP client for WayBill & Invoice (tempuri.org namespace)
    │   └── tax-client.ts       # SOAP client for TaxPayer (services.rs.ge namespace)
    ├── xml/
    │   ├── parser.ts           # XML-to-JSON parser (fast-xml-parser)
    │   └── waybill-builder.ts  # Structured JSON to Waybill XML converter
    ├── commands/               # CLI command handlers (one file per domain)
    │   ├── waybill.ts
    │   ├── invoice.ts
    │   ├── taxpayer.ts
    │   ├── reference.ts
    │   ├── helpers.ts
    │   └── confirm.ts
    ├── tools/                  # MCP tool registrations (one file per domain)
    │   ├── reference.ts
    │   ├── waybill.ts
    │   ├── waybill-write.ts
    │   ├── helpers.ts
    │   ├── invoice.ts
    │   ├── invoice-query.ts
    │   ├── invoice-desc.ts
    │   ├── invoice-helpers.ts
    │   ├── taxpayer.ts
    │   ├── taxpayer-reports.ts
    │   ├── taxpayer-auth.ts
    │   └── confirm.ts
    └── types/
        ├── reference.ts
        ├── waybill.ts
        ├── invoice.ts
        └── taxpayer.ts

Architecture

flowchart LR
    Client["MCP Client\n(Cursor, Claude Desktop, etc.)"] -->|stdio| McpServer["MCP Server\n(index.ts)"]
    Terminal["Terminal / Script"] -->|argv| CLI["CLI\n(cli.ts → rs-cli)"]

    McpServer --> Tools["MCP Tools\n(tools/)"]
    CLI --> Commands["CLI Commands\n(commands/)"]

    subgraph soap_layer [Shared SOAP Layer]
        SoapClient["callSoap / callSoapXml\n(tempuri.org)"]
        TaxClient["callTaxSoap\n(services.rs.ge)"]
    end

    subgraph hitl_mcp [MCP HITL]
        Queue["queueAction → preview"]
        Execute["confirm_action → execute"]
    end

    Tools -->|read-only| SoapClient
    Tools -->|destructive| Queue
    Queue --> Execute
    Execute --> SoapClient

    Commands -->|read-only| SoapClient
    Commands -->|destructive: prompt y/N| SoapClient

    Tools -->|read-only| TaxClient
    Commands --> TaxClient

    SoapClient --> RS_WB["rs.ge\nWayBill API"]
    SoapClient --> RS_INV["rs.ge\nInvoice API"]
    TaxClient --> RS_TAX["rs.ge\nTaxPayer API"]

Data flow — MCP:

1. MCP client sends a tool call via stdio
2. Read-only tools call SOAP directly and return JSON
3. Destructive tools queue the action (HITL), return a preview, wait for confirm_action

Data flow — CLI:

1. User runs rs-cli <domain> <action> [flags]
2. Read-only commands call SOAP and print JSON
3. Destructive commands prompt [y/N] (or skip with --yes), then call SOAP directly

Human-in-the-Loop (HITL) Safety System

All 32 destructive tools (create, update, delete, send, confirm, reject) use a two-phase confirmation system to prevent accidental data changes.

How it works

sequenceDiagram
    participant User
    participant AI as AI Assistant
    participant Tool as Destructive Tool
    participant Store as Pending Store
    participant Confirm as confirm_action
    participant SOAP as rs.ge API

    User->>AI: "Delete waybill #12345"
    AI->>Tool: del_waybill(waybill_id=12345)
    Tool->>Store: queueAction(...)
    Store-->>Tool: action_id + preview
    Tool-->>AI: Preview with action_id
    AI-->>User: "This will delete waybill #12345. Confirm?"
    User->>AI: "Yes, confirm"
    AI->>Confirm: confirm_action(action_id, "CONFIRM")
    Confirm->>Store: executeAction(action_id)
    Store->>SOAP: Actual SOAP call
    SOAP-->>Store: Result
    Store-->>Confirm: Result
    Confirm-->>AI: Result JSON
    AI-->>User: "Waybill #12345 deleted successfully"

Key rules

• Pending actions expire after 5 minutes
• The AI must show the preview to the user and wait for explicit approval
• confirm_action requires confirmation_text: "CONFIRM" -- the AI cannot auto-confirm
• Use reject_action to cancel a queued action
• Use list_pending_actions to see all actions awaiting confirmation

HITL tools

| Tool | Description | |------|-------------| | confirm_action | Execute a queued destructive action (requires explicit user approval) | | reject_action | Cancel a queued destructive action | | list_pending_actions | List all pending actions with remaining time |

Tool Reference

WayBill Reference (5 tools)

Fetch reference/lookup data for waybill fields. All read-only, no parameters required.

| Tool | Description | |------|-------------| | get_waybill_types | List all waybill types | | get_waybill_units | List all measurement units | | get_trans_types | List all transport types | | get_akciz_codes | List all excise/akciz codes | | get_wood_types | List all wood types |

WayBill Read (6 tools)

Query and filter waybills. All read-only.

| Tool | Description | Key Parameters | |------|-------------|----------------| | get_waybill | Get a single waybill by ID | waybill_id | | get_waybills | List seller waybills with filters | types, buyer_tin, statuses, create_date_s/e, begin_date_s/e | | get_buyer_waybills | List buyer waybills with filters | types, seller_tin, statuses, create_date_s/e, begin_date_s/e | | get_waybills_v1 | List waybills by last-update date range (max 3-day span) | last_update_date_s, last_update_date_e, buyer_tin | | get_waybills_ex | Seller waybills with confirmation filter | Same as get_waybills + is_confirmed (0/1/-1) | | get_buyer_waybills_ex | Buyer waybills with confirmation filter | Same as get_buyer_waybills + is_confirmed (0/1/-1) |

Waybill statuses: 0=saved, 1=active, 2=closed, 8=sent to transporter, -1=deleted, -2=cancelled

WayBill Write (9 tools)

Create, activate, close, and manage waybills. All destructive (HITL-protected).

| Tool | Description | Key Parameters | |------|-------------|----------------| | save_waybill | Create or update a waybill | type, buyer_tin, buyer_name, start_address, end_address, driver_tin, driver_name, goods_list[], trans_id, begin_date, status | | send_waybill | Activate a saved waybill | waybill_id | | send_waybill_vd | Activate with a specific begin date | waybill_id, begin_date | | confirm_waybill | Buyer confirms receipt of goods | waybill_id | | reject_waybill | Buyer rejects a waybill | waybill_id | | close_waybill | Close/complete a waybill | waybill_id | | close_waybill_vd | Close with a specific delivery date | waybill_id, delivery_date | | del_waybill | Delete a saved (not yet activated) waybill | waybill_id | | ref_waybill | Cancel an active waybill | waybill_id |

Waybill types: 1=inner, 2=transportation, 3=without transport, 4=distribution, 5=return, 6=sub-waybill

Goods list item fields: w_name, unit_id, quantity, price, and optionally unit_txt, bar_code, a_id, vat_type, quantity_ext

WayBill Helpers (4 tools)

Utility tools for waybill-related lookups. All read-only.

| Tool | Description | Key Parameters | |------|-------------|----------------| | get_name_from_tin | Look up a taxpayer name by TIN | tin | | get_error_codes | List all waybill error codes | (none) | | chek_service_user | Verify service user credentials | (none) | | get_service_users | List all service users for the account | (none) |

Invoice CRUD & Status (12 tools)

Create, manage, and control invoice lifecycle. 8 destructive + 4 read-only.

| Tool | Type | Description | Key Parameters | |------|------|-------------|----------------| | save_invoice | Write | Save/create a tax invoice | invois_id (0=new), operation_date, seller_un_id, buyer_un_id | | save_invoice_n | Write | Save/create with comment | Same + note | | save_invoice_a | Write | Save/create advance/compensation invoice | Same as save_invoice | | get_invoice | Read | Get a single invoice by ID | invois_id | | change_invoice_status | Write | Change invoice status | inv_id, status | | acsept_invoice_status | Write | Accept/confirm an invoice | inv_id, status | | ref_invoice_status | Write | Reject an invoice with reason | inv_id, ref_text | | k_invoice | Write | Create a correction invoice | inv_id, k_type (1-4) | | get_makoreqtirebeli | Read | Get correction invoice ID | inv_id | | add_inv_to_decl | Write | Attach invoice to VAT declaration | seq_num, inv_id | | get_seq_nums | Read | Get declaration numbers by period | sag_periodi (e.g. "202404") | | get_decl_date | Read | Get declaration date | decl_num, un_id |

Invoice statuses: -1=deleted, 0=saved, 1=sent, 2=confirmed, 3=corrected-primary, 4=correction, 5=correction-sent, 6=cancelled-sent, 7=cancellation-confirmed, 8=correction-confirmed

Correction types (k_type): 1=cancel operation, 2=change operation type, 3=price/compensation change, 4=goods return

Invoice Query (9 tools)

Search and list invoices. All read-only.

| Tool | Description | Key Parameters | |------|-------------|----------------| | get_seller_invoices | List seller-side invoices | un_id, date filters (s_dt/e_dt, op_s_dt/op_e_dt), invoice_no, sa_ident_no | | get_buyer_invoices | List buyer-side invoices | Same as above | | get_user_invoices | List by last-update date (max 3-day span) | un_id, last_update_date_s/e | | get_seller_invoices_r | Seller invoices needing reaction | un_id, status | | get_buyer_invoices_r | Buyer invoices needing reaction | un_id, status | | get_invoice_numbers | Autocomplete invoice numbers | un_id, v_invoice_n, v_count | | get_invoice_tins | Autocomplete buyer/seller TINs | un_id, v_invoice_t, v_count | | get_invoice_d | Autocomplete declaration numbers | un_id, v_invoice_d, v_count | | print_invoices | Get invoice data for printing | inv_id |

Invoice Goods & Links (6 tools)

Manage goods line items and waybill links on invoices. 4 destructive + 2 read-only.

| Tool | Type | Description | Key Parameters | |------|------|-------------|----------------| | save_invoice_desc | Write | Save a goods/service line item | invois_id, goods, g_unit, g_number, full_amount, drg_amount | | get_invoice_desc | Read | Get all line items for an invoice | invois_id | | delete_invoice_desc | Write | Delete a line item | id, inv_id | | get_ntos_invoices_inv_nos | Read | Get waybills linked to an invoice | invois_id | | save_ntos_invoices_inv_nos | Write | Link a waybill to an invoice | invois_id, overhead_no, overhead_dt | | delete_ntos_invoices_inv_nos | Write | Unlink a waybill from an invoice | id, inv_id |

VAT amount (drg_amount): positive = normal VAT, 0 = zero-rate, -1 = non-taxable

Invoice Helpers (13 tools)

Lookups, excise codes, service users, and invoice requests. 3 destructive + 10 read-only.

| Tool | Type | Description | Key Parameters | |------|------|-------------|----------------| | ntos_get_un_id_from_tin | Read | Get unique ID from TIN | tin | | ntos_get_tin_from_un_id | Read | Get TIN from unique ID | un_id | | ntos_get_org_name_from_un_id | Read | Get org name from unique ID | un_id | | ntos_get_un_id_from_user_id | Read | Get unique ID from e-declaration user ID | (none) | | ntos_get_akciz | Read | Search excise/akciz codes | s_text | | ntos_chek | Read | Verify NTOS service credentials | (none) | | ntos_get_ser_users | Read | List NTOS service users | user_name, user_password | | save_invoice_request | Write | Create invoice issuance reminder | inv_id, bayer_un_id, seller_un_id, dt | | del_invoice_request | Write | Delete an invoice reminder | inv_id, bayer_un_id | | get_invoice_request | Read | Get reminder details | inv_id | | acsept_invoice_request_status | Write | Forward invoice request to seller | id, seller_un_id | | get_requested_invoices | Read | List requests received by seller | seller_un_id | | get_invoice_requests | Read | List requests sent by buyer | bayer_un_id |

TaxPayer Info (8 tools)

Query taxpayer information and lookups. All read-only.

| Tool | Description | Key Parameters | |------|-------------|----------------| | tax_get_tp_info_public | Public taxpayer info (name, legal form, status, VAT, address) | tp_code | | tax_get_tp_contacts | Taxpayer contact info (phone, email) | tp_code | | tax_get_payer_info | Comprehensive payer info (status, declarations, waybills, cash box) | said_code | | tax_get_legal_person_info | Legal entity details (name, form, address, responsible persons) | said_code | | tax_get_person_income_data | Person income data (yearly/monthly amounts) | personal_number | | tax_get_payer_nace_info | NACE activity codes for a taxpayer | said_code | | tax_get_income_amount | Joint/total income amount for a year | year | | tax_get_payer_info_gita | GITA payer info with financial data | payer_code, start_date, end_date |

Note: Some TaxPayer methods may require additional service activation or 2-step SMS verification on your sub-user account. Methods that return "authorization error" likely need activation through the rs.ge portal.

TaxPayer Reports (8 tools)

Financial reports and customs data. 7 read-only + 1 destructive.

| Tool | Type | Description | Key Parameters | |------|------|-------------|----------------| | tax_get_z_report_sum | Read | Z-report cash register totals | start_date, end_date | | tax_get_z_report_details | Read | Z-report per-device details | start_date, end_date | | tax_get_waybill_month_amount | Read | Monthly waybill amounts | said_code, start_date, end_date | | tax_get_quick_cash_info | Read | Financial dashboard overview | (none) | | tax_get_comp_act_old | Read | Comparison act (old format) | said_code, start_date, end_date | | tax_get_comp_act_new | Read | Comparison act (new format) | said_code, start_date, end_date | | tax_get_cargo200_info | Read | Cargo 200 customs information | start_date, end_date | | tax_customs_warehouse_exit | Write | Register customs warehouse exit | declaration_number, customs_code, car_number |

TaxPayer Auth (4 tools)

SMS-based 2-step authentication for sensitive TaxPayer operations. 2 read-only + 2 destructive.

| Tool | Type | Description | Key Parameters | |------|------|-------------|----------------| | tax_tp_sms_verification | Read | Verify SMS code for payer info auth | said_code, sms_code | | tax_gita_sms_verification | Read | Verify SMS code for GITA payer info auth | payer_code, sms_code | | tax_payer_info_activation | Write | Activate/deactivate payer info access | said_code, status (1=activate, 0=deactivate) | | tax_gita_payer_activation | Write | Activate GITA payer info access | payer_code, start_date, status |

SOAP Services Reference

The server communicates with three rs.ge SOAP endpoints:

WayBill Service

• Endpoint: https://services.rs.ge/WayBillService/WayBillService.asmx
• Namespace: http://tempuri.org/
• Auth: su (username:TIN) and sp (password) auto-injected into every request
• Client: src/soap/client.ts -- callSoap() and callSoapXml()

Invoice Service (NTOS)

• Endpoint: https://www.revenue.mof.ge/ntosservice/ntosservice.asmx
• Namespace: http://tempuri.org/
• Auth: Same su/sp credentials, plus user_id injected for most methods
• Client: Same callSoap() with custom baseUrl

TaxPayer Service

• Endpoint: https://services.rs.ge/taxservice/taxpayerservice.asmx
• Namespace: services.rs.ge
• Auth: Credentials passed explicitly per method (parameter names vary: UserName, userName, inUserName, user)
• Client: src/soap/tax-client.ts -- callTaxSoap()

Development

Build

npm run build    # Compiles TypeScript to dist/

Run

# MCP server (normally spawned by your MCP client, not run manually)
npm start                      # node dist/index.js

# CLI
node dist/cli.js               # show usage
node dist/cli.js reference waybill-types
node dist/cli.js waybill list --from 2025-01-01 --to 2025-03-31

Tech stack

• TypeScript — strict mode, ES2022 target, Node16 modules
• ES Modules ("type": "module")
• @modelcontextprotocol/sdk — MCP server framework
• zod — MCP input schema validation
• fast-xml-parser — XML response parsing
• dotenv — environment variable loading
• node:util parseArgs — CLI argument parsing (no external framework)

Adding a new MCP tool

1. Add to an existing file in src/tools/ (or create a new one)
2. Use server.tool(name, description, schema, annotations, handler)
3. Annotations:

   const READONLY = { readOnlyHint: true, destructiveHint: false } as const;
   const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true } as const;

4. Destructive tools: use mcpQueueAction() from ../mcp-confirm.js instead of calling SOAP directly
5. Export register*Tools(server: McpServer) and call it in src/index.ts

Adding a new CLI command

1. Add to the matching file in src/commands/
2. Read-only: call SOAP directly and output(result)
3. Destructive: prompt with confirm() from ../prompt.js, or check flags.yes
4. Register any new --flag names in the parseArgs options block in src/cli.ts

Adding a new SOAP service

1. Add endpoint to src/config.ts and .env.example
2. Create SOAP client in src/soap/ if namespace differs
3. Add type interfaces in src/types/
4. Add MCP tools in src/tools/ and CLI commands in src/commands/

License

ISC