MCP(Model Context Protocol) nonosXsemo에 적용해보기!

안녕하세요!
태하팍 입니다.
오늘은 MCP를 nonos와 semo에 적용해보겠습니다.
tip. skill중에 superpowers > brainstorming이 있는데 사용하면 무척 유용합니다 ㅎ

MCP란?

Anthropic이 주도하여 만든 오픈 프로토콜로,
AI 모델(클라이언트)이 외부 도구와 데이터소스(서버)에 표준화된 방식으로 연결할 수 있게 해줍니다.

핵심 개념

클라이언트-서버 구조
  - MCP Host: Claude Desktop, Claude Code 등 AI가 동작하는 앱
  - MCP Client: Host 내에서 서버와 1:1 연결을 관리
  - MCP Server: 외부 도구/데이터를 노출하는 프로그램 (이것을 만들려는 것)

MCP 서버가 제공할 수 있는 3가지

MCP로 nonos 송장처리 해보기

마무리 어떻게 해야할지 선택!

보안쪽에서 AWS관련해서 연락와서..ㅠㅠ 지양하는걸루..SEMO는 PASS~

결과

엑셀다운로드!

---

nonos+semo에 적용해보기

단일 MCP 서버 + API 직접 호출
  MCP 서버가 nonos/semo REST API를 직접 호출하는 구조.
  사용자 → Claude → MCP 서버 → nonos API → semo API
                        ↕
                    엑셀 파싱 (openpyxl)

  장점: 구현 간단, 기존 API 그대로 활용, 유지보수 쉬움
  단점: nonos/semo에 API 키 인증 추가 필요

아키텍처

⏺ 설계 1/4: 전체 아키텍처
  사용자: "이 엑셀로 송장처리해줘" + 파일 첨부
           │
      Claude Desktop / Claude Code
           │
      MCP Server (Python)
      ├── Tool: process_invoice
      │   ├── 1. 엑셀 파일 읽기 (openpyxl)
      │   ├── 2. 헤더 분석 → 컬럼 매핑 후보 반환
      │   ├── 3. 사용자 확인 후 파싱
      │   ├── 4. Nonos API: 송장 매칭 요청
      │   ├── 5. 매칭 결과를 사용자에게 보여주고 확인
      │   ├── 6. Nonos API: 매칭 확정 + 네이버 발송
      │   └── 7. Semo API: 같은 송장 데이터 저장
      └── 설정: 환경변수 (API 키, 이메일, 서버 URL)

⏺ 설계 2/4: MCP Tools 설계
  총 5개의 tool로 나눕니다:

 대화 흐름 예시
  사용자: "이 엑셀로 송장처리해줘" + 파일
  Claude: [read_invoice_excel 호출]
  Claude: "컬럼을 이렇게 매핑했습니다:
    - B열 '운송장번호' → 송장번호
    - D열 '받는분' → 수취인
    - E열 '받는분HP' → 전화번호
    맞나요?"
  사용자: "어"
  Claude: [parse_invoice_excel 호출]
  Claude: [match_invoices 호출]
  Claude: "매칭 결과입니다:
    - 자동 매칭: 45건
    - 매칭 실패: 3건 (홍길동/010-1234-****, ...)
    진행할까요?"
  사용자: "진행해"
  Claude: [confirm_and_dispatch 호출]
  Claude: [save_to_semo 호출]
  Claude: "완료! Nonos 45건 발송, Semo 저장 완료.
     실패 3건은 문자이거나 혹은 이슈 확인 후 수동처리 해주세요.

⏺ 설계 3/4: 인증 및 설정
  nonos/semo에 추가할 API 키 인증
  기존 네이버 OAuth와 별개로, MCP 전용 API 키 인증 미들웨어를 추가합니다:
  요청 헤더: X-API-Key: abc123
             X-User-Email: teri@example.com
  서버 측: API 키 검증 → 해당 이메일의 유저로 요청 처리
  MCP 서버 설정 파일
  {
    "mcpServers": {
      "nonos-semo": {
        "command": "python",
        "args": ["-m", "nonos_semo_mcp"],
        "env": {
          "NONOS_BASE_URL": "http://localhost:8080",
          "NONOS_API_KEY": "abc123",
          "NONOS_USER_EMAIL": "teri@example.com",
          "SEMO_BASE_URL": "http://localhost:8081",
          "SEMO_API_KEY": "def456",
          "SEMO_USER_EMAIL": "teri@example.com"
        }
      }
    }
  }
  Claude Desktop과 Claude Code 모두 이 설정으로 연결합니다.
  프로젝트 구조
  mcpProject/
  ├── src/
  │   └── nonos_semo_mcp/
  │       ├── __init__.py
  │       ├── __main__.py          # 진입점
  │       ├── server.py            # MCP 서버 정의 + tool 등록
  │       ├── tools/
  │       │   ├── read_excel.py    # read_invoice_excel
  │       │   ├── parse_excel.py   # parse_invoice_excel
  │       │   ├── match.py         # match_invoices
  │       │   ├── dispatch.py      # confirm_and_dispatch
  │       │   └── save_semo.py     # save_to_semo
  │       └── clients/
  │           ├── nonos_client.py  # Nonos REST API 클라이언트
  │           └── semo_client.py   # Semo REST API 클라이언트
 ├── pyproject.toml
  └── README.md

⏺ 설계 4/4: 에러 처리 및 엣지 케이스

  에러 시나리오별 처리

핵심 원칙

  - Nonos 먼저, Semo는 후속 — Nonos 처리가 실패하면 Semo로 진행하지 않음
  - Semo 실패는 정산에 직접 영향 — 반드시 경고하고 재시도 옵션 제공
  - 매 단계마다 사용자 확인 — 자동으로 넘어가지 않고, Claude가 결과를 보여주고 승인 후 진행전체 설계 정리:

요약

  - 언어: Python (MCP SDK + openpyxl)
  - 구조: 단일 MCP 서버 → nonos/semo REST API 호출
  - 인증: API 키 + 이메일 (환경변수)
  - Tool 5개: read_excel → parse_excel → match → dispatch → save_semo
  - 1차 범위: 송장처리만
  - 실행환경: Claude Desktop + Claude Code 둘 다

⏺ Plan 작성 완료. docs/superpowers/plans/2026-03-31-nonos-semo-mcp.md에 저장했습니다.
  총 12개 Task:
  1. 프로젝트 설정 (pyproject.toml, config)
  2. Nonos API 클라이언트
  3. Semo API 클라이언트
  4. read_invoice_excel tool
  5. parse_invoice_excel tool
  6. match_invoices tool
  7. confirm_and_dispatch tool
  8. save_to_semo tool
  9. MCP 서버 조립
  10. Nonos API 키 인증 미들웨어
  11. Semo API 키 인증 미들웨어
  12. 통합 테스트 & README

⏺ 실행방식

 Task 1: Project Setup… (2m 4s · ↓ 3.3k tokens · thought for 5s)
  ⎿  ◼ Task 1: Project Setup
     ◻ Task 2: Nonos API Client
     ◻ Task 3: Semo API Client
     ◻ Task 4: read_invoice_excel Tool
     ◻ Task 5: parse_invoice_excel Tool
     ◻ Task 6: match_invoices Tool
     ◻ Task 7: confirm_and_dispatch Tool
     ◻ Task 8: save_to_semo Tool
     ◻ Task 9: MCP Server Assembly
     ◻ Task 10: Nonos API Key Auth Middleware

---

semo까지 확인하고 싶었는데..일단 MCP가 뭐하는 친구인지 알았으니 PASS~
나중에는 여러 ai들이 발주,송장, 고객응대 등 다 할수 있을것 같다.
물론 미리 만들어놓은 Product들의 api과 불편함들을 해소하기 위한 좋은 기능들이 뒷받침되어야할 것이다.

끝~