daiso 1.0.8 → 1.0.10

package/dist/services/opinet/client.js

@@ -0,0 +1,231 @@
+import { resolveOpinetLocation } from './location.js';
+const OPINET_API_BASE_URL = 'https://www.opinet.co.kr/api';
+const OPINET_SOURCE = '한국석유공사 오피넷';
+const DEFAULT_TIMEOUT_MS = 10000;
+const FUEL_CODES = new Set(['B027', 'D047', 'B034', 'C004', 'K015']);
+const BRAND_NAMES = {
+    SKE: 'SK에너지',
+    GSC: 'GS칼텍스',
+    HDO: '현대오일뱅크',
+    SOL: 'S-OIL',
+    RTE: '자영알뜰',
+    RTX: '고속도로알뜰',
+    NHO: '농협알뜰',
+    ETC: '자가상표',
+    E1G: 'E1',
+    SKG: 'SK가스',
+};
+function getProcessEnvValue(name) {
+    /* c8 ignore next -- Worker 런타임은 bindings로 키를 주입합니다. */
+    return typeof process !== 'undefined' ? process.env[name] : undefined;
+}
+function requireApiKey(apiKey) {
+    const resolved = apiKey?.trim() || getProcessEnvValue('OPINET_API_KEY')?.trim();
+    if (!resolved) {
+        throw new Error('OPINET_API_KEY 환경 변수가 필요합니다.');
+    }
+    return resolved;
+}
+export function normalizeFuelCode(value, fallback = 'B027') {
+    const normalized = (value || fallback).trim().toUpperCase();
+    if (!FUEL_CODES.has(normalized)) {
+        throw new Error('fuelCode는 B027, D047, B034, C004, K015 중 하나여야 합니다.');
+    }
+    return normalized;
+}
+export function normalizeOpinetSort(value) {
+    return value === 'distance' || value === '2' ? 'distance' : 'price';
+}
+function toOpinetSortCode(sort) {
+    return sort === 'distance' ? '2' : '1';
+}
+function toNumber(value) {
+    if (value === null || value === undefined || value === '') {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function toStringValue(value) {
+    return typeof value === 'string' || typeof value === 'number' ? String(value).trim() : '';
+}
+function toBooleanYn(value) {
+    const normalized = toStringValue(value).toUpperCase();
+    if (normalized === 'Y') {
+        return true;
+    }
+    if (normalized === 'N') {
+        return false;
+    }
+    return undefined;
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+function asArray(value) {
+    if (Array.isArray(value)) {
+        return value.map(asRecord);
+    }
+    if (value && typeof value === 'object') {
+        return [asRecord(value)];
+    }
+    return [];
+}
+function unwrapOil(payload) {
+    return asArray(payload.RESULT?.OIL ?? payload.OIL);
+}
+async function fetchOpinetJson(path, params, options) {
+    const url = new URL(`${OPINET_API_BASE_URL}/${path}`);
+    for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, value);
+    }
+    url.searchParams.set('out', 'json');
+    url.searchParams.set('certkey', requireApiKey(options.apiKey));
+    const response = await (options.fetchImpl ?? fetch)(url.toString(), {
+        signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+    const bodyText = await response.text();
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch {
+        parsed = {};
+    }
+    if (!response.ok) {
+        throw new Error(`오피넷 API 호출 실패: HTTP ${response.status} ${bodyText}`);
+    }
+    return parsed;
+}
+function normalizeStationSummary(row) {
+    const brandCode = toStringValue(row.POLL_DIV_CD || row.POLL_DIV_CO);
+    return {
+        stationId: toStringValue(row.UNI_ID),
+        brandCode,
+        brandName: BRAND_NAMES[brandCode] || brandCode,
+        name: toStringValue(row.OS_NM),
+        price: toNumber(row.PRICE),
+        distanceMeters: toNumber(row.DISTANCE),
+        address: toStringValue(row.VAN_ADR) || undefined,
+        roadAddress: toStringValue(row.NEW_ADR) || undefined,
+        katecX: toNumber(row.GIS_X_COOR),
+        katecY: toNumber(row.GIS_Y_COOR),
+        raw: row,
+    };
+}
+function normalizeAveragePrice(row) {
+    return {
+        tradeDate: toStringValue(row.TRADE_DT),
+        productCode: toStringValue(row.PRODCD),
+        productName: toStringValue(row.PRODNM),
+        price: toNumber(row.PRICE),
+        diff: toStringValue(row.DIFF),
+        raw: row,
+    };
+}
+function normalizeStationDetail(row) {
+    const summary = normalizeStationSummary(row);
+    const prices = asArray(row.OIL_PRICE).map((priceRow) => ({
+        productCode: toStringValue(priceRow.PRODCD),
+        price: toNumber(priceRow.PRICE),
+        tradeDate: toStringValue(priceRow.TRADE_DT),
+        tradeTime: toStringValue(priceRow.TRADE_TM),
+        raw: priceRow,
+    }));
+    return {
+        ...summary,
+        phone: toStringValue(row.TEL) || undefined,
+        areaCode: toStringValue(row.SIGUNCD) || undefined,
+        lpgType: toStringValue(row.LPG_YN) || undefined,
+        hasMaintenance: toBooleanYn(row.MAINT_YN),
+        hasCarWash: toBooleanYn(row.CAR_WASH_YN),
+        hasConvenienceStore: toBooleanYn(row.CVS_YN),
+        isKpetroCertified: toBooleanYn(row.KPETRO_YN),
+        prices,
+    };
+}
+export async function fetchOpinetAveragePrices(options = {}) {
+    const payload = await fetchOpinetJson('avgAllPrice.do', {}, options);
+    const prices = unwrapOil(payload).map(normalizeAveragePrice);
+    return {
+        provider: 'opinet',
+        source: OPINET_SOURCE,
+        fetchedAt: new Date().toISOString(),
+        count: prices.length,
+        prices,
+    };
+}
+export async function fetchOpinetLowestStations(params, options = {}) {
+    const fuelCode = normalizeFuelCode(params.fuelCode);
+    const count = Math.min(Math.max(Math.trunc(params.count ?? 10), 1), 20);
+    const apiParams = {
+        prodcd: fuelCode,
+        cnt: String(count),
+    };
+    const areaCode = params.areaCode?.trim();
+    if (areaCode) {
+        apiParams.area = areaCode;
+    }
+    const payload = await fetchOpinetJson('lowTop10.do', apiParams, options);
+    const stations = unwrapOil(payload).map(normalizeStationSummary);
+    return {
+        provider: 'opinet',
+        source: OPINET_SOURCE,
+        fetchedAt: new Date().toISOString(),
+        fuelCode,
+        areaCode: areaCode || null,
+        count: stations.length,
+        stations,
+    };
+}
+export async function fetchOpinetStationsAround(params, options = {}) {
+    const resolvedLocation = await resolveOpinetLocation(params, {
+        googleMapsApiKey: options.googleMapsApiKey,
+        timeoutMs: options.timeoutMs,
+        fetchImpl: options.fetchImpl,
+    });
+    const radiusMeters = Math.min(Math.max(Math.trunc(params.radiusMeters ?? 3000), 100), 5000);
+    const fuelCode = normalizeFuelCode(params.fuelCode);
+    const sort = normalizeOpinetSort(params.sort);
+    const payload = await fetchOpinetJson('aroundAll.do', {
+        x: String(resolvedLocation.katec.x),
+        y: String(resolvedLocation.katec.y),
+        radius: String(radiusMeters),
+        prodcd: fuelCode,
+        sort: toOpinetSortCode(sort),
+    }, options);
+    const stations = unwrapOil(payload).map(normalizeStationSummary);
+    return {
+        provider: 'opinet',
+        source: OPINET_SOURCE,
+        fetchedAt: new Date().toISOString(),
+        fuelCode,
+        radiusMeters,
+        sort,
+        katec: resolvedLocation.katec,
+        location: {
+            latitude: resolvedLocation.latitude,
+            longitude: resolvedLocation.longitude,
+            location: resolvedLocation.location,
+            formattedAddress: resolvedLocation.formattedAddress,
+            geocodeUsed: resolvedLocation.geocodeUsed,
+            inputType: resolvedLocation.inputType,
+        },
+        count: stations.length,
+        stations,
+    };
+}
+export async function fetchOpinetStationDetail(stationId, options = {}) {
+    const id = stationId.trim();
+    if (!id) {
+        throw new Error('주유소 ID를 입력해주세요.');
+    }
+    const payload = await fetchOpinetJson('detailById.do', { id }, options);
+    const station = unwrapOil(payload).map(normalizeStationDetail)[0] ?? null;
+    return {
+        provider: 'opinet',
+        source: OPINET_SOURCE,
+        fetchedAt: new Date().toISOString(),
+        station,
+    };
+}

package/dist/services/opinet/index.js

@@ -0,0 +1,26 @@
+import { createOpinetAveragePricesTool, createOpinetLowestStationsTool, createOpinetStationDetailTool, createOpinetStationsAroundTool, } from './tools.js';
+const OPINET_METADATA = {
+    id: 'opinet',
+    name: '오피넷',
+    version: '1.0.0',
+    description: '한국석유공사 오피넷 기반 전국 평균 유가, 최저가 주유소, 반경 내 주유소 조회 서비스',
+};
+class OpinetService {
+    options;
+    metadata = OPINET_METADATA;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    getTools() {
+        return [
+            createOpinetAveragePricesTool(this.options.apiKey),
+            createOpinetLowestStationsTool(this.options.apiKey),
+            createOpinetStationsAroundTool(this.options.apiKey, this.options.googleMapsApiKey),
+            createOpinetStationDetailTool(this.options.apiKey),
+        ];
+    }
+}
+export function createOpinetService(options = {}) {
+    return new OpinetService(options);
+}
+export * from './types.js';

package/dist/services/opinet/location.js

@@ -0,0 +1,119 @@
+import proj4 from 'proj4';
+const WGS84 = 'EPSG:4326';
+const KATEC = 'KATEC';
+const KATEC_PROJ4 = '+proj=tmerc +lat_0=38 +lon_0=128 +k=0.9999 +x_0=400000 +y_0=600000 +ellps=bessel +units=m +no_defs +towgs84=-115.80,474.99,674.11,1.16,-2.31,-1.63,6.43';
+proj4.defs(KATEC, KATEC_PROJ4);
+const GEOCODE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const geocodeCache = new Map();
+function getProcessEnvValue(name) {
+    /* c8 ignore next -- Worker 런타임은 bindings로 키를 주입합니다. */
+    return typeof process !== 'undefined' ? process.env[name] : undefined;
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+export function wgs84ToKatec(latitude, longitude) {
+    if (!isFiniteNumber(latitude) || !isFiniteNumber(longitude)) {
+        throw new Error('유효한 위도/경도를 입력해주세요.');
+    }
+    const [x, y] = proj4(WGS84, KATEC, [longitude, latitude]);
+    return {
+        x: Number(x.toFixed(3)),
+        y: Number(y.toFixed(3)),
+    };
+}
+async function geocodeLocation(location, options) {
+    const keyword = location.trim();
+    const cached = geocodeCache.get(keyword);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.value;
+    }
+    const apiKey = options.googleMapsApiKey?.trim() || getProcessEnvValue('GOOGLE_MAPS_API_KEY')?.trim();
+    if (!apiKey) {
+        throw new Error('location 검색에는 GOOGLE_MAPS_API_KEY가 필요합니다.');
+    }
+    const endpoint = new URL('https://maps.googleapis.com/maps/api/geocode/json');
+    endpoint.searchParams.set('address', keyword);
+    endpoint.searchParams.set('key', apiKey);
+    const response = await (options.fetchImpl ?? fetch)(endpoint.toString(), {
+        headers: { Accept: 'application/json' },
+        signal: AbortSignal.timeout(options.timeoutMs ?? 10000),
+    });
+    const bodyText = await response.text();
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch {
+        parsed = { status: 'INVALID_JSON' };
+    }
+    if (!response.ok) {
+        throw new Error(`Google Geocoding 호출 실패: HTTP ${response.status} ${bodyText}`);
+    }
+    if (parsed.status !== 'OK') {
+        geocodeCache.set(keyword, {
+            expiresAt: Date.now() + GEOCODE_CACHE_TTL_MS,
+            value: null,
+        });
+        return null;
+    }
+    const first = parsed.results?.[0];
+    const latitude = first?.geometry?.location?.lat;
+    const longitude = first?.geometry?.location?.lng;
+    const value = isFiniteNumber(latitude) && isFiniteNumber(longitude)
+        ? {
+            latitude,
+            longitude,
+            formattedAddress: first?.formatted_address ?? null,
+        }
+        : null;
+    geocodeCache.set(keyword, {
+        expiresAt: Date.now() + GEOCODE_CACHE_TTL_MS,
+        value,
+    });
+    return value;
+}
+export async function resolveOpinetLocation(input, options = {}) {
+    if (isFiniteNumber(input.x) && isFiniteNumber(input.y)) {
+        return {
+            katec: { x: input.x, y: input.y },
+            latitude: null,
+            longitude: null,
+            location: input.location?.trim() || null,
+            formattedAddress: null,
+            geocodeUsed: false,
+            inputType: 'katec',
+        };
+    }
+    if (isFiniteNumber(input.latitude) && isFiniteNumber(input.longitude)) {
+        return {
+            katec: wgs84ToKatec(input.latitude, input.longitude),
+            latitude: input.latitude,
+            longitude: input.longitude,
+            location: input.location?.trim() || null,
+            formattedAddress: null,
+            geocodeUsed: false,
+            inputType: 'coordinates',
+        };
+    }
+    const location = input.location?.trim() || '';
+    if (location.length > 0) {
+        const geocoded = await geocodeLocation(location, options);
+        if (!geocoded) {
+            throw new Error(`위치를 좌표로 변환하지 못했습니다: ${location}`);
+        }
+        return {
+            katec: wgs84ToKatec(geocoded.latitude, geocoded.longitude),
+            latitude: geocoded.latitude,
+            longitude: geocoded.longitude,
+            location,
+            formattedAddress: geocoded.formattedAddress,
+            geocodeUsed: true,
+            inputType: 'location',
+        };
+    }
+    throw new Error('KATEC x/y, 위도/경도(latitude/longitude), 또는 location 중 하나를 입력해주세요.');
+}
+export function __testOnlyClearOpinetGeocodeCache() {
+    geocodeCache.clear();
+}

package/dist/services/opinet/tools.js

@@ -0,0 +1,80 @@
+import * as z from 'zod';
+import { fetchOpinetAveragePrices, fetchOpinetLowestStations, fetchOpinetStationDetail, fetchOpinetStationsAround, } from './client.js';
+function buildTextResponse(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+    };
+}
+export function createOpinetAveragePricesTool(apiKey) {
+    return {
+        name: 'opinet_get_average_prices',
+        metadata: {
+            title: '오피넷 전국 평균 유가',
+            description: '한국석유공사 오피넷의 전국 평균 유가를 조회합니다.',
+            inputSchema: {
+                timeoutMs: z.number().optional().default(10000).describe('요청 제한 시간(ms)'),
+            },
+        },
+        handler: (async (args) => buildTextResponse(await fetchOpinetAveragePrices({ apiKey, timeoutMs: args.timeoutMs }))),
+    };
+}
+export function createOpinetLowestStationsTool(apiKey) {
+    return {
+        name: 'opinet_get_lowest_price_stations',
+        metadata: {
+            title: '오피넷 최저가 주유소',
+            description: '전국 또는 지역별 최저가 주유소를 유종별로 조회합니다.',
+            inputSchema: {
+                fuelCode: z
+                    .enum(['B027', 'D047', 'B034', 'C004', 'K015'])
+                    .optional()
+                    .default('B027')
+                    .describe('유종 코드: B027 휘발유, D047 경유, B034 고급휘발유, C004 실내등유, K015 자동차부탄'),
+                areaCode: z.string().optional().describe('오피넷 지역 코드. 미입력 시 전국 기준'),
+                count: z.number().optional().default(10).describe('최저가 결과 수(1~20)'),
+                timeoutMs: z.number().optional().default(10000).describe('요청 제한 시간(ms)'),
+            },
+        },
+        handler: (async (args) => buildTextResponse(await fetchOpinetLowestStations(args, { apiKey, timeoutMs: args.timeoutMs }))),
+    };
+}
+export function createOpinetStationsAroundTool(apiKey, googleMapsApiKey) {
+    return {
+        name: 'opinet_search_stations_around',
+        metadata: {
+            title: '오피넷 반경 내 주유소',
+            description: 'KATEC x/y, 위도/경도, 또는 장소 키워드 기준 반경 내 주유소를 가격순 또는 거리순으로 조회합니다.',
+            inputSchema: {
+                x: z.number().optional().describe('기준 위치 X좌표(KATEC)'),
+                y: z.number().optional().describe('기준 위치 Y좌표(KATEC)'),
+                latitude: z.number().optional().describe('위도(WGS84)'),
+                longitude: z.number().optional().describe('경도(WGS84)'),
+                location: z.string().optional().describe('장소/주소 키워드. 예: 강남역, 서울역'),
+                radiusMeters: z.number().optional().default(3000).describe('검색 반경 m(100~5000)'),
+                fuelCode: z
+                    .enum(['B027', 'D047', 'B034', 'C004', 'K015'])
+                    .optional()
+                    .default('B027')
+                    .describe('유종 코드'),
+                sort: z.enum(['price', 'distance']).optional().default('price').describe('정렬 기준'),
+                timeoutMs: z.number().optional().default(10000).describe('요청 제한 시간(ms)'),
+            },
+        },
+        handler: (async (args) => buildTextResponse(await fetchOpinetStationsAround(args, { apiKey, googleMapsApiKey, timeoutMs: args.timeoutMs }))),
+    };
+}
+export function createOpinetStationDetailTool(apiKey) {
+    return {
+        name: 'opinet_get_station_detail',
+        metadata: {
+            title: '오피넷 주유소 상세정보',
+            description: '오피넷 주유소 ID로 상세 정보, 부가시설, 유종별 가격을 조회합니다.',
+            inputSchema: {
+                stationId: z.string().describe('오피넷 주유소 ID'),
+                timeoutMs: z.number().optional().default(10000).describe('요청 제한 시간(ms)'),
+            },
+        },
+        handler: (async (args) => buildTextResponse(await fetchOpinetStationDetail(args.stationId, { apiKey, timeoutMs: args.timeoutMs }))),
+    };
+}

package/dist/services/opinet/types.js

@@ -0,0 +1 @@
+export {};

package/dist/services/places/client.js

@@ -5,22 +5,43 @@ const CATEGORY_KEYWORDS = {
     dessert: '디저트',
     all: '',
 };
+const HTML_ENTITY_REPLACEMENTS = {
+    '&': '&',
+    '"': '"',
+    ''': "'",
+    ''': "'",
+};
 function getProcessEnvValue(name) {
     /* c8 ignore next -- Node 테스트와 CLI 런타임은 process를 제공하며, Worker에는 API에서 키를 주입합니다. */
     return typeof process !== 'undefined' ? process.env[name] : undefined;
 }
+function stripHtmlTags(value) {
+    let result = '';
+    let insideTag = false;
+    for (const character of value) {
+        if (character === '<') {
+            insideTag = true;
+            continue;
+        }
+        if (character === '>' && insideTag) {
+            insideTag = false;
+            continue;
+        }
+        if (!insideTag) {
+            result += character;
+        }
+    }
+    return result;
+}
 function cleanHtml(value) {
     if (!value) {
         return '';
     }
-    return value
-        .replace(/<[^>]*>/g, '')
-        .replace(/&amp;/g, '&')
-        .replace(/&lt;/g, '<')
-        .replace(/&gt;/g, '>')
-        .replace(/&quot;/g, '"')
-        .replace(/&#39;/g, "'")
-        .trim();
+    let result = stripHtmlTags(value);
+    for (const [entity, replacement] of Object.entries(HTML_ENTITY_REPLACEMENTS)) {
+        result = result.split(entity).join(replacement);
+    }
+    return result.trim();
 }
 function toCoordinate(value) {
     if (!value) {

package/dist/services/seveneleven/tools/searchProducts.js

@@ -14,23 +14,40 @@ async function searchProducts(args) {
     if (!query || query.trim().length === 0) {
         throw new Error('상품 검색어(query)를 입력해주세요.');
     }
-    const result = await searchSevenElevenProductsWithVariants(query, {
-        page,
-        size,
-        sort,
-        timeout: timeoutMs,
-    });
-    return buildTextResponse({
-        query: result.query,
-        page,
-        size,
-        sort,
-        totalCount: result.totalCount,
-        count: result.products.length,
-        collectionIds: result.collectionIds,
-        appliedQueries: result.appliedQueries,
-        products: result.products,
-    });
+    try {
+        const result = await searchSevenElevenProductsWithVariants(query, {
+            page,
+            size,
+            sort,
+            timeout: timeoutMs,
+        });
+        return buildTextResponse({
+            query: result.query,
+            page,
+            size,
+            sort,
+            totalCount: result.totalCount,
+            count: result.products.length,
+            collectionIds: result.collectionIds,
+            appliedQueries: result.appliedQueries,
+            products: result.products,
+        });
+    }
+    catch (error) {
+        return buildTextResponse({
+            query,
+            page,
+            size,
+            sort,
+            totalCount: 0,
+            count: 0,
+            collectionIds: [],
+            appliedQueries: [query],
+            products: [],
+            status: 'degraded',
+            message: error instanceof Error ? error.message : '세븐일레븐 상품 검색에 실패했습니다.',
+        });
+    }
 }
 const searchProductsOutputSchema = {
     query: z.string().describe('적용된 검색어'),
@@ -42,6 +59,8 @@ const searchProductsOutputSchema = {
     collectionIds: z.array(z.string()).describe('검색 컬렉션 ID 목록'),
     appliedQueries: z.array(z.string()).describe('실제로 시도한 검색어 목록'),
     products: z.array(z.unknown()).describe('세븐일레븐 상품 검색 결과'),
+    status: z.string().optional().describe('외부 API 차단 등으로 결과가 제한된 경우 degraded'),
+    message: z.string().optional().describe('degraded 상태의 원인 메시지'),
 };
 export function createSearchProductsTool() {
     return {

package/openapi.json

@@ -55,6 +55,7 @@
                 "sevenelevenGetCatalog",
                 "compareProducts",
                 "placesSearchNearby",
+                "submitDeveloperRequest",
                 "megaboxFindTheaters",
                 "megaboxListMovies",
                 "megaboxGetSeats",
@@ -139,6 +140,87 @@
               "type": "string"
             }
           },
+          {
+            "name": "type",
+            "in": "query",
+            "required": false,
+            "description": "개발자 요청 유형(bug, improvement, feature, docs, other)",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "severity",
+            "in": "query",
+            "required": false,
+            "description": "개발자 요청 영향도(low, medium, high, critical)",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "title",
+            "in": "query",
+            "required": false,
+            "description": "개발자 요청 제목",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "description",
+            "in": "query",
+            "required": false,
+            "description": "개발자 요청 상세 설명",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "toolName",
+            "in": "query",
+            "required": false,
+            "description": "문제가 발생했거나 개선이 필요한 MCP 도구 이름",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "reproduction",
+            "in": "query",
+            "required": false,
+            "description": "오류 재현 방법",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "expected",
+            "in": "query",
+            "required": false,
+            "description": "기대 결과",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "actual",
+            "in": "query",
+            "required": false,
+            "description": "실제 결과",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "source",
+            "in": "query",
+            "required": false,
+            "description": "요청 출처(mcp, chatgpt, claude, cli, api, other)",
+            "schema": {
+              "type": "string"
+            }
+          },
           {
             "name": "sido",
             "in": "query",