MCP 서버 & 클라이언트 (Azure OpenAI & OpenAI 사용)

Model Context Protocol(MCP)와 Azure OpenAI를 활용한 최소한의 서버/클라이언트 애플리케이션 구현입니다.
1. MCP 서버는 FastMCP로 구축되었습니다.
2. Playwright는 현대적인 웹 애플리케이션을 테스트하기 위한 Microsoft의 오픈 소스 엔드 투 엔드 테스트 프레임워크입니다.
3. 도구에 대한 MCP 응답은 OpenAI 함수 호출 형식으로 변환됩니다.
4. MCP 서버 응답을 OpenAI 함수 호출 형식으로 변환하는 브릿지는 MCP-LLM Bridge 구현을 커스터마이징합니다.
5. 안정적인 연결을 보장하기 위해 서버 객체가 브릿지로 직접 전달됩니다.
6. client_bridge는 인프로세스 및 외부(stdio) MCP 서버 연결을 모두 지원하여 다양한 클라이언트(예: Claude Code, VS Code, 커스텀 스크립트)에서 재사용할 수 있습니다.

Related MCP server: MCP Simple OpenAI Assistant

Model Context Protocol (MCP)

Model Context Protocol (MCP) MCP는 AI 애플리케이션과 로컬 또는 원격 리소스 간의 안전하고 제어된 상호 작용을 가능하게 하는 오픈 프로토콜입니다.

공식 저장소

커뮤니티 리소스

MCP Playwright

구성

2024년 12월 개발 단계에서 파이썬 프로젝트는 'uv'로 시작해야 합니다. 'pip' 및 'poetry'와 같은 다른 의존성 관리 라이브러리는 아직 MCP CLI에서 완전히 지원되지 않습니다.

.env.template 파일 이름을 .env로 변경한 후, Azure OpenAI를 위해 .env 파일의 값을 채우십시오:
```
AZURE_OPEN_AI_ENDPOINT=
AZURE_OPEN_AI_API_KEY=
AZURE_OPEN_AI_DEPLOYMENT_MODEL=
AZURE_OPEN_AI_API_VERSION=
```
파이썬 라이브러리 관리를 위해 uv를 설치하십시오
```
pip install uv
uv sync
```
python chatgui.py를 실행하십시오
- 샘플 화면은 클라이언트가 브라우저를 실행하여 URL로 이동하는 모습을 보여줍니다.

외부 클라이언트와 함께 사용하기

MCP 서버는 mcp.json 구성을 통해 외부 클라이언트(Claude Desktop, VS Code, Claude Code 등)에서 사용할 수 있습니다.

Claude Desktop / Claude Code

claude_desktop_config.json(Claude Desktop) 또는 .claude/mcp.json(Claude Code)에 추가하십시오:

{
  "mcpServers": {
    "browser-navigator": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "./server/browser_navigator_server.py:app"],
      "cwd": "/path/to/mcp-aoai-web-browsing",
      "env": {
        "AZURE_OPEN_AI_ENDPOINT": "...",
        "AZURE_OPEN_AI_API_KEY": "...",
        "AZURE_OPEN_AI_DEPLOYMENT_MODEL": "...",
        "AZURE_OPEN_AI_API_VERSION": "..."
      }
    }
  }
}

VS Code

작업 공간의 .vscode/mcp.json에 추가하십시오:

{
  "servers": {
    "browser-navigator": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "./server/browser_navigator_server.py:app"],
      "cwd": "${workspaceFolder}",
      "env": {
        "AZURE_OPEN_AI_ENDPOINT": "...",
        "AZURE_OPEN_AI_API_KEY": "...",
        "AZURE_OPEN_AI_DEPLOYMENT_MODEL": "...",
        "AZURE_OPEN_AI_API_VERSION": "..."
      }
    }
  }
}

프로그래밍 방식으로 브릿지 사용하기 (stdio)

client_bridge는 파이썬에서 stdio를 통해 외부 MCP 서버에 연결하는 것도 지원합니다:

from client_bridge import BridgeConfig, MCPServerConfig, BridgeManager
from client_bridge.llm_config import get_default_llm_config

config = BridgeConfig(
    server_config=MCPServerConfig(
        command="uv",
        args=["run", "fastmcp", "run", "./server/browser_navigator_server.py:app"],
    ),
    llm_config=get_default_llm_config(),
    system_prompt="You are a helpful assistant.",
)

async with BridgeManager(config) as bridge:
    response = await bridge.process_message("Navigate to https://example.com")

표준 OpenAI 사용하기 (Azure 아님)

from client_bridge.llm_config import get_openai_llm_config

config = BridgeConfig(
    mcp=server,
    llm_config=get_openai_llm_config(),
)

환경 변수를 설정하십시오:

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-...

직접 도구 실행

자체 LLM 루프를 관리하는 클라이언트의 경우, 브릿지는 도구 메타데이터와 직접 실행 기능을 노출합니다:

async with BridgeManager(config) as bridge:
    tools = bridge.get_tools()  # OpenAI function calling format
    result = await bridge.execute_tool("playwright_navigate", {"url": "https://example.com"})

'stdio' 관련

stdio는 전송 계층(원시 데이터 흐름)인 반면, JSON-RPC는 애플리케이션 프로토콜(구조화된 통신)입니다. 이 둘은 서로 다르지만 프로토콜에서 "JSON-RPC over stdio"와 같이 혼용되는 경우가 많습니다.

도구 설명

@self.mcp.tool()
async def playwright_navigate(url: str, timeout=30000, wait_until="load"):
    """Navigate to a URL.""" -> This comment provides a description, which may be used in a mechanism similar to function calling in LLMs.

# Output
Tool(name='playwright_navigate', description='Navigate to a URL.', inputSchema={'properties': {'url': {'title': 'Url', 'type': 'string'}, 'timeout': {'default': 30000, 'title': 'timeout', 'type': 'string'}

팁: uv

기능

uv run: Run a script.
uv venv: Create a new virtual environment. By default, '.venv'.
uv add: Add a dependency to a script
uv remove: Remove a dependency from a script
uv sync: Sync (Install) the project's dependencies with the environment.

팁

python.exe에 대한 taskkill 명령어

taskkill /IM python.exe /F

Visual Code: Python 디버거: launch.json을 사용한 디버깅은 .vscode/launch.json의 구성을 사용하여 디버거를 시작합니다.

Azure OpenAI