Haohao-end/mcp-agent

MCP Agent Orchestrator는 **Model Context Protocol (MCP)**의 전문가급 Python 구현체입니다. 이는 대규모 언어 모델 (LLMs)이 표준화된 통신 계층을 통해 외부 도구 및 지식 베이스와 상호작용할 수 있는 구조화된 환경을 제공합니다. 이 프로젝트는 서버 측 도구 정의를 위해 FastMCP를 사용하며, OpenAI 호환 인터페이스를 위한 비동기 클라이언트 측 브릿지를 활용합니다.

이 프로젝트는 분리된 클라이언트-서버 아키텍처를 따릅니다:

MCP Client: 오케스트레이터 역할을 수행합니다. MCP 서버의 생명주기를 관리하고, 도구 검색(tool discovery)을 수행하며, LLM 완료(completions)를 처리하고, 모델이 반환한 도구 호출(tool calls)을 실행합니다. MCP Servers: Model Context Protocol을 통해 클라이언트에 특정 기능을 노출하는 독립적인 서비스 (Weather, RAG)입니다. Transport Layer: 고성능 로컬 프로세스 간 통신을 위해 표준 입출력 (StdIO)을 사용합니다.

클라이언트 구현 (rag_agent.py, client.py)은 다음을 용이하게 합니다:

• AsyncExitStack을 사용한 비동기 생명주기 관리.
• OpenAI 호환 함수 호출 (function calling)을 위한 자동 도구 스키마 변환.
• 지속적인 대화 상태 및 다회차 추론 루프 (multi-turn reasoning loops).

날씨 서버 (server.py)는 실시간 API 통합을 보여줍니다:

• 외부 REST API (WeatherAPI)와의 통합.
• LLM 소비를 위한 데이터 정규화 및 포맷팅.
• httpx를 사용한 비동기 요청 처리.

RAG 서버 (rag_server.py)는 고급 문서 지능을 제공합니다:

데이터 수집 (Data Ingestion): LangChain을 사용한 PDF 및 TXT 형식 지원.
벡터 데이터베이스 (Vector Database): ChromaDB를 통한 지속적 저장.
검색 최적화 (Search Optimization): 다양한 정보 검색을 위해 최대 한계 관련성 (Maximal Marginal Relevance, MMR) 구현.
임베딩 (Embeddings): HuggingFace 트랜스포머 모델과의 통합.

├── client.py # 표준 MCP 클라이언트 구현
├── rag_agent.py # RAG 작업을 위한 특화된 에이전트
├── server.py # 날씨 서비스 MCP 서버
...

프로토콜 (Protocol): Model Context Protocol (MCP)
LLM 인터페이스 (LLM Interface): OpenAI SDK (Qwen/DashScope와 호환)
RAG 프레임워크 (RAG Framework): LangChain
벡터 스토어 (Vector Store): ChromaDB
통신 (Communication): 비동기 I/O (asyncio)

• Python 3.10+
• 가상 환경 (Virtual environment) 권장

루트 디렉토리에 다음과 같은 변수를 포함하는 .env 파일을 생성하세요:

API_KEY=your_llm_api_key
BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
MODEL=qwen-plus
...

pip install mcp langchain langchain-community langchain-openai chromadb httpx python-dotenv openai

클라이언트를 시작하고 MCP 서버에 연결하려면:

python client.py server.py

이제 서버는 다음 두 가지 도구 (tools)를 노출합니다:

query_weather(city)

search_web(query, count=5)

(You.com Search API (GET https://api.you.com/v1/agents/search) 사용)

프롬프트 예시:

• "심천(Shenzhen)의 날씨는 어때?"
• "MCP Python 베스트 프랙티스에 대해 웹에서 검색해줘"

지식 베이스 (knowledge base)를 초기화하고 RAG 기능이 활성화된 에이전트를 시작하려면:

python rag_agent.py --server_script rag_server.py

구현은 MCP 명세 (specification)를 엄격히 준수합니다:

초기화 (Initialization): 클라이언트가 세션을 초기화하고 도구 매니페스트 (tool manifests)를 가져옵니다.
도구 발견 (Tool Discovery): LLM은 JSON 스키마 (JSON schema)를 통해 사용 가능한 함수들을 안내받습니다.
실행 (Execution): 클라이언트가 tool_calls를 가로채어, 해당하는 서버 함수를 실행하고, 최종 합성을 위해 그 결과를 LLM에 반환합니다.