# RS.ge Waybill MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](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