Bolta MCP Server

Korean electronic tax invoice (전자세금계산서) issuance through natural language conversation using the Model Context Protocol (MCP).

📋 Overview

The Bolta MCP Server enables AI assistants to issue Korean electronic tax invoices through natural language conversation. It provides a seamless interface between AI models and the Bolta tax invoice API, handling all the complexities of Korean tax regulations and business requirements.

Key Features

• 🇰🇷 Full Korean Tax Invoice Support - 정발행 (Regular), 역발행 (Reverse), 수정발행 (Amendment)
• 💬 Natural Language Interface - Conversational flow guides users through invoice creation
• 📝 Flexible Input Formats - Accepts both XXX-XX-XXXXX and XXXXXXXXXX business registration formats
• 🎯 Smart Field Parsing - Automatically extracts invoice details from natural language
• 📦 Item Details Support - Specification (규격) and description (비고) fields for detailed itemization
• 🔐 Certificate Integration - Public certificate (공동인증서) registration status checking
• 🛡️ Type-Safe - Full TypeScript support with Zod validation
• 📊 Comprehensive Logging - Structured logging with Winston for debugging
• 🔄 Auto-retry Logic - Intelligent retry mechanism for network failures

🚀 Quick Start

Installation

# Install from npm
npm install @baryonlabs/bolta-mcp

# Or install from source
git clone https://github.com/baryonlabs/bolta-mcp.git
cd bolta-mcp
npm install
npm run build

Configuration

Create a .env file with your Bolta API credentials:

# Required: Your Bolta API key
BOLTA_API_KEY=your_api_key_here

# Required: Customer key for invoice operations
BOLTA_CUSTOMER_KEY=your_customer_key_here

# Optional: API configuration
BOLTA_API_BASE_URL=https://xapi.bolta.io/v1
PORT=3000
NODE_ENV=production
LOG_LEVEL=info

🖥️ Integration with Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bolta-mcp": {
      "command": "node",
      "args": ["/path/to/bolta-mcp/dist/index.js"],
      "env": {
        "BOLTA_API_KEY": "your_api_key",
        "BOLTA_CUSTOMER_KEY": "your_customer_key"
      }
    }
  }
}

📚 MCP Tools & Resources

MCP Tools

issueTaxInvoice

Issues Korean electronic tax invoices through guided conversation.

Parameters:

• request (string): Natural language invoice request
• context (optional): Conversation context for multi-step flow

Example Request:

"ABC회사(사업자번호 123-88-00016)에 소프트웨어 개발 서비스 1,000,000원 세금계산서를 발행해주세요"

Supports:

• Multi-line item input with specifications and descriptions
• Automatic tax calculation (10% VAT)
• Business registration number format validation
• Certificate registration status checking

checkSupplier

Checks if a supplier is registered and has valid certificates.

Example:

{
  "identifier": "123-88-00001"  // Optional BRN verification
}

registerCustomerSimple

Registers new customers with minimal required information.

Parameters:

• customerData: Customer information including:
  • identificationNumber: Business registration number (both formats accepted)
  • organizationName: Company name
  • representativeName: Representative name
  • manager.email: Manager email (required)

certificateRegistration

Manages public certificate (공동인증서) registration for tax invoice issuance.

Actions:

• generate_url: Create registration URL
• check_status: Verify certificate status
• process_result: Handle registration result

MCP Resources

guide://tax-invoice-complete

전자세금계산서 발행 완전 가이드

Comprehensive unified guide for Korean electronic tax invoice issuance:

• 기본 개념: Electronic tax invoice fundamentals and benefits
• 대화형 프로세스: 6-step conversational issuance process with smart questioning
• 정보 요구사항: Required vs. optional information with conditional asking
• 질문 전략: Intelligent questioning strategy - only ask for unknown information
• 오류 처리: Comprehensive error handling and resolution guidance
• 사용 팁: Efficiency tips and best practices for optimal usage

Key Features:

• ✅ No Dummy Data: All examples are realistic and applicable
• 🤖 Smart Questioning: Only asks for information that's not already known
• 📋 Conditional Fields: Clear guidance on when to ask for optional information
• 🎯 정발행 전용: Optimized specifically for regular invoice issuance (우리 회사 → 고객사)
• 📖 실용적 가이드: Practical, actionable guidance for real-world usage

Example Usage:

// Access the complete guide through MCP client
const completeGuide = await mcp.readResource('guide://tax-invoice-complete');

📋 Supported Features

Required Fields for Tax Invoice Issuance

공급자 (Supplier) - Required Fields

• ✅ 사업자등록번호 (Business Registration Number) - XXX-XX-XXXXX format
• ✅ 상호명 (Organization Name)
• ✅ 대표자명 (Representative Name)
• ✅ 담당자 이메일 (Manager Email) - Required for notifications
• ✅ 담당자 이름 (Manager Name)
• ✅ 담당자 전화번호 (Manager Phone) - 010-XXXX-XXXX format
• ⚠️ 주소 (Address) - Optional but recommended
• ⚠️ 업태 (Business Type) - Optional but recommended
• ⚠️ 종목 (Business Item) - Optional but recommended

공급받는자 (Customer/Recipient) - Required Fields

• ✅ 사업자등록번호 (Business Registration Number) - XXX-XX-XXXXX format
• ✅ 상호명 (Organization Name)
• ✅ 대표자명 (Representative Name)
• ✅ 담당자 이메일 (Manager Email) - Required for invoice delivery
• ✅ 담당자 이름 (Manager Name)
• ✅ 담당자 전화번호 (Manager Phone) - 010-XXXX-XXXX format
• ⚠️ 주소 (Address) - Optional but recommended
• ⚠️ 업태 (Business Type) - Optional but recommended
• ⚠️ 종목 (Business Item) - Optional but recommended

품목 정보 (Item Details) - Required Fields

• ✅ 품목명 (Item Name) - Required
• ✅ 수량 (Quantity) - Required
• ✅ 단가 (Unit Price) - Required
• ✅ 공급가액 (Supply Cost) - Auto-calculated (수량 × 단가)
• ✅ 세액 (Tax) - Auto-calculated (공급가액 × 10%)
• ⚠️ 규격 (Specification) - Optional, defaults to '없음' if empty
• ⚠️ 비고 (Description/Remarks) - Optional, defaults to '없음' if empty

세금계산서 정보 (Invoice Details)

• ✅ 작성일자 (Issue Date) - Auto-set to current date
• ✅ 발행목적 (Purpose) - CLAIM (청구용) or RECEIPT (영수용)
• ⚠️ 세금계산서 비고 (Invoice Description) - Optional, defaults to '없음' if empty

Business Registration Number Handling

• ✅ Accepts both XXX-XX-XXXXX and XXXXXXXXXX formats
• ✅ Automatic conversion to API format (10 digits) when needed
• ✅ Display format preserved for user interface
• ✅ No strict format validation - accepts valid 10-digit numbers

Input Formats

Simple Format:

컨설팅 서비스, 1, 1000000
개발 용역, 2, 500000, 규격: A4, 비고: 1차 납품

Detailed Format:

품목명: 소프트웨어 개발
규격: 웹 애플리케이션
수량: 1
단가: 1000000
비고: React 기반 프론트엔드 개발

🔧 Development

Building from Source

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run development server
npm run dev

# Run tests
npm test

# Lint and format
npm run lint
npm run format

Project Structure

src/
├── handlers/
│   ├── issueTaxInvoice.ts      # Main invoice issuance logic
│   ├── checkSupplier.ts         # Supplier verification
│   ├── registerCustomerSimple.ts # Customer registration
│   └── certificateRegistration.ts # Certificate management
├── services/
│   └── boltaClient.ts           # Bolta API client
├── types/
│   └── bolta.ts                 # TypeScript definitions
├── utils/
│   ├── validators.ts            # Input validation
│   └── logger.ts                # Logging utilities
└── index.ts                     # MCP server entry point

📄 API Reference

Tax Invoice Flow

1. Supplier Check → Verify supplier registration and certificates
2. Customer Validation → Check if customer exists or needs registration
3. Item Collection → Gather invoice items with details
4. Confirmation → Review and confirm invoice details
5. Issuance → Submit to Bolta API
6. Response → Return invoice number and status

Error Handling

The server includes comprehensive error handling for:

• Certificate registration requirements
• Network failures with automatic retry
• Invalid business registration numbers
• Missing required fields
• API authentication errors

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

# Run specific test suite
npm test -- handlers/issueTaxInvoice

📝 Changelog

Version 1.0.0 (2024-12-18)

Features:

• ✨ Initial release with full Korean tax invoice support
• ✨ Business registration number flexible format handling
• ✨ Item specification and description field support
• ✨ Public certificate registration status checking
• ✨ Natural language conversation interface
• ✨ Multi-step invoice creation flow
• ✨ Automatic VAT calculation

Improvements:

• 🔧 Remove strict BRN format validation
• 🔧 Add 10-digit API format conversion
• 🔧 Preserve display format for users
• 🔧 Enhanced error messages
• 🔧 Comprehensive TypeScript types

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🔗 Resources

• Bolta API Documentation
• Model Context Protocol
• Korean Tax Invoice Guide

💡 Support

For issues and questions:

• GitHub Issues: https://github.com/baryonlabs/bolta-mcp/issues
• Bolta Support: https://bolta.io/support

Made with ❤️ by BaryonLabs