본문으로 건너뛰기

MCP 모듈 개요

MCP(Model Context Protocol) 모듈은 외부 MCP 서버와의 연결, 도구 검색, 형식 변환, 호출 실행을 관리합니다. 이 모듈은 계층형 아키텍처를 사용하며, 코어는 메인 프로세스에 위치하고 IPC를 통해 렌더러 프로세스에 노출됩니다.

아키텍처 다이어그램​

graph TB
    subgraph Renderer["렌더러 프로세스"]
        McpPage["McpServersPage"]
        McpForm["McpServerForm"]
        McpManage["McpManageDialog"]
        UseMcp["useMcpMode Hook"]
        UseMgmt["useMcpManagement Hook"]
    end

    subgraph Main["메인 프로세스"]
        McpRouter["McpRouter<br/>(IPC 라우팅)"]
        McpService["McpService<br/>(연결 풀)"]
        ToolsLoader["ToolsLoader<br/>(형식 변환)"]
        DepCheck["DependencyCheckService<br/>(의존성 검사)"]

        subgraph Transports["전송 레이어"]
            Stdio["StdioClientTransport"]
            SSE["SSEClientTransport"]
            HTTP["StreamableHTTPClientTransport"]
        end

        subgraph TinyElf["TinyElf 엔진"]
            McpAdapter["McpToolAdapter<br/>(ITool 래핑)"]
            DirectAdapter["DirectMcpToolAdapter<br/>(내장 서버)"]
            Tracker["McpProcessTracker<br/>(프로세스 추적)"]
        end
    end

    subgraph Worker["Worker 스레드"]
        McpWorker["mcp.worker.ts<br/>(CLI 브리징)"]
    end

    subgraph External["외부"]
        MCP1["MCP Server A<br/>(stdio)"]
        MCP2["MCP Server B<br/>(SSE/HTTP)"]
        ClaudeCLI["claude CLI"]
    end

    McpPage -->|IPC| McpRouter
    McpRouter --> McpService
    McpRouter --> DepCheck
    McpService --> Stdio
    McpService --> SSE
    McpService --> HTTP
    Stdio --> MCP1
    SSE --> MCP2
    HTTP --> MCP2
    McpService --> ToolsLoader
    McpService --> McpAdapter
    McpAdapter --> McpService
    DirectAdapter --> MCP1
    Tracker --> DirectAdapter
    McpWorker --> ClaudeCLI

주요 파일​

파일경로역할
McpService.tsdesktop/app/main/services/capabilities/tools/mcp-users/연결 풀 관리, 클라이언트 라이프사이클, 도구 캐싱
ToolsLoader.tsdesktop/app/main/services/capabilities/tools/mcp-users/MCP 도구를 OpenAI/Anthropic/Gemini 형식으로 변환
DependencyCheckService.tsdesktop/app/main/services/capabilities/tools/mcp-users/커맨드라인 의존성 감지 및 자동 설치
McpRouter.tsdesktop/app/main/services/routers/IPC 라우팅 등록, 파라미터 유효성 검사
McpToolAdapter.tsdesktop/app/main/services/agent-core/engine/tinyelf/tools/MCPTool에서 ITool로의 어댑터
McpProcessTracker.tsdesktop/app/main/services/agent-core/engine/tinyelf/tools/자식 프로세스 PID 추적 및 정리
mcp.worker.tsdesktop/app/main/workers/Worker 스레드, CLI 브리징
mcp-types.tsdesktop/app/shared/contracts/공유 타입 정의
mcp-presets.tsdesktop/app/shared/공식 MCP 서버 프리셋
mcp-detector.tsdesktop/app/main/lib/utils/MCP 설정 감지 유틸리티
McpServersPage.tsxrenderer/src/pages/MCP 서버 관리 페이지
McpServerForm.tsxrenderer/src/features/settings/components/tabs/tools-tab/추가/편집 폼
McpManageDialog.tsxrenderer/src/features/marketplace/components/mcp/Agent 연관 관리
useMcpMode.tsrenderer/src/features/marketplace/hooks/mcp/MCP 모드 및 도구 선택 Hook
useMcpManagement.tsrenderer/src/features/settings/components/tabs/tools-tab/hooks/CRUD 관리 Hook

IPC 채널​

모든 MCP 관련 IPC 채널은 McpRouter를 통해 등록되며, secureHandle로 인증됩니다:

채널방향파라미터반환값설명
mcp:listR→M없음McpServerRecord[]모든 서버 목록 조회
mcp:addR→MMcpServerInputMcpActionResult서버 추가
mcp:addJsonR→MMcpServerJsonInputMcpActionResultJSON에서 일괄 추가
mcp:removeR→MMcpServerRemoveInputMcpActionResult서버 삭제
mcp:updateR→M{ id, updates }McpActionResult서버 설정 수정
mcp:testR→MMcpServerRemoveInputMcpTestResult연결 테스트
mcp:discoverR→MMcpServerRemoveInputMcpDiscoverResult도구/리소스/프롬프트 검색
mcp:list-server-toolsR→M{ serverId }MCPTool[]단일 서버 도구 목록
mcp:list-all-toolsR→M없음MCPTool[]모든 활성 서버 도구 목록
mcp:call-toolR→M{ serverId, toolName, args, callId }MCPCallToolResponse도구 호출
mcp:check-dependencyR→M{ command }DependencyCheckResult의존성 확인
mcp:install-dependencyR→M{ command }DependencyInstallResult의존성 설치

코어 타입​

type McpServerTransport = 'stdio' | 'http' | 'sse';
type McpServerScope = 'user' | 'local';
type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
type McpMode = 'disabled' | 'auto' | 'manual';

interface McpServerRecord {
  id: string;
  name: string;
  scope: McpServerScope;
  type: McpServerTransport;
  config: McpServerConfig;
  isActive?: boolean;
  isTrusted?: boolean;
  disabledTools?: string[];
  installSource?: 'builtin' | 'manual' | 'protocol' | 'unknown';
  createdAt?: number;
  updatedAt?: number;
}

interface MCPTool {
  id: string;           // mcp__serverName__toolName
  serverId: string;
  serverName: string;
  name: string;
  description?: string;
  inputSchema: Record<string, any>;
  type: 'mcp';
}

모듈 간 의존 관계​

graph LR
    McpRouter --> McpService
    McpRouter --> DependencyCheckService
    McpService --> ConfigStore["Electron Store<br/>(mcp-config)"]
    McpService --> MCP_SDK["@modelcontextprotocol/sdk"]
    ToolsLoader --> McpService
    McpToolAdapter --> McpService
    CompletionService["CompletionService"] --> ToolsLoader
    TinyElfEngine --> McpToolAdapter
    TinyElfEngine --> DirectMcpToolAdapter

데이터 흐름​

도구 로딩 흐름​

사용자가 채팅 시작
    ↓
CompletionService가 setupMcpTools() 호출
    ↓
fetchMcpTools()가 MCP 모드에 따라 로드할 서버 결정
    ↓ (auto: 모든 활성 서버 / manual: 선택된 서버)
McpService.listServerTools() / listAllActiveServerTools()
    ↓ (캐시 확인 → 히트: 반환 / 미스: initClient + listTools)
ToolsLoader가 대상 형식으로 변환 (OpenAI / Anthropic / Gemini)
    ↓
도구 정의가 LLM 요청에 주입됨

도구 호출 흐름​

LLM이 tool_call 반환 (name = mcp__server__tool)
    ↓
서버 ID 및 도구 이름 파싱
    ↓
McpService.callTool(serverId, toolName, args, callId)
    ↓
initClient()로 연결 확보 → client.callTool()
    ↓
MCPCallToolResponse 반환 (isError, content[])
    ↓
결과가 LLM에 전달되어 대화 계속

관련 문서​