kimhyungsik/ax_hub_mcp_tool

Fork 1

Files

jade 046c9dee75 fix: Restore and convert README.md to UTF-8

2026-07-16 20:55:11 +09:00

11 KiB

Raw Blame History

AXHUB Backend

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

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

AXHUB Backend??3媛쒖쓽 二쇱슂 ?좏뵆由ъ??댁뀡?쇰줈 遺꾨━ ?댁쁺?⑸땲??

AXHUB Admin (AxHubAdminApplication): 愿由ъ옄 ???붾㈃???꾪븳 REST API ?쒕쾭
MCP Gateway (AxHubGatewayApplication): ?몃? LLM(Claude, GPT ?? ?쒕쾭??MCP ?듭떊??諛쏆븘, ?대? Tool ?쒕쾭?ㅻ줈 遺꾨같(?쇱슦???섎뒗 ?덈툕 ?쒕쾭 (?ы듃: 8081)
MCP Tool (AxHubToolApplication): ?ㅼ젣 ?덇굅???쒖뒪??MCI, EAI ??怨??듭떊?섏뿬 鍮꾩쫰?덉뒪 濡쒖쭅(寃곗젣, ?닿??좎껌 ?????섑뻾?섎뒗 ?대뙌???쒕쾭 (?ы듃: 8082~8084 遺꾩궛 援ъ꽦 媛??

?섍꼍 (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. Gateway & Tool ?쒕쾭 ?ㅽ뻾 (MCP ?곕룞??

Gateway ?쒕쾭 湲곕룞:
- ./gradlew bootRun -PmainClass=io.shinhanlife.AxHubGatewayApplication (湲곕낯 ?ы듃: 8081)
Tool ?쒕쾭 湲곕룞 (?꾩슂???곕씪 N? ?ㅼ????꾩썐 媛??:
- ./gradlew bootRun -PmainClass=io.shinhanlife.AxHubToolApplication --args="--server.port=8082"
- Tool ?쒕쾭媛湲곕룞?섎㈃ ?먮룞?쇰줈 Gateway(8081)???먯떊???깅줉(Auto-Registration)?⑸땲??
- (?좏깮) ?뱀젙 Tool 洹몃９留??ㅽ뻾?섍린:
  - ?낅Т ?뱀꽦???곕씪 ?몃텇?붾맂 洹몃９???랁븳 Tool留??꾩슦怨??띕떎硫? ?ㅽ뻾 ?몄닔??`--mcp.tool.target=洹몃９紐???異붽??⑸땲??
  - 吏?먮릺??洹몃９紐?
    - NOTIFICATION: ?대찓?? SMS 諛쒖넚
    - CLAIM: 泥?뎄 泥섎━, ?ъ궗 ?곹깭 議고쉶
    - POLICY: 利앷텒 諛쒗뻾, 諛쒗뻾 媛???щ? 議고쉶
    - HR: ?닿? ?깅줉, ?곗감 媛?닔 議고쉶
    - CONTRACT: 怨꾩빟 ?곹깭, 怨꾩빟 ?곸꽭 議고쉶
    - CUSTOMER: 怨좉컼 ?깃툒, 怨좉컼 ?곸꽭 ?뺣낫 議고쉶
  - IntelliJ IDEA: Run/Debug Configurations AxHubToolApplication Program arguments ??--mcp.tool.target=NOTIFICATION ?낅젰

2. Admin 愿由ъ옄 ?쒕쾭 ?ㅽ뻾

Admin ?쒕쾭 湲곕룞:
- ./gradlew bootRun -PmainClass=io.shinhanlife.AxHubAdminApplication (?ы듃: 8080)

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

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

1. 濡쒖뺄 肄붾뵫 AI (Antigravity, Cursor, Claude Desktop ?? ?곕룞

?쒖? MCP ?듭떊(Stdio)???붽뎄?섎뒗 濡쒖뺄 AI ?먯씠?꾪듃瑜??꾪빐 ?먮컮 湲곕컲??釉뚮┸吏 ?ㅽ겕由쏀듃(McpBridge.java)瑜??댁옣?섍퀬 ?덉뒿?덈떎. 釉뚮┸吏媛 Stdio ?붿껌??HTTP濡?蹂?섑븯??濡쒖뺄 ?섍꼍??Gateway(?ы듃: 8281)濡??꾨떖?⑸땲??

?ㅼ젙 諛⑸쾿: IDE??mcp_config.json ?ㅼ젙 ?뚯씪???꾨옒? 媛숈씠 ?깅줉?⑸땲??

"mcpServers": {
  "axhub-gateway": {
    "command": "java",
    "args": ["C:/?덈?寃쎈줈/axhub-backend-main/McpBridge.java"]
  }
}

**?뱀젙 移댄뀒怨좊━ ???꾪꽣留?*: McpBridge.java ?대???URI ?뚮씪誘명꽣(?categoryKey=common)瑜??섏젙?섏뿬 ?먰븯???꾨찓?몄쓽 ?대쭔 ?좏깮?곸쑝濡?AI?먭쾶 ?숈뒿?쒗궗 ???덉뒿?덈떎.

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) 臾몄꽌留??대씪?곕뱶 肄섏넄???깅줉?섎㈃利됱떆 ?쇱씠釉?梨쀫큸/?먯씠?꾪듃濡??쒕퉬?ㅽ븷 ???덉뒿?덈떎.

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

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

visible = false: ?덉??ㅽ듃由ъ뿉 ?뺤긽?곸쑝濡??깅줉?섏뼱 寃뚯씠?몄썾?닿? ?숈쟻?쇰줈 ?쇱슦?낇븯吏留? ?대씪?댁뼵?몄뿉寃??쒓났?섎뒗 /tools/list API 紐⑸줉?먯꽌???④꺼吏묐땲??
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 諛⑹뼱 泥닿퀎瑜?援ъ텞?덉뒿?덈떎.

Gateway ?쇱슦??諛⑹뼱 (Timeout & Fallback):
- MCP ?쇱슦??McpRouterController) ?⑥뿉 1珥???꾩븘?껋쓣 媛뺤젣 ?곸슜?섏뿬 ?뱀젙 Tool Pod???묐떟 吏?곗씠 ?꾩껜 ?쒖뒪???μ븷濡??댁뼱吏??寃껋쓣 諛⑹??섍퀬 ?좎냽?섍쾶 ?뺤쟻 Fallback ?쇱슦?낆쑝濡??꾪솚?⑸땲??
MCI ?ㅽ듃?뚰겕 ?덉젙??(HTTP/1.1 Downgrade):
- 湲곗〈 HTTP/2 ?ъ슜 ???덇굅???쒖뒪???곕룞 以?媛꾪뿉?곸쑝濡?諛쒖깮?섎뜕 RST_STREAM ?ㅻ쪟瑜??먯쿇 李⑤떒?섍린 ?꾪빐, MCI ?꾩슜 HttpEimsSender?먮뒗 怨좊룄濡?理쒖쟻?붾맂 HTTP/1.1 ?꾩슜 而ㅻ꽖???(Factory)??怨좎젙 ?곸슜?섏뼱 ?ㅽ듃?뚰겕 ?⑥젅??諛⑹??⑸땲??
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 紐⑤뱢???댁옣?????붾㈃?먯꽌 鍮덉뭏留?梨꾩슦硫?肄붾뱶媛留덈쾿泥섎읆 李랁? ?섏샃?덈떎.

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

2. CLI ?ㅼ틦?대뜑 (湲곗〈 ?곕???諛⑹떇)

???붾㈃???ъ슜?????녿뒗 ?섍꼍?닿굅???곕??먯씠 ?듭닕??寃쎌슦, ?꾨옒 紐낅졊?대? ?듯빐 CLI 留덈쾿?щ? ?ъ슜?????덉뒿?덈떎.

1???덈줈??Pod(紐⑤뱢) ?꾩껜瑜??앹꽦???? `PodScaffolder`

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

# ?ъ슜踰? 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 肄붾뱶瑜?吏?뺣맂 紐⑤뱢 ?⑦궎吏猷곗뿉 留욎떠 ?먮룞 ?앹꽦?⑸땲??

# ?ъ슜踰? 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)

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 ?쒕쾭???낅┰?곸쑝濡??뺤옣 諛?諛고룷?????덉뒿?덈떎.)

11 KiB Raw Blame History Unescape Escape