🏢 Company Database AI Manager

📖 개요

Company Database AI Manager는 기업 데이터베이스를 위한 자연어 인터페이스입니다. 데이터를 삽입, 업데이트 또는 검색하기 위해 복잡한 SQL 쿼리를 작성하는 대신, 사용자는 일상적인 영어로 명령을 입력하기만 하면 됩니다 (예: "IT 부서를 추가하고 직원 5명을 해당 부서에 배정하세요").

이 시스템은 **Model Context Protocol (MCP)**를 사용하여 Groq 기반 LangGraph 에이전트를 로컬 Python 데이터베이스 서버에 안전하게 연결합니다. AI는 사용자의 프롬프트를 자율적으로 추론하여 올바른 데이터베이스 도구를 선택하고, SQL 작업을 실행한 후, 결과를 깔끔한 Streamlit 웹 인터페이스로 반환합니다.

Related MCP server: PySqlitMCP

⚙️ 아키텍처 및 작동 방식

이 프로젝트는 진정한 서버/클라이언트 아키텍처를 사용하여 데이터베이스 로직과 AI 로직을 분리합니다:

1. 서버 (server.py & models.py): SQLite 데이터베이스 도구(setup_database, add_record, search_database)를 호스팅하는 독립적인 FastMCP 서버를 실행합니다.

2. 클라이언트 (client.py & app.py): Groq의 llama-3.3-70b-versatile 또는 openai/gpt-oss-120b로 구동되는 LangGraph 에이전트를 실행합니다.

3. 프로토콜 (MCP): 클라이언트는 표준 입력/출력(stdio)을 통해 서버에 안전하게 연결합니다. 클라이언트는 서버에 사용 가능한 도구를 요청하고, 이를 LangGraph 에이전트에 전달하며, Python 함수를 직접 임포트하지 않고도 실행합니다.

📂 폴더 구조

📦 llm-db-mcp
 ┣ 📜 .env                # Stores secure API keys (Do NOT commit to GitHub)
 ┣ 📜 .gitignore          # Prevents sensitive files from being pushed to Git
 ┣ 📜 app.py              # The Streamlit web UI for interacting with the AI
 ┣ 📜 client.py           # The terminal-based LangGraph agent script
 ┣ 📜 company.db          # The automatically generated SQLite database file
 ┣ 📜 models.py           # SQLAlchemy schemas (Departments, Roles, Employees, Projects)
 ┣ 📜 requirements.txt    # Project dependencies and version numbers
 ┗ 📜 server.py           # The FastMCP server hosting the database tools

🚀 설치 및 설정

1. 사전 요구 사항

Python 3.10 이상.

무료 Groq API 키.

2. 환경 설정

가상 환경을 생성하고 활성화하세요 (Conda 권장):

conda create -n db_mcp python=3.11
conda activate db_mcp

3. 의존성 설치

requirements.txt 파일에서 필요한 모든 패키지를 설치하세요:

pip install -r requirements.txt

4. API 키 구성

루트 디렉터리에 .env 파일을 만들고 Groq API 키를 추가하세요:

GROQ_API_KEY=gsk_your_api_key_here

🖥️ 사용 방법

옵션 1: 웹 UI 실행 (권장)

대화형 채팅 인터페이스를 시작하려면 다음을 실행하세요:

streamlit run app.py

옵션 2: 터미널 클라이언트 실행

에이전트를 명령줄에서만 실행하려면:

🛠️ 사용해 볼 예시 프롬프트

앱이 실행되면 채팅에 다음 프롬프트를 입력해 보세요:

"데이터베이스 테이블을 설정하세요." (먼저 실행하세요!)

"IT 부서를 추가하세요."

"IT 부서에 연봉 75000의 John Doe라는 새 직원을 추가하세요."

"50000 이상 버는 모든 직원을 보여주세요."

🔒 보안 참고 사항

.env 파일이나 API 키를 버전 관리 시스템에 커밋하지 마세요.

.gitignore 파일은 .env와 company.db가 GitHub에 업로드되지 않도록 미리 구성되어 있습니다.