RS.ge Waybill MCP Server

# RS.ge Waybill MCP Server [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://www.typescriptlang.org/) **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](#quick-start) - [Features](#features) - [Documentation](#documentation) - [Installation](#installation) - [Configuration](#configuration) - [Usage Examples](#usage-examples) - [Troubleshooting](#troubleshooting) - [Development](#development) - [Project Structure](#project-structure) --- ## 🚀 Quick Start ```bash # 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](docs/SETUP_AND_DEPLOYMENT.md)** - Installation, configuration, troubleshooting ### For Developers - **[Project Documentation](docs/PROJECT_DOCUMENTATION.md)** - Architecture, components, data flow - **[RS.ge API Best Practices](docs/RS_GE_API_BEST_PRACTICES.md)** - Critical lessons learned and correct API patterns - **[MCP Development Guide](docs/MCP_DEVELOPMENT_GUIDE.md)** - How to build MCP servers --- ## 📦 Installation ### Prerequisites - **Node.js** 18+ ([Download](https://nodejs.org/)) - **Claude Desktop** ([Download](https://claude.ai/download)) - **RS.ge Credentials** - Service user and password ### Setup Steps 1. **Get the Code** ```bash git clone <repository-url> MCPWaybill cd MCPWaybill ``` 2. **Install Dependencies** ```bash npm install ``` 3. **Configure Environment** ```bash cp .env.example .env ``` Edit `.env`: ```bash RS_SERVICE_USER=4053098841:405309884 RS_SERVICE_PASSWORD=YourPasswordHere ``` 4. **Build** ```bash npm run build ``` 5. **Configure Claude Desktop** Edit `claude_desktop_config.json`: ```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: ```bash # 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: ```json { "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](docs/SETUP_AND_DEPLOYMENT.md#troubleshooting) for detailed help. --- ## 👨‍💻 Development ### Scripts ```bash 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](https://github.com/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](docs/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/](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