Toss Place MCP

Codex에게 실시간 Toss Place POS 매출, 주문, 메뉴 판매 가능 여부, 테이블, 결제, POS에서 추적하는 재고를 질문할 수 있습니다.

Toss Place MCP는 오 소스 프 호스팅 통합 도구입니다. 작은 플러그인이 Toss POS 안에서 실행되며 읽을 수 있는 POS 데이터를 사용자의 브리지로 안전하게 동기화합니다. Codex는 표준 로컬 MCP 프로세스 또는 브리지의 Streamable HTTP 엔드포인트를 통해 연결됩니다.

[!IMPORTANT] 이 프로젝트는 Toss Payments가 아니라 Toss Place POS를 연동합니다. Toss Payments는 API와 인증 방식이 다른 별도의 향후 공급자입니다.

질문할 수 있는 내용

• “오늘 밤 오픈 탭을 제외하고 얼마나 팔았나요?”

• “오후 8시부터 자정까지 가장 많이 팔린 음료는 무엇인가요?”

• “이번 주 금요일을 지난주 금요일과 비교해 주세요.”

• “시간대별 매출을 보여 주고 추가 바텐더를 배치해야 할 때를 알려 주세요.”

• “어떤 제품이 품절되었거나 10개 미만인가요?”

• “카드, 현금, 외부 결제를 구분해 주세요.”

• “현재 어떤 테이블에 오픈 체크가 있나요?”

• “이 번호에 해당하는 원시 Toss 주문을 보여 주세요.”

서버는 원시 POS 도구와 해석이 포함된 분석을 모두 제공합니다. 오픈 체크는 항상 확정 매출과 별도로 보고됩니다.

Related MCP server: lightspeed-x

작동 방식

Toss POS plugin ──signed HTTPS──▶ self-hosted bridge + database
                                      │
                         ┌────────────┴────────────┐
                         ▼                         ▼
                 local stdio MCP          Streamable HTTP MCP
                         │                         │
                         └──────────▶ Codex ◀─────┘

이 구분은 Toss POS가 iPad나 매장 데스크톱에서 실행되고 Codex가 다른 컴퓨터에서 실행될 때 중요합니다. Docker는 브리지를 배포하는 편리한 방법일 뿐이며, MCP 프로토콜의 일부가 아니고 로컬 개발에 필요하지 않습니다.

현재 플랫폼 상태

• 데이터 경로는 실제 데스크톱 샌드박스 통합에서 성공적으로 사용된 Toss Place POS 플러그인 SDK를 기반으로 합니다.

• 전체 데스크톱 경로(가맹점 활성화, POS 설치, 일회용 페어링, 초기 동기화, MCP 매출/재고 조회)는 macOS의 Toss 테스트 가맹점을 대상으로 검증되었습니다.

• SDK는 Windows, macOS, Android, iOS 기기 플랫폼을 지원합니다. 이 프로젝트는 iPad Toss POS 인스턴스에서 전체 설치 흐름을 아직 검증하지 않았습니다.

• 셀프 호스팅 브리지 도메인은 일반적으로 Toss 개발자 플러그인의 HTTP 허용 목록/ACL에 추가되어야 합니다. 이것이 주요 수동 온보딩 단계이며, Toss Place는 현재 이 통합을 일반 가맹점 OAuth로 제공하지 않습니다.

• 가맹점은 현재 GitHub 저장소를 스스로 Toss POS에 설치할 수 없습니다. 필요한 Toss 개발자 포털 접근 권한이 있는 사람이 작업자 플러그인을 생성/배포하고, 단말과 가맹점을 지정하고, POS에 서비스 코드를 입력해야 합니다. 그 수동 설치 후 Codex가 페어링 및 MCP 설정을 안내할 수 있습니다.

• 재고 수량은 가맹점이 해당 카탈로그 가격에 대해 Toss 재고 추적을 활성화한 경우에만 사용할 수 있습니다. 그렇지 않으면 MCP는 판매 가능 여부와 품절 상태만 보고할 수 있습니다.

요구 사항

• Node.js 22 이상

• 분리된 기기 사용을 위해 Toss POS 기기에서 접근 가능한 안정적인 HTTPS URL

• Toss Place 개발자 플러그인을 생성하거나 설치할 수 있는 권한

• 컨테이너 배포를 선택하는 경우에만 Docker 및 Docker Compose

빠른 시작

1. 클론 및 초기화

git clone https://github.com/danyay/toss-place-mcp.git
cd toss-place-mcp
npm install
npm run build:all
node dist/cli.js init

생성된 .env는 권한 0600이며 Git에서 무시됩니다. TOSS_MCP_PUBLIC_URL을 POS 기기가 접근할 수 있는 안정적인 HTTPS URL로 설정하세요.

2. 브리지 실행

로컬에서:

npm run bridge

또는 Docker로:

docker compose up -d --build

POS 플러그인을 설치하기 전에 브리지에 안정적인 HTTPS 호스트 이름을 부여하세요. 권장 경로는 Docker와 Caddy를 함께 사용하는 것입니다. NAT 뒤에서는 지속적인 Cloudflare Tunnel이 유용합니다. DNS, 방화벽, Caddyfile, 터널, 검증 및 재시작 지침은 docs/deployment.md를 따르세요. 공용 일반 HTTP로 페어링 또는 POS 트래픽을 보내지 마세요.

3. Toss POS 플러그인 빌드 및 설치

npm run build:plugin
npm run zip --workspace plugin

업로드 산출물은 plugin/place-mcp-bridge.zip이며, ZIP 안의 Toss 엔트리 포인트는 dist/main.js입니다.

이 섹션은 Toss 개발자 포털 접근 권한이 있는 사람이 필요합니다. Toss 개발자 포털에서:

1. POS_BACKGROUND_WORKER 엔트리 포인트를 사용하는 POS 워커 플러그인 애플리케이션을 생성하세요. 패키지 ID를 업로드된 번들(이 저장소의 경우 place-mcp-bridge)과 일치하게 유지하세요.

2. 브리지 출처(예: https://toss-mcp.example.com)를 애플리케이션의 HTTP ACL/허용 목록에 추가하세요.

3. plugin/place-mcp-bridge.zip을 개발/테스트 트랙에 업로드한 다음 해당 버전을 테스트 트랙에 배포하거나 배포하세요. 업로드만으로는 충분하지 않습니다.

4. 애플리케이션의 테스트 단말 설정에서 POS 단말을 등록하세요. Toss POS의 설정 → POS 정보/소프트웨어에 표시된 일련번호를 사용하세요.

5. 테스트 가맹점 관리를 열고 가맹점을 선택한 다음 애플리케이션 테이블에서 Place MCP Bridge를 찾아 ON으로 전환하세요. Toss가 업데이트 성공을 보고하는지 확인하세요.

6. Toss POS를 완전히 종료하고 다시 시작하세요.

7. Toss POS에서 설정 → 서비스 연동 → 서비스 코드로 연결을 열고 개발자 애플리케이션에 표시된 서비스 코드를 입력한 다음 Place MCP Bridge가 사용 중으로 표시되는지 확인하세요.

테스트 단말 등록과 가맹점별 애플리케이션 → ON 스위치가 모두 필요합니다. 서비스 코드를 인식한다고 해서 해당 가맹점에 대해 작업자가 권한을 부여받은 것은 아닙니다. 지속적인 읽기 전용 데이터 연결을 가맹점주가 승인한 가맹점에 대해서만 활성화하세요.

전체 클릭별 체크리스트, 각 단계 후 예상 결과, 실패 진단 및 공개 가맹점 온보딩의 한계는 docs/toss-developer-setup.md를 참조하세요.

4. POS 페어링

브리지가 실행 중인 상태에서:

npm run pair

Toss POS 플러그인 설정에 표시된 브리지 URL과 일회용 코드를 입력하세요. 코드는 15분 후 만료되며 한 번만 사용할 수 있습니다. 생성된 연결 비밀 값은 Toss 보안 저장소에 저장됩니다. 플러그인 요청은 타임스탬프, 논스 보호 및 HMAC 서명이 적용됩니다.

필드는 설정 → 서비스 연동 → Place MCP Bridge 아래에 있습니다. 저장한 다음 백그라운드 작업자가 로드되어 초기 동기화를 수행하도록 Toss POS를 한 번 완전히 다시 시작하세요.

연결을 확인하세요:

npm run doctor

첫 연결은 최대 90일의 주문을 백필합니다. 대규모 가맹점은 나중에 refresh_pos_data MCP 도구를 통해 다른 기간을 요청할 수 있습니다.

5. Codex 연결

로컬 stdio MCP 서버의 경우:

codex mcp add toss-place \
  --env TOSS_MCP_BRIDGE_URL=http://127.0.0.1:8787 \
  --env TOSS_MCP_ACCESS_TOKEN=YOUR_LOCAL_ENV_TOKEN \
  -- npx -y toss-place-mcp mcp

패키지가 npm에 게시될 때까지 -- 뒤의 명령을 빌드된 저장소 경로로 바꾸세요:

node /absolute/path/to/toss-place-mcp/dist/cli.js mcp

원격 Streamable HTTP의 경우 ~/.codex/config.toml에 다음을 추가하세요:

[mcp_servers.toss_place]
url = "https://toss-mcp.example.com/mcp"
bearer_token_env_var = "TOSS_MCP_ACCESS_TOKEN"
default_tools_approval_mode = "writes"

그런 다음 Codex를 실행하는 환경에서 TOSS_MCP_ACCESS_TOKEN을 내보내세요. 같은 호스트의 Codex 데스크톱, CLI 및 IDE 클라이언트는 이 구성을 공유합니다. 공식 Codex MCP 문서를 참조하세요.

이 저장소를 Codex에 제공하기

이것은 개발자가 아닌 사용자를 대상으로 한 온보딩 경험입니다:

이 저장소에서 Toss Place MCP 서버를 설치하세요. 모든 자격 증명을 git에 남기지 마세요. 브리지를 로컬 또는 Docker로 배포하고, 안정적인 HTTPS URL을 할당하도록 도와주고, Toss POS 플러그인 ZIP을 빌드한 다음, 제가 Toss 개발자 포털을 승인하거나 조작해야 할 때 멈추세요. 일회용 페어링 코드를 만들고, POS가 동기화 중인지 확인하고, 내 Codex 구성에 MCP를 추가한 다음, 오늘의 확정 매출을 오픈 체크와 별도로 보여 주세요.

Codex는 로컬 설치와 확인을 수행할 수 있습니다. 계정에서 요구하는 경우 사람이 Toss 포털/기기 단계를 완료해야 합니다.

MCP 도구

MCP는 또한 toss-place://capabilities 및 toss-place://data-dictionary 리소스와 daily-sales-review 프롬프트를 게시합니다.

이것은 Toss Place SDK의 모든 호출 가능한 네임스페이스는 아닙니다. 일반적인 매출, 주문, 결제, 메뉴, 테이블 및 재고 분석에 필요한 읽기 전용 가맹점 데이터를 다룹니다. KDS 상태, 실시간 임시 주문, 기기/UI 제어 및 모든 변경 작업은 v1에서 제외됩니다. SDK 적용 범위 매트릭스는 전체, 부분, 내부 및 지원되지 않는 영역을 구분합니다.

안전 모델

이 버전은 분석 우선이며 읽기 전용입니다. 기반 Toss SDK에는 주문, 결제, 현금영수증 및 임시 주문 변경 작업이 포함되어 있지만, 이러한 작업은 의도적으로 MCP 도구로 노출되지 않습니다. 오픈 탭을 실수로 취소하는 것은 매출 분석 서버의 기본 기능으로 허용될 수 없습니다.

• 브리지 API와 원격 MCP는 긴 베어러 토큰을 요구합니다.

• POS 동기화 요청은 HMAC-SHA256, 타임스탬프 및 일회용 논스를 사용합니다.

• 페어링 코드는 해시 처리되고 수명이 짧으며 일회용입니다.

• 비밀 값은 .gitignore를 통해 제외됩니다. 예시에는 플레이스홀더만 포함됩니다.

• 브리지는 기본적으로 127.0.0.1에 바인딩됩니다.

• 로그에는 액세스 토큰이나 플러그인 비밀 값이 의도적으로 포함되지 않습니다.

브리지를 인터넷에 노출하기 전에 SECURITY.md를 읽으세요.

데이터 및 지표

기본 일 경계는 Asia/Seoul을 사용합니다. “확정 매출”은 완료되고 취소되지 않은 주문에 대한 Toss chargePrice.chargePriceValue의 합계를 의미합니다. 현재 테이블 체크는 요청한 매출 기간 이전에 탭이 열렸더라도 별도로 표시되며, 확정 매출로 계산되지 않습니다. 환불과 취소가 부호에 영향을 줄 수 있으므로 부호가 있는 원시 할인 필드는 보존됩니다.

docs/api-coverage.md 및 docs/architecture.md를 참조하세요.

데이터베이스

기본값은 SQLite입니다:

TOSS_MCP_DATABASE_URL=sqlite:./data/toss-place.sqlite

PostgreSQL은 동일한 저장소를 사용합니다:

TOSS_MCP_DATABASE_URL=postgresql://user:password@localhost:5432/toss_mcp

데이터베이스에는 가맹점 매출 데이터와 암호화된 전송 연결 비밀 값이 포함됩니다. 다른 운영 POS 데이터처럼 보호하고 자체 보존 정책에 따라 백업하세요.

개발

npm install
npm run check
npm run build:all

테스트는 합성 픽스처를 사용합니다. 실제 통합 자격 증명은 무시되는 환경 변수를 통해서만 제공되어야 하며 일반 테스트 스위트에서는 절대 필요하지 않습니다.

macOS 샌드박스 테스트 앱과 모든 로컬 POS 데이터는 Git에서 제외됩니다. 가맹점 브리지 URL, 액세스 토큰, 페어링 코드, 데이터베이스 또는 Toss POS 애플리케이션 번들을 커밋에 복사하지 마세요.

로드맵

• 실제 가맹점에서 iPad 배포 검증 및 문서화

• 플랫폼이 허용하는 경우 Toss 검토/게시 플러그인 온보딩

• 구성 가능한 보존 및 증분 장기 백필 체크포인트

• CI에서 PostgreSQL 통합 테스트

• 원격 MCP 엔드포인트에 대한 선택적 OAuth

• 별도의 Toss Payments 공급자

• 명시적인 승인 및 감사 모델이 마련된 후에만 신중하게 게이트된 운영 도구

라이선스 및 상표

MIT. Toss와 Toss Place는 각 소유자의 상표입니다. 이 커뮤니티 프로젝트는 별도로 명시되지 않는 한 Toss와 제휴하거나 보증하지 않습니다.

• “미결제 주문을 제외하면 오늘 밤 매출이 얼마야?”

• “오후 8시부터 자정까지 가장 많이 팔린 주류는 뭐야?”

• “이번 주 금요일과 지난주 금요일을 비교해 줘.”

• “시간대별 매출을 보여주고 바텐더를 한 명 더 배치해야 할 시간을 알려줘.”

• “품절이거나 재고가 10개 미만인 상품은 뭐야?”

• “카드, 현금, 외부 결제 비중을 나눠서 보여줘.”

• “현재 미결제 주문이 있는 테이블은 어디야?”

• “이 수치의 근거가 된 원본 Toss 주문을 보여줘.”

서버는 원시 POS 도구와 기준이 명확한 분석 도구를 모두 제공합니다. 현재 미결제 주문은 항상 확정 매출과 별도로 보고합니다.

작동 방식

Toss POS 플러그인 ──서명된 HTTPS──▶ 셀프 호스팅 브리지 + 데이터베이스
                                            │
                              ┌─────────────┴─────────────┐
                              ▼                           ▼
                       로컬 stdio MCP             Streamable HTTP MCP
                              │                           │
                              └──────────▶ Codex ◀────────┘

Toss POS는 iPad 또는 매장 데스크톱에서 실행되고 Codex는 다른 컴퓨터에서 실행될 수 있으므로 이 분리가 중요합니다. Docker는 브리지를 편리하게 배포하는 방법일 뿐 MCP 프로토콜의 일부가 아니며 로컬 개발에 필수도 아닙니다.

현재 플랫폼 상태

• 실제 데스크톱 샌드박스 연동에 성공한 Toss Place POS 플러그인 SDK를 기반으로 데이터 경로를 구현했습니다.

• 가맹점 활성화, POS 설치, 일회성 페어링, 최초 동기화, MCP 매출/재고 조회를 포함한 전체 데스크톱 경로를 macOS의 Toss 테스트 가맹점에서 검증했습니다.

• SDK는 Windows, macOS, Android, iOS 장비 플랫폼을 선언합니다. 이 프로젝트는 아직 iPad Toss POS에서 전체 설치 과정을 검증하지 않았습니다.

• 일반적으로 셀프 호스팅 브리지 도메인을 Toss 개발자 플러그인의 HTTP 허용 목록/ACL에 추가해야 합니다. 이것이 가장 중요한 수동 온보딩 단계이며, Toss Place는 현재 이 연동을 일반적인 가맹점 OAuth로 제공하지 않습니다.

• 현재 가맹점이 GitHub 저장소만으로 Toss POS에 직접 설치할 수는 없습니다. 필요한 Toss 개발자 포털 권한을 가진 사람이 워커 플러그인을 생성/배포하고, 단말과 가맹점을 할당하고, POS에서 서비스 코드를 입력해야 합니다. 사람이 설치를 마치면 Codex가 페어링과 MCP 설정을 안내할 수 있습니다.

• 재고 수량은 가맹점이 해당 카탈로그 가격에 Toss 재고 추적을 활성화한 경우에만 제공됩니다. 그렇지 않으면 MCP는 판매 가능 여부와 품절 상태만 보고할 수 있습니다.

요구사항

• Node.js 22 이상

• POS와 브리지가 다른 장비에 있는 경우 Toss POS 장비에서 접근 가능한 안정적인 HTTPS URL

• Toss Place 개발자 플러그인을 만들거나 설치할 수 있는 권한

• 컨테이너 배포를 선택한 경우에만 Docker 및 Docker Compose

빠른 시작

1. 복제 및 초기화

git clone https://github.com/danyay/toss-place-mcp.git
cd toss-place-mcp
npm install
npm run build:all
node dist/cli.js init

생성된 .env는 권한 모드 0600이며 Git에서 무시됩니다. TOSS_MCP_PUBLIC_URL을 POS 장비에서 접근할 수 있는 안정적인 HTTPS URL로 설정하세요.

2. 브리지 시작

로컬 실행:

npm run bridge

Docker 실행:

docker compose up -d --build

POS 플러그인을 설치하기 전에 브리지에 안정적인 HTTPS 호스트명을 지정하세요. Docker와 Caddy 조합을 권장하며, NAT 뒤에서는 영구 Cloudflare Tunnel이 유용합니다. DNS, 방화벽, Caddyfile, 터널, 검증, 재시작 방법은 docs/deployment.md를 따르세요. 페어링 또는 POS 트래픽을 공개 일반 HTTP로 전송하지 마세요.

3. Toss POS 플러그인 빌드 및 설치

npm run build:plugin
npm run zip --workspace plugin

업로드 파일은 plugin/place-mcp-bridge.zip이며 ZIP 안의 Toss 엔트리포인트는 dist/main.js입니다.

이 단계는 Toss 개발자 포털 권한을 가진 사람이 진행해야 합니다. Toss 개발자 포털에서 다음을 진행합니다.

1. POS_BACKGROUND_WORKER 엔트리포인트를 사용하는 POS 워커 플러그인 애플리케이션을 만듭니다. 패키지 ID가 업로드 번들과 일치해야 합니다. 이 저장소에서는 place-mcp-bridge입니다.

2. https://toss-mcp.example.com과 같은 브리지 origin을 애플리케이션 HTTP ACL/허용 목록에 추가합니다.

3. plugin/place-mcp-bridge.zip을 개발/테스트 트랙에 업로드한 뒤 해당 버전을 테스트 트랙에 배포합니다. 업로드만 해서는 충분하지 않습니다.

4. 애플리케이션의 테스트 단말 설정에 POS 단말을 등록합니다. Toss POS의 설정 → POS 정보/소프트웨어에 표시되는 일련번호를 사용합니다.

5. 테스트 가맹점 관리를 열고 가맹점을 선택한 뒤 애플리케이션 표에서 Place MCP Bridge를 찾아 ON으로 전환합니다. Toss가 변경 성공을 표시하는지 확인합니다.

6. Toss POS를 완전히 종료하고 다시 시작합니다.

7. Toss POS에서 설정 → 서비스 연동 → 서비스 코드로 연결을 열고 개발자 애플리케이션의 서비스 코드를 입력한 뒤 Place MCP Bridge가 사용 중으로 표시되는지 확인합니다.

테스트 단말 등록과 가맹점별 애플리케이션 → ON 스위치가 모두 필요합니다. 서비스 코드를 인식한다고 해서 워커가 해당 가맹점에 승인된 것은 아닙니다. 지속적인 읽기 전용 데이터 연결을 가맹점주가 승인한 경우에만 활성화하세요.

전체 단계별 체크리스트, 각 단계의 예상 결과, 장애 진단, 일반 가맹점 온보딩의 제약은 docs/toss-developer-setup.md를 참고하세요.

4. POS 페어링

브리지가 실행 중인 상태에서 다음을 실행합니다.

npm run pair

표시된 브리지 URL과 일회용 코드를 Toss POS 플러그인 설정에 입력합니다. 코드는 15분 후 만료되며 한 번만 사용할 수 있습니다. 생성된 연결 비밀키는 Toss 보안 저장소에 저장됩니다. 플러그인 요청에는 타임스탬프와 재사용 방지 nonce가 포함되고 HMAC으로 서명됩니다.

입력 필드는 설정 → 서비스 연동 → Place MCP Bridge에 있습니다. 저장한 뒤 Toss POS를 완전히 한 번 재시작하여 백그라운드 워커가 로드되고 최초 동기화를 수행하게 합니다.

연결을 확인합니다.

npm run doctor

최초 연결은 최대 90일의 주문을 백필합니다. 대규모 가맹점은 나중에 refresh_pos_data MCP 도구로 다른 기간을 요청할 수 있습니다.

5. Codex 연결

로컬 stdio MCP 서버:

codex mcp add toss-place \
  --env TOSS_MCP_BRIDGE_URL=http://127.0.0.1:8787 \
  --env TOSS_MCP_ACCESS_TOKEN=YOUR_LOCAL_ENV_TOKEN \
  -- npx -y toss-place-mcp mcp

패키지가 npm에 공개되기 전에는 -- 뒤의 명령을 빌드된 저장소 경로로 바꾸세요.

node /absolute/path/to/toss-place-mcp/dist/cli.js mcp

원격 Streamable HTTP를 사용하려면 ~/.codex/config.toml에 다음을 추가합니다.

[mcp_servers.toss_place]
url = "https://toss-mcp.example.com/mcp"
bearer_token_env_var = "TOSS_MCP_ACCESS_TOKEN"
default_tools_approval_mode = "writes"

그런 다음 Codex를 실행하는 환경에 TOSS_MCP_ACCESS_TOKEN을 내보냅니다. 같은 호스트의 Codex 데스크톱, CLI, IDE 클라이언트는 이 설정을 공유합니다. 공식 Codex MCP 문서를 참고하세요.

이 저장소를 Codex에 맡기기

다음은 개발자가 아닌 사용자를 위해 의도한 온보딩 방식입니다.

이 저장소에서 Toss Place MCP 서버를 설치해 줘. 모든 자격 증명은 Git에 포함하지 마. 브리지를 로컬 또는 Docker로 배포하고, 안정적인 HTTPS URL을 지정하도록 도와주고, Toss POS 플러그인 ZIP을 빌드해 줘. 내가 Toss 개발자 포털에서 승인하거나 직접 조작해야 하는 단계에서는 멈춰 줘. 일회용 페어링 코드를 생성하고 POS가 동기화되는지 확인한 뒤 MCP를 내 Codex 설정에 추가해 줘. 마지막으로 오늘 확정 매출과 현재 미결제 주문을 나눠서 보여줘.

Codex는 로컬 설치와 검증을 수행할 수 있습니다. 계정에서 요구하는 Toss 포털 및 장비 단계는 사람이 직접 완료해야 합니다.

MCP 도구

MCP는 toss-place://capabilities, toss-place://data-dictionary 리소스와 daily-sales-review 프롬프트도 제공합니다.

이 프로젝트는 Toss Place SDK에서 호출할 수 있는 모든 네임스페이스를 제공하지 않습니다. 일반적인 매출, 주문, 결제, 메뉴, 테이블, 재고 분석에 필요한 읽기 전용 가맹점 데이터를 지원합니다. KDS 상태, 실시간 임시 주문, 장비/UI 제어, 모든 데이터 변경 기능은 v1에서 제외합니다. SDK 지원 범위 표에서 전체 지원, 일부 지원, 내부 사용, 미지원 표면을 구분합니다.

안전 모델

이 버전은 분석 우선의 읽기 전용 서비스입니다. Toss SDK에는 주문, 결제, 현금영수증, 임시 주문 변경 기능이 있지만 MCP 도구로 의도적으로 노출하지 않습니다. 매출 분석 서버가 실수로 실제 미결제 주문을 취소할 수 있어서는 안 됩니다.

• 브리지 API와 원격 MCP는 긴 Bearer 토큰을 요구합니다.

• POS 동기화 요청은 HMAC-SHA256, 타임스탬프, 일회용 nonce를 사용합니다.

• 페어링 코드는 해시되어 저장되고 수명이 짧으며 한 번만 사용할 수 있습니다.

• 비밀정보는 .gitignore를 통해 제외되며 예제에는 자리표시자만 들어 있습니다.

• 브리지는 기본적으로 127.0.0.1에 바인딩됩니다.

• 로그에는 액세스 토큰이나 플러그인 비밀키를 의도적으로 기록하지 않습니다.

브리지를 인터넷에 공개하기 전에 SECURITY.md를 읽으세요.

데이터 및 지표

기본 일자 경계는 Asia/Seoul 시간대를 사용합니다. “확정 매출”은 완료되고 취소되지 않은 주문의 Toss chargePrice.chargePriceValue 합계입니다. 현재 테이블 주문이 요청한 매출 기간보다 먼저 시작되었더라도 별도로 표시하며 확정 매출에 포함하지 않습니다. 환불과 취소 처리가 부호에 영향을 줄 수 있으므로 원시 할인 필드의 부호를 보존합니다.

docs/api-coverage.md와 docs/architecture.md를 참고하세요.

데이터베이스

기본 데이터베이스는 SQLite입니다.

TOSS_MCP_DATABASE_URL=sqlite:./data/toss-place.sqlite

동일한 저장소에서 PostgreSQL도 사용할 수 있습니다.

TOSS_MCP_DATABASE_URL=postgresql://user:password@localhost:5432/toss_mcp

데이터베이스에는 가맹점 매출 데이터와 암호화된 전송 연결 비밀키가 들어 있습니다. 다른 운영 POS 데이터와 동일하게 보호하고 자체 보존 정책에 따라 백업하세요.

개발

npm install
npm run check
npm run build:all

테스트는 합성 픽스처를 사용합니다. 실제 통합 자격 증명은 Git에서 무시되는 환경 변수로만 제공해야 하며 일반 테스트 스위트에는 필요하지 않습니다.

macOS 샌드박스 테스트 앱과 모든 로컬 POS 데이터는 Git에서 제외됩니다. 가맹점 브리지 URL, 액세스 토큰, 페어링 코드, 데이터베이스, Toss POS 애플리케이션 번들을 커밋에 복사하지 마세요.

로드맵

• 실제 가맹점에서 iPad 배포 검증 및 문서화

• 플랫폼이 허용하는 경우 Toss 검토/공개 플러그인 온보딩

• 설정 가능한 보존 기간 및 증분 장기 백필 체크포인트

• CI에서 PostgreSQL 통합 테스트

• 원격 MCP 엔드포인트의 선택적 OAuth

• 별도의 Toss Payments 공급자

• 명시적 승인 및 감사 모델이 준비된 후에만 신중하게 제한된 운영 도구 제공

라이선스 및 상표

MIT 라이선스입니다. Toss 및 Toss Place는 각 소유자의 상표입니다. 별도 명시가 없는 한 이 커뮤니티 프로젝트는 Toss와 제휴 관계가 없으며 Toss의 보증을 받지 않습니다.