动态MCP代理工具搜索

┌─────────────────────────────────────────────────────────────────────┐
│                     사용자 쿼리 입력                                  │
│                "문서를 영어로 번역해 줘"                              │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│            🔍 Multi-layer Hybrid Search + RRF Fusion                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  1️⃣ BM25 검색 (무료, ~1ms)                                          │
│     ├─ 점수 ≥ 5.0 → ✅ 즉시 반환                                     │
│     └─ 점수 < 5.0 → ⬇️ 다음 단계로                                   │
│                                                                      │
│  2️⃣ Sentence-Transformers (로컬, ~50ms)                             │
│     ├─ 모델: paraphrase-multilingual-MiniLM-L12-v2                   │
│     ├─ 유사도 ≥ 0.65 → ✅ 반환                                       │
│     └─ 유사도 < 0.65 → ⬇️ RRF 통합                                  │
│                                                                      │
│  3️⃣ 🔀 RRF (Reciprocal Rank Fusion)                                │
│     └─ BM25 + Sentence 결과를 RRF 점수로 통합 재순위                 │
│                                                                      │
│  4️⃣ MCP Registry API (외부, ~200ms)                                 │
│     └─ 공식 레지스트리에서 새로운 도구 발견                           │
│                                                                      │
│  5️⃣ GPT-5.2 LLM 추론 (~1-2s)                                       │
│     └─ 후보군 중 최적 도구 선택 & 재순위화                            │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│              📦 동적 도구 로딩 & 실행                                 │
│                                                                      │
│  load_tool("azure_translator_tool")                                 │
│       └─→ 에이전트 컨텍스트에 도구 주입                               │
│       └─→ azure_translator_tool(text, target_lang)                  │
│                                                                      │
├─────────────────────────────────────────────────────────────────────┤
│              🌐 네이티브 원격 MCP 서버 도구                           │
│                                                                      │
│  Responses API type: "mcp" 네이티브 통합                             │
│       └─→ Microsoft Learn MCP 서버                                   │
│       └─→ GitHub MCP 서버                                            │
│       └─→ 런타임에 mcp-add로 추가 가능                               │
│                                                                      │
├─────────────────────────────────────────────────────────────────────┤
│              🤝 멀티 에이전트 오케스트레이션 (v3.0 신규)              │
│                                                                      │
│  OpenAI Agents SDK 기반 전문 에이전트 핸드오프                       │
│       └─→ 트리아지 에이전트 → 검색 전문가 / 코드 전문가             │
│       └─→ 에이전트 트레이싱/관찰성 지원                               │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

dynamic_mcp_agent/
├── agent.py                 # 메인 에이전트 (v1 Responses API + Agents SDK)
│   ├── DynamicMCPAgent          # 동적 도구 검색/로딩 에이전트
│   │   ├── chat()                   # Responses API 비동기 대화
│   │   ├── chat_stream()            # 스트리밍 응답 (도구 호출 루프 포함)
│   │   ├── chat_sync()             # 동기 래퍼
│   │   ├── chat_with_reasoning()    # GPT-5.2 네이티브 추론 모드
│   │   ├── chat_structured()        # Structured Outputs (Pydantic v2)
│   │   ├── _resolve_json_type()     # 제네릭 타입 → JSON Schema 변환
│   │   └── _dynamic_tool_injection()# 런타임 도구 주입
│   ├── create_agent()           # 팩토리 함수
│   └── DEFAULT_REMOTE_MCP_SERVERS   # 기본 MCP 서버 설정
├── main.py                  # CLI / Web / Demo / Stream / Reasoning / Agents 실행
│   ├── run_cli_mode()           # 대화형 CLI
│   ├── run_web_mode()           # Gradio 웹 UI
│   ├── run_demo_mode()          # 데모 시나리오
│   ├── run_stream_cli_mode()    # 스트리밍 CLI (단일 이벤트 루프)
│   ├── run_reasoning_cli_mode() # GPT-5.2 네이티브 추론 CLI
│   └── run_agents_mode()        # Agents SDK 멀티 에이전트
├── requirements.txt         # Python 의존성 (openai≥1.93, openai-agents≥0.3)
├── __init__.py              # 패키지 초기화 (v3.0.0)
├── tests/
│   ├── __init__.py
│   └── test_all_scenarios.py    # 103개 시나리오별 테스트 (8개 시나리오)
└── lib/
    ├── __init__.py              # 라이브러리 exports
    ├── registry.py              # 다층 하이브리드 검색 + RRF 레지스트리
    │   ├── MCPRegistryClient        # MCP Registry API 클라이언트 (httpx/aiohttp)
    │   └── HybridToolRegistry       # 5단계 하이브리드 검색 + RRF
    │       ├── register()               # 단일 도구 등록 (중복 감지)
    │       ├── register_batch()         # 일괄 등록 (인덱스 1회 재구축)
    │       ├── search()                 # 다층 하이브리드 검색
    │       ├── _bm25_search()           # BM25 키워드 검색
    │       ├── _sentence_search()       # Sentence-Transformers 시맨틱 검색
    │       ├── _hybrid_search()         # RRF Fusion 통합 검색
    │       └── _llm_search()            # GPT-5.2 LLM 재순위화
    └── tools.py                 # 25개 Azure MCP 도구 정의
        ├── TOOL_DEFINITIONS         # 도구 메타데이터 리스트 (25개)
        ├── search_available_tools() # 도구 검색 함수
        ├── load_tool()              # 도구 로드 함수
        ├── register_tool()          # 도구 등록 함수
        ├── initialize_mcp_tools()   # 일괄 초기화 (register_batch)
        └── calculator_tool()        # AST 기반 안전한 수식 계산

git clone https://github.com/your-username/dynamic-mcp-agent.git
cd dynamic-mcp-agent

# 가상 환경 생성
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # macOS/Linux

# 의존성 설치
pip install -r requirements.txt

# =============================================================
# Dynamic MCP Agent v3.0 - Azure OpenAI v1 Responses API
# =============================================================
# v1 API 사용 (버전 관리 불필요, preview/latest만 지정)

# Azure OpenAI Configuration (Required)
AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key-here

# v1 API 버전: "preview" (최신 프리뷰 기능) 또는 "latest" (GA 안정 버전)
AZURE_OPENAI_API_VERSION=preview

# 모델 배포명 (GPT-5.2 시리즈 권장)
# 사용 가능: gpt-5, gpt-5.1, gpt-5.2, gpt-5-mini, gpt-5-nano, gpt-5-pro
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-5.2

# 추론 모델 (Optional - --reasoning 모드, 기본: gpt-5.2 네이티브 추론)
AZURE_OPENAI_REASONING_MODEL=gpt-5.2

# Azure AI Search (Optional - for azure_ai_search_tool)
AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_KEY=your-search-key-here

# CLI 모드 (대화형)
python main.py

# 스트리밍 모드 (실시간 토큰 출력)
python main.py --stream

# 추론 모드 (GPT-5.2 네이티브) ← v3.0 신규
python main.py --reasoning

# 멀티 에이전트 모드 (Agents SDK) ← v3.0 신규
python main.py --agents

# 데모 모드
python main.py --demo

# 웹 인터페이스 (Gradio)
python main.py --web

👤 You: 번역 도구가 필요해요

🤖 Agent: 번역 도구를 검색하고 있습니다...
   [SENTENCE HIT] 쿼리: '번역', 유사도: 0.73

   검색 결과:
   1. azure_translator_tool: Azure Translator를 사용하여 텍스트를 번역합니다.

   이 도구를 로드해드릴까요?

👤 You: 네

🤖 Agent: ✅ 도구 'azure_translator_tool'가 로드되었습니다.

👤 You: mcp-add https://learn.microsoft.com/api/mcp microsoft_learn

🌐 MCP 서버 추가됨: microsoft_learn (https://learn.microsoft.com/api/mcp)

python main.py --agents

🤝 Dynamic MCP Agent - 멀티 에이전트 모드 (Agents SDK)
🤝 3개의 전문 에이전트가 준비되었습니다: 트리아지, 검색, 코드

👤 You: Azure Functions 관련 문서를 찾아줘

🤝 Agents: [트리아지 → 검색 전문가에게 핸드오프]
   Microsoft Learn에서 Azure Functions 관련 문서를 검색합니다...

# 전체 시나리오별 테스트 실행 (103개)
python -m pytest dynamic_mcp_agent/tests/test_all_scenarios.py -v

# BM25 검색 성능 테스트
python test_bm25.py

======================================================================
[SEARCH] Multi-layer Hybrid Search + RRF Test
   BM25 -> Sentence-Transformers -> RRF -> MCP Registry -> GPT-5.2 LLM
   Korean/English multilingual support
======================================================================

[INFO] Model Info:
   - Sentence-Transformers: paraphrase-multilingual-MiniLM-L12-v2
   - MCP Registry API: ENABLED
   - LLM Model: gpt-5.2
   - RRF k-parameter: 60
   - Registered tools: 25

----------------------------------------------------------------------
[KO] Korean Query Test
----------------------------------------------------------------------

[Q] Query: '문서에서 텍스트 추출하고 싶어'
   1. azure_form_recognizer_tool: Azure Form Recognizer를 사용하여 문서에서 데이터를 추출...

[Q] Query: '영어를 한국어로 번역해줘'
   1. azure_translator_tool: Azure Translator를 사용하여 텍스트를 번역합니다...

from dynamic_mcp_agent import register_tool

def my_custom_tool(param1: str) -> dict:
    """나만의 커스텀 도구입니다."""
    return {"result": f"처리됨: {param1}"}

# 도구 등록 (한국어 태그 지원)
register_tool(
    my_custom_tool,
    category="custom",
    tags=["나만의", "도구", "custom", "tool"]
)

from dynamic_mcp_agent import create_agent

# 기본 Microsoft Learn + GitHub MCP 서버 포함하여 에이전트 생성
agent = create_agent(enable_remote_mcp=True)

# 런타임에 추가 MCP 서버 연결
agent.add_remote_mcp_server(
    server_url="https://your-mcp-server.com/sse",
    server_label="my_mcp_server",
    server_description="커스텀 MCP 서버"
)

# Responses API가 네이티브로 MCP 서버 도구를 호출
response = agent.chat_sync("Microsoft Learn에서 Azure Functions 관련 문서를 찾아줘")

from agents import Agent, Runner
from dynamic_mcp_agent import create_agent

# 기본 에이전트 생성
base_agent = create_agent(enable_tracing=True)

# 전문 에이전트 정의
search_agent = Agent(name="검색 전문가", instructions="...", model=base_agent.model)
code_agent   = Agent(name="코드 전문가", instructions="...", model=base_agent.model)
triage_agent = Agent(
    name="트리아지",
    instructions="사용자 요청을 분석하여 적절한 전문가에게 전달",
    handoffs=[search_agent, code_agent],
)

# 실행
result = Runner.run_sync(triage_agent, "Azure Functions 관련 코드를 분석해 줘")
print(result.final_output)

from dynamic_mcp_agent import registry

# 외부 MCP 서버 검색 (API v0.1, httpx 기반)
external_tools = registry.discover_external_tools("database", limit=5)
for tool in external_tools:
    server = tool.get("server", {})
    print(f"{server.get('name')}: {server.get('description')}")

# v1 API: OpenAI 클라이언트 + base_url 방식
from openai import OpenAI

base_url = f"{endpoint}/openai/v1/"
client = OpenAI(api_key=key, base_url=base_url, default_query={"api-version": "preview"})

# Responses API 호출 + previous_response_id 자동 체이닝
response = client.responses.create(
    model="gpt-5.2",
    input=[{"role": "user", "content": message}],
    tools=tools,                             # 네이티브 MCP 서버 도구 포함
    previous_response_id=last_response_id,   # 대화 자동 체이닝
)

# 네이티브 원격 MCP 서버 도구 정의
mcp_tool = {
    "type": "mcp",
    "server_label": "microsoft_learn",
    "server_url": "https://learn.microsoft.com/api/mcp",
    "require_approval": "never",
}

# 제네릭 타입 변환 (Optional, List, Dict 등)
DynamicMCPAgent._resolve_json_type(Optional[List[str]])  # → "array"

# MCPRegistryClient - 공식 MCP Registry API 클라이언트 (httpx 우선)
class MCPRegistryClient:
    BASE_URL = "https://registry.modelcontextprotocol.io"
    API_VERSION = "v0.1"

    async def search_servers(self, query, limit=10): ...   # httpx → aiohttp 폴백
    async def get_server_details(self, server_name): ...
    async def list_all_servers(self, limit=30): ...

# HybridToolRegistry - 5단계 하이브리드 검색 + RRF
class HybridToolRegistry:
    BM25_CONFIDENCE_THRESHOLD = 5.0
    EMBEDDING_SIMILARITY_THRESHOLD = 0.65
    RRF_K = 60                               # Reciprocal Rank Fusion 파라미터

    def search(self, query, top_k=5, strategy="hybrid"): ...
    def register(self, tool, name, ...): ...     # 중복 감지 + in-place 업데이트
    def register_batch(self, tools): ...         # 인덱스 1회 재구축

# 도구 정의를 리스트로 관리하여 유지보수성 향상
TOOL_DEFINITIONS = [
    (azure_ai_search_tool, "search", ["azure", "search", "문서검색"]),
    (azure_translator_tool, "ai", ["translate", "번역", "언어"]),
    # v3.0 신규 도구
    (azure_ai_agent_service_tool, "ai", ["azure", "agent", "서버리스"]),
    (azure_computer_use_tool, "ai", ["CUA", "GUI", "자동화"]),
    (mcp_server_discovery_tool, "mcp", ["mcp", "서버검색"]),
    (structured_output_tool, "ai", ["structured", "pydantic", "스키마"]),
    (azure_realtime_audio_tool, "ai", ["realtime", "음성대화"]),
    # ... 총 25개 도구
]

# 모듈 레벨 안전한 계산기 상수 (호출당 재생성 방지)
_SAFE_OPERATORS = { ast.Add: operator.add, ... }
_SAFE_FUNCTIONS = { 'sqrt': math.sqrt, 'pi': math.pi, ... }

# Clone and install
git clone https://github.com/your-username/dynamic-mcp-agent.git
cd dynamic-mcp-agent
pip install -r requirements.txt

# Configure environment — create .env file
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_API_VERSION=preview
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-5.2

# Run
python main.py                # CLI mode
python main.py --stream       # Streaming mode
python main.py --reasoning    # GPT-5.2 native reasoning (NEW v3.0)
python main.py --agents       # Multi-agent mode (NEW v3.0)
python main.py --web          # Gradio web UI
python main.py --demo         # Demo scenarios

# Test (103 tests, 8 scenarios)
python -m pytest dynamic_mcp_agent/tests/test_all_scenarios.py -v