# AXHUB Backend

Spring Boot 湲곕컲 AXHUB 愿由ъ옄 諛깆뿏??API ?쒕쾭 諛?MCP(Model Context Protocol) Gateway / Tool 遺꾩궛 ?쒕쾭 ?꾨줈?앺듃?낅땲??

---

##  ?꾪궎?띿쿂 媛쒖슂 (Architecture Overview)

AXHUB Backend???ш쾶 2媛쒖쓽 二쇱슂 ?좏뵆由ъ??댁뀡 怨꾩링?쇰줈 遺꾨━ ?댁쁺?⑸땲??

1. **MCP Gateway (`AxHubGatewayApplication`)**: ?댁옣????UI(AI 梨쀫큸, ?ㅼ틦?대뜑) ?쒓났 諛??몃? LLM(Claude, GPT ?? ?쒕쾭??MCP ?듭떊??諛쏆븘 ?대? Tool ?쒕쾭?ㅻ줈 遺꾨같(?쇱슦???섎뒗 ?덈툕 ?쒕쾭 (?ы듃: 8081)
2. **MCP Tool (`AxHubToolApplication`)**: ?ㅼ젣 ?덇굅???쒖뒪??MCI, EAI ??怨??듭떊?섏뿬 鍮꾩쫰?덉뒪 濡쒖쭅(寃곗젣, ?닿??좎껌 ?????섑뻾?섎뒗 ?대뙌???쒕쾭 (?ы듃: 8082~8085 ??遺꾩궛 援ъ꽦 媛??

---

##  ?섍꼍 (Environment)

| ??ぉ | 踰꾩쟾 |
|------|------|
| Java | 21 |
| Spring Boot | 4.0.5 |
| Build Tool | Gradle |
| 二쇱슂 湲곗닠 ?ㅽ깮 | MyBatis, Lombok, MapStruct, P6Spy |
| ?곗씠?곕쿋?댁뒪 | H2 (in-memory, 濡쒖뺄 媛쒕컻?? |
| ?몄뀡/罹먯떆 ??μ냼 | Redis |
| **?μ븷 寃⑸━ / ?쒖뼱** | **Resilience4j (RateLimiter, CircuitBreaker, Retry)** |
| **硫붿떆吏 ??* | **Kafka (?몃옒????＜ ???湲곗뿴 ?꾪솚??** |

---

## ???ㅽ뻾 諛⑸쾿 (How to Run)

### 1. Docker Compose瑜??댁슜???꾩껜 ?ㅽ뻾 (沅뚯옣)
留덉씠?щ줈?쒕퉬???꾪궎?띿쿂 ?뱀꽦???щ윭 媛쒖쓽 Tool Pod???꾩슂?섎?濡? Docker Compose瑜??댁슜???꾩껜 ?ㅽ뻾??沅뚯옣?⑸땲??

```bash
# ?꾩껜 ?쒖뒪??Gateway + Redis + 紐⑤뱺 Tool Pod) 鍮뚮뱶 諛?諛깃렇?쇱슫???ㅽ뻾
./gradlew build -x test
docker compose up -d --build
```
- **Gateway (Chat UI & ?쇱슦??**: `http://localhost:8281`
- Gateway媛 ?⑤㈃ ?댁옣??梨쀫큸 ??UI(`http://localhost:8281/chat.html`)???묒냽?섏뿬 諛붾줈 ?뚯뒪?명븷 ???덉뒿?덈떎.

### 2. 濡쒖뺄 媛쒕컻 ??媛쒕퀎 ?ㅽ뻾 (IntelliJ / Gradle)
媛쒕컻 以??뱀젙 紐⑤뱢留??꾩썙 ?붾쾭源낇빐????寃쎌슦 ?꾨옒? 媛숈씠 ?ㅽ뻾?⑸땲??

- **Gateway ?쒕쾭 湲곕룞:**
  - `./gradlew :axhub-gateway:bootRun`
- **Tool ?쒕쾭 湲곕룞 (?? other ??:**
  - `./gradlew :axhub-tool-other:bootRun`
  - Tool ?쒕쾭媛 湲곕룞?섎㈃ ?먮룞?쇰줈 Gateway???먯떊???깅줉(Auto-Registration)?⑸땲??


---

## ?쨼 AI Agent ?곕룞 ?꾪궎?띿쿂 (Spring AI & MCP)

蹂??쒖뒪?쒖? **?ы듃??Two-Track) AI ?곕룞 ?꾪궎?띿쿂**瑜??쒓났?섏뿬 濡쒖뺄 媛쒕컻 ?섍꼍怨??꾨줈?뺤뀡 ?섍꼍 紐⑤몢瑜??꾨꼍?섍쾶 吏?먰빀?덈떎.

### 1. ?댁옣????梨쀫큸 (Spring AI 湲곕컲) - NEW! ?럦
媛??鍮좊Ⅴ怨?吏곴??곸쑝濡?AI ?먯씠?꾪듃瑜??뚯뒪?명븷 ???덈뒗 ?댁옣??梨쀫큸 ?붾㈃???쒓났?⑸땲?? Gateway ?쒕쾭 ?먯껜??**Spring AI (spring-ai-starter-mcp-server-webmvc)** 媛 ?곕룞?섏뼱 ?덉뼱 蹂꾨룄???뚯씠???ㅽ겕由쏀듃???몃? ???놁씠??利됯컖?곸씤 ?뚯뒪?멸? 媛?ν빀?덈떎.

- **?묒냽 諛⑸쾿**: Gateway(Docker) 湲곕룞 ??釉뚮씪?곗??먯꽌 `http://localhost:8281/chat.html` ?묒냽
- **?숈옉 諛⑹떇**: 
  1. ?ъ슜?먭? 吏덈Ц???낅젰?섎㈃ ?대? `ChatClient` (Gemini API ??濡??꾩넚
  2. Spring AI媛 ?대? ?덉??ㅽ듃由ъ쓽 Tool 紐⑸줉??遺꾩꽍?섏뿬 ?꾩슂??Tool ?먯깋
  3. LLM??Tool ?몄텧 ?먮떒 ?? Gateway??`ExecuteService`瑜?嫄곗퀜 Tool Pod??湲곕뒫??吏곸젒 ?ㅽ뻾
  4. 寃곌낵瑜?LLM???ㅼ떆 ?댁꽍?섏뿬 ?ъ슜?먯뿉寃??먯뿰?대줈 ?묐떟

### 2. ?꾨줈?뺤뀡 ?대씪?곕뱶 AI (Google Cloud Agent Builder ?? ?곕룞
?ㅼ젣 ?쇱씠釉??쒕퉬?ㅼ뿉???숈옉?섎뒗 ?대씪?곕뱶 Agent Builder??REST API 湲곕컲??OpenAPI Spec???붽뎄?⑸땲?? 
`axhub-gateway`???대? **Agent Builder 洹쒓꺽??REST API(`/mcp/api/v1/tools/call`)瑜??ㅼ씠?곕툕濡??쒓났**?섎?濡? 蹂꾨룄??釉뚮┸吏???대뙌???놁씠 Endpoint URL怨?Swagger(OpenAPI) 臾몄꽌留??대씪?곕뱶 肄섏넄???깅줉?섎㈃ 利됱떆 ?쇱씠釉?梨쀫큸/?먯씠?꾪듃濡??쒕퉬?ㅽ븷 ???덉뒿?덈떎.

### 3. (Legacy) 濡쒖뺄 肄붾뵫 AI (Cursor, Claude Desktop ?? ?곕룞
?쒖? MCP ?듭떊(Stdio)???붽뎄?섎뒗 濡쒖뺄 AI ?먯씠?꾪듃瑜??꾪빐 ?먮컮 湲곕컲??釉뚮┸吏 ?ㅽ겕由쏀듃(`McpBridge.java`)瑜??댁옣?섍퀬 ?덉뒿?덈떎. 釉뚮┸吏媛 Stdio ?붿껌??HTTP濡?蹂?섑븯??濡쒖뺄 ?섍꼍??Gateway濡??꾨떖?⑸땲??

- **?ㅼ젙 諛⑸쾿**: IDE??`mcp_config.json` ?ㅼ젙 ?뚯씪???꾨옒? 媛숈씠 ?깅줉?⑸땲??
  ```json
  "mcpServers": {
    "axhub-gateway": {
      "command": "java",
      "args": ["C:/?덈?寃쎈줈/axhub-backend-main/McpBridge.java"]
    }
  }
  ```

---

##  鍮꾧났媛?Tool 愿由?諛?Fallback ?곕룞 (Visibility & Routing)

????쒖뒪?쒖? MSA 蹂댁븞 諛??꾪궎?띿쿂 ?먯튃???곕씪 Tool??**?덉??ㅽ듃由??깅줉 ?щ?(?쇱슦??**? **API ?몄텧 ?щ?(媛?쒖꽦)**瑜??꾨꼍??遺꾨━?섏뿬 愿由ы빀?덈떎.

1. **`visible = false`**: 
   ?덉??ㅽ듃由ъ뿉 ?뺤긽?곸쑝濡??깅줉?섏뼱 寃뚯씠?몄썾?닿? ?숈쟻?쇰줈 ?쇱슦?낇븯吏留? ?대씪?댁뼵?몄뿉寃??쒓났?섎뒗 `/tools/list` API 紐⑸줉?먯꽌???④꺼吏묐땲??
2. **`register = false`**: 
   ?대? ?덉??ㅽ듃由?Redis)?????뺣낫瑜??깅줉?섏? ?딆뒿?덈떎 (?몃? ?덉??ㅽ듃由щ? ?낆옄?곸쑝濡??ъ슜??寃쎌슦 ??. 
   ??寃쎌슦 寃뚯씠?몄썾?대뒗 `application.properties`??`mcp.gateway.fallback.routes` ?ㅼ젙??李몄“?섏뿬 **Fallback ?뺤쟻 ?쇱슦??*???섑뻾?섎?濡??곕룞??100% 蹂댁옣?⑸땲??

```java
@McpFunction(
    name = "secret_tool",
    visible = false, // 紐⑸줉 ?④? ?щ? (湲곕낯媛? true)
    register = false // ?대? Redis ?깅줉 ?щ? (湲곕낯媛? true)
)
```

---

## ?썳截??쒖뒪???덉젙??諛??ㅽ듃?뚰겕 ?쒖뼱 (Resilience & Network)

MSA 諛??몃? ?쒖뒪??MCI) ?곕룞 ?섍꼍???덉젙?깆쓣 ?꾪빐 ?꾨꼍??3-Tier 諛⑹뼱 泥닿퀎瑜?援ъ텞?덉뒿?덈떎.

1. **Gateway ?쇱슦??諛⑹뼱 (Timeout & Fallback):**
   - MCP ?쇱슦??`McpRouterController`) ?⑥뿉 1珥???꾩븘?껋쓣 媛뺤젣 ?곸슜?섏뿬 ?뱀젙 Tool Pod???묐떟 吏?곗씠 ?꾩껜 ?쒖뒪???μ븷濡??댁뼱吏??寃껋쓣 諛⑹??섍퀬 ?좎냽?섍쾶 ?뺤쟻 Fallback ?쇱슦?낆쑝濡??꾪솚?⑸땲??
2. **MCI ?ㅽ듃?뚰겕 ?덉젙??(HTTP/1.1 Downgrade):**
   - 湲곗〈 HTTP/2 ?ъ슜 ???덇굅???쒖뒪???곕룞 以?媛꾪뿉?곸쑝濡?諛쒖깮?섎뜕 `RST_STREAM` ?ㅻ쪟瑜??먯쿇 李⑤떒?섍린 ?꾪빐, MCI ?꾩슜 `HttpEimsSender`?먮뒗 怨좊룄濡?理쒖쟻?붾맂 **HTTP/1.1 ?꾩슜 而ㅻ꽖???(Factory)**??怨좎젙 ?곸슜?섏뼱 ?ㅽ듃?뚰겕 ?⑥젅??諛⑹??⑸땲??
3. **Resilience4j 湲곕컲 ?몃옒???쒖뼱:**
   - **Gateway 怨꾩링 (?숈쟻 諛⑹뼱):** Tool ?깅줉 ???쒖텧??SLA 硫뷀??곗씠?곕? 湲곕컲?쇰줈 ?숈쟻 CircuitBreaker 諛?RateLimiter瑜?媛?숉븯硫? ?쒓퀎移?珥덇낵 ??Kafka ?먮줈 鍮꾨룞湲??꾪솚?⑸땲??
   - **Tool 怨꾩링 (?뺤쟻 諛⑹뼱):** ?덇굅??而ㅻ꽖???대???`@CircuitBreaker`, `@RateLimiter` ?대끂?뚯씠??湲곕컲???μ븷 ?꾪뙆 李⑤떒 濡쒖쭅??2李⑥쟻?쇰줈 媛?숇맗?덈떎.

---

##  紐⑤뱢(Pod) 諛?Tool 肄붾뱶 ?먮룞 ?앹꽦 (Scaffolders)

?덈줈???꾨찓?몄쓽 湲곕뒫??異붽?????諛쒖깮?섎뒗 諛섎났?곸씤 ?ㅼ젙(蹂댁씪?ы뵆?덉씠?? ?ㅼ젙 ?뚯씪 蹂듭궗 ????1珥?留뚯뿉 ?먮룞?뷀븯湲??꾪빐 **AXHUB Developer Portal (Web UI)** 諛?**CLI ?ㅼ틦?대뜑 2醫?*???쒓났?⑸땲??

###  1. AXHUB Developer Portal (Web UI) - 媛??異붿쿇?섎뒗 諛⑹떇!
?댁젣 ???댁긽 ?곕??먯뿉??紐낅졊?대? 移??꾩슂媛 ?놁뒿?덈떎. Gateway 紐⑤뱢???댁옣?????붾㈃?먯꽌 鍮덉뭏留?梨꾩슦硫?肄붾뱶媛 留덈쾿泥섎읆 李랁? ?섏샃?덈떎.

1. **?묒냽 諛⑸쾿**: Gateway ?쒕쾭 湲곕룞 ??釉뚮씪?곗??먯꽌 `http://localhost:8081/admin/scaffold.html` ?묒냽
2. **Pod (紐⑤뱢) ?앹꽦 ??*: 紐⑤뱢紐??? hr)怨??ы듃留??낅젰?섎㈃ ?낅┰?곸씤 Spring Boot 紐⑤뱢???붾젆?좊━遺??鍮뚮뱶 ?ㅽ겕由쏀듃源뚯? ?꾨꼍???앹꽦?⑸땲??
3. **Tool (湲곕뒫) ?앹꽦 ??*: ?앹꽦??紐⑤뱢???덈줈?????쒕퉬??DTO) 肄붾뱶瑜??먮룞?쇰줈 二쇱엯?⑸땲??

### 2. CLI ?ㅼ틦?대뜑 (湲곗〈 ?곕???諛⑹떇)
???붾㈃???ъ슜?????녿뒗 ?섍꼍?닿굅???곕??먯씠 ?듭닕??寃쎌슦, ?꾨옒 紐낅졊?대? ?듯빐 CLI 留덈쾿?щ? ?ъ슜?????덉뒿?덈떎.

### 1???덈줈??Pod(紐⑤뱢) ?꾩껜瑜??앹꽦???? `PodScaffolder`
?덈줈???꾨찓???? 寃곗젣, HR)???꾪븳 ?꾩쟾???낅┰?곸씤 Spring Boot 紐⑤뱢???앹꽦?⑸땲?? ?대뜑 援ъ“, 鍮뚮뱶 ?ㅽ겕由쏀듃, 媛곸쥌 ?꾨줈?쇳떚 諛??꾩빱 ?ㅼ젙源뚯? ?꾨꼍?섍쾶 ?명똿?⑸땲??

```bash
# ?ъ슜踰? javac濡?而댄뙆?????ㅽ뻾
javac -encoding UTF-8 axhub-common/src/main/java/io/shinhanlife/axhub/common/util/PodScaffolder.java
java -cp axhub-common/src/main/java io.shinhanlife.axhub.common.util.PodScaffolder [紐⑤뱢紐? [?ы듃踰덊샇]

# ?ㅽ뻾 ?덉떆 (axhub-tool-hr 紐⑤뱢??8086 ?ы듃濡??앹꽦)
java -cp axhub-common/src/main/java io.shinhanlife.axhub.common.util.PodScaffolder hr 8086
```

### 2???앹꽦??紐⑤뱢???덈줈????Function)??異붽????? `ToolScaffolder`
?대끂?뚯씠??`@McpTool`, `@McpFunction`)???꾨꼍???щ┛ Service? ?낆텧??DTO 肄붾뱶瑜?吏?뺣맂 紐⑤뱢 ?⑦궎吏 猷곗뿉 留욎떠 ?먮룞 ?앹꽦?⑸땲??

```bash
# ?ъ슜踰? javac濡?而댄뙆?????ㅽ뻾
javac -encoding UTF-8 axhub-common/src/main/java/io/shinhanlife/axhub/common/util/ToolScaffolder.java
java -cp axhub-common/src/main/java io.shinhanlife.axhub.common.util.ToolScaffolder [Tool?대쫫] [?명꽣?섏씠?짪D] "[湲곕뒫?ㅻ챸]" "[洹몃９紐?" "[?듭떊諛⑹떇]" "[紐⑤뱢紐?"

# ?ㅽ뻾 ?덉떆 (payment 紐⑤뱢??寃곗젣 ?뱀씤 湲곕뒫 異붽?)
java -cp axhub-common/src/main/java io.shinhanlife.axhub.common.util.ToolScaffolder PaymentApproval PAY_001 "寃곗젣 ?뱀씤 泥섎━ 湲곕뒫" "COMMON" "HTTP" "axhub-tool-payment"
```

---

##  ?⑦궎吏 援ъ“ (Package Structure)

```text
axhub-backend-main (Root)
?쒋?? axhub-gateway           #  MCP ?쇱슦???덈툕 ?쒕쾭 (?몃? LLM怨??듭떊 諛?Tool 遺꾨같)
?쒋?? axhub-common            # 怨듯넻 紐⑤뱢 (Security, Session, Config ??
?쒋?? axhub-tool-core         # Tool 怨듯넻 湲곕뒫 (AbstractMcpToolService, Annotation, Scaffolder)
?쒋?? axhub-tool-email        # [Tool] ?대찓??諛쒖넚 ?뱁솕 ?대뙌??紐⑤뱢
?쒋?? axhub-tool-sms          # [Tool] SMS 諛쒖넚 ?뱁솕 ?대뙌??紐⑤뱢
?쒋?? axhub-tool-payment      # [Tool] 寃곗젣 鍮꾩쫰?덉뒪 ?대뙌??紐⑤뱢 (Scaffolded)
?붴?? axhub-tool-other        # [Tool] 湲고? 鍮꾩쫰?덉뒪(泥?뎄, 怨꾩빟, 怨좉컼, HR ?? ?대뙌??紐⑤뱢
```

*(李멸퀬: 湲곗〈 ?⑥씪 紐⑤뱢 ?꾨줈?앺듃?먯꽌 留덉씠?щ줈?쒕퉬???뺤옣???꾪빐 紐⑤뱢蹂꾨줈 遺꾨━?섏뿀?쇰ŉ, 媛?Tool ?쒕쾭???낅┰?곸쑝濡??뺤옣 諛?諛고룷?????덉뒿?덈떎.)*