# ECOUNT MCP Server

[English](README.md) | [한국어](README_KO.md)

A Model Context Protocol (MCP) server for [ECOUNT ERP](https://www.ecount.com/) OpenAPI integration.

[![npm version](https://badge.fury.io/js/mcp-server-ecount.svg)](https://www.npmjs.com/package/mcp-server-ecount)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

This MCP server enables AI assistants like Claude to interact with ECOUNT ERP through natural language. It wraps ECOUNT's OpenAPI with proper session management, rate limiting, and caching.

### Features

- **22 Tools** - Products, customers, inventory, sales, purchases, production, accounting, e-commerce, attendance, bulletin board
- **Automatic Session Management** - Zone caching, session auto-renewal on expiry, file-based persistence
- **Smart Throttling** - Automatic rate limit management with intelligent waiting (no manual retry needed)
- **Multi-Process Support** - File-based rate limit state sharing across multiple instances
- **Response Caching** - 10-minute cache for query results
- **Error Handling** - Continuous error monitoring with user-friendly messages

## Quick Start

### Prerequisites

- **ECOUNT ERP Account** with Master ID privileges
- **API Certificate Key** ([How to get one](#api-certificate-key))
- **Node.js 18+**

### Installation

#### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ecount": {
      "command": "npx",
      "args": ["-y", "mcp-server-ecount"],
      "env": {
        "ECOUNT_COM_CODE": "your_company_code",
        "ECOUNT_USER_ID": "your_user_id",
        "ECOUNT_API_CERT_KEY": "your_api_key"
      }
    }
  }
}
```

#### Claude Code

```bash
claude mcp add mcp-server-ecount -e ECOUNT_COM_CODE=회사코드 -e ECOUNT_USER_ID=사용자ID -e ECOUNT_API_CERT_KEY=인증키
```

Or add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "ecount": {
      "command": "npx",
      "args": ["-y", "mcp-server-ecount"],
      "env": {
        "ECOUNT_COM_CODE": "your_company_code",
        "ECOUNT_USER_ID": "your_user_id",
        "ECOUNT_API_CERT_KEY": "your_api_key"
      }
    }
  }
}
```

## Tools

### Connection & Status

| Tool                      | Description                                             |
| ------------------------- | ------------------------------------------------------- |
| `ecount_test_connection`  | Test API connection                                     |
| `ecount_get_session_info` | Get current session status                              |
| `ecount_server_status`    | Get server internal status (rate limits, cache, errors) |

### Products

| Tool                    | Description                | Rate Limit |
| ----------------------- | -------------------------- | ---------- |
| `ecount_get_product`    | Get single product details | 1s         |
| `ecount_get_products`   | Get multiple products      | 10min      |
| `ecount_create_product` | Create new products        | 10s        |

### Customers

| Tool                     | Description          | Rate Limit |
| ------------------------ | -------------------- | ---------- |
| `ecount_create_customer` | Create new customers | 10s        |

### Inventory

| Tool                                     | Description                              | Rate Limit |
| ---------------------------------------- | ---------------------------------------- | ---------- |
| `ecount_get_inventory`                   | Get inventory for single product         | 1s         |
| `ecount_get_inventory_list`              | Get inventory for multiple products      | 10min      |
| `ecount_get_inventory_by_warehouse`      | Get warehouse-level inventory (single)   | 1s         |
| `ecount_get_inventory_by_warehouse_list` | Get warehouse-level inventory (multiple) | 10min      |

### Sales

| Tool                       | Description        | Rate Limit |
| -------------------------- | ------------------ | ---------- |
| `ecount_create_quotation`  | Create quotation   | 10s        |
| `ecount_create_sale_order` | Create sales order | 10s        |
| `ecount_create_sale`       | Create sales slip  | 10s        |

### Purchases

| Tool                         | Description          | Rate Limit |
| ---------------------------- | -------------------- | ---------- |
| `ecount_get_purchase_orders` | Get purchase orders  | 10min      |
| `ecount_create_purchase`     | Create purchase slip | 10s        |

### Production

| Tool                          | Description               | Rate Limit |
| ----------------------------- | ------------------------- | ---------- |
| `ecount_create_job_order`     | Create job order          | 10s        |
| `ecount_create_goods_issued`  | Create goods issued slip  | 10s        |
| `ecount_create_goods_receipt` | Create goods receipt slip | 10s        |

### Accounting

| Tool                    | Description                                  | Rate Limit |
| ----------------------- | -------------------------------------------- | ---------- |
| `ecount_create_invoice` | Create sales/purchase invoice (auto journal) | 10s        |

### E-Commerce

| Tool                             | Description                            | Rate Limit |
| -------------------------------- | -------------------------------------- | ---------- |
| `ecount_create_openmarket_order` | Import orders from online marketplaces | 10s        |

### Attendance

| Tool                         | Description       | Rate Limit |
| ---------------------------- | ----------------- | ---------- |
| `ecount_create_clock_in_out` | Record attendance | 10s        |

### Bulletin Board

| Tool                       | Description       | Rate Limit |
| -------------------------- | ----------------- | ---------- |
| `ecount_create_board_post` | Create board post | 10s        |

## Configuration

### Environment Variables

| Variable                 | Required | Description                                     |
| ------------------------ | -------- | ----------------------------------------------- |
| `ECOUNT_COM_CODE`        | Yes      | ECOUNT company code (6 digits)                  |
| `ECOUNT_USER_ID`         | Yes      | ECOUNT user ID (must be Master ID)              |
| `ECOUNT_API_CERT_KEY`    | Yes      | API certificate key                             |
| `ECOUNT_USE_TEST_SERVER` | No       | Use test server (`true`)                        |
| `ECOUNT_SESSION_FILE`    | No       | Session file path for persistence               |
| `ECOUNT_RATE_LIMIT_FILE` | No       | Rate limit state file for multi-process support |
| `DEBUG`                  | No       | Enable debug logging (`true`)                   |

### API Certificate Key

1. Login to ECOUNT ERP with **Master ID**
2. Navigate to `Self-Customizing` > `External Connection Settings` > `Open API Management`
3. Apply for API usage and get certificate key
4. Start with test key for development, then get production key after verification

> **Note**: Only Master ID can issue API certificate keys.

## Rate Limits

ECOUNT OpenAPI has strict rate limits:

| API Type     | Production | Test Server |
| ------------ | ---------- | ----------- |
| Zone/Login   | 10min      | 10s         |
| Batch Query  | 10min      | 10s         |
| Single Query | 1s         | 1s          |
| Save         | 10s        | 10s         |

### Additional Limits

- Consecutive errors per hour: **30** (blocked if exceeded)
- Daily API calls: **5,000**
- Max items per save: **300**

### Smart Throttling

This MCP server features intelligent rate limit management:

| API Type            | Auto-Wait | Max Wait |
| ------------------- | --------- | -------- |
| Single Query (1s)   | ✅ Yes    | 5s       |
| Save (10s)          | ✅ Yes    | 15s      |
| Batch Query (10min) | ❌ No     | Error    |
| Zone/Login (10min)  | ❌ No     | Error    |

- **Auto-Wait**: For short intervals (1s, 10s), the server automatically waits before retrying
- **Multi-Process Safe**: When `ECOUNT_RATE_LIMIT_FILE` is set, rate limit state is shared across all instances
- **100ms Safety Margin**: All intervals include a safety margin to prevent edge-case failures

When rate limits are exceeded beyond auto-wait thresholds, friendly error messages are returned with remaining wait time.

## Security

**Never hardcode API credentials!**

```bash
# Create .env file for development
ECOUNT_COM_CODE=your_code
ECOUNT_USER_ID=your_id
ECOUNT_API_CERT_KEY=your_key

# Add to .gitignore
echo ".env" >> .gitignore
```

> **Warning**: Leaked ECOUNT credentials can compromise your entire ERP system.

## Development

```bash
# Clone repository
git clone https://github.com/gilbreth-ai/mcp-server-ecount.git
cd mcp-server-ecount

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

# Test with MCP Inspector
npm run inspect
```

### Project Structure

```
mcp-server-ecount/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server setup
│   ├── client/
│   │   ├── ecount-client.ts  # API client
│   │   ├── session-manager.ts
│   │   ├── rate-limiter.ts
│   │   ├── cache.ts
│   │   └── error-counter.ts
│   ├── tools/
│   │   ├── register.ts       # Tool registration
│   │   └── schemas.ts        # Zod schemas
│   ├── types/
│   └── utils/
├── docs/                     # API documentation
├── package.json
└── README.md
```

## Usage Examples

### Check Inventory

```
User: "What's the inventory for product A001 across all warehouses?"

Claude uses ecount_get_inventory_by_warehouse tool.

Result:
- Main Warehouse: 100 units
- Distribution Center: 50 units
- Store: 25 units
Total: 175 units
```

### Create Sales Slip

```
User: "Create a sale for customer C001, product A001, 10 units at 1000 won each"

Claude uses ecount_create_sale tool.

Result:
- Slip No: 20240115-1
- Success: 1 item
```

### Low Stock Alert & Purchase Decision Support

```
User: "Show me items with less than 5 units in stock,
       with their recent purchase prices, and suggest order quantities"

Claude uses ecount_get_inventory_list, ecount_get_products tools.

Result:
- Product A: Stock 3, Last price 5,000 KRW → Suggest order: 20 units
- Product B: Stock 2, Last price 12,000 KRW → Suggest order: 15 units
- Product C: Stock 1, Last price 8,000 KRW → Suggest order: 25 units
Total estimated cost: 456,000 KRW
```

### Natural Language Customer Registration

```
User: "Register new customer: ABC Corp, Business No. 123-45-67890,
       CEO: John Doe, Address: 123 Main St, Seoul"

Claude uses ecount_create_customer tool.

Result:
- Customer Code: C0042 (auto-generated)
- Registration complete
```

### Post Analysis to ERP Bulletin Board

```
User: "Summarize our sales trend analysis and post it to the company bulletin board"

Claude uses ecount_create_board_post tool.

Result:
- Board: Announcements
- Title: [Analysis] H1 Sales Trend Summary
- Posted successfully
```

## Troubleshooting

### "Item not found" error when saving

You need to configure "Web Data Upload" in ECOUNT ERP:

1. Go to the input menu (e.g., Sales > Sales Input)
2. Click "Web Data Upload" button at the bottom
3. Add required fields with "Add Upload Items"

### Session expires frequently

Increase auto-logout time in ERP settings:

- `ERP Settings` > `Security Settings` > `Auto Logout Time`

### Rate limit exceeded

Wait for the cooldown period. Use `ecount_server_status` to check current rate limit status.

## Disclaimer

This is a community project with no official affiliation to ECOUNT.
Using ECOUNT OpenAPI requires a valid ECOUNT account and API certificate key.
All API usage is subject to ECOUNT's terms of service.

## License

MIT

## Contributing

Bug reports, feature requests, and PRs are welcome!

- [Issues](https://github.com/gilbreth-ai/mcp-server-ecount/issues)
- [Pull Requests](https://github.com/gilbreth-ai/mcp-server-ecount/pulls)