RS.ge Waybill MCP Server

MCP (Model Context Protocol) server that integrates the RS.ge Waybill SOAP API with Claude Desktop, enabling natural language queries for Georgian tax system waybills.

📋 Table of Contents

• Quick Start

• Features

• Documentation

• Installation

• Configuration

• Usage Examples

• Troubleshooting

• Development

• Project Structure

🚀 Quick Start

✨ Features

• ✅ Natural Language Interface - Query waybills through Claude chat

• ✅ Date Range Queries - Get waybills for specific periods

• ✅ TIN Lookup - Get company names from Tax IDs

• ✅ Dictionaries - Access error codes, akciz codes, waybill types

• ✅ Type-Safe - Full TypeScript with strict typing

• ✅ Error Handling - Automatic retries and detailed logging

• ✅ Production Ready - Tested with real RS.ge API

📚 Documentation

Comprehensive guides in the docs/ folder:

For Users

• Setup & Deployment Guide - Installation, configuration, troubleshooting

For Developers

• Project Documentation - Architecture, components, data flow

• RS.ge API Best Practices - Critical lessons learned and correct API patterns

• MCP Development Guide - How to build MCP servers

📦 Installation

Prerequisites

• Node.js 18+ (Download)

• Claude Desktop (Download)

• RS.ge Credentials - Service user and password

Setup Steps

1. Get the Code

   git clone <repository-url> MCPWaybill cd MCPWaybill

2. Install Dependencies

   npm install

3. Configure Environment

   cp .env.example .env

   Edit .env:

   RS_SERVICE_USER=4053098841:405309884 RS_SERVICE_PASSWORD=YourPasswordHere

4. Build

   npm run build

5. Configure Claude Desktop

   Edit claude_desktop_config.json:

   { "mcpServers": { "rs-waybill": { "command": "node", "args": [ "C:\absolute\path\to\MCPWaybill\dist\index.js" ] } } }

   ⚠️ Important: Use absolute paths!

6. Restart Claude Desktop (quit completely, then restart)

⚙️ Configuration

Environment Variables

Create .env file:

Config File

Edit config/config.json for advanced settings:

💬 Usage Examples

Get Waybills

Lookup Company

Get Error Codes

🛠️ Troubleshooting

Server Not Showing in Claude

1. Check absolute path in claude_desktop_config.json

2. Verify dist/index.js exists

3. Restart Claude Desktop completely

4. Check Developer Tools (View → Toggle Developer Tools)

Authentication Errors

1. Verify credentials in .env

2. Check format: username:company_id

3. Ensure no spaces: RS_SERVICE_USER=value (not RS_SERVICE_USER = value)

Tools Not Working

1. Check logs: tail -f logs/mcp-server.log

2. Test with: "Show waybills from yesterday"

3. Verify date format: YYYY-MM-DD

See Troubleshooting Guide for detailed help.

👨‍💻 Development

Scripts

Project Structure

Key Technologies

• @modelcontextprotocol/sdk - MCP framework

• Axios - HTTP client

• fast-xml-parser - XML parsing

• Winston - Logging

• Zod - Validation

🎯 Critical Lessons Learned

This project solved complex RS.ge API integration challenges:

Correct API Usage

XML Parsing

• Filter out @_ attributes before extracting data

• Handle both single and array responses

See RS_GE_API_BEST_PRACTICES.md for complete details.

📄 License

MIT License - See LICENSE file for details

🤝 Contributing

1. Fork the repository

2. Create feature branch

3. Make changes

4. Test thoroughly

5. Submit pull request

📞 Support

• Documentation: docs/

• Issues: GitHub Issues

• Questions: Check docs first

🏆 Acknowledgments

• Anthropic - Claude Desktop and MCP SDK

• RS.ge - Waybill SOAP API

• Community - Testing and feedback

Version: 1.0.0
Status: Production Ready ✅
Last Updated: January 2025

Built with ❤️ using TypeScript and MCP SDK