|
1 | | -# MCP Client Chatbot: 로컬 기반 AI 어시스턴트 앱 |
| 1 | +# MCP Client Chatbot |
2 | 2 |
|
3 | | -[](#) |
| 3 | +[](#) |
4 | 4 | [](https://modelcontextprotocol.io/introduction) |
5 | 5 |
|
6 | | -**MCP Client Chatbot**은 [OpenAI](https://openai.com/), [Anthropic](https://www.anthropic.com/), [Google](https://ai.google.dev/), [Ollama](https://ollama.com/) 등 다양한 AI 모델 프로바이더를 손쉽게 활용할 수 있는 다재다능한 채팅 인터페이스입니다. **무엇보다 100% 로컬 환경에서 복잡한 설정 없이 즉시 실행**할 수 있도록 설계되어, 개인 컴퓨터나 서버에서 **편리하게 컴퓨팅 자원을 활용하고 모든 것을 직접 제어**할 수 있습니다. |
| 6 | +**MCP Client Chatbot**은 [OpenAI](https://openai.com/), [Anthropic](https://www.anthropic.com/), [Google](https://ai.google.dev/), [Ollama](https://ollama.com/)와 같은 다양한 AI 모델 제공업체를 지원하는 다목적 채팅 인터페이스입니다. **복잡한 설정 없이 100% 로컬 환경에서 즉시 실행되도록 설계**되어 사용자가 개인 컴퓨터나 서버의 컴퓨팅 리소스를 완전히 제어할 수 있습니다. |
7 | 7 |
|
8 | | -> 이 앱은 [Vercel AI SDK](https://sdk.vercel.ai)와 [Next.js](https://nextjs.org/)를 기반으로 구축되었으며, 최신 AI 챗 인터페이스 개발 방식을 반영합니다. |
9 | | -[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)을 통해 강력한 외부 AI 도구들을 매끄럽게 연결하고 활용하여 채팅 경험을 극대화하세요. |
| 8 | +> [Vercel AI SDK](https://sdk.vercel.ai)와 [Next.js](https://nextjs.org/)로 구축된 이 앱은 AI 채팅 인터페이스 구축을 위한 현대적인 패턴을 채택했습니다. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)의 강력한 기능을 활용하여 외부 도구를 채팅 경험에 원활하게 통합할 수 있습니다. |
10 | 9 |
|
11 | | -> **우리의 목표:** 누구나 쉽게 사용할 수 있는, 개인에게 최적화된 AI 챗봇 앱을 만드는 것입니다. |
| 10 | +**🌟 오픈소스 프로젝트** |
| 11 | +MCP Client Chatbot은 커뮤니티 주도의 100% 오픈소스 프로젝트입니다. |
12 | 12 |
|
13 | 13 | ## 목차 |
14 | 14 |
|
15 | | -- [MCP Client Chatbot: 로컬 기반 AI 어시스턴트 앱](#mcp-client-chatbot-로컬-기반-ai-어시스턴트-앱) |
| 15 | +- [MCP Client Chatbot](#mcp-client-chatbot) |
16 | 16 | - [목차](#목차) |
17 | 17 | - [데모](#데모) |
18 | | - - [✨ 핵심 기능](#-핵심-기능) |
19 | | - - [🚀 빠른 시작](#-빠른-시작) |
20 | | - - [환경 변수 설정](#환경-변수-설정) |
| 18 | + - [🧩 Playwright MCP를 통한 브라우저 자동화](#-playwright-mcp를-통한-브라우저-자동화) |
| 19 | + - [⚡️ 빠른 도구 언급 (`@`)](#️-빠른-도구-언급-) |
| 20 | + - [🔌 MCP 서버 쉽게 추가하기](#-mcp-서버-쉽게-추가하기) |
| 21 | + - [🛠️ 독립적인 도구 테스트](#️-독립적인-도구-테스트) |
| 22 | + - [✨ 주요 기능](#-주요-기능) |
| 23 | + - [🚀 시작하기](#-시작하기) |
| 24 | + - [환경 변수](#환경-변수) |
21 | 25 | - [MCP 서버 설정](#mcp-서버-설정) |
22 | | - - [💡 활용 사례](#-활용-사례) |
23 | | - - [🗺️ 로드맵: 앞으로 추가될 기능들](#️-로드맵-앞으로-추가될-기능들) |
| 26 | + - [💡 사용 사례](#-사용-사례) |
| 27 | + - [🗺️ 로드맵: 향후 기능](#️-로드맵-향후-기능) |
24 | 28 | - [🙌 기여하기](#-기여하기) |
25 | 29 |
|
26 | | ------ |
| 30 | +--- |
27 | 31 |
|
28 | 32 | ## 데모 |
29 | 33 |
|
| 34 | +MCP Client Chatbot을 사용할 수 있는 몇 가지 빠른 예시입니다: |
30 | 35 |
|
| 36 | +--- |
31 | 37 |
|
32 | | - |
| 38 | +### 🧩 Playwright MCP를 통한 브라우저 자동화 |
33 | 39 |
|
34 | | -**MCP 도구 연동 예시:** Microsoft의 [playwright-mcp](https://github.com/microsoft/playwright-mcp)와 통합하여 웹 브라우저를 제어하는 모습입니다. |
| 40 | + |
35 | 41 |
|
36 | | -*예시 프롬프트:* "Reddit에 접속해서 r/mcp를 열고, 가장 최근 글을 확인한 다음 어떤 내용인지 말해줘 — 그리고 다 끝났으면 Reddit을 닫아줘." |
| 42 | +**예시:** Microsoft의 [playwright-mcp](https://github.com/microsoft/playwright-mcp) 도구를 사용하여 웹 브라우저를 제어합니다. |
37 | 43 |
|
38 | | ->이 프로젝트에는 기본 MCP 서버로 microsoft/playwright-mcp가 미리 설정되어 있습니다. |
39 | | ->위의 프롬프트를 직접 입력해보며 작동하는 모습을 확인해보세요! |
| 44 | +샘플 프롬프트: |
40 | 45 |
|
| 46 | +```prompt |
| 47 | +GitHub로 이동하여 cgoinglove 프로필을 방문해주세요. |
| 48 | +mcp-client-chatbot 프로젝트를 열어주세요. |
| 49 | +그런 다음, README.md 파일을 클릭 하세요. |
| 50 | +완료 후, 브라우저를 닫아주세요. |
| 51 | +마지막으로, 패키지 설치 방법을 알려주세요. |
| 52 | +``` |
41 | 53 | --- |
42 | 54 |
|
43 | | - |
| 55 | +### ⚡️ 빠른 도구 언급 (`@`) |
44 | 56 |
|
45 | | -**간편한 도구 호출:** 메시지 입력창에서 '@' 기호를 사용하여 사용 가능한 MCP 도구를 쉽게 선택하고 호출할 수 있습니다. |
| 57 | + |
46 | 58 |
|
| 59 | +채팅 중에 `@도구이름`을 입력하여 등록된 MCP 도구를 빠르게 호출할 수 있습니다. 외울 필요 없이 `@`를 입력하고 목록에서 선택하세요! |
47 | 60 |
|
48 | 61 | --- |
49 | 62 |
|
50 | | - |
| 63 | +### 🔌 MCP 서버 쉽게 추가하기 |
| 64 | + |
| 65 | + |
51 | 66 |
|
52 | | -**독립적인 도구 테스트:** 채팅 흐름과 별개로 MCP 도구의 기능을 개별적으로 테스트하고 결과를 확인할 수 있습니다. |
| 67 | +UI를 통해 새로운 MCP 서버를 쉽게 추가하고, 앱을 재시작하지 않고도 새로운 도구를 사용할 수 있습니다. |
53 | 68 |
|
54 | 69 | --- |
55 | 70 |
|
56 | | - |
| 71 | +### 🛠️ 독립적인 도구 테스트 |
57 | 72 |
|
58 | | -**모델 & 도구 선택 UI:** 프롬프트 입력창에 LLM 선택 버튼, MCP 도구 목록과 활성 상태를 즉시 확인하고 제어할 수 있습니다. |
| 73 | + |
59 | 74 |
|
60 | | ------ |
| 75 | +더 쉬운 개발과 디버깅을 위해 채팅 세션과 독립적으로 MCP 도구를 테스트할 수 있습니다. |
61 | 76 |
|
62 | | -## ✨ 핵심 기능 |
| 77 | +--- |
63 | 78 |
|
64 | | -* **💻 100% 로컬 실행:** 복잡한 배포 과정 없이 개인 PC나 서버에서 바로 실행하여 **컴퓨팅 자원을 직접 활용하고 모든 과정을 제어합니다.** |
65 | | -* **🤖 다양한 AI 모델 지원:** OpenAI, Anthropic, Google AI, Ollama 등 원하는 AI 공급자를 자유롭게 선택하고 연결하세요. |
66 | | -* **🛠️ 강력한 MCP 통합:** Model Context Protocol을 통해 외부 도구(웹 브라우저 자동화, 데이터베이스 연동 등)를 채팅에 손쉽게 통합하고 활용합니다. |
67 | | -* **🚀 MCP 도구 단독 테스트:** 채팅과 별개로 MCP 도구의 요청/응답을 직접 테스트하여 개발 및 디버깅 효율을 높입니다. |
68 | | -* **💬 직관적인 도구 멘션:** 채팅 입력창에서 `@` 키를 눌러 사용 가능한 MCP 도구를 즉시 확인하고 선택하여 호출할 수 있습니다. |
69 | | -* **⚙️ 쉬운 서버 설정:** 사용자 친화적인 UI 또는 간단한 `.mcp-config.json` 파일 수정을 통해 MCP 서버 연결을 간편하게 관리합니다. |
70 | | -* **📄 마크다운 UI:** 깔끔하고 가독성 높은 인터페이스에서 마크다운 형식의 대화를 주고받을 수 있습니다. |
71 | | -* **💾 제로 설정 로컬 DB:** 기본 SQLite 데이터베이스를 사용하여 별도 설정 없이 대화 내역 등을 로컬에 저장합니다 (PostgreSQL 옵션도 제공). |
72 | | -* **🧩 커스텀 MCP 서버 지원:** 내장된 MCP 서버 코드를 직접 수정하여 나만의 도구를 만들거나 로직을 확장할 수 있습니다. |
| 79 | +## ✨ 주요 기능 |
73 | 80 |
|
| 81 | +* **💻 100% 로컬 실행:** 복잡한 배포 없이 PC나 서버에서 직접 실행하여 컴퓨팅 리소스를 완전히 활용하고 제어합니다. |
| 82 | +* **🤖 다중 AI 모델 지원:** OpenAI, Anthropic, Google AI, Ollama와 같은 제공업체 간에 유연하게 전환할 수 있습니다. |
| 83 | +* **🛠️ 강력한 MCP 통합:** Model Context Protocol을 통해 외부 도구(브라우저 자동화, 데이터베이스 작업 등)를 채팅에 원활하게 연결합니다. |
| 84 | +* **🚀 독립 도구 테스터:** 주 채팅 인터페이스와 별도로 MCP 도구를 테스트하고 디버깅할 수 있습니다. |
| 85 | +* **💬 직관적인 멘션:** 입력 필드에서 `@`로 사용 가능한 도구를 트리거합니다. |
| 86 | +* **⚙️ 쉬운 서버 설정:** UI 또는 `.mcp-config.json` 파일을 통해 MCP 연결을 구성합니다. |
| 87 | +* **📄 마크다운 UI:** 깔끔하고 읽기 쉬운 마크다운 기반 인터페이스로 소통합니다. |
| 88 | +* **💾 설정 필요 없는 로컬 DB:** 기본적으로 로컬 저장소로 SQLite를 사용합니다(PostgreSQL도 지원). |
| 89 | +* **🧩 커스텀 MCP 서버 지원:** 내장된 MCP 서버 로직을 수정하거나 직접 만들 수 있습니다. |
74 | 90 |
|
75 | | -## 🚀 빠른 시작 |
| 91 | +## 🚀 시작하기 |
76 | 92 |
|
77 | 93 | 이 프로젝트는 [pnpm](https://pnpm.io/)을 권장 패키지 매니저로 사용합니다. |
78 | 94 |
|
79 | 95 | ```bash |
80 | 96 | # 1. 의존성 설치 |
81 | 97 | pnpm i |
82 | 98 |
|
83 | | -# 2. 프로젝트 초기화 (.env 파일 생성 및 DB 설정 포함) |
| 99 | +# 2. 프로젝트 초기화(.env 생성, DB 설정) |
84 | 100 | pnpm initial |
85 | 101 |
|
86 | | -# 3. 개발 서버 실행 |
| 102 | +# 3. 개발 서버 시작 |
87 | 103 | pnpm dev |
88 | 104 | ``` |
89 | 105 |
|
90 | | -위 명령어를 실행한 후, 웹 브라우저에서 [http://localhost:3000](https://www.google.com/search?q=http://localhost:3000)으로 접속하여 애플리케이션을 확인하세요. |
| 106 | +브라우저에서 [http://localhost:3000](http://localhost:3000)을 열어 시작하세요. |
91 | 107 |
|
92 | 108 | ----- |
93 | 109 |
|
94 | | -### 환경 변수 설정 |
| 110 | +### 환경 변수 |
95 | 111 |
|
96 | | -`pnpm initial` 명령어를 실행하면 프로젝트 루트에 `.env` 파일이 생성됩니다. 이 파일을 열어 사용하려는 AI 제공업체의 API 키를 추가하세요: |
| 112 | +`pnpm initial` 명령은 `.env` 파일을 생성합니다. 여기에 API 키를 추가하세요: |
97 | 113 |
|
98 | 114 | ```dotenv |
99 | 115 | GOOGLE_GENERATIVE_AI_API_KEY=**** |
100 | 116 | OPENAI_API_KEY=**** |
101 | 117 | # ANTHROPIC_API_KEY=**** |
102 | 118 | ``` |
103 | 119 |
|
104 | | -기본적으로 데이터는 로컬 SQLite 파일(`db.sqlite`)에 저장됩니다. PostgreSQL 사용을 원하시면 `.env` 파일의 `USE_FILE_SYSTEM_DB=false`로 변경하고 `DATABASE_URL`을 설정하세요. |
| 120 | +SQLite가 기본 DB(`db.sqlite`)입니다. PostgreSQL을 사용하려면 `.env`에서 `USE_FILE_SYSTEM_DB=false`로 설정하고 `DATABASE_URL`을 정의하세요. |
105 | 121 |
|
106 | 122 | ----- |
107 | 123 |
|
108 | 124 | ### MCP 서버 설정 |
109 | 125 |
|
| 126 | +다음과 같은 방법으로 MCP 도구를 연결할 수 있습니다: |
110 | 127 |
|
111 | | -MCP 서버(도구)를 연결하는 방법은 다양합니다: |
112 | | - |
113 | | -1. **UI 활용:** http://localhost:3000/mcp 페이지에서 그래픽 인터페이스를 통해 MCP 서버를 추가하고 관리합니다. |
114 | | -2. **설정 파일 직접 수정:** 프로젝트 루트의 `.mcp-config.json` 파일을 직접 편집하여 MCP 서버 정보를 구성합니다. |
115 | | -3. **커스텀 서버 로직 작성:** 프로젝트 내 `./custom-mcp-server/index.ts` 파일을 수정하여 자신만의 MCP 서버 로직을 구현하거나 외부 도구와 연동할 수 있습니다. |
116 | | - |
117 | | - |
| 128 | +1. **UI 설정:** http://localhost:3000/mcp로 이동하여 인터페이스를 통해 구성합니다. |
| 129 | +2. **직접 파일 편집:** 프로젝트 루트의 `.mcp-config.json`을 수정합니다. |
| 130 | +3. **커스텀 로직:** `./custom-mcp-server/index.ts`를 편집하여 자체 로직을 구현합니다. |
118 | 131 |
|
119 | 132 | ----- |
120 | 133 |
|
121 | | -## 💡 활용 사례 |
| 134 | +## 💡 사용 사례 |
122 | 135 |
|
123 | | - |
124 | | - * [Supabase Integration](./use-cases/supabase.md) - MCP를 사용해 Supabase 데이터베이스 조작, 인증, 실시간 기능을 활용하는 방법을 알아보세요. |
| 136 | +* [Supabase 통합](./docs/use-cases/supabase.md): MCP를 사용하여 Supabase DB, 인증 및 실시간 기능을 관리합니다. |
125 | 137 |
|
126 | 138 | ----- |
127 | 139 |
|
128 | | -## 🗺️ 로드맵: 앞으로 추가될 기능들 |
| 140 | +## 🗺️ 로드맵: 향후 기능 |
129 | 141 |
|
130 | | -MCP Client Chatbot을 더욱 강력한 개인 AI 비서로 만들기 위해 다음과 같은 기능들을 계획하고 있습니다: |
| 142 | +다음과 같은 계획된 기능으로 MCP Client Chatbot을 더욱 강력하게 만들고 있습니다: |
131 | 143 |
|
132 | | - * **🎨 Canvas 기능:** 협업 Canvas 기능: LLM이 생성한 결과물(코드, 블로그 글, 텍스트 등)을 사용자와 LLM이 함께 실시간으로 편집하고 발전시킬 수 있는 인터페이스. |
133 | | - * **🧩 LLM UI 생성:** LLM이 직접 차트, 테이블, 폼 등 동적인 UI 컴포넌트를 생성하여 보여주는 기능. |
134 | | - * **📜 규칙(Rule) 기능:** 채팅 세션 전반에 적용될 수 있는 사용자 정의 시스템 프롬프트 또는 규칙 설정. |
135 | | - * **🖼️ 이미지 생성 및 파일 업로드:** 이미지 생성 요청 및 파일(문서, 이미지 등) 업로드를 통한 멀티모달 상호작용 지원. |
136 | | - * **🐙 GitHub 프로젝트 마운트:** 로컬의 GitHub 저장소를 마운트하여 코드 관련 질문 및 작업 수행. |
137 | | - * **📚 RAG 에이전트:** 자체 문서나 데이터를 기반으로 답변을 생성하는 Retrieval-Augmented Generation 기능. |
138 | | - * **🧠 플래닝 에이전트:** 복잡한 작업을 단계별로 계획하고 실행하는 더욱 지능적인 에이전트 구현. |
139 | | - * **🧑💻 에이전트 생성 기능:** 사용자가 특정 목적을 가진 맞춤형 AI 에이전트를 쉽게 정의하고 생성할 수 있는 도구. |
| 144 | +* **🎨 캔버스 모드:** LLM + 사용자 협업을 위한 실시간 편집 인터페이스(예: 코드, 블로그). |
| 145 | +* **🧩 LLM UI 생성:** LLM이 차트, 테이블, 양식을 동적으로 렌더링할 수 있게 합니다. |
| 146 | +* **📜 규칙 엔진:** 세션 전체에 걸쳐 지속되는 시스템 프롬프트/규칙. |
| 147 | +* **🖼️ 이미지 및 파일 업로드:** 업로드 및 이미지 생성을 통한 멀티모달 상호작용. |
| 148 | +* **🐙 GitHub 마운팅:** 질문하고 코드 작업을 위해 로컬 GitHub 저장소를 마운트합니다. |
| 149 | +* **📚 RAG 에이전트:** 자신의 문서를 사용한 검색 증강 생성(Retrieval-Augmented Generation). |
| 150 | +* **🧠 계획 에이전트:** 복잡한 작업을 계획하고 실행하는 더 스마트한 에이전트. |
| 151 | +* **🧑💻 에이전트 빌더:** 특정 목표를 위한 커스텀 AI 에이전트를 만드는 도구. |
140 | 152 |
|
141 | | -👉 전체 로드맵은 [ROADMAP.md](./ROADMAP.md)에서 확인하세요\! |
| 153 | +👉 전체 로드맵은 [ROADMAP.md](./docs/ROADMAP.md)에서 확인하세요. |
142 | 154 |
|
143 | 155 | ----- |
144 | 156 |
|
145 | 157 | ## 🙌 기여하기 |
146 | 158 |
|
| 159 | +모든 기여를 환영합니다! 버그 보고, 기능 아이디어, 코드 개선 - 모든 것이 최상의 로컬 AI 어시스턴트를 구축하는 데 도움이 됩니다. |
147 | 160 |
|
148 | | -MCP Client Chatbot 프로젝트에 기여해주실 분들을 언제나 환영합니다\! 버그 제보, 새로운 기능 제안, 코드 개선 등 어떤 형태의 기여든 좋습니다. 여러분의 도움으로 이 프로젝트를 더욱 멋지게 만들 수 있습니다. |
149 | | - |
150 | | -함께 최고의 개인 AI 어시스턴트를 만들어가요\! |
| 161 | +함께 만들어 나갑시다 🚀 |
0 commit comments