RS.ge Waybill MCP Server

A production-ready Model Context Protocol (MCP) server that lets Claude Desktop talk to the Georgian Revenue Service (RS.ge) waybill system using natural language.

Quick Start (For End Users)

The easiest way to get started:

1. Configure Claude Desktop - Add the MCP server to claude_desktop_config.json with your RS.ge credentials
2. Run one command - npx @borissolomonia/rs-waybill-mcp setup

That's it! The setup command will automatically:

• Check and install Docker if needed
• Build and start the backend container
• Verify everything is working

📖 See QUICK_START.md for detailed step-by-step instructions.

Manual Setup (Alternative)

If you prefer to run the scripts manually:

1. Start the backend in Docker

   • Windows: cd docker && start-backend-docker.bat
   • macOS/Linux: cd docker && ./start-backend-docker.sh
   • First run only: copy docker/.env.example to docker/.env and add your RS.ge credentials

2. Add the MCP server to Claude Desktop config:

   {
     "mcpServers": {
       "rs-waybill": {
         "command": "npx",
         "args": ["-y", "@borissolomonia/rs-waybill-mcp"],
         "env": {
           "BACKEND_URL": "http://localhost:8081",
           "RS_SERVICE_USER": "your-username:your-tin",
           "RS_SERVICE_PASSWORD": "your-password"
         }
       }
     }
   }

3. Restart Claude Desktop

Claude will auto-launch the MCP server via npx whenever it starts. No git clone or local build required.

Verify Installation

• docker-compose -f docker/docker-compose-backend-only.yml ps should show the backend container as Up on port 8081.
• curl http://localhost:8081/actuator/health should return {"status":"UP"} once the backend is ready.
• Inside Claude Desktop ask What custom MCP servers do I have? and confirm rs-waybill appears with 16 tools.
• Ask Check if my RS.ge credentials are valid to confirm everything works end-to-end.

Available MCP Tools

| Category | Tools | | --- | --- | | Lookup | get_error_codes, get_akciz_codes, get_name_from_tin, get_service_users, check_service_user, get_waybill_types | | Waybill queries | get_waybill, get_waybills, get_waybills_v1, get_buyer_waybills | | Waybill management | save_waybill, send_waybill, close_waybill, confirm_waybill, reject_waybill | | Invoices | save_invoice |

Each tool proxies through the Spring Boot backend, which handles SOAP/XML communication with RS.ge.

When You Launch the Backend

• Run start-backend-docker.bat (Windows) or ./start-backend-docker.sh (macOS/Linux) whenever you need RS.ge access.
• Leave the terminal open; stop the backend with docker-compose -f docker/docker-compose-backend-only.yml down when finished.
• Keep RS_SERVICE_USER and RS_SERVICE_PASSWORD in both docker/.env (for the backend) and the Claude config (for the MCP server).

Documentation Map

• Quick Start (New Users): QUICK_START.md - Get started in 2 steps!
• User Installation Guide: docs/USER_INSTALLATION_GUIDE.md - Complete guide for end users
• Detailed Setup: docs/SETUP.md - Manual setup instructions
• Troubleshooting: docs/TROUBLESHOOTING.md - Common issues and solutions
• Architecture & Learning: docs/LEARNING.md - Design decisions and how it works
• Docker Details: docker/README-DOCKER.md - Advanced Docker usage
• MCP Package: mcp-server/README.md - MCP server specifics

Architecture Snapshot

Claude Desktop (local process)
    ? launches `npx @borissolomonia/rs-waybill-mcp`
        ? HTTP to backend at http://localhost:8081
            ? Spring Boot service (Docker) ? RS.ge SOAP API

Claude must start the MCP server locally over STDIO, so only the backend runs in Docker. This keeps setup simple and still lets other machines use the MCP server via npx.

Contributing & Support

• Issues and pull requests welcome in this repository.
• Open docker/README-DOCKER.md for backend-only Docker commands.
• See docs/LEARNING.md for background, design rationale, and extension ideas.

License

MIT License. See LICENSE for details.