invoice-rpa-mcp 0.2.0
MCP server for invoice automation — extracts, maps, and outputs standardized invoices from Excel files
License: MIT
Requires Python: >=3.10
Keywords: automation, invoice, mcp, model-context-protocol, rpa

# Invoice RPA MCP Server

[![PyPI](https://img.shields.io/pypi/v/invoice-rpa-mcp)](https://pypi.org/project/invoice-rpa-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/invoice-rpa-mcp)](https://pypi.org/project/invoice-rpa-mcp/)

Excel 인보이스 파일에서 데이터를 자동 추출하여 표준 출력 템플릿으로 매핑하는 MCP 서버입니다. Claude Desktop, Claude Code, Cursor 등 AI 에이전트에서 인보이스 처리를 호출할 수 있습니다.

## Quick Start

### 요구사항

- Python 3.10+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) 패키지 매니저

### mcp.json 등록

AI 클라이언트 설정에 아래를 추가하면 자동으로 다운로드+실행됩니다:

```json
{
  "mcpServers": {
    "invoice-rpa": {
      "command": "uvx",
      "args": ["invoice-rpa-mcp"],
      "env": {
        "INVOICE_INPUT_FOLDER": "/path/to/input",
        "INVOICE_OUTPUT_FOLDER": "/path/to/output",
        "INVOICE_CUSTOMER_MASTER_PATH": "/path/to/customer_master.csv",
        "INVOICE_ITEM_LIST_PATH": "/path/to/itemList.csv"
      }
    }
  }
}
```

> `env`의 4개 경로를 실제 환경에 맞게 수정하세요. Windows에서는 슬래시(`/`)를 사용합니다: `"C:/Invoice/input"`

### 설정 파일 위치

| 클라이언트 | 파일 위치 |
|-----------|----------|
| **Claude Desktop** (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Claude Desktop** (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Claude Code** | 프로젝트 루트 `.mcp.json` 또는 `claude mcp add` CLI |
| **Cursor** | 프로젝트 루트 `.cursor/mcp.json` |

Claude Code CLI로 추가하는 경우:

```bash
claude mcp add invoice-rpa -- uvx invoice-rpa-mcp
```

## Available Tools

| Tool | 설명 | 파라미터 |
|------|------|----------|
| `process_all_invoices` | input 폴더의 모든 인보이스 일괄 처리 | — |
| `process_single_invoice` | 특정 파일 1개 처리 | `filename` (str) |
| `list_input_files` | 처리 대상 파일 목록 및 크기 조회 | — |
| `get_server_config` | 현재 서버 설정 및 로드된 데이터 건수 조회 | — |

## Environment Variables

모든 환경변수는 `INVOICE_` 접두사를 사용합니다.

| 환경변수 | 필수 (uvx) | 기본값 | 설명 |
|----------|-----------|--------|------|
| `INVOICE_INPUT_FOLDER` | **필수** | `./input` | 입력 파일 디렉토리 |
| `INVOICE_OUTPUT_FOLDER` | **필수** | `./output` | 출력 파일 디렉토리 |
| `INVOICE_CUSTOMER_MASTER_PATH` | **필수** | `./variation_data/customer_master.csv` | 고객 마스터 CSV |
| `INVOICE_ITEM_LIST_PATH` | **필수** | `./variation_data/itemList.csv` | 아이템 리스트 CSV |
| `INVOICE_MCP_TRANSPORT` | 선택 | `stdio` | Transport: `stdio`, `streamable-http`, `sse` |
| `INVOICE_MCP_HOST` | 선택 | `0.0.0.0` | HTTP/SSE 바인딩 호스트 |
| `INVOICE_MCP_PORT` | 선택 | `8000` | HTTP/SSE 포트 |

> `uvx`는 격리 환경에서 실행되므로 기본 경로가 의미 없습니다. 4개 경로는 반드시 설정하세요. 로컬 개발(`uv run --directory`)에서는 프로젝트 기본 경로가 동작하므로 생략 가능합니다.

## Transport 모드별 설정

### 1. stdio (권장)

AI 클라이언트가 로컬에서 프로세스를 직접 실행합니다.

**uvx (권장)** — 소스코드 불필요, PyPI에서 자동 다운로드:

```json
{
  "mcpServers": {
    "invoice-rpa": {
      "command": "uvx",
      "args": ["invoice-rpa-mcp"],
      "env": {
        "INVOICE_INPUT_FOLDER": "/path/to/input",
        "INVOICE_OUTPUT_FOLDER": "/path/to/output",
        "INVOICE_CUSTOMER_MASTER_PATH": "/path/to/customer_master.csv",
        "INVOICE_ITEM_LIST_PATH": "/path/to/itemList.csv"
      }
    }
  }
}
```

**uv run** — 소스코드를 클론한 로컬 개발 환경:

```json
{
  "mcpServers": {
    "invoice-rpa": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/invoice_rpa",
        "invoice-rpa-mcp"
      ]
    }
  }
}
```

> `--directory`로 프로젝트 루트를 지정하면 기본 경로(`./input` 등)가 동작하므로 `env`를 생략할 수 있습니다. 커스텀 경로가 필요하면 `env` 블록을 추가하세요.

### 2. Streamable HTTP (원격)

서버에서 HTTP로 호스팅하고 네트워크를 통해 접속합니다. **경로 설정은 서버 측에서 관리**합니다.

**서버 실행:**

```bash
INVOICE_MCP_TRANSPORT=streamable-http \
INVOICE_INPUT_FOLDER=/path/to/input \
INVOICE_OUTPUT_FOLDER=/path/to/output \
INVOICE_CUSTOMER_MASTER_PATH=/path/to/customer_master.csv \
INVOICE_ITEM_LIST_PATH=/path/to/itemList.csv \
uvx invoice-rpa-mcp
```

**클라이언트 mcp.json:**

```json
{
  "mcpServers": {
    "invoice-rpa": {
      "type": "streamable-http",
      "url": "http://서버IP:8000/mcp"
    }
  }
}
```

### 3. SSE (레거시 원격)

Streamable HTTP를 지원하지 않는 클라이언트용입니다. endpoint가 `/sse`인 것 외에는 동일합니다.

**서버 실행:**

```bash
INVOICE_MCP_TRANSPORT=sse \
INVOICE_INPUT_FOLDER=/path/to/input \
INVOICE_OUTPUT_FOLDER=/path/to/output \
INVOICE_CUSTOMER_MASTER_PATH=/path/to/customer_master.csv \
INVOICE_ITEM_LIST_PATH=/path/to/itemList.csv \
uvx invoice-rpa-mcp
```

**클라이언트 mcp.json:**

```json
{
  "mcpServers": {
    "invoice-rpa": {
      "type": "sse",
      "url": "http://서버IP:8000/sse"
    }
  }
}
```

## 동작 확인

```bash
# MCP Inspector로 테스트 (브라우저에서 tool 목록 확인 및 호출)
npx @modelcontextprotocol/inspector uvx invoice-rpa-mcp
```

## 입력 파일 형식

파일명 패턴:
```
Contract No.DRBVN XXXXX (DD-MM-YYYY) 고객명-위치.xlsx
```

예시:
```
Contract No.DRBVN 12345 (15-01-2024) KUBOTA-OSK, JAPAN.xlsx
```

### 지원 고객

- **미국**: Caterpillar, Bobcat MHE/MT/CTL, GPM, YCENA, JohnDeere
- **일본**: Kubota, Yanmar, Takeuchi, CJL, Hitachi, Komatsu
- **인도**: Caterpillar India, JCB India, Bobcat India
- **유럽**: VolvoFrance, Bobcat CZ, YanmarFrance

## 개발

```bash
# 클론 및 설치
git clone https://github.com/your-repo/invoice_rpa.git
cd invoice_rpa
uv sync

# 로컬 실행
uv run invoice-rpa-mcp

# Standalone 배치 처리
uv run python invoice_rpa_mcp/main.py

# MCP Inspector 테스트
npx @modelcontextprotocol/inspector uv run invoice-rpa-mcp
```

### 프로젝트 구조

```
invoice_rpa/
├── invoice_rpa_mcp/            # Python 패키지
│   ├── mcp_server.py           # MCP 서버 진입점
│   ├── main.py                 # Standalone 배치 진입점
│   ├── invoice_processor.py    # 처리 오케스트레이션
│   ├── data_extractor.py       # 데이터 추출
│   ├── mapper.py               # 데이터 매핑
│   ├── customer_identifier.py  # 고객 식별
│   ├── template_selector.py    # 템플릿 선택
│   ├── sequence_manager.py     # 인보이스 번호 시퀀싱
│   └── utils/                  # 유틸리티
├── config/                     # JSON 설정 파일 (패키지에 포함)
├── templates/                  # Excel 출력 템플릿 (패키지에 포함)
├── variation_data/             # 사용자 CSV 데이터
│   ├── customer_master.csv     # 고객 마스터
│   └── itemList.csv            # 제품 카탈로그
├── input/                      # 입력 파일 디렉토리
└── output/                     # 출력 파일 디렉토리
```

### 신규 고객 추가

1. `config/customer_patterns.json`에 별칭 추가
2. `config/customer_types.json`의 해당 지역에 추가
3. `variation_data/customer_master.csv`에 행 추가
4. `variation_data/itemList.csv`에 제품 항목 추가

## License

MIT