SETUP_AND_DEPLOYMENT.md•16.3 kB
# RS.ge Waybill MCP Server - Setup & Deployment Guide
## Table of Contents
1. [Quick Start](#quick-start)
2. [Local Development Setup](#local-development-setup)
3. [Configuration](#configuration)
4. [Running the Server](#running-the-server)
5. [Claude Desktop Integration](#claude-desktop-integration)
6. [Deployment to Other Computers](#deployment-to-other-computers)
7. [Troubleshooting](#troubleshooting)
8. [Maintenance](#maintenance)
---
## Quick Start
### Prerequisites
- **Node.js 18+** - [Download](https://nodejs.org/)
- **Claude Desktop** - [Download](https://claude.ai/download)
- **RS.ge Credentials** - Service user and password
### 5-Minute Setup
```bash
# 1. Clone or download the project
cd C:\Users\YourName\Projects
git clone <repository-url> MCPWaybill
# OR download and extract ZIP
# 2. Navigate to project
cd MCPWaybill
# 3. Install dependencies
npm install
# 4. Create environment file
copy .env.example .env
# Edit .env and add your credentials
# 5. Build the project
npm run build
# 6. Configure Claude Desktop
# Edit: %APPDATA%\Claude\claude_desktop_config.json
# Add server configuration (see below)
# 7. Restart Claude Desktop
# 8. Test
# In Claude: "Show me waybills from today"
```
---
## Local Development Setup
### Step 1: Install Node.js
**Windows:**
1. Download from https://nodejs.org/ (LTS version)
2. Run installer
3. Verify installation:
```bash
node --version # Should show v18.x or higher
npm --version
```
**Mac:**
```bash
# Using Homebrew
brew install node@18
# Verify
node --version
npm --version
```
**Linux:**
```bash
# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
# Verify
node --version
npm --version
```
### Step 2: Get the Project
**Option A: Clone from Git**
```bash
git clone <repository-url> MCPWaybill
cd MCPWaybill
```
**Option B: Download ZIP**
1. Download project ZIP file
2. Extract to desired location
3. Open terminal in extracted folder
### Step 3: Install Dependencies
```bash
# Install all npm packages
npm install
# This installs:
# - @modelcontextprotocol/sdk (MCP framework)
# - axios (HTTP client)
# - fast-xml-parser (XML parsing)
# - winston (logging)
# - zod (validation)
# - TypeScript and types
```
**Common Issues:**
**Issue: npm install fails**
```bash
# Clear npm cache
npm cache clean --force
# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json
# Reinstall
npm install
```
**Issue: Permission errors (Linux/Mac)**
```bash
# Fix npm permissions
sudo chown -R $USER:$GROUP ~/.npm
sudo chown -R $USER:$GROUP ~/.config
```
### Step 4: Build the Project
```bash
# Compile TypeScript to JavaScript
npm run build
# This creates:
# - dist/ directory with compiled .js files
# - Type declaration files (.d.ts)
# - Source maps (.js.map)
```
**Verify Build:**
```bash
# Check dist folder exists
ls dist/
# Should contain:
# - index.js (main entry point)
# - config/
# - services/
# - tools/
# - types/
# - utils/
```
---
## Configuration
### Environment Variables
Create `.env` file in project root:
```bash
# Copy example
cp .env.example .env
# Edit .env
nano .env # or use any text editor
```
**Required Variables:**
```bash
# RS.ge Credentials
RS_SERVICE_USER=4053098841:405309884
RS_SERVICE_PASSWORD=YourPasswordHere
# Optional: Logging level
LOG_LEVEL=info
# Optional: Custom log file location
LOG_FILE=logs/mcp-server.log
```
**Security Notes:**
- ✅ `.env` is git-ignored (won't be committed)
- ✅ Never share your credentials
- ✅ Use different credentials for dev/prod
### Configuration File
Edit `config/config.json`:
```json
{
"server": {
"name": "rs-waybill-mcp",
"version": "1.0.0",
"description": "MCP server for RS.ge Waybill SOAP API"
},
"api": {
"baseUrl": "https://services.rs.ge/WayBillService/WayBillService.asmx",
"timeout": 30000,
"retries": 3,
"retryDelay": 2000
},
"credentials": {
"serviceUser": "${RS_SERVICE_USER}",
"servicePassword": "${RS_SERVICE_PASSWORD}"
},
"logging": {
"level": "info",
"file": "logs/mcp-server.log",
"console": true,
"maxSize": "10m",
"maxFiles": 7
},
"features": {
"getWaybills": true,
"saveWaybill": false,
"sendWaybill": false,
"closeWaybill": false,
"confirmWaybill": false,
"rejectWaybill": false,
"getErrorCodes": true,
"getAkcizCodes": true,
"getNameFromTin": true
}
}
```
**Configuration Options:**
| Option | Description | Default |
|--------|-------------|---------|
| `api.timeout` | Request timeout (ms) | 30000 |
| `api.retries` | Max retry attempts | 3 |
| `api.retryDelay` | Initial retry delay (ms) | 2000 |
| `logging.level` | Log level (error/warn/info/debug) | info |
| `logging.console` | Log to console | true |
| `features.*` | Enable/disable specific tools | varies |
---
## Running the Server
### Development Mode
**Run once:**
```bash
npm run dev
# This does:
# 1. Compiles TypeScript (npm run build)
# 2. Runs dist/index.js
```
**Watch mode (auto-rebuild on changes):**
```bash
npm run watch
# Uses nodemon to watch for file changes
# Automatically rebuilds and restarts server
```
### Production Mode
```bash
# Build for production
npm run build
# Run compiled JavaScript
node dist/index.js
```
### Testing the Server Standalone
```bash
# Run server and test manually
node dist/index.js
# Server waits for JSON-RPC messages on stdin
# Try sending a test request:
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
# Press Enter
# You should see response with available tools
```
---
## Claude Desktop Integration
### Step 1: Locate Config File
**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```
**Full path example:**
```
C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json
```
**Mac:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Linux:**
```
~/.config/Claude/claude_desktop_config.json
```
### Step 2: Edit Configuration
Open `claude_desktop_config.json` in a text editor.
**If file doesn't exist, create it:**
```json
{
"mcpServers": {}
}
```
**Add the MCP server:**
**Windows:**
```json
{
"mcpServers": {
"rs-waybill": {
"command": "node",
"args": [
"C:\\Users\\YourName\\Projects\\MCPWaybill\\dist\\index.js"
],
"env": {
"RS_SERVICE_USER": "4053098841:405309884",
"RS_SERVICE_PASSWORD": "YourPasswordHere"
}
}
}
}
```
**Mac/Linux:**
```json
{
"mcpServers": {
"rs-waybill": {
"command": "node",
"args": [
"/Users/YourName/Projects/MCPWaybill/dist/index.js"
],
"env": {
"RS_SERVICE_USER": "4053098841:405309884",
"RS_SERVICE_PASSWORD": "YourPasswordHere"
}
}
}
}
```
**Important Notes:**
- Use **absolute paths** (not relative like `./dist/index.js`)
- Use **forward slashes** on Mac/Linux
- Use **double backslashes** `\\` on Windows
- Environment variables override `.env` file
**Multiple MCP Servers:**
```json
{
"mcpServers": {
"rs-waybill": {
"command": "node",
"args": ["C:\\path\\to\\rs-waybill\\dist\\index.js"]
},
"other-server": {
"command": "node",
"args": ["C:\\path\\to\\other-server\\dist\\index.js"]
}
}
}
```
### Step 3: Restart Claude Desktop
**Important:** Must **fully quit** Claude Desktop, not just close the window.
**Windows:**
1. Right-click Claude in system tray
2. Click "Quit"
3. Start Claude Desktop again
**Mac:**
1. Cmd+Q to quit
2. Start Claude Desktop again
**Linux:**
```bash
killall claude-desktop
claude-desktop &
```
### Step 4: Verify Integration
**Check Server Status:**
1. Open Claude Desktop
2. Open Developer Tools: View → Toggle Developer Tools
3. Go to Console tab
4. Look for log messages about MCP servers
5. Should see: `MCP server running on stdio`
**Test in Chat:**
```
User: What tools do you have available?
Claude: I have access to RS.ge Waybill tools:
- rs_get_waybills: Get waybills for a date range
- rs_get_error_codes: Get error code dictionary
- rs_lookup_tin: Look up company name from TIN
[etc.]
```
**Run a Real Query:**
```
User: Show me waybills from October 19-21, 2025
Claude: [Uses rs_get_waybills tool]
Found 61 waybills:
- October 19: 12 waybills
- October 20: 32 waybills
- October 21: 17 waybills
[Shows details...]
```
---
## Deployment to Other Computers
### Package for Distribution
**Create a deployment package:**
```bash
# 1. Build the project
npm run build
# 2. Create distribution folder
mkdir -p deploy/rs-waybill-mcp
# 3. Copy necessary files
cp -r dist deploy/rs-waybill-mcp/
cp -r config deploy/rs-waybill-mcp/
cp package.json deploy/rs-waybill-mcp/
cp package-lock.json deploy/rs-waybill-mcp/
cp .env.example deploy/rs-waybill-mcp/
cp README.md deploy/rs-waybill-mcp/
cp -r docs deploy/rs-waybill-mcp/
# 4. Create installation script
cat > deploy/rs-waybill-mcp/install.sh << 'EOF'
#!/bin/bash
echo "Installing RS.ge Waybill MCP Server..."
npm install --production
echo "Installation complete!"
echo "Next steps:"
echo "1. Copy .env.example to .env"
echo "2. Edit .env with your credentials"
echo "3. Configure Claude Desktop"
EOF
chmod +x deploy/rs-waybill-mcp/install.sh
# 5. Create ZIP
cd deploy
zip -r rs-waybill-mcp.zip rs-waybill-mcp/
```
### Installation on New Computer
**Recipient steps:**
1. **Install Prerequisites:**
```bash
# Ensure Node.js 18+ is installed
node --version
```
2. **Extract Package:**
```bash
unzip rs-waybill-mcp.zip
cd rs-waybill-mcp
```
3. **Install Dependencies:**
```bash
# Mac/Linux
./install.sh
# Windows
npm install --production
```
4. **Configure Credentials:**
```bash
# Copy example
cp .env.example .env
# Edit with actual credentials
nano .env # or notepad .env on Windows
```
5. **Configure Claude Desktop:**
Edit `claude_desktop_config.json` with correct path.
6. **Restart Claude Desktop**
### Docker Deployment (Advanced)
**Create Dockerfile:**
```dockerfile
FROM node:18-alpine
WORKDIR /app
# Copy package files
COPY package*.json ./
# Install dependencies
RUN npm ci --production
# Copy built files
COPY dist ./dist
COPY config ./config
# Set environment
ENV NODE_ENV=production
# Run server
CMD ["node", "dist/index.js"]
```
**Build and run:**
```bash
# Build image
docker build -t rs-waybill-mcp .
# Run container
docker run -it \
-e RS_SERVICE_USER="4053098841:405309884" \
-e RS_SERVICE_PASSWORD="YourPassword" \
rs-waybill-mcp
```
---
## Troubleshooting
### Server Not Appearing in Claude
**Problem:** Server configured but Claude doesn't see tools.
**Solutions:**
1. **Check path is absolute:**
```json
// ❌ Wrong
"args": ["./dist/index.js"]
// ✅ Correct
"args": ["C:\\Users\\Boris\\Projects\\MCPWaybill\\dist\\index.js"]
```
2. **Verify file exists:**
```bash
# Does this file exist?
ls C:\Users\Boris\Projects\MCPWaybill\dist\index.js
```
3. **Check file is executable:**
```bash
# Mac/Linux
chmod +x dist/index.js
```
4. **Restart Claude properly:**
- Quit completely (not just close window)
- Wait 5 seconds
- Start again
5. **Check Claude logs:**
- Open Developer Tools
- Look for error messages
- Check for "MCP server running" message
### Server Crashes Immediately
**Problem:** Server starts then exits.
**Solutions:**
1. **Run manually to see error:**
```bash
node dist/index.js
# What error do you see?
```
2. **Check dependencies installed:**
```bash
npm install
```
3. **Rebuild:**
```bash
npm run build
```
4. **Check environment variables:**
```bash
# Print env vars
echo $RS_SERVICE_USER
# Or check .env file exists
ls -la .env
```
### Authentication Errors
**Problem:** "Authentication failed" or "Invalid credentials"
**Solutions:**
1. **Verify credentials in .env:**
```bash
cat .env
# Check user and password are correct
```
2. **Test credentials manually:**
Use Postman or similar to test RS.ge API
3. **Check credentials format:**
```bash
# Correct format:
RS_SERVICE_USER=username:company_id
RS_SERVICE_PASSWORD=password
# Example:
RS_SERVICE_USER=4053098841:405309884
```
4. **Ensure no extra spaces:**
```bash
# ❌ Wrong
RS_SERVICE_USER = 4053098841:405309884
# ✅ Correct
RS_SERVICE_USER=4053098841:405309884
```
### Tools Not Working
**Problem:** Server runs but tools fail when called.
**Solutions:**
1. **Check logs:**
```bash
# View log file
tail -f logs/mcp-server.log
```
2. **Test with simple date:**
```
User: Show me waybills from yesterday
```
3. **Check date format:**
- API requires YYYY-MM-DD format
- Claude usually gets this right
4. **Verify API is accessible:**
```bash
curl https://services.rs.ge/WayBillService/WayBillService.asmx
# Should return WSDL
```
### Performance Issues
**Problem:** Slow responses or timeouts.
**Solutions:**
1. **Increase timeout:**
```json
// config/config.json
{
"api": {
"timeout": 60000 // Increase to 60 seconds
}
}
```
2. **Reduce date range:**
```
// Instead of full month
User: Show waybills from Oct 1-31
// Use smaller ranges
User: Show waybills from Oct 1-3
```
3. **Check network connection:**
```bash
ping services.rs.ge
```
4. **Check API status:**
- RS.ge API might be slow or down
- Try again later
---
## Maintenance
### Updating Dependencies
```bash
# Check for updates
npm outdated
# Update all dependencies
npm update
# Update specific package
npm install axios@latest
# Rebuild after updates
npm run build
```
### Updating Credentials
**Method 1: Edit .env**
```bash
nano .env
# Change credentials
# Restart Claude Desktop
```
**Method 2: Edit Claude config**
```json
{
"mcpServers": {
"rs-waybill": {
"env": {
"RS_SERVICE_USER": "new_user",
"RS_SERVICE_PASSWORD": "new_password"
}
}
}
}
```
### Viewing Logs
**Real-time:**
```bash
tail -f logs/mcp-server.log
```
**Search logs:**
```bash
grep "error" logs/mcp-server.log
grep "waybills" logs/mcp-server.log
```
**Clean old logs:**
```bash
# Logs auto-rotate (7 days by default)
# Manual cleanup:
rm logs/mcp-server.log.*
```
### Backup Configuration
```bash
# Backup current setup
mkdir backup
cp .env backup/
cp config/config.json backup/
cp %APPDATA%\Claude\claude_desktop_config.json backup/
```
### Version Control
```bash
# Initialize git (if not already)
git init
# Add files (excluding secrets)
git add .
git commit -m "Initial commit"
# .gitignore already excludes:
# - .env (credentials)
# - logs/ (log files)
# - dist/ (compiled code)
# - node_modules/ (dependencies)
```
---
## Production Deployment Checklist
Before deploying to production:
- [ ] All tests pass
- [ ] Dependencies up to date
- [ ] Environment variables set correctly
- [ ] Logging configured appropriately
- [ ] Error handling tested
- [ ] Claude Desktop integration tested
- [ ] Backup of configuration made
- [ ] Documentation updated
- [ ] Security review completed
- [ ] Performance tested with real data
---
## Getting Help
### Resources
- **Project Documentation:** `docs/` folder
- **API Best Practices:** `docs/RS_GE_API_BEST_PRACTICES.md`
- **MCP Guide:** `docs/MCP_DEVELOPMENT_GUIDE.md`
### Common Commands Reference
```bash
# Development
npm install # Install dependencies
npm run build # Build TypeScript
npm run dev # Build and run
npm run watch # Watch mode
# Testing
node dist/index.js # Run manually
npm test # Run tests (if configured)
# Maintenance
npm outdated # Check for updates
npm update # Update dependencies
npm audit # Security audit
npm audit fix # Fix vulnerabilities
# Troubleshooting
rm -rf node_modules package-lock.json && npm install # Fresh install
npm run build # Rebuild
npm cache clean --force # Clear cache
```
---
**Last Updated:** 2025-01-XX
**Version:** 1.0.0
**Tested With:** Claude Desktop (Latest), Node.js 18+, Windows 10/11, macOS Ventura+