Metadata-Version: 2.4
Name: invoice-rpa-mcp
Version: 0.1.0
Summary: MCP server for invoice automation — extracts, maps, and outputs standardized invoices from Excel files
License: MIT
Keywords: automation,invoice,mcp,model-context-protocol,rpa
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: openpyxl>=3.1.2
Requires-Dist: pillow>=10.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# 인보이스 자동화 RPA 시스템

Excel 파일에서 데이터를 자동으로 추출하여 표준화된 출력 템플릿으로 매핑하는 지능형 인보이스 처리 시스템입니다. 다양한 고객 유형과 레이아웃을 지원합니다.

## 🚀 주요 기능

### 핵심 기능
- **동적 셀 참조 매핑**: 하드코딩된 셀 위치 없이 설정으로 관리
- **유연한 시트 감지**: 별칭과 대체 전략을 통한 지능형 시트 이름 매칭
- **고객 유형 지원**: 미국, 일본, 인도, 유럽 고객을 위한 다양한 템플릿
- **자동 번호 생성**: 고객별 패턴에 따른 스마트 인보이스 번호 시퀀싱
- **중복 방지**: 내장된 중복 확인 및 처리 추적

### 고급 기능
- **테이블 구조 분석**: 자동 헤더 감지 및 컬럼 매핑
- **행 조정**: 데이터 양에 따른 동적 행 삽입/삭제
- **수식 적용**: 자동 SUM 및 계산 수식
- **통화 처리**: 통화 코드가 포함된 자동 헤더 업데이트
- **오류 복구**: 상세 로깅을 통한 강력한 오류 처리

## 📁 프로젝트 구조

```
invoice_rpa/
├── config/                     # 설정 파일
│   ├── cell_references.json    # 동적 셀 참조 매핑
│   ├── search_config.json      # 검색 범위 및 파라미터
│   ├── sheet_config.json      # 시트 이름 매핑 및 별칭
│   ├── customer_patterns.json  # 고객 식별 패턴
│   ├── customer_types.json     # 고객 유형 분류
│   └── mapping_config.json     # 필드 매핑 규칙
├── invoice_rpa_mcp/            # 소스 코드 (패키지)
│   ├── utils/                  # 유틸리티 클래스
│   │   ├── excel_operations.py # 통합 Excel 작업
│   │   ├── header_detector.py  # 헤더 감지 유틸리티
│   │   ├── table_mapper.py     # 테이블 매핑 작업
│   │   ├── excel_helper.py     # Excel 헬퍼 함수
│   │   └── logger.py           # 로깅 유틸리티
│   ├── config_loader.py        # 설정 관리
│   ├── data_loader.py          # CSV 데이터 로딩
│   ├── data_extractor.py       # Excel에서 데이터 추출
│   ├── mapper.py              # 템플릿으로 데이터 매핑
│   ├── invoice_processor.py   # 메인 처리 오케스트레이션
│   ├── customer_identifier.py  # 고객 식별
│   ├── template_selector.py    # 템플릿 선택 로직
│   ├── duplicate_checker.py    # 중복 감지
│   ├── sequence_manager.py    # 인보이스 시퀀싱
│   ├── filename_normalizer.py # 파일명 정규화
│   └── detail_pl_handler.py   # 상세 P/L 처리
├── variation_data/            # 변수 데이터
│   ├── customer_master.csv    # 고객 마스터 데이터
│   ├── itemList.csv           # 제품 카탈로그
│   └── process_config.json    # 처리 설정
├── templates/                  # Excel 템플릿
│   ├── OUTPUT_BLANKFILE_V2.xlsx  # 표준 템플릿
│   └── OUTPUT_BLANKFILE_US_V2.2.xlsx # 미국 전용 템플릿
├── input/                     # 입력 파일 디렉토리
├── output/                    # 출력 파일 디렉토리
└── logs/                      # 로그 파일 디렉토리
```

## ⚙️ 설정

### 경로 설정 (`variation_data/process_config.json`)

Standalone 실행(`invoice_rpa_mcp/main.py`)에서 사용하는 경로 설정입니다. 미설정 항목은 프로젝트 기본 경로를 사용합니다.

**macOS / Linux:**
```json
{
  "input_folder": "/Users/drb/invoice/input",
  "output_folder": "/Users/drb/invoice/output",
  "customer_master_path": "/Users/drb/invoice/customer_master.csv",
  "item_list_path": "/Users/drb/invoice/itemList.csv"
}
```

**Windows:**
```json
{
  "input_folder": "C:/Users/drb/invoice/input",
  "output_folder": "C:/Users/drb/invoice/output",
  "customer_master_path": "C:/Users/drb/invoice/customer_master.csv",
  "item_list_path": "C:/Users/drb/invoice/itemList.csv"
}
```

> **Windows 경로 주의사항**: JSON에서 백슬래시(`\`)는 이스케이프 문자입니다. Windows 경로를 입력할 때 **슬래시(`/`)를 사용**하세요. `C:\Users\drb` → `"C:/Users/drb"`. 백슬래시를 사용하려면 이중으로 입력해야 합니다: `"C:\\Users\\drb"`. 이 규칙은 `process_config.json`, `mcp.json`, `claude_desktop_config.json` 등 모든 JSON 설정 파일에 동일하게 적용됩니다.

### 고객 유형 설정 (`config/customer_types.json`)
고객 유형별 템플릿과 행 위치를 정의합니다.

### 매핑 설정 (`config/mapping_config.json`)
필드 매핑 규칙을 설정합니다.

## 🏃‍♂️ 사용법

### 사전 요구사항
- Python 3.13+
- 필수 패키지 (`uv`로 설치):

```bash
uv sync
```

### 실행 방법

두 가지 실행 방식을 지원합니다:

| 방식 | 명령어 | 용도 |
|------|--------|------|
| **Standalone** | `uv run python invoice_rpa_mcp/main.py` | 일괄 배치 처리 |
| **MCP 서버** | `uv run invoice-rpa-mcp` | AI 에이전트 연동 |

#### Standalone 실행

1. Excel 파일을 `input/` 디렉토리에 넣으세요
2. 스크립트 실행:
```bash
uv run python invoice_rpa_mcp/main.py
```
3. 처리된 파일이 `output/` 디렉토리에 나타납니다

#### MCP 서버 실행

아래 [MCP 서버](#-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

## 🔧 아키텍처

### 핵심 컴포넌트

#### 1. **InvoiceProcessor** (`invoice_rpa_mcp/invoice_processor.py`)
전체 처리 워크플로우를 조율하는 메인 오케스트레이터:
- 고객 식별
- 템플릿 선택
- 데이터 추출
- 매핑 및 출력 생성

#### 2. **DataExtractor** (`invoice_rpa_mcp/data_extractor.py`)
동적 설정으로 입력 Excel 파일에서 데이터 추출:
- 인보이스 메타데이터 (번호, 날짜, 당사자)
- 운송 정보
- 자동 테이블 감지가 포함된 라인 아이템

#### 3. **Mapper** (`invoice_rpa_mcp/mapper.py`)
추출된 데이터를 출력 템플릿으로 매핑:
- 필드 수준 매핑
- 테이블 구조 적응
- 수식 적용

#### 4. **유틸리티 클래스**

**ExcelOperations** (`invoice_rpa_mcp/utils/excel_operations.py`)
- 통합 Excel 파일 작업
- 별칭이 있는 시트 찾기
- 대체가 포함된 셀 값 추출
- 수식 적용

**HeaderDetector** (`invoice_rpa_mcp/utils/header_detector.py`)
- 동적 헤더 감지
- 컬럼 매핑 추론
- 테이블 구조 분석

**TableMapper** (`invoice_rpa_mcp/utils/table_mapper.py`)
- 테이블 행 조정
- 데이터 매핑 작업
- 합계 행 처리

### 처리 흐름

1. **파일 발견**: 입력 디렉토리에서 Excel 파일 스캔
2. **고객 식별**: 파일명에서 고객 추출
3. **템플릿 선택**: 고객 유형에 따라 적절한 템플릿 선택
4. **데이터 추출**: 메타데이터, 운송 정보 및 아이템 추출
5. **데이터 매핑**: 추출된 데이터를 템플릿 필드로 매핑
6. **행 조정**: 아이템 수에 따라 테이블 행 조정
7. **출력 생성**: 정규화된 파일명으로 처리된 파일 저장
8. **중복 트래킹**: 파일을 처리된 것으로 표시

## 🌐 MCP 서버

MCP(Model Context Protocol) 서버를 통해 Claude Desktop, Claude Code, Cursor 등 AI 에이전트에서 인보이스 처리 기능을 호출할 수 있습니다.

### Transport 모드

| 모드 | 프로토콜 | 용도 | mcp.json 키 |
|------|----------|------|-------------|
| **stdio** (기본) | 표준 입출력 | 로컬에서 AI 클라이언트가 프로세스 직접 실행 | `command` + `args` |
| **streamable-http** | HTTP | 원격 서버 호스팅, 네트워크 접속 | `url` (endpoint: `/mcp`) |
| **sse** | Server-Sent Events | streamable-http 미지원 클라이언트용 레거시 | `url` (endpoint: `/sse`) |

### 환경변수

모든 환경변수는 선택사항이며, 미설정 시 프로젝트 디렉토리 기준 기본값을 사용합니다.

| 환경변수 | 기본값 | 설명 |
|----------|--------|------|
| `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 포트 |

> `env` 블록에는 변경이 필요한 항목만 선택적으로 설정하세요. `uvx`로 실행할 경우 프로젝트 디렉토리가 없으므로 4개 경로 환경변수는 **필수**입니다.

### 제공 Tool

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

---

### 1. stdio 모드 — `uv run` (로컬 개발)

프로젝트 소스를 클론한 로컬 환경에서 사용합니다. `--directory`로 프로젝트 루트를 지정하면 기본 경로가 동작하므로 `env`는 커스텀 경로가 필요한 경우에만 설정합니다.

#### Claude Desktop (`claude_desktop_config.json`)

설정 파일 위치:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

**macOS / Linux:**
```json
{
  "mcpServers": {
    "invoice-rpa": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/Users/username/workspace/invoice_rpa",
        "invoice-rpa-mcp"
      ],
      "env": {
        "INVOICE_INPUT_FOLDER": "/Users/username/invoice/input",
        "INVOICE_OUTPUT_FOLDER": "/Users/username/invoice/output",
        "INVOICE_CUSTOMER_MASTER_PATH": "/Users/username/invoice/customer_master.csv",
        "INVOICE_ITEM_LIST_PATH": "/Users/username/invoice/itemList.csv"
      }
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "invoice-rpa": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "C:/Projects/invoice_rpa",
        "invoice-rpa-mcp"
      ],
      "env": {
        "INVOICE_INPUT_FOLDER": "C:/Invoice/input",
        "INVOICE_OUTPUT_FOLDER": "C:/Invoice/output",
        "INVOICE_CUSTOMER_MASTER_PATH": "C:/Invoice/customer_master.csv",
        "INVOICE_ITEM_LIST_PATH": "C:/Invoice/itemList.csv"
      }
    }
  }
}
```

#### Claude Code (`.mcp.json`)

프로젝트 루트에 `.mcp.json` 파일을 생성하거나 CLI로 추가합니다:

```json
{
  "mcpServers": {
    "invoice-rpa": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/Users/username/workspace/invoice_rpa",
        "invoice-rpa-mcp"
      ],
      "env": {
        "INVOICE_INPUT_FOLDER": "/Users/username/invoice/input",
        "INVOICE_OUTPUT_FOLDER": "/Users/username/invoice/output",
        "INVOICE_CUSTOMER_MASTER_PATH": "/Users/username/invoice/customer_master.csv",
        "INVOICE_ITEM_LIST_PATH": "/Users/username/invoice/itemList.csv"
      }
    }
  }
}
```

```bash
claude mcp add invoice-rpa -- uv run --directory /path/to/invoice_rpa invoice-rpa-mcp
```

> **`--directory`**: 프로젝트 루트의 **절대 경로**. 기본 경로(`./input`, `./output` 등)를 사용하면 `env` 블록 전체를 생략할 수 있습니다. **Windows**: JSON 경로에 슬래시(`/`)를 사용하세요.

---

### 2. stdio 모드 — `uvx` (PyPI 배포 후)

PyPI에 배포된 패키지를 `uvx`로 설치 없이 바로 실행합니다. 프로젝트 소스가 불필요하며 `config/`와 `templates/`는 패키지에 포함되어 있습니다. 단, 사용자 데이터 경로(`input`, `output`, `customer_master`, `itemList`)는 프로젝트 디렉토리가 없으므로 **4개 경로 환경변수가 필수**입니다.

#### Claude Desktop (`claude_desktop_config.json`)

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

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

#### Claude Code (`.mcp.json`)

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

> `uvx`는 `uv tool run`의 단축 명령으로, 패키지를 격리 환경에서 자동 설치+실행합니다. PyPI 배포 전에는 사용할 수 없습니다. 배포: `uv build && uv publish`

---

### 3. Streamable HTTP 모드 (원격)

서버 컴퓨터에서 HTTP로 호스팅하고, 다른 컴퓨터에서 네트워크를 통해 접속합니다. 클라이언트는 URL만 지정하며, **경로 설정은 서버 측에서 관리**됩니다.

#### 서버 실행

**macOS / Linux:**
```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 \
uv run --directory /path/to/invoice_rpa invoice-rpa-mcp
```

**Windows (PowerShell):**
```powershell
$env:INVOICE_MCP_TRANSPORT="streamable-http"
$env:INVOICE_INPUT_FOLDER="C:/Invoice/input"
$env:INVOICE_OUTPUT_FOLDER="C:/Invoice/output"
$env:INVOICE_CUSTOMER_MASTER_PATH="C:/Invoice/customer_master.csv"
$env:INVOICE_ITEM_LIST_PATH="C:/Invoice/itemList.csv"
uv run --directory C:/Projects/invoice_rpa invoice-rpa-mcp
```

서버가 `http://0.0.0.0:8000/mcp` 에서 대기합니다. 포트/호스트 변경: `INVOICE_MCP_PORT=9000`, `INVOICE_MCP_HOST=192.168.1.100`

#### 클라이언트 설정

**Claude Desktop (`claude_desktop_config.json`) / Claude Code (`.mcp.json`):**
```json
{
  "mcpServers": {
    "invoice-rpa": {
      "type": "streamable-http",
      "url": "http://서버IP:8000/mcp"
    }
  }
}
```

```bash
claude mcp add --transport http invoice-rpa http://서버IP:8000/mcp
```

> `서버IP`를 실제 IP 주소 또는 호스트명으로 교체하세요.

---

### 4. SSE 모드 (레거시 원격)

Streamable HTTP를 지원하지 않는 클라이언트를 위한 레거시 transport입니다. endpoint가 `/sse`인 것 외에는 HTTP 모드와 동일합니다.

#### 서버 실행

```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 \
uv run --directory /path/to/invoice_rpa invoice-rpa-mcp
```

서버가 `http://0.0.0.0:8000/sse` 에서 대기합니다.

#### 클라이언트 설정

**Claude Desktop (`claude_desktop_config.json`) / Claude Code (`.mcp.json`):**
```json
{
  "mcpServers": {
    "invoice-rpa": {
      "type": "sse",
      "url": "http://서버IP:8000/sse"
    }
  }
}
```

```bash
claude mcp add --transport sse invoice-rpa http://서버IP:8000/sse
```

---

### 동작 확인

```bash
# stdio 실행 확인 (Ctrl+C로 종료)
uv run --directory /path/to/invoice_rpa invoice-rpa-mcp

# MCP Inspector로 테스트 (브라우저에서 tool 목록 확인 및 호출)
npx @modelcontextprotocol/inspector uv run --directory /path/to/invoice_rpa invoice-rpa-mcp

# HTTP 서버 응답 확인
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

### 백그라운드 실행

```bash
INVOICE_MCP_TRANSPORT=streamable-http \
nohup uv run --directory /path/to/invoice_rpa invoice-rpa-mcp &

tail -f /path/to/invoice_rpa/logs/mcp_server.log
```

---

## 🐛 문제 해결

### 일반적인 문제

1. **시트를 찾을 수 없음**
   - `sheet_config.json`에서 적절한 별칭 확인
   - 입력 파일에 예상되는 시트가 있는지 확인

2. **헤더 감지 안됨**
   - `search_config.json` 헤더 키워드 검토
   - 검색 범위 파라미터 확인

3. **고객 식별 안됨**
   - 파일명이 예상 패턴을 따르는지 확인
   - `customer_patterns.json`에서 적절한 별칭 확인

4. **템플릿 선택 실패**
   - `customer_types.json`에 고객이 분류되어 있는지 확인
   - `templates/` 디렉토리에 템플릿 파일이 있는지 확인

### 로깅

시스템은 `logs/` 디렉토리에 상세한 로그를 생성합니다:
- `invoice_automation.log`: 메인 처리 로그
- 오류 상세, 처리 상태, 성능 메트릭 포함

## 📈 성능

### 처리 속도
- **소형 파일** (≤ 50개 아이템): ~2-3초
- **중형 파일** (51-200개 아이템): ~5-8초
- **대형 파일** (200+개 아이템): ~10-15초

### 메모리 사용량
- **기본 메모리**: ~50MB
- **파일당**: 크기에 따라 +5-20MB
- **피크 메모리**: 대형 배치 처리 시 ~200MB

## 🔧 커스터마이징

### 새로운 고객 유형 추가

1. `config/customer_types.json` 업데이트:
```json
{
  "customer_types": {
    "NEW_REGION": ["NewCustomer1", "NewCustomer2"]
  },
  "row_positions": {
    "NEW_REGION": {
      "contract_item_start": 20,
      "output_item_start": 35
    }
  }
}
```

2. 템플릿 생성 `templates/OUTPUT_BLANKFILE_NEW_REGION.xlsx`

3. `config/customer_patterns.json`에 고객 패턴 추가

### 커스텀 셀 매핑

새 필드 추가 또는 기존 필드 수정을 위해 `config/cell_references.json` 업데이트:

```json
{
  "input_sheets": {
    "custom_section": {
      "sheet_name": "Custom Sheet",
      "cells": {
        "custom_field": {
          "primary": "B10",
          "fallback": "B9"
        }
      }
    }
  }
}
```

## 📋 시스템 요구사항

### 시스템 요구사항
- **OS**: Windows, macOS 또는 Linux
- **Python**: 3.13 이상
- **메모리**: 최소 4GB RAM
- **저장공간**: 100MB 여유 공간

### Python 의존성
```txt
openpyxl>=3.1.2
python-dotenv>=1.0.0
pillow>=10.0.0
mcp>=1.0.0
```

## 📄 라이선스

이 프로젝트는 기업용이며 기밀입니다. 모든 권리는 보유됩니다.

## 📞 지원

기술 지원이나 질문이 있는 경우:
- `logs/` 디렉토리의 로그 파일 확인
- 설정 파일이 올바르게 포맷되어 있는지 확인
- 입력 파일이 예상 형식을 따르는지 확인

---

**버전**: 0.2.0
**마지막 업데이트**: 2026-02-17
**상태**: 운영 가능
