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瑜??댁슜???꾩껜 ?ㅽ뻾??沅뚯옣?⑸땲??

# ?꾩껜 ?쒖뒪??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 :dap-gateway:bootRun
• Tool ?쒕쾭 湲곕룞 (?? other ??:
  • ./gradlew :dap-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???붽뎄?⑸땲?? dap-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 ?ㅼ젙 ?뚯씪???꾨옒?€ 媛숈씠 ?깅줉?⑸땲??

  "mcpServers": {
    "dap-gateway": {
      "command": "java",
      "args": ["C:/?덈?寃쎈줈/dap-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% 蹂댁옣?⑸땲??

@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 紐⑤뱢???앹꽦?⑸땲?? ?대뜑 援ъ“, 鍮뚮뱶 ?ㅽ겕由쏀듃, 媛곸쥌 ?꾨줈?쇳떚 諛??꾩빱 ?ㅼ젙源뚯? ?꾨꼍?섍쾶 ?명똿?⑸땲??

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

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

2???앹꽦??紐⑤뱢???덈줈????Function)??異붽????? ToolScaffolder

?대끂?뚯씠??@McpTool, @McpFunction)???꾨꼍???щ┛ Service?€ ?낆텧??DTO 肄붾뱶瑜?吏€?뺣맂 紐⑤뱢 ?⑦궎吏€ 猷곗뿉 留욎떠 ?먮룞 ?앹꽦?⑸땲??

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

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

---

?⑦궎吏€ 援ъ“ (Package Structure)

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

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