@sazuapp/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @sazuapp/mcp-server
+
+[SAZU API](https://sazu.app/manse-api) 의 **MCP (Model Context Protocol)** 서버.
+AI 에이전트 (Claude Code, Cursor, Windsurf 등) 가 사주·만세력 API 를 직접 호출합니다.
+
+## 누가 사용하나
+
+**Pro 플랜 구독자만**. Free 사용자는 [docs 페이지](https://sazu.app/manse-api/docs) 의 curl 예시를 사용하세요.
+
+## 설치
+
+### Claude Code
+
+```bash
+claude mcp add sazu --env SAZU_API_KEY=sazu_pro_xxx -- npx -y @sazuapp/mcp-server
+```
+
+### Cursor / Windsurf
+
+`~/.cursor/mcp.json` 또는 `.windsurf/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sazu": {
+      "command": "npx",
+      "args": ["-y", "@sazuapp/mcp-server"],
+      "env": {
+        "SAZU_API_KEY": "sazu_pro_xxx"
+      }
+    }
+  }
+}
+```
+
+## API 키 발급
+
+[https://sazu.app/manse-api/dashboard/keys](https://sazu.app/manse-api/dashboard/keys) → Pro 키 발급 → `SAZU_API_KEY` 환경변수에 설정.
+
+## 노출 도구
+
+| 도구 | 설명 |
+|---|---|
+| `sazu_calculate` | 사주팔자 + 14개 명리 분석 (오행·합형충파해·격국·용신·12운성·신살·허자·대운 등) |
+| `sazu_calendar_convert` | 양력 ↔ 음력 변환 (200년 만세력) |
+
+## 사용 예시
+
+AI 에이전트에게 자연어로:
+
+```
+"1985년 3월 15일 14시 출생 남자의 사주를 분석해줘"
+"1990년 음력 4월 8일을 양력으로 변환해줘"
+```
+
+→ AI 가 `sazu_calculate` / `sazu_calendar_convert` 도구를 자동 호출.
+
+## 환경변수
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `SAZU_API_KEY` | (필수) | Pro 플랜 API 키 |
+| `SAZU_API_BASE` | `https://api.sazu.app` | API 베이스 URL (커스텀 환경용) |
+
+## 보안
+
+- 시작 시 `/v1/me` 호출로 tier 검증 → Pro 가 아니면 즉시 종료
+- 모든 요청에 `X-Client-Type: mcp` 헤더 부착 (서버 측 통계 분리)
+- 응답에 `X-Response-Id` watermark — 유출 시 추적 가능
+
+## 제한
+
+- 운세 텍스트 생성 기능은 노출하지 않습니다 (별도 라이선스 필요)
+- 인증·결제 엔드포인트는 노출하지 않습니다
+
+## 문의
+
+contact@sazu.app

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+/**
+ * SAZU API HTTP 클라이언트 (MCP server 내부 사용).
+ *
+ * - 환경변수 SAZU_API_KEY 필수
+ * - 환경변수 SAZU_API_BASE 선택 (기본 https://api.sazu.app)
+ * - 모든 요청에 X-Client-Type: mcp 헤더 부착 → 서버 측 통계 분리·추후 정책 적용 근거
+ */
+export declare class SazuApiError extends Error {
+    status: number;
+    code: string | undefined;
+    constructor(status: number, code: string | undefined, message: string);
+}
+export declare function callApi<T = unknown>(path: string, init?: RequestInit): Promise<T>;
+export interface MeResponse {
+    success: boolean;
+    data: {
+        tier: 'free' | 'pro' | 'event';
+        keyPrefix: string;
+        rateLimitPerMinute?: number;
+        monthlyQuota?: number;
+    };
+}
+export declare function fetchMe(): Promise<MeResponse>;

package/dist/client.js

@@ -0,0 +1,57 @@
+/**
+ * SAZU API HTTP 클라이언트 (MCP server 내부 사용).
+ *
+ * - 환경변수 SAZU_API_KEY 필수
+ * - 환경변수 SAZU_API_BASE 선택 (기본 https://api.sazu.app)
+ * - 모든 요청에 X-Client-Type: mcp 헤더 부착 → 서버 측 통계 분리·추후 정책 적용 근거
+ */
+const DEFAULT_BASE = 'https://api.sazu.app';
+export class SazuApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'SazuApiError';
+    }
+}
+function getApiKey() {
+    const key = process.env.SAZU_API_KEY;
+    if (!key) {
+        throw new SazuApiError(0, 'NO_API_KEY', 'SAZU_API_KEY 환경변수가 필요합니다. https://sazu.app/manse-api/dashboard/keys 에서 Pro 키를 발급받으세요.');
+    }
+    return key;
+}
+function getBase() {
+    return process.env.SAZU_API_BASE?.replace(/\/$/, '') ?? DEFAULT_BASE;
+}
+export async function callApi(path, init = {}) {
+    const apiKey = getApiKey();
+    const url = `${getBase()}${path.startsWith('/') ? path : `/${path}`}`;
+    const res = await fetch(url, {
+        ...init,
+        headers: {
+            'Content-Type': 'application/json',
+            'x-api-key': apiKey,
+            'X-Client-Type': 'mcp',
+            ...(init.headers ?? {}),
+        },
+    });
+    const text = await res.text();
+    let body = null;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        /* 비 JSON 응답 */
+    }
+    if (!res.ok) {
+        const errObj = body?.error;
+        throw new SazuApiError(res.status, errObj?.code, errObj?.message ?? `HTTP ${res.status}: ${text.slice(0, 200)}`);
+    }
+    return body;
+}
+export async function fetchMe() {
+    return callApi('/v1/me');
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * SAZU MCP server — stdio transport
+ *
+ * AI 에이전트 (Claude Code / Cursor / Windsurf 등) 가 사주·만세력 API 를 직접 호출.
+ *
+ * 보안 정책:
+ *   - SAZU_API_KEY 환경변수 필수
+ *   - 시작 시 /v1/me 호출로 tier 확인 → Pro 가 아니면 즉시 종료
+ *   - Free 사용자는 https://sazu.app/manse-api/docs 의 curl 예시 활용
+ *
+ * 노출 도구:
+ *   - sazu_calculate          : 사주팔자 + 14개 명리 분석
+ *   - sazu_calendar_convert   : 양/음력 변환
+ *
+ * 비노출 (영구):
+ *   - 운세 텍스트 생성 (Fortune Complete)
+ *   - 인증 엔드포인트 (/auth/*)
+ *   - 결제 엔드포인트
+ *
+ * 설치:
+ *   claude mcp add sazu npx -y @sazuapp/mcp-server
+ *
+ * Cursor / Windsurf:
+ *   설정 파일에 동일 명령 등록
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * SAZU MCP server — stdio transport
+ *
+ * AI 에이전트 (Claude Code / Cursor / Windsurf 등) 가 사주·만세력 API 를 직접 호출.
+ *
+ * 보안 정책:
+ *   - SAZU_API_KEY 환경변수 필수
+ *   - 시작 시 /v1/me 호출로 tier 확인 → Pro 가 아니면 즉시 종료
+ *   - Free 사용자는 https://sazu.app/manse-api/docs 의 curl 예시 활용
+ *
+ * 노출 도구:
+ *   - sazu_calculate          : 사주팔자 + 14개 명리 분석
+ *   - sazu_calendar_convert   : 양/음력 변환
+ *
+ * 비노출 (영구):
+ *   - 운세 텍스트 생성 (Fortune Complete)
+ *   - 인증 엔드포인트 (/auth/*)
+ *   - 결제 엔드포인트
+ *
+ * 설치:
+ *   claude mcp add sazu npx -y @sazuapp/mcp-server
+ *
+ * Cursor / Windsurf:
+ *   설정 파일에 동일 명령 등록
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { fetchMe, SazuApiError } from './client.js';
+import { TOOL_DEFINITIONS, executeSazuCalculate, executeCalendarConvert, } from './tools.js';
+const SERVER_NAME = '@sazuapp/mcp-server';
+const SERVER_VERSION = '0.1.0';
+async function main() {
+    // ── 1) Pro 자격 사전 검증 ──
+    // 정책: tier === 'pro' 만 허용. event(이벤트·관리자 부여) 도 MCP 미허용 — 결제 기반 Pro 만.
+    let tier = 'free';
+    try {
+        const me = await fetchMe();
+        tier = me.data.tier;
+    }
+    catch (err) {
+        if (err instanceof SazuApiError) {
+            console.error(`[sazu-mcp] 인증 실패 (${err.status} ${err.code ?? ''}): ${err.message}`);
+        }
+        else {
+            console.error(`[sazu-mcp] /v1/me 호출 실패: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        process.exit(1);
+    }
+    if (tier !== 'pro') {
+        console.error('[sazu-mcp] Pro 플랜 전용 기능입니다. 현재 등급: ' +
+            tier +
+            '\n→ Pro 업그레이드: https://sazu.app/manse-api/pricing' +
+            '\n→ Free 사용자는 https://sazu.app/manse-api/docs 의 curl 예시 활용');
+        process.exit(1);
+    }
+    // ── 2) MCP server 초기화 ──
+    const server = new Server({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // ── 3) 도구 목록 ──
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOL_DEFINITIONS.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    }));
+    // ── 4) 도구 실행 ──
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args } = req.params;
+        try {
+            let result;
+            if (name === 'sazu_calculate') {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                result = await executeSazuCalculate(args);
+            }
+            else if (name === 'sazu_calendar_convert') {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                result = await executeCalendarConvert(args);
+            }
+            else {
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: `알 수 없는 도구: ${name}` }],
+                };
+            }
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof SazuApiError
+                ? `[${err.status} ${err.code ?? 'ERR'}] ${err.message}`
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `호출 실패: ${message}` }],
+            };
+        }
+    });
+    // ── 5) stdio transport 연결 ──
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[sazu-mcp] ready (tier=${tier}, tools=${TOOL_DEFINITIONS.length}). docs: https://sazu.app/manse-api/docs`);
+}
+main().catch((err) => {
+    console.error('[sazu-mcp] fatal:', err);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,106 @@
+/**
+ * MCP 도구 정의 — SAZU API 의 데이터 엔드포인트만 노출.
+ *
+ * 비공개 (절대 노출 금지):
+ *   - 운세 텍스트 (Fortune Complete) → LLM 출력 자산이므로 MCP 미노출
+ *   - 인증 엔드포인트 (/auth/*) → MCP 와 무관
+ *
+ * 공개:
+ *   - sazu_calculate          : 사주팔자 + 14개 모듈 분석
+ *   - sazu_calendar_convert   : 양력 ↔ 음력 변환
+ */
+import { z } from 'zod';
+export declare const SazuCalculateInputSchema: z.ZodObject<{
+    birthDate: z.ZodString;
+    birthTime: z.ZodOptional<z.ZodString>;
+    gender: z.ZodEnum<{
+        male: "male";
+        female: "female";
+    }>;
+    calendar: z.ZodDefault<z.ZodEnum<{
+        solar: "solar";
+        lunar: "lunar";
+    }>>;
+    isLeapMonth: z.ZodOptional<z.ZodBoolean>;
+    location: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SazuCalculateInput = z.infer<typeof SazuCalculateInputSchema>;
+export declare const CalendarConvertInputSchema: z.ZodObject<{
+    date: z.ZodString;
+    from: z.ZodEnum<{
+        solar: "solar";
+        lunar: "lunar";
+    }>;
+    to: z.ZodEnum<{
+        solar: "solar";
+        lunar: "lunar";
+    }>;
+    isLeapMonth: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CalendarConvertInput = z.infer<typeof CalendarConvertInputSchema>;
+export declare function executeSazuCalculate(input: SazuCalculateInput): Promise<unknown>;
+export declare function executeCalendarConvert(input: CalendarConvertInput): Promise<unknown>;
+export declare const TOOL_DEFINITIONS: readonly [{
+    readonly name: "sazu_calculate";
+    readonly description: "생년월일·시간·성별을 입력하면 사주팔자(연·월·일·시주) + 14개 명리 분석 모듈(오행·합형충파해·격국·용신·12운성·신살·허자·대운 등) 을 반환합니다. 한국 명리학 정밀 계산.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly birthDate: {
+                readonly type: "string";
+                readonly description: "생년월일 (YYYY-MM-DD)";
+            };
+            readonly birthTime: {
+                readonly type: "string";
+                readonly description: "생시 (HH:MM, 24시간제). 시간 미상이면 생략.";
+            };
+            readonly gender: {
+                readonly type: "string";
+                readonly enum: readonly ["male", "female"];
+                readonly description: "성별";
+            };
+            readonly calendar: {
+                readonly type: "string";
+                readonly enum: readonly ["solar", "lunar"];
+                readonly description: "양/음력 (기본 solar)";
+                readonly default: "solar";
+            };
+            readonly isLeapMonth: {
+                readonly type: "boolean";
+                readonly description: "윤달 여부 (lunar 일 때만)";
+            };
+            readonly location: {
+                readonly type: "string";
+                readonly description: "출생 도시 (선택, 진태양시 보정)";
+            };
+        };
+        readonly required: readonly ["birthDate", "gender"];
+    };
+}, {
+    readonly name: "sazu_calendar_convert";
+    readonly description: "양력 ↔ 음력 변환. 200년 범위 만세력 기반. 윤달 처리 포함.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly date: {
+                readonly type: "string";
+                readonly description: "변환할 날짜 (YYYY-MM-DD)";
+            };
+            readonly from: {
+                readonly type: "string";
+                readonly enum: readonly ["solar", "lunar"];
+                readonly description: "입력 달력";
+            };
+            readonly to: {
+                readonly type: "string";
+                readonly enum: readonly ["solar", "lunar"];
+                readonly description: "출력 달력";
+            };
+            readonly isLeapMonth: {
+                readonly type: "boolean";
+                readonly description: "입력이 음력이고 윤달인 경우 true";
+            };
+        };
+        readonly required: readonly ["date", "from", "to"];
+    };
+}];

package/dist/tools.js

@@ -0,0 +1,81 @@
+/**
+ * MCP 도구 정의 — SAZU API 의 데이터 엔드포인트만 노출.
+ *
+ * 비공개 (절대 노출 금지):
+ *   - 운세 텍스트 (Fortune Complete) → LLM 출력 자산이므로 MCP 미노출
+ *   - 인증 엔드포인트 (/auth/*) → MCP 와 무관
+ *
+ * 공개:
+ *   - sazu_calculate          : 사주팔자 + 14개 모듈 분석
+ *   - sazu_calendar_convert   : 양력 ↔ 음력 변환
+ */
+import { z } from 'zod';
+import { callApi } from './client.js';
+// ── 입력 스키마 (AI 가 파싱하기 쉬운 한국어 description) ──
+export const SazuCalculateInputSchema = z.object({
+    birthDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'YYYY-MM-DD 형식'),
+    birthTime: z
+        .string()
+        .regex(/^\d{2}:\d{2}$/, 'HH:MM (24시간제)')
+        .optional(),
+    gender: z.enum(['male', 'female']),
+    calendar: z.enum(['solar', 'lunar']).default('solar'),
+    isLeapMonth: z.boolean().optional(),
+    location: z.string().optional(),
+});
+export const CalendarConvertInputSchema = z.object({
+    date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'YYYY-MM-DD'),
+    from: z.enum(['solar', 'lunar']),
+    to: z.enum(['solar', 'lunar']),
+    isLeapMonth: z.boolean().optional(),
+});
+// ── 도구 실행 ──
+export async function executeSazuCalculate(input) {
+    const parsed = SazuCalculateInputSchema.parse(input);
+    return callApi('/v1/sazu/calculate', {
+        method: 'POST',
+        body: JSON.stringify(parsed),
+    });
+}
+export async function executeCalendarConvert(input) {
+    const parsed = CalendarConvertInputSchema.parse(input);
+    return callApi('/v1/calendar/convert', {
+        method: 'POST',
+        body: JSON.stringify(parsed),
+    });
+}
+// ── 도구 메타데이터 (MCP server 등록용) ──
+export const TOOL_DEFINITIONS = [
+    {
+        name: 'sazu_calculate',
+        description: '생년월일·시간·성별을 입력하면 사주팔자(연·월·일·시주) + 14개 명리 분석 모듈(오행·합형충파해·격국·용신·12운성·신살·허자·대운 등) 을 반환합니다. 한국 명리학 정밀 계산.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                birthDate: { type: 'string', description: '생년월일 (YYYY-MM-DD)' },
+                birthTime: { type: 'string', description: '생시 (HH:MM, 24시간제). 시간 미상이면 생략.' },
+                gender: { type: 'string', enum: ['male', 'female'], description: '성별' },
+                calendar: { type: 'string', enum: ['solar', 'lunar'], description: '양/음력 (기본 solar)', default: 'solar' },
+                isLeapMonth: { type: 'boolean', description: '윤달 여부 (lunar 일 때만)' },
+                location: { type: 'string', description: '출생 도시 (선택, 진태양시 보정)' },
+            },
+            required: ['birthDate', 'gender'],
+        },
+    },
+    {
+        name: 'sazu_calendar_convert',
+        description: '양력 ↔ 음력 변환. 200년 범위 만세력 기반. 윤달 처리 포함.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                date: { type: 'string', description: '변환할 날짜 (YYYY-MM-DD)' },
+                from: { type: 'string', enum: ['solar', 'lunar'], description: '입력 달력' },
+                to: { type: 'string', enum: ['solar', 'lunar'], description: '출력 달력' },
+                isLeapMonth: { type: 'boolean', description: '입력이 음력이고 윤달인 경우 true' },
+            },
+            required: ['date', 'from', 'to'],
+        },
+    },
+];

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@sazuapp/mcp-server",
+  "version": "0.1.0",
+  "description": "SAZU API MCP server — AI agents (Claude Code/Cursor/Windsurf) 가 사주·만세력 API 를 직접 호출.",
+  "type": "module",
+  "bin": {
+    "sazu-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/index.js",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "saju",
+    "sazu",
+    "fortune",
+    "manse",
+    "korean-fortune"
+  ],
+  "author": "Inavan",
+  "license": "MIT",
+  "homepage": "https://sazu.app/manse-api",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ainvention/sazu-app-manse-api.git",
+    "directory": "mcp-server"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.11.0"
+  }
+}