kr-medicine-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zzjiho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# kr-medicine-mcp
+
+식품의약품안전처(MFDS) 공개 API를 **MCP 도구 10개**로 노출하는 서버입니다. 의약품 검색·상호작용·임부금기 검증과 식품 영양·알레르기·회수 정보를 Claude Desktop, Cursor, Claude Code 등 MCP 호환 클라이언트에서 바로 사용할 수 있습니다.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-1.27-blue)](https://modelcontextprotocol.io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6)](https://www.typescriptlang.org/)
+[![Node](https://img.shields.io/badge/Node-%3E%3D20-339933)](https://nodejs.org/)
+
+---
+
+## 왜 만들었나
+
+LLM은 한국 약품명·성분·DUR(약물 안전사용) 정보를 잘 모릅니다. "이트라코나졸이랑 심바스타틴 같이 먹어도 되나"를 물으면 그럴듯하게 지어내기 쉬운데, 의료 영역에서 틀린 답은 사람을 다치게 할 수 있습니다.
+
+```
+사용자: "이트라코나졸이랑 심바스타틴 같이 먹어도 돼?"
+
+LLM 단독:    "둘 다 흔한 처방약입니다. 큰 문제는 없을 것으로 보이지만
+             의사 상담을 권장합니다."          ← 환각
+
+LLM + MCP:   ⚠️ 병용금기 — 횡문근융해증 위험
+             출처: 식약처 DUR 품목정보
+             → 의사·약사 상담 필수
+```
+
+이 서버는 모든 답을 식약처 공식 DB와 교차검증합니다. 진단·처방은 범위 밖이며, 조회된 사실만 전달하고 전문가 상담을 안내합니다.
+
+---
+
+## 도구 10개
+
+### 의약품 (7개)
+
+| 도구 | 역할 | API |
+|---|---|---|
+| `search_drug` | 약 이름/성분으로 검색 → 품목코드 획득 | e약은요 |
+| `get_drug_detail` | 효능·용법·주의·상호작용·부작용 풀세트 | e약은요 |
+| `find_alternatives` | 동일 주성분 다른 제품 | e약은요 |
+| `check_interaction` | 두 약 병용금기 직접 검증 | DUR 품목정보 |
+| `check_pregnancy_safety` | 임부금기 + 사유 | DUR 품목정보 |
+| `check_age_caution` | 노인주의 + 특정연령대금기 | DUR 품목정보 |
+| `identify_pill` | 모양·색상·각인으로 약 식별 | 의약품 낱알식별 |
+
+### 식품 (3개)
+
+| 도구 | 역할 | API |
+|---|---|---|
+| `search_food_nutrition` | 식품 칼로리·영양성분 조회 | 식품영양성분 DB |
+| `check_food_allergen` | 가공식품 원재료·알레르기 유발물질 확인 | 식품안전나라 |
+| `get_food_recall` | 회수·판매중지 식품 조회 | 식품안전나라 |
+
+> `search_food_nutrition` 은 `MFDS_API_KEY` 로 동작합니다. `check_food_allergen`·`get_food_recall` 은 별도의 `FOOD_SAFETY_API_KEY`(식품안전나라) 가 있을 때만 활성화되며, 없으면 이 두 도구만 안내 메시지를 반환하고 나머지는 정상 작동합니다.
+
+---
+
+## 사용 예시
+
+일상 대화에서 다음과 같이 물으면, 모델이 적절한 도구를 골라 식약처 DB를 조회한 뒤 답합니다.
+
+### 약물 상호작용 — LLM이 가장 위험하게 틀리는 영역
+```
+"이트라코나졸이랑 심바스타틴 같이 먹어도 돼?"
+  → check_interaction: 병용금기(횡문근융해증 위험) 탐지, 사유·출처 제시
+
+"지금 와파린 먹는 중인데 아스피린 추가해도 되나?"
+  → 기존 복용약 대비 신규 약 병용금기 교차검증
+```
+
+### 다제 복용 점검 (고령자)
+```
+"75세 어머니가 클로르페니라민, 디아제팜, 아미트립틸린을 같이 드세요. 괜찮을까요?"
+  → check_age_caution + check_interaction:
+    노인주의 성분 + 약물 간 금기를 한 번에 점검
+```
+
+### 임신 중 복용
+```
+"임신 12주인데 감기약에 아미노필린 들어있어. 안전해?"
+  → check_pregnancy_safety: 임부금기 등급과 사유 조회
+    (DB 미등재가 곧 '안전'은 아님을 명시)
+```
+
+### 정체불명 알약 식별
+```
+"서랍에서 나온 흰색 둥근 알약, 한쪽 면에 'TYL 500' 각인됐어. 이거 뭐야?"
+  → identify_pill: 모양·색상·각인으로 품목 특정
+```
+
+### 대체약 탐색 (품절·성분 동일)
+```
+"타이레놀이 약국에 없대. 같은 성분 다른 제품 알려줘"
+  → find_alternatives: 동일 주성분 제품 목록
+```
+
+### 식품 안전
+```
+"우리 애가 땅콩 알레르기 있는데, 이 과자 먹여도 돼?"
+  → check_food_allergen: 가공식품 원재료·알레르기 유발물질 확인
+
+"OO 제품 회수됐는지 확인해줘"
+  → get_food_recall: 회수·판매중지 처분 식품 조회
+```
+
+진단·처방 권고는 의료 안전상 일부러 거부하고, `의사·약사 상담`이 필요한 영역으로 안내합니다.
+
+---
+
+## 설치
+
+### 0단계: API 키 발급 (무료)
+
+**(1) 공공데이터포털** — [data.go.kr](https://www.data.go.kr) 회원가입 후 다음 6개를 검색해서 활용신청 (모두 자동승인). 마이페이지의 **인증키(Decoding 버전)** 하나를 `MFDS_API_KEY` 로 사용합니다:
+
+- 식품의약품안전처 의약품개요정보(e약은요)
+- 식품의약품안전처 의약품 제품 허가정보
+- 식품의약품안전처 의약품안전사용서비스(DUR) 품목정보
+- 식품의약품안전처 의약품안전사용서비스(DUR) 성분정보
+- 식품의약품안전처 의약품 낱알식별 정보
+- 식품의약품안전처 식품영양성분 DB (`search_food_nutrition` 용)
+
+**(2) 식품안전나라** (선택) — [foodsafetykorea.go.kr](https://www.foodsafetykorea.go.kr) 회원가입 → 활용신청(즉시 발급). `check_food_allergen`·`get_food_recall` 사용 시에만 필요하며 `FOOD_SAFETY_API_KEY` 로 사용합니다. 없으면 이 두 도구만 비활성화됩니다.
+
+설치할 필요 없이 `npx` 로 바로 실행됩니다.
+
+### 방법 1: Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 또는 `%APPDATA%\Claude\claude_desktop_config.json` (Windows) 편집:
+
+```json
+{
+  "mcpServers": {
+    "kr-medicine": {
+      "command": "npx",
+      "args": ["-y", "kr-medicine-mcp"],
+      "env": {
+        "MFDS_API_KEY": "발급받은_인증키_Decoding",
+        "FOOD_SAFETY_API_KEY": "식품안전나라_키 (선택)"
+      }
+    }
+  }
+}
+```
+
+저장 후 Claude Desktop 을 완전히 종료했다가 재실행합니다.
+
+### 방법 2: Claude Code
+
+```bash
+claude mcp add kr-medicine \
+  --env MFDS_API_KEY=발급받은_인증키 \
+  --env FOOD_SAFETY_API_KEY=식품안전나라_키 \
+  -- npx -y kr-medicine-mcp
+```
+
+### 방법 3: 직접 빌드 (개발용)
+
+```bash
+git clone https://github.com/zzjiho/kr-medicine-mcp.git
+cd kr-medicine-mcp
+npm install
+npm run build
+
+cp .env.example .env
+# .env 파일을 열어 MFDS_API_KEY=... 입력
+```
+
+---
+
+## 개발
+
+```bash
+npm install
+npm run build              # tsc 컴파일
+npm run watch              # tsc --watch
+bash test-all-tools.sh     # 도구 종합 회귀 테스트
+```
+
+자세한 시나리오는 [TESTING.md](TESTING.md) 참고.
+
+---
+
+## 아키텍처
+
+```
+src/
+├── core/        defineTool 헬퍼 + 미들웨어 합성 (캐시·면책·에러)
+├── shared/      HTTP 클라이언트, TTL 캐시
+├── domains/
+│   ├── drug/    e약은요 (search · detail · alternatives)
+│   ├── dur/     DUR 안전사용 (interaction · pregnancy · age-caution)
+│   ├── pill/    낱알식별 (identify)
+│   └── food/    식품 (nutrition · allergen · recall)
+└── server.ts    MCP stdio / HTTP 부팅 + DI 컨텍스트
+```
+
+도메인 기반 구조 + 미들웨어 자동 합성. 새 도구는 도메인 폴더에 `*.tool.ts` 파일 하나만 추가하면 등록·면책·캐싱·에러 처리가 자동으로 붙습니다.
+
+stdio(로컬 클라이언트) 와 HTTP/SSE(원격 배포) 두 가지 트랜스포트를 지원합니다 (`MCP_MODE=http`).
+
+---
+
+## ⚠️ 의료 면책
+
+본 정보는 식약처 공식 데이터에 기반한 **참고용**입니다.
+
+- 실제 복용 전 반드시 **의사·약사와 상담**하세요.
+- 응급 상황은 **119**에 즉시 연락하세요.
+- 진단·처방 등 의료 전문 영역은 본 도구의 범위 밖입니다.
+- DB 미등재가 안전을 의미하지는 않습니다 — 등록되지 않은 위험이 있을 수 있습니다.
+
+본 도구의 답변은 의료진의 전문적 판단을 대체할 수 없습니다.
+
+---
+
+## 라이선스
+
+[MIT](LICENSE)
+
+---
+
+## 출처
+
+- 식약처 의약품개요정보(e약은요) — 공공데이터포털
+- 식약처 의약품 제품 허가정보 — 공공데이터포털
+- 식약처 의약품안전사용서비스(DUR) 품목정보 — 공공데이터포털
+- 식약처 의약품안전사용서비스(DUR) 성분정보 — 공공데이터포털
+- 식약처 의약품 낱알식별 정보 — 공공데이터포털
+- 식약처 식품영양성분 DB — 공공데이터포털
+- 식약처 가공식품 원재료·알레르기 정보 — 식품안전나라
+- 식약처 회수·판매중지 식품 정보 — 식품안전나라

package/dist/core/context.d.ts

@@ -0,0 +1,17 @@
+import type { Cache } from "../shared/cache.js";
+import type { DrugClient } from "../domains/drug/client.js";
+import type { DurClient } from "../domains/dur/client.js";
+import type { PillClient } from "../domains/pill/client.js";
+import type { FoodNutritionClient, FoodSafetyClient } from "../domains/food/client.js";
+/**
+ * 모든 도구가 공유하는 의존성 컨텍스트.
+ * 서버 부팅 시 1회 생성, 모든 도구 핸들러에 전달.
+ */
+export interface ToolContext {
+    readonly drug: DrugClient;
+    readonly dur: DurClient;
+    readonly pill: PillClient;
+    readonly food: FoodNutritionClient;
+    readonly foodSafety: FoodSafetyClient | null;
+    readonly cache: Cache;
+}

package/dist/core/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/core/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":""}

package/dist/core/middleware.d.ts

@@ -0,0 +1,19 @@
+import type { ToolDefinition } from "./tool.js";
+export type ToolMiddleware = <T extends ToolDefinition>(tool: T) => T;
+/**
+ * 미들웨어를 오른쪽부터 적용하여 도구를 감싼다.
+ * compose(a, b, c)(tool)  ===  a(b(c(tool)))
+ */
+export declare function compose(...middlewares: ToolMiddleware[]): ToolMiddleware;
+/**
+ * 모든 응답 끝에 의료 면책 문구 자동 첨부.
+ */
+export declare const withDisclaimer: ToolMiddleware;
+/**
+ * 핸들러에서 throw된 에러를 MCP 에러 응답으로 변환.
+ */
+export declare const withErrorHandling: ToolMiddleware;
+/**
+ * 도구 응답을 메모리 캐시 (입력별 키). TTL 만료 시 무효화.
+ */
+export declare const withCache: (ttlMs: number) => ToolMiddleware;

package/dist/core/middleware.js

@@ -0,0 +1,82 @@
+import { MEDICAL_DISCLAIMER } from "../shared/disclaimer.js";
+/**
+ * 미들웨어를 오른쪽부터 적용하여 도구를 감싼다.
+ * compose(a, b, c)(tool)  ===  a(b(c(tool)))
+ */
+export function compose(...middlewares) {
+    return (tool) => middlewares.reduceRight((wrapped, mw) => mw(wrapped), tool);
+}
+/**
+ * 모든 응답 끝에 의료 면책 문구 자동 첨부.
+ */
+export const withDisclaimer = (tool) => {
+    const original = tool.handler;
+    return {
+        ...tool,
+        handler: async (input, ctx) => {
+            const result = await original(input, ctx);
+            return appendText(result, "\n\n" + MEDICAL_DISCLAIMER);
+        },
+    };
+};
+/**
+ * 핸들러에서 throw된 에러를 MCP 에러 응답으로 변환.
+ */
+export const withErrorHandling = (tool) => {
+    const original = tool.handler;
+    return {
+        ...tool,
+        handler: async (input, ctx) => {
+            try {
+                return await original(input, ctx);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: "text", text: `❌ ${tool.name} 실행 중 오류: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+};
+/**
+ * 도구 응답을 메모리 캐시 (입력별 키). TTL 만료 시 무효화.
+ */
+export const withCache = (ttlMs) => {
+    return (tool) => {
+        const original = tool.handler;
+        return {
+            ...tool,
+            handler: async (input, ctx) => {
+                const key = `${tool.name}:${stableStringify(input)}`;
+                const cached = ctx.cache.get(key);
+                if (cached !== undefined)
+                    return cached;
+                const result = await original(input, ctx);
+                ctx.cache.set(key, result, ttlMs);
+                return result;
+            },
+        };
+    };
+};
+function appendText(result, text) {
+    if (typeof result === "string")
+        return result + text;
+    if (result.isError)
+        return result; // 에러 응답에는 면책 첨부 안 함
+    const appended = {
+        ...result,
+        content: [...result.content, { type: "text", text }],
+    };
+    return appended;
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+}
+//# sourceMappingURL=middleware.js.map

package/dist/core/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/core/middleware.ts"],"names":[],"mappings":"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"}

package/dist/core/registry.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "./tool.js";
+export declare function getRegisteredTools(): ToolDefinition[];

package/dist/core/registry.js

@@ -0,0 +1,17 @@
+import { compose, withCache, withDisclaimer, withErrorHandling } from "./middleware.js";
+import allDomainTools from "../domains/index.js";
+const ONE_HOUR = 60 * 60 * 1000;
+/**
+ * 모든 도구에 공통 미들웨어를 적용한다.
+ * 적용 순서: 캐시 ← 면책 ← 에러처리 (밖에서 안으로)
+ *
+ * 즉 실행 시:
+ *   1) 에러처리: try/catch
+ *   2) 면책: 응답에 disclaimer 추가
+ *   3) 캐시: 입력 키로 응답 저장
+ */
+const wrapWithCommonMiddleware = compose(withErrorHandling, withDisclaimer, withCache(ONE_HOUR));
+export function getRegisteredTools() {
+    return allDomainTools.map(wrapWithCommonMiddleware);
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/core/registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACvF,OAAO,cAAc,MAAM,qBAAqB,CAAA;AAEhD,MAAM,QAAQ,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAE/B;;;;;;;;GAQG;AACH,MAAM,wBAAwB,GAAG,OAAO,CACtC,iBAAiB,EACjB,cAAc,EACd,SAAS,CAAC,QAAQ,CAAC,CACpB,CAAA;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,cAAc,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAA;AACrD,CAAC"}

package/dist/core/tool.d.ts

@@ -0,0 +1,42 @@
+import type { z } from "zod";
+import type { ToolContext } from "./context.js";
+export interface ToolResponse {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export type ToolHandlerResult = string | ToolResponse;
+/**
+ * 등록 시 사용되는 도구 인터페이스.
+ *
+ * input은 의도적으로 `any` — 함수 파라미터 타입 변성(variance) 때문에
+ * 좁은 타입으로 정의된 핸들러를 일반 배열에 담을 수 없는 문제를 회피한다.
+ * 런타임에는 schema.parse()가 타입을 보장하므로 안전.
+ *
+ * 도구 작성자는 defineTool() 헬퍼를 통해 타입 안전하게 작성한다.
+ */
+export interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly schema: z.ZodTypeAny;
+    readonly handler: (input: any, ctx: ToolContext) => Promise<ToolHandlerResult>;
+}
+/**
+ * 도구 정의 헬퍼. 작성 시점에는 schema에 따라 input 타입이 추론되어 안전.
+ *
+ * @example
+ *   export default defineTool({
+ *     name: "search_drug",
+ *     description: "...",
+ *     schema: z.object({ query: z.string() }),
+ *     handler: async (input, ctx) => { input.query 자동 추론 ... }
+ *   })
+ */
+export declare function defineTool<TSchema extends z.ZodTypeAny>(def: {
+    name: string;
+    description: string;
+    schema: TSchema;
+    handler: (input: z.infer<TSchema>, ctx: ToolContext) => Promise<ToolHandlerResult>;
+}): ToolDefinition;

package/dist/core/tool.js

@@ -0,0 +1,15 @@
+/**
+ * 도구 정의 헬퍼. 작성 시점에는 schema에 따라 input 타입이 추론되어 안전.
+ *
+ * @example
+ *   export default defineTool({
+ *     name: "search_drug",
+ *     description: "...",
+ *     schema: z.object({ query: z.string() }),
+ *     handler: async (input, ctx) => { input.query 자동 추론 ... }
+ *   })
+ */
+export function defineTool(def) {
+    return def;
+}
+//# sourceMappingURL=tool.js.map

package/dist/core/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/core/tool.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAA+B,GAKxD;IACC,OAAO,GAAqB,CAAA;AAC9B,CAAC"}

package/dist/domains/drug/alternatives.tool.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("../../core/tool.js").ToolDefinition;
+export default _default;

package/dist/domains/drug/alternatives.tool.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { defineTool } from "../../core/tool.js";
+import { truncate } from "../../shared/format.js";
+const FindAlternativesSchema = z.object({
+    drugName: z
+        .string()
+        .min(1)
+        .describe("기준 의약품 이름 (예: '타이레놀'). 이 약과 동일 주성분의 다른 제품을 찾음."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(30)
+        .optional()
+        .default(10)
+        .describe("최대 결과 개수 (기본 10)"),
+});
+export default defineTool({
+    name: "find_alternatives",
+    description: "[대체약] 입력 의약품과 동일한 주성분을 가진 다른 제품들을 검색. " +
+        "사용 케이스: '이 약 단종됐다는데 같은 약 뭐 있어?', '저렴한 동일 성분 제네릭 있어?'. " +
+        "내부 동작: 1) 약 검색 → 주성분 추출 (괄호 안) → 2) 그 성분으로 재검색.",
+    schema: FindAlternativesSchema,
+    handler: async (input, ctx) => {
+        // 1) 기준 약 검색
+        const baseSearch = await ctx.drug.search(input.drugName, 5);
+        const baseDrug = baseSearch.items[0];
+        if (!baseDrug) {
+            return `'${input.drugName}' 검색 결과 없음. 정확한 약품명 확인 필요.`;
+        }
+        // 2) 주성분 추출
+        const ingredient = ctx.drug.extractMainIngredient(baseDrug.itemName);
+        if (!ingredient) {
+            return [
+                `'${baseDrug.itemName}' 의 주성분을 자동 추출하지 못했습니다.`,
+                `💡 search_drug 결과에서 약품명 끝 괄호 안의 성분을 확인 후 그 성분명으로 다시 시도하세요.`,
+            ].join("\n");
+        }
+        // 3) 주성분으로 재검색 → 동일 성분 다른 제품
+        const alts = await ctx.drug.search(ingredient, input.limit + 1);
+        const filtered = alts.items.filter((d) => d.itemSeq !== baseDrug.itemSeq).slice(0, input.limit);
+        return formatAlternatives(baseDrug, ingredient, filtered);
+    },
+});
+function formatAlternatives(base, ingredient, alts) {
+    const header = [
+        `🔍 기준 약: ${base.itemName}`,
+        `   • 주성분: ${ingredient}`,
+        "",
+    ];
+    if (alts.length === 0) {
+        return header.concat([`동일 주성분 다른 제품 없음.`]).join("\n");
+    }
+    const lines = [...header, `📌 동일 주성분(${ingredient}) 다른 제품 ${alts.length}건:`, ""];
+    alts.forEach((d, i) => {
+        lines.push(`${i + 1}. ${d.itemName}`);
+        lines.push(`   • 제조/수입사: ${d.entpName}`);
+        lines.push(`   • 품목코드: ${d.itemSeq}`);
+        if (d.efcyQesitm)
+            lines.push(`   • 효능: ${truncate(d.efcyQesitm, 80)}`);
+        lines.push("");
+    });
+    return lines.join("\n");
+}
+//# sourceMappingURL=alternatives.tool.js.map

package/dist/domains/drug/alternatives.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alternatives.tool.js","sourceRoot":"","sources":["../../../src/domains/drug/alternatives.tool.ts"],"names":[],"mappings":"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"}

package/dist/domains/drug/client.d.ts

@@ -0,0 +1,21 @@
+import type { HttpClient } from "../../shared/http-client.js";
+import type { DrugSearchResult, EasyDrugItem } from "./types.js";
+/**
+ * 의약품 정보 조회 클라이언트.
+ *
+ * 사용 API:
+ * - DrbEasyDrugInfoService (e약은요): 일반의약품 효능/용법/주의/부작용
+ */
+export declare class DrugClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    search(query: string, limit?: number): Promise<DrugSearchResult>;
+    getByItemSeq(itemSeq: string): Promise<EasyDrugItem | undefined>;
+    /**
+     * 단일 약품의 주성분명을 추출 — itemName 끝의 괄호 안 텍스트.
+     * 예: "타이레놀정500밀리그람(아세트아미노펜)" → "아세트아미노펜"
+     */
+    extractMainIngredient(itemName: string): string | undefined;
+    private fetch;
+    private assertSuccess;
+}

package/dist/domains/drug/client.js

@@ -0,0 +1,47 @@
+import { ApiError } from "../../shared/errors.js";
+const E_DRUG_BASE = "https://apis.data.go.kr/1471000/DrbEasyDrugInfoService/getDrbEasyDrugList";
+/**
+ * 의약품 정보 조회 클라이언트.
+ *
+ * 사용 API:
+ * - DrbEasyDrugInfoService (e약은요): 일반의약품 효능/용법/주의/부작용
+ */
+export class DrugClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async search(query, limit = 10) {
+        return this.fetch({ itemName: query, numOfRows: limit });
+    }
+    async getByItemSeq(itemSeq) {
+        const result = await this.fetch({ itemSeq, numOfRows: 1 });
+        return result.items[0];
+    }
+    /**
+     * 단일 약품의 주성분명을 추출 — itemName 끝의 괄호 안 텍스트.
+     * 예: "타이레놀정500밀리그람(아세트아미노펜)" → "아세트아미노펜"
+     */
+    extractMainIngredient(itemName) {
+        const match = itemName.match(/\(([^()]+)\)\s*$/);
+        return match?.[1]?.trim();
+    }
+    async fetch(params) {
+        const data = await this.http.getJson({
+            url: E_DRUG_BASE,
+            params: { ...params, pageNo: 1 },
+        });
+        this.assertSuccess(data);
+        return {
+            totalCount: data.body?.totalCount ?? 0,
+            items: data.body?.items ?? [],
+        };
+    }
+    assertSuccess(data) {
+        const code = data.header?.resultCode;
+        if (code !== undefined && code !== "00") {
+            throw new ApiError(`식약처 API 오류 (${code}): ${data.header?.resultMsg ?? "unknown"}`, undefined, E_DRUG_BASE);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/domains/drug/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/domains/drug/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAGjD,MAAM,WAAW,GAAG,2EAA2E,CAAA;AAE/F;;;;;GAKG;AACH,MAAM,OAAO,UAAU;IACQ;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,KAAK,GAAG,EAAE;QACpC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAA;IAC1D,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,OAAe;QAChC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAA;QAC1D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IACxB,CAAC;IAED;;;OAGG;IACH,qBAAqB,CAAC,QAAgB;QACpC,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAA;QAChD,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAA;IAC3B,CAAC;IAEO,KAAK,CAAC,KAAK,CAAC,MAAuC;QACzD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAsB;YACxD,GAAG,EAAE,WAAW;YAChB,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE;SACjC,CAAC,CAAA;QAEF,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAA;QAExB,OAAO;YACL,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,IAAI,CAAC;YACtC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;SAC9B,CAAA;IACH,CAAC;IAEO,aAAa,CAAC,IAAyB;QAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,UAAU,CAAA;QACpC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACxC,MAAM,IAAI,QAAQ,CAChB,eAAe,IAAI,MAAM,IAAI,CAAC,MAAM,EAAE,SAAS,IAAI,SAAS,EAAE,EAC9D,SAAS,EACT,WAAW,CACZ,CAAA;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/domains/drug/detail.tool.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("../../core/tool.js").ToolDefinition;
+export default _default;