Multi-Tenant Invoice Autofill MCP Server

함수 호출 또는 MCP 지원 LLM(Claude, Gemini, GPT 등)이 테넌트를 대신하여 Digital Invoicing Software에서 인보이스를 자동 작성하고 저장할 수 있게 해주는 Python 백엔드 서비스입니다.

기능

• 이중 전송 지원: 표준 MCP 프로토콜(stdio / Streamable HTTP) 및 OpenAPI 스키마를 갖춘 REST API(FastAPI)를 통해 노출됩니다.

• 멀티 테넌시 및 인증: 테넌트별 자격 증명 암호화, 사용자 지정 MCP API 키 및 격리된 세션 관리.

• 복원력 있는 어댑터: 브라우저 헤더를 재현하는 캡슐화된 HTTP 어댑터로, 반응형 세션 갱신 및 동적 쿠키 만료 파싱을 제공합니다.

• 멱등성 및 동시성: 문서 해시를 통한 중복 제거 및 테넌트별 Redis 분산 잠금(lock:tenant:{id}).

• 프라이버시 우선: 비밀번호, 쿠키, 키, 토큰을 제거하는 필수 구조화 로그 편집 계층.

• 하드코딩 값 없음: 코드, 주석 또는 테스트에 자격 증명이나 비즈니스 식별 정보가 포함되지 않으며, 완전한 합성 테스트 데이터를 생성합니다.

Related MCP server: Invoice MCP Server

로컬 사전 요구 사항

• Python 3.12+

• Docker & Docker Compose (로컬 Postgres 및 Redis용)

시작하기

1. 환경 설정

.env.example을 .env로 복사하고 로컬 변수를 설정합니다:

cp .env.example .env

2. 로컬 데이터베이스 및 Redis 실행

docker-compose up -d

3. 종속성 설치

python -m venv .venv
# Windows:
.\.venv\Scripts\pip install -r requirements.txt
# Linux/macOS:
source .venv/bin/activate
pip install -r requirements.txt

4. 마이그레이션 실행

.\.venv\Scripts\alembic upgrade head

5. 서버 시작

# Start FastAPI REST server:
.\.venv\Scripts\uvicorn mcp_digitalinvoice.main:app --reload --port 8000

# Run MCP stdio server:
.\.venv\Scripts\python -m mcp_digitalinvoice.mcp_server.server

보안

[!CAUTION] 암호화 키 관리: ENCRYPTION_KEY 환경 변수는 안전한 32바이트 base64 인코딩 Fernet 키로 설정해야 합니다. ENCRYPTION_KEY가 제공되지 않으면 애플리케이션 시작이 즉시 실패합니다. 암호화 키가 실제 테넌트 데이터를 암호화하는 데 사용된 적이 있고 노출이 의심되는 경우, 이전 키는 손상된 것으로 간주해야 하므로 새로 생성된 키로 해당 데이터를 다시 암호화해야 합니다.

워크플로

테넌트 온보딩 (connect_account)

1. 테넌트의 Digital Invoicing Software 로그인 이메일, 비밀번호 및 비즈니스 이름으로 connect_account를 호출합니다.

2. 서버는 자격 증명을 암호화하고 초기 로그인을 통해 검증한 후 고유한 mcp_api_key를 반환합니다.

3. 이후 도구 호출을 위해 이 mcp_api_key를 LLM에(Bearer 토큰 또는 헤더로) 제공합니다.

인보이스 자동 작성 (fill_invoice)

LLM은 추출된 인보이스 JSON 페이로드(buyer, items, meta)와 함께 fill_invoice를 호출합니다. 서비스는 필수 필드를 검증하고, 단일 문서 순차 처리를 강제하며, 멱등성을 확인하고, 테넌트 세션을 확인한 후 페이로드를 다운스트림 형식에 매핑하여 인보이스 초안을 생성합니다.

테스트 실행

.\.venv\Scripts\pytest -v tests/