[OSSCA 2025] React Component를 활용한 MCP Tool 개발

✨ 공부하며 성장하는 기록 공간입니다.
아직 부족한 점이 많고 배워야 할 것도 많지만, 그만큼 배우는 즐거움도 큽니다.
틀리거나 부족한 내용이 있다면 언제든지 편하게 지적해 주세요 😁

이 블로그는 오픈소스 프로젝트 githru-vscode-extension을 공부하고 기여한 내용을 정리한 공간입니다.
처음보다 성장해 있는 나 자신을 기대하며 꾸준히 기록해나가겠습니다!

 

서론

이전 포스팅에서는 Githru MCP Server에 기여자 추천 Tool을 구현하였습니다.

https://dev-hiro.tistory.com/194

[OSSCA 2025] Githru MCP Server - 기여자 추천 Tool 개발

 

하지만 이전 MCP Tool은 Githru의 기능을 반의반의반도 사용하지 않았는데, Githru는 다음과 같은 장점을 가집니다.

1. Git 히스토리 시각화
   1. 단순한 커밋 목록이나 선형 그래프를 넘어, Git 메타데이터 분석을 기반으로 프로젝트의 개발 흐름과 변천사를 직관적으로 파악합니다.
2. 개발 컨텍스트 이해
   1. 소프트웨어 개발 과정에서 코드의 변화 흐름, 기여도, 히스토리를 시각화된 인터페이스로 제공하여 프로젝트 파악 시간을 줄여줍니다.
3. 가벼운 구동
   1. 핵심 기능에 집중하여 무겁지 않고 안정적으로 동작하도록 설계되었습니다.

하지만 이러한 기능들을 MCP Server에서 사용할 수 없습니다.

왜냐하면 Githru는 VS Code Extension 으로 통해 Git의 메타데이터를 파악하기에 MCP로 사용할 수 없습니다.

 

또한, 뛰어난 시각화를 가진 해당 프로젝트를 MCP 서버로 옮기면 어떨까라는 생각으로
Githru의 StoryLine UI MCP Tool를 개발해보기로 하였습니다.

 

이번 포스팅은 제가 작업한 결과들을 따라가면서 저의 생각과 고민의 흐름대로 포스팅을 진행합니다.

 

MCP Server에서 React Component를 사용할 수 있을까?

MCP Tool의 응답 구조

이전 MCP Server와 MCP Client에 대한 내용을 설명했는데 간단하게 한번 더 말해보면

MCP는 AI 애플리케이션이 외부 시스템의 기능과 데이터에 접근할 수 있도록 표준화된 인터페이스를 제공하는 프로토콜입니다.

 

MCP Server는 Tool을 정의하고 MCP Client는 Tool을 호출하여 결과를 전달 받습니다.

호출 흐름은 다음과 같습니다.

MCP 호출 흐름

 

MCP Tool은 CallToolResult 형식으로 결과를 반환하며, content 배열에는 텍스트나 이미지와 같은 콘텐츠를 포함할 수 있다.

예를 들어 텍스트나 Image를 반환하는 경우 type에 다음과 같이 할 수 있습니다.

# 텍스트를 반환하는 경우
return {
  content: [
    {
      type: "text",
      text: "Git 저장소 분석이 완료되었습니다."
    }
  ]
};

# 이미지를 반환하는 경우
return {
  content: [
    {
      type: "image",
      data: pngBuffer.toString("base64"),
      mimeType: "image/png"
    }
  ]
};

 

MCP Tool은 이렇게 제한된 타입만을 반환할 수 있어, React Component를 직접 렌더링 할 수 없습니다..!

 

React Component는 JavaScript 실행 환경과 렌더링 과정이 필요한 UI 구성 요소입니다.

반면 MCP Tool 응답은 프로토콜을 통해 전달할 수 있는 데이터 형태로 직렬화 되었어야 합니다.

 

그렇기에 React Component를 반환한다고 하더라도 MCP Host가 이를 실행하거나 화면에 표시할 수 없습니다.

 

여기서 제가 고민한 부분은 다음과 같습니다.

1. React Component를 서버사이드에서 렌더링해서 화면을 보여줄 수 있을까?
2. Component를 Client로 props에 전달할 수 있는 방법이 있을까?
3. 렌더링 결과를 정적인 이미지로 전달하면 어떨까?

이러한 부분을 검증하기 위해 새로운 PR을 진행하게 되었습니다.

컴포넌트를 텍스트로 넘기면 LLM이 어떻게 읽을까?

간단한 React Component를 대상으로 MCP Server와의 연동 가능성을 확인했습다.

PR에서는 크게 두가지를 검증했습니다.

 

• React Component의 MCP Server 연동
• React Component에 props를 전달하는 방식.

React Component의 서버사이드 렌더링

React는 브라우저에서만 사용할 수 있는 라이브러리가 아니기에, react-dom/server 를 통해 서버 사이드 렌더링을 하여 Node.js 환경에서도 React Component를 HTML 문자열로 렌더링할 수 있는 방식을 고민했습니다.

import React from "react";
import { renderToStaticMarkup } from "react-dom/server";

function Greeting({ name }: { name: string }) {
  return <h1>Hello, {name}!</h1>;
}

const html = renderToStaticMarkup(
  <Greeting name="Githru" />
);

console.log(html);

# 실행 결과
<h1>Hello, Githru!</h1>

 

코드를 예시로 구성하면 다음과 같다.

const html = renderToStaticMarkup(
  <Greeting name="Githru" />
);

# 실행 결과
<h1>Hello, Githru!</h1>

# MCP Tool 반환
return {
  content: [
    {
      type: "text",
      text: html
    }
  ]
};

 

하지만 여기서 한 가지 문제가 발생합니다.

 

Node.js에서 SSR을 통해 React Component를 HTML 문자열로 변환하는 것은 가능하지만, 이를 MCP Tool의 text 콘텐츠로 반환한다고 해서 MCP Host가 실제 HTML 화면으로 렌더링하는 것은 보장되지 않습니다.

 

즉, React Component를 HTML로 변환하는 것과 MCP Host에서 이를 UI로 표시하는 것은 별개의 문제입니다.

 

따라서 React Component를 직접 렌더링하는 방식 외에, MCP Tool이 컴포넌트의 구조와 데이터를 전달하고 Claude가 이를 이해하고 활용할 수 있는지도 확인하고자 했습니다.

 

Props로 전달하기

이번에는 React Component를 HTML로 렌더링하는 대신, 컴포넌트의 소스코드와 Props에 필요한 데이터 구조를 텍스트로 전달하는 방식을 테스트했습니다.

 

핵심적으로 고민한 부분은 다음과 같습니다.

MCP Tool은 텍스트 형태로 컴포넌트의 소스코드를 전달할 수 있습니다. 그렇다면 컴포넌트의 사용 방법과 Props 데이터 구조까지 함께 제공했을 때, Claude가 이를 이해하고 활용할 수 있을까?

 

이를 확인하기 위해 dataDrivenComponentTester.ts에서는 컴포넌트의 소스코드뿐 아니라 사용 예시, 샘플 데이터, 데이터 타입 정보까지 함께 정의했습니다.

// dataDrivenComponentTester.ts (발췌)
chart: {
  title: "Bar Chart Component",
  component: `const BarChart = ({ data, title, width = 400, height = 300 }) => { ... }`,
  usage: `<BarChart data={[{ name: 'A', value: 30 }, ...]} title="Sales Data" />`,
  sampleData: [{ name: 'A', value: 30 }, { name: 'B', value: 50 }, { name: 'C', value: 20 }],
  dataStructure: `{ name: string; value: number; }[]`,
}

이를 통해 컴포넌트 소스에 더해 입력 데이터 타입과 샘플까지 주면 Claude가 컴포넌트의 props의 구조를 읽고 설명하는 것까지 확인할 수 있었습니다!

react_component_test Tool을 활용한 결과

data_driven_component_test Tool을 통한 결과

 

개발한 MCP Tool

Tool	역할
react_component_test	난이도별(simple/medium/complex) 컴포넌트 소스를 마크다운으로 반환
data_driven_component_test	props로 데이터를 받는 컴포넌트(chart/table/list/card)와 sampleData, dataStructure를 함께 반환
generate_csm_dict	AnalysisEngine을 돌려 CSMDict를 JSON으로 반환

 

한계

다만 이 방식도 이전 문제를 모두 해결하진 않았습니다.

Claude가 제가 원하는 코드를 실제 MCP Host 내에서 구현은 해주었지만, 실제 코드를 렌더링하는 것과는 다른 문제입니다.

 

이는 MCP Host(Claude)가 MCP Server에서 받은 결과를 토대로 코드를 "이해"해서 화면을 그려준 것이기 때문입니다.

 

또한 Githru의 NewViz 컴포넌트에 적용하는 것은 다른 문제였습니다.

이것은 React Component를 서버에서 우회해서 처리하여 Claude에 보여준 것이지만, 실제 Githru의 NewViz 컴포넌트에 적용할 수 있을 지는 미지수 였습니다.

 

특히 완성된 HTML 템플릿이 아닌 React Componet를 반환해야했기에, MCP Tool 응답으로 전달하는 방식으로 해결할 수는 없었기에,

1. 컴포넌트가 요구하는 데이터 구조를 조립하여,
2. 렌더링 환경을 구성한 뒤
3. 최종 결과를 MCP Host가 표시할 수 있는 형태로 변환해야했습니다.

이 문제를 해결하기 위해, 실제 Storyline UI 연동작업을 진행하였습니다.

 

다음 포스팅에서는 Githru의 NewViz 컴포넌트를 MCP Host에 연동한, MCP Tool에 대한 포스팅을 진행하겠습니다.

 

 

참조

• PR 932: https://github.com/githru/githru-vscode-ext/pull/932
• repo: https://github.com/githru/githru-vscode-ext