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:

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)

Related MCP server: ezPay E-Invoice MCP Server

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:

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

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 Reference

WayBill Reference (5 tools)

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

WayBill Read (6 tools)

Query and filter waybills. All read-only.

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).

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.

Invoice CRUD & Status (12 tools)

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

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.

Invoice Goods & Links (6 tools)

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

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.

TaxPayer Info (8 tools)

Query taxpayer information and lookups. All read-only.

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.

TaxPayer Auth (4 tools)

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

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