sap-b1-mcp-server/CLAUDE_DESKTOP_SETUP.md

SAP Business One Service Layer MCP Server

# 🚀 Claude Desktop Integration Guide
## SAP Business One MCP Server Setup

This guide will help you integrate your SAP B1 MCP Server with Claude Desktop to access SAP Business One directly from Claude conversations.

## 📋 Prerequisites

1. ✅ **Claude Desktop App** - Download from [claude.ai](https://claude.ai)
2. ✅ **Bun Runtime** - Already installed
3. ✅ **SAP B1 MCP Server** - Already built and ready
4. ✅ **SAP B1 Access** - Server credentials configured

## 🔧 Step 1: Configure MCP Server for STDIO Transport

Your `.env` file should have:
```env
# SAP Business One Configuration
SAP_B1_SERVER_URL=https://c21291hs01p01.cloudiax.com:50000
SAP_B1_DATABASE=UAT_CGC_UAT_18032025
SAP_B1_USERNAME=manager
SAP_B1_PASSWORD=B1@dmin11
SAP_B1_SESSION_TIMEOUT=30

# MCP Server Configuration - IMPORTANT: Use STDIO for Claude Desktop
MCP_TRANSPORT=stdio

# Logging Configuration
LOG_LEVEL=INFO
NODE_ENV=development
```

## 🖥️ Step 2: Configure Claude Desktop

### Find Claude Desktop Configuration File

**Location by OS:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

### Add SAP B1 MCP Server Configuration

Create or edit the `claude_desktop_config.json` file:

```json
{
  "mcpServers": {
    "sap-b1": {
      "command": "/Users/alexchabanenko/.bun/bin/bun",
      "args": ["start"],
      "cwd": "/Users/alexchabanenko/Projects/sap_mcp",
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

**⚠️ Important**: Use the **full path to bun** (`/Users/alexchabanenko/.bun/bin/bun`) instead of just `bun`. Claude Desktop doesn't have access to your shell's PATH environment.

**If you already have other MCP servers, add the SAP B1 configuration:**

```json
{
  "mcpServers": {
    "existing-server": {
      "command": "...",
      "args": ["..."]
    },
    "sap-b1": {
      "command": "bun",
      "args": ["start"],
      "cwd": "/Users/alexchabanenko/Projects/sap_mcp",
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

## 🚀 Step 3: Start Using SAP B1 Tools in Claude Desktop

### 1. Restart Claude Desktop
After saving the configuration, completely quit and restart Claude Desktop.

### 2. Verify Connection
In a new Claude conversation, you should see a 🔌 MCP connection indicator, or you can ask:

**"What MCP tools do you have access to?"**

Claude should list the SAP B1 tools including your new stock and price tools.

### 3. Available Tools (22 Total)

#### 🔑 **Authentication & Session Management (3 tools)**
- `sap_login` - Establish SAP B1 session
- `sap_logout` - Terminate session  
- `sap_session_status` - Check session status

#### 👥 **Master Data Operations (9 tools)**
- `sap_get_business_partners` - Get customers/vendors
- `sap_get_business_partner` - Get single business partner
- `sap_create_business_partner` - Create new business partner
- `sap_update_business_partner` - Update business partner
- `sap_get_items` - Get items/products
- `sap_get_item` - Get single item
- `sap_create_item` - Create new item
- `sap_get_warehouses` - Get warehouses
- `sap_get_pricelists` - Get price lists

#### 📄 **Document Operations (6 tools)**
- `sap_get_orders` - Get sales orders
- `sap_create_order` - Create sales order
- `sap_get_purchase_orders` - Get purchase orders
- `sap_create_purchase_order` - Create purchase order
- `sap_get_invoices` - Get invoices
- `sap_create_invoice` - Create invoice

#### 🔍 **Advanced Queries (2 tools)**
- `sap_query` - Custom OData queries
- `sap_cross_join` - Cross-entity queries

#### 📊 **Stock & Pricing Tools (4 NEW tools)**
- `sap_get_item_stock` - Get stock for item in specific warehouse
- `sap_get_item_stock_all` - Get stock for item in all warehouses
- `sap_get_item_price` - Get price for item in specific price list
- `sap_get_item_prices_all` - Get prices for item in all price lists

## 💬 Step 4: Example Conversations

### Stock Level Inquiries
**You**: "What's the stock level for item 10001 in warehouse 01?"

**Claude**: *Uses `sap_get_item_stock` and shows current stock levels*

### Price Inquiries  
**You**: "What are all the prices for item 10001 across different price lists?"

**Claude**: *Uses `sap_get_item_prices_all` and shows pricing matrix*

### Business Partner Lookup
**You**: "Find all customers with 'Tech' in their name"

**Claude**: *Uses `sap_get_business_partners` with filtering*

### Create Sales Orders
**You**: "Create a sales order for customer C20000 with item SERVICE-01"

**Claude**: *Uses `sap_create_order` to create the document*

## 🔧 Troubleshooting

### Issue 1: "spawn bun ENOENT" Error in Logs
**Problem**: Claude Desktop can't find the `bun` command (most common issue)
**Solution**: 
1. Find your bun path: `which bun` (usually `/Users/[username]/.bun/bin/bun`)
2. Use the **full path** in your config: `"command": "/Users/alexchabanenko/.bun/bin/bun"`
3. **Never use just** `"command": "bun"` - Claude Desktop doesn't have your shell's PATH
4. Restart Claude Desktop after fixing the config

### Issue 2: Claude Desktop Doesn't Show MCP Tools
**Solution**: 
1. Check the configuration file path and syntax
2. Ensure the `cwd` path is correct: `/Users/alexchabanenko/Projects/sap_mcp`
3. Restart Claude Desktop completely
4. Check Claude Desktop logs: `~/Library/Logs/Claude/mcp-server-sap-b1.log`

### Issue 2: SAP Connection Fails
**Solution**:
1. Verify SAP credentials in `.env` file
2. Check SAP server accessibility
3. Test with: `bun start` in terminal to see error messages

### Issue 3: Permission Issues
**Solution**:
1. Ensure Bun is in PATH: `which bun`
2. Check file permissions: `chmod +x /Users/alexchabanenko/Projects/sap_mcp/dist/index.js`

### Issue 4: Tools Not Working
**Solution**:
1. Check SAP session: Ask Claude to use `sap_session_status`
2. Login if needed: Ask Claude to use `sap_login`
3. Check server logs for detailed errors

## 🎯 Testing Your Setup

### Quick Test Commands for Claude:

1. **Test Connection**: "Check my SAP session status"
2. **Test Stock Tool**: "Get stock levels for item 10001 in warehouse 01"  
3. **Test Price Tool**: "Get all prices for item 10001"
4. **Test Business Partners**: "Get first 5 customers"
5. **Test Items**: "Get first 5 inventory items"

## 📊 Performance Notes

- **Session Management**: Automatic session renewal every 25 minutes
- **Rate Limits**: SAP B1 limit of ~20 records per query (pagination supported)
- **Caching**: Sessions are cached and reused efficiently
- **Error Handling**: Graceful fallbacks and detailed error messages

## 🔒 Security Notes

- **Credentials**: Stored in local `.env` file only
- **Session**: Automatic logout on server shutdown
- **Logs**: Passwords are masked in all log output
- **Access**: Only local Claude Desktop can access via STDIO

---

## 📝 Configuration Template

Save this as your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sap-b1": {
      "command": "/Users/alexchabanenko/.bun/bin/bun",
      "args": ["start"],
      "cwd": "/Users/alexchabanenko/Projects/sap_mcp",
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

**⚠️ Important**: Use the **full path to bun** (`/Users/alexchabanenko/.bun/bin/bun`) instead of just `bun`. Claude Desktop doesn't have access to your shell's PATH environment.

**🎉 You're Ready!** Start Claude Desktop and begin managing your SAP Business One data through natural conversation!