diff --git a/README.md b/README.md index 56324d0..4c539c9 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,11 @@ Spring Boot 湲곕컲 AXHUB 愿€由ъ옄 諛깆뿏??API ?쒕쾭 諛?MCP(Model C ## ?꾪궎?띿쿂 媛쒖슂 (Architecture Overview) -AXHUB Backend???ш쾶 2媛쒖쓽 二쇱슂 ?좏뵆由ъ??댁뀡 怨꾩링?쇰줈 遺꾨━ ?댁쁺?⑸땲?? +AXHUB Backend??3媛쒖쓽 二쇱슂 ?좏뵆由ъ??댁뀡?쇰줈 遺꾨━ ?댁쁺?⑸땲?? -1. **MCP Gateway (`AxHubGatewayApplication`)**: ?댁옣????UI(AI 梨쀫큸, ?ㅼ틦?대뜑) ?쒓났 諛??몃? LLM(Claude, GPT ?? ?쒕쾭??MCP ?듭떊??諛쏆븘 ?대? Tool ?쒕쾭?ㅻ줈 遺꾨같(?쇱슦???섎뒗 ?덈툕 ?쒕쾭 (?ы듃: 8081) -2. **MCP Tool (`AxHubToolApplication`)**: ?ㅼ젣 ?덇굅???쒖뒪??MCI, EAI ??怨??듭떊?섏뿬 鍮꾩쫰?덉뒪 濡쒖쭅(寃곗젣, ?닿??좎껌 ?????섑뻾?섎뒗 ?대뙌???쒕쾭 (?ы듃: 8082~8085 ??遺꾩궛 援ъ꽦 媛€?? +1. **AXHUB Admin (`AxHubAdminApplication`)**: 愿€由ъ옄 ???붾㈃???꾪븳 REST API ?쒕쾭 +2. **MCP Gateway (`AxHubGatewayApplication`)**: ?몃? LLM(Claude, GPT ?? ?쒕쾭??MCP ?듭떊??諛쏆븘, ?대? Tool ?쒕쾭?ㅻ줈 遺꾨같(?쇱슦???섎뒗 ?덈툕 ?쒕쾭 (?ы듃: 8081) +3. **MCP Tool (`AxHubToolApplication`)**: ?ㅼ젣 ?덇굅???쒖뒪??MCI, EAI ??怨??듭떊?섏뿬 鍮꾩쫰?덉뒪 濡쒖쭅(寃곗젣, ?닿??좎껌 ?????섑뻾?섎뒗 ?대뙌???쒕쾭 (?ы듃: 8082~8084 遺꾩궛 援ъ꽦 媛€?? --- @@ -30,60 +31,50 @@ AXHUB Backend???ш쾶 2媛쒖쓽 二쇱슂 ?좏뵆由ъ??댁뀡 怨꾩링?쇰줈 ## ???ㅽ뻾 諛⑸쾿 (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) -媛쒕컻 以??뱀젙 紐⑤뱢留??꾩썙 ?붾쾭源낇빐????寃쎌슦 ?꾨옒?€ 媛숈씠 ?ㅽ뻾?⑸땲?? - +### 1. Gateway & Tool ?쒕쾭 ?ㅽ뻾 (MCP ?곕룞?? - **Gateway ?쒕쾭 湲곕룞:** - - `./gradlew :dap-gateway:bootRun` -- **Tool ?쒕쾭 湲곕룞 (?? other ??:** - - `./gradlew :dap-tool-other:bootRun` - - Tool ?쒕쾭媛€ 湲곕룞?섎㈃ ?먮룞?쇰줈 Gateway???먯떊???깅줉(Auto-Registration)?⑸땲?? - + - `./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 ?곕룞 ?꾪궎?띿쿂 (Spring AI & MCP) +## ?쨼 AI Agent ?곕룞 ?꾪궎?띿쿂 (MCP & Agent Builder) 蹂??쒖뒪?쒖? **?ы듃??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濡??꾨떖?⑸땲?? +### 1. 濡쒖뺄 肄붾뵫 AI (Antigravity, Cursor, Claude Desktop ?? ?곕룞 +?쒖? MCP ?듭떊(Stdio)???붽뎄?섎뒗 濡쒖뺄 AI ?먯씠?꾪듃瑜??꾪빐 ?먮컮 湲곕컲??釉뚮┸吏€ ?ㅽ겕由쏀듃(`McpBridge.java`)瑜??댁옣?섍퀬 ?덉뒿?덈떎. 釉뚮┸吏€媛€ Stdio ?붿껌??HTTP濡?蹂€?섑븯??濡쒖뺄 ?섍꼍??Gateway(?ы듃: 8281)濡??꾨떖?⑸땲?? - **?ㅼ젙 諛⑸쾿**: IDE??`mcp_config.json` ?ㅼ젙 ?뚯씪???꾨옒?€ 媛숈씠 ?깅줉?⑸땲?? ```json "mcpServers": { - "dap-gateway": { + "axhub-gateway": { "command": "java", - "args": ["C:/?덈?寃쎈줈/dap-backend-main/McpBridge.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) 臾몄꽌留??대씪?곕뱶 肄섏넄???깅줉?섎㈃ 利됱떆 ?쇱씠釉?梨쀫큸/?먯씠?꾪듃濡??쒕퉬?ㅽ븷 ???덉뒿?덈떎. --- @@ -140,11 +131,11 @@ MSA 諛??몃? ?쒖뒪??MCI) ?곕룞 ?섍꼍???덉젙?깆쓣 ?꾪빐 ?꾨꼍??3-T ```bash # ?ъ슜踰? 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 [紐⑤뱢紐? [?ы듃踰덊샇] +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 [紐⑤뱢紐? [?ы듃踰덊샇] -# ?ㅽ뻾 ?덉떆 (dap-tool-hr 紐⑤뱢??8086 ?ы듃濡??앹꽦) -java -cp dap-common/src/main/java io.shinhanlife.dap.common.util.PodScaffolder hr 8086 +# ?ㅽ뻾 ?덉떆 (axhub-tool-hr 紐⑤뱢??8086 ?ы듃濡??앹꽦) +java -cp axhub-common/src/main/java io.shinhanlife.axhub.common.util.PodScaffolder hr 8086 ``` ### 2???앹꽦??紐⑤뱢???덈줈????Function)??異붽????? `ToolScaffolder` @@ -152,11 +143,11 @@ java -cp dap-common/src/main/java io.shinhanlife.dap.common.util.PodScaffolder h ```bash # ?ъ슜踰? 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] "[湲곕뒫?ㅻ챸]" "[洹몃９紐?" "[?듭떊諛⑹떇]" "[紐⑤뱢紐?" +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 dap-common/src/main/java io.shinhanlife.dap.common.util.ToolScaffolder PaymentApproval PAY_001 "寃곗젣 ?뱀씤 泥섎━ 湲곕뒫" "COMMON" "HTTP" "dap-tool-payment" +java -cp axhub-common/src/main/java io.shinhanlife.axhub.common.util.ToolScaffolder PaymentApproval PAY_001 "寃곗젣 ?뱀씤 泥섎━ 湲곕뒫" "COMMON" "HTTP" "axhub-tool-payment" ``` --- @@ -164,14 +155,14 @@ java -cp dap-common/src/main/java io.shinhanlife.dap.common.util.ToolScaffolder ## ?⑦궎吏€ 援ъ“ (Package Structure) ```text -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 ?? ?대뙌??紐⑤뱢 +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 ?? ?대뙌??紐⑤뱢 ``` *(李멸퀬: 湲곗〈 ?⑥씪 紐⑤뱢 ?꾨줈?앺듃?먯꽌 留덉씠?щ줈?쒕퉬???뺤옣???꾪빐 紐⑤뱢蹂꾨줈 遺꾨━?섏뿀?쇰ʼn, 媛?Tool ?쒕쾭???낅┰?곸쑝濡??뺤옣 諛?諛고룷?????덉뒿?덈떎.)*