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

# 1. Install dependencies
npm install

# 2. Configure credentials
cp .env.example .env
# Edit .env with your RS.ge credentials

# 3. Build
npm run build

# 4. Configure Claude Desktop
# Windows: %APPDATA%\Claude\claude_desktop_config.json
# Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

# Add to config:
{
  "mcpServers": {
    "rs-waybill": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_PROJECT/dist/index.js"]
    }
  }
}

# 5. Restart Claude Desktop

# 6. Test in Claude
"Show me waybills from October 19-21, 2025"

---

✨ 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:

# Required
RS_SERVICE_USER=username:company_id
RS_SERVICE_PASSWORD=your_password

# Optional
LOG_LEVEL=info

Config File

Edit config/config.json for advanced settings:

{
  "api": {
    "timeout": 30000,
    "retries": 3
  },
  "logging": {
    "level": "info",
    "console": true
  }
}

---

💬 Usage Examples

Get Waybills

User: Show me waybills from October 19-21, 2025

Claude: I'll retrieve those waybills for you.
[Uses rs_get_waybills tool]

Found 61 waybills:
- October 19: 12 waybills
- October 20: 32 waybills
- October 21: 17 waybills
...

Lookup Company

User: What company has TIN 405309884?

Claude: [Uses rs_lookup_tin tool]
Company: შპს თეისთი

Get Error Codes

User: Show me RS.ge error codes

Claude: [Uses rs_get_error_codes tool]
Error codes:
- -1072: Date range issue
- -101: Missing seller_un_id
...

---

🛠️ 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

npm run build   # Compile TypeScript
npm run dev     # Build and run
npm run watch   # Auto-rebuild on changes

Project Structure

src/
├── index.ts              # MCP server entry point
├── config/               # Configuration management
├── services/             # RS.ge API client & XML parsing
│   ├── soap-client.ts    # SOAP API client
│   └── xml-parser.ts     # XML handling
├── tools/                # MCP tools
│   ├── get-waybills.ts
│   ├── get-dictionaries.ts
│   └── lookup-tin.ts
├── types/                # TypeScript types
└── utils/                # Utilities

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

Aspect	❌ Wrong	✅ Correct
Operation	get_waybills_v1	get_waybills
Date Param	last_update_date_s/e	create_date_s/e
Date Format	YYYY-MM-DD	YYYY-MM-DDTHH:MM:SS
End Date	As-is	Add +1 day
Seller ID	Not included	Extract from credentials
ID Field	WAYBILL_ID	ID

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