Saju Fortune-Telling MCP Server

Instructions

Implementation Reference

• src/tools/convert_calendar.ts:15-60 (handler)

  The main tool handler for 'convert_calendar' that validates input, performs conversion, and returns formatted JSON response.

  export function handleConvertCalendar(args: ConvertCalendarArgs): string {
    // 입력 검증
    if (!isValidDate(args.date)) {
      throw new Error(`유효하지 않은 날짜 형식입니다: ${args.date}. YYYY-MM-DD 형식을 사용하세요.`);
    }
  
    if (args.fromCalendar === args.toCalendar) {
      return JSON.stringify(
        {
          success: true,
          message: '동일한 달력 체계입니다.',
          data: {
            originalDate: args.date,
            convertedDate: args.date,
          },
        },
        null,
        2
      );
    }
  
    // 달력 변환 (로컬 테이블 사용)
    const result = convertCalendar(args.date, args.fromCalendar, args.toCalendar);
  
    const formatted = `
  📅 음양력 변환 결과
  
  ${getCalendarKorean(args.fromCalendar)} → ${getCalendarKorean(args.toCalendar)}
  
  입력: ${result.originalDate} (${getCalendarKorean(result.originalCalendar)})
  결과: ${result.convertedDate} (${getCalendarKorean(result.convertedCalendar)})
  
  ${result.isLeapMonth ? '⚠️ 윤달입니다' : ''}
  ${result.solarTerm ? `절기: ${result.solarTerm}` : ''}
    `.trim();
  
    return JSON.stringify(
      {
        success: true,
        data: result,
        formatted,
      },
      null,
      2
    );
  }

• src/lib/calendar.ts:15-86 (helper)

  Core implementation of calendar conversion logic between solar and lunar calendars using local data tables.

  export function convertCalendar(
    date: string,
    fromCalendar: CalendarType,
    toCalendar: CalendarType
  ): CalendarConversion {
    const inputDate = new Date(date);
  
    if (fromCalendar === toCalendar) {
      return {
        originalDate: date,
        originalCalendar: fromCalendar,
        convertedDate: date,
        convertedCalendar: toCalendar,
        solarTerm: getCurrentSolarTerm(inputDate),
      };
    }
  
    // 양력 → 음력
    if (fromCalendar === 'solar' && toCalendar === 'lunar') {
      const result = solarToLunarLocal(
        inputDate.getFullYear(),
        inputDate.getMonth() + 1,
        inputDate.getDate()
      );
  
      if (!result) {
        throw new Error(
          `지원하지 않는 연도입니다: ${inputDate.getFullYear()} (1900-2200만 지원)`
        );
      }
  
      const dateString = `${result.year}-${String(result.month).padStart(2, '0')}-${String(result.day).padStart(2, '0')}`;
  
      return {
        originalDate: date,
        originalCalendar: 'solar',
        convertedDate: dateString,
        convertedCalendar: 'lunar',
        isLeapMonth: result.isLeapMonth,
        solarTerm: getCurrentSolarTerm(inputDate),
      };
    }
  
    // 음력 → 양력
    if (fromCalendar === 'lunar' && toCalendar === 'solar') {
      const result = lunarToSolarLocal(
        inputDate.getFullYear(),
        inputDate.getMonth() + 1,
        inputDate.getDate(),
        false // 기본적으로 평달로 가정
      );
  
      if (!result) {
        throw new Error(
          `지원하지 않는 연도입니다: ${inputDate.getFullYear()} (1900-2200만 지원)`
        );
      }
  
      const dateString = `${result.year}-${String(result.month).padStart(2, '0')}-${String(result.day).padStart(2, '0')}`;
      const solarDate = new Date(dateString);
  
      return {
        originalDate: date,
        originalCalendar: 'lunar',
        convertedDate: dateString,
        convertedCalendar: 'solar',
        solarTerm: getCurrentSolarTerm(solarDate),
      };
    }
  
    throw new Error('유효하지 않은 달력 변환입니다');
  }

• src/core/tool-definitions.ts:82-95 (registration)

  Registration of the 'convert_calendar' tool schema factory in the MCP tool definitions.

  convert_calendar: () => ({
    name: 'convert_calendar',
    description: '양력↔음력 변환',
    inputSchema: {
      type: 'object',
      properties: {
        date: { type: 'string', description: 'YYYY-MM-DD' },
        fromCalendar: { type: 'string', enum: ['solar', 'lunar'] },
        toCalendar: { type: 'string', enum: ['solar', 'lunar'] },
        isLeapMonth: { type: 'boolean', default: false },
      },
      required: ['date', 'fromCalendar', 'toCalendar'],
    },
  }),

• src/schemas/index.ts:83-88 (schema)

  Zod schema definition for input validation of the 'convert_calendar' tool.

  export const ConvertCalendarSchema = z.object({
    date: DateSchema.describe('변환할 날짜 (YYYY-MM-DD)'),
    fromCalendar: CalendarTypeSchema.describe('입력 달력 타입'),
    toCalendar: CalendarTypeSchema.describe('출력 달력 타입'),
    isLeapMonth: z.boolean().default(false).describe('음력 윤달 여부 (음력 입력 시)')
  });

• src/core/tool-handler.ts:32-34 (registration)

  Dispatch case in central tool handler that routes 'convert_calendar' calls to the specific handler.

  case 'convert_calendar':
    return handleConvertCalendar(args as Parameters<typeof handleConvertCalendar>[0]);