데스크톱 채팅 클라이언트 안에서 인터랙티브 HTML 카드를 렌더링하는 MCP(Model Context Protocol) 서버입니다. 긴 텍스트의 벽 대신, 대화에 탭 박스, 표, 차트, 폼, 짧은 비디오 클립, 접이식 섹션, 번호 매기기 개요가 들어옵니다. MCP Apps 확장(SEP-1865)을 지원하는 호스트에서는 카드가 샌드박스 iframe으로 대화에 인라인 렌더링되고, 다른 호스트에서는 각 카드가 독립형 임베디드 HTML 리소스로 전달됩니다.

기능

• 탭 카드: 한 주제의 서로 다른 맥락(언어별, OS별, 숙련도별)을 나란히 볼 수 있으며, 복사 버튼이 있는 코드 샘플을 포함합니다.

• 표 카드: 명시적 행 또는 느슨하게 구분된 원시 텍스트로 HTML 표를 만듭니다. 구분 기호는 자동 감지되고, 열은 균형을 이루며, URL 셀은 링크가 됩니다.

• 차트 카드: 범례와 접근성을 위한 접이식 데이터 테이블을 갖춘 동적으로 생성된 SVG 막대, 선, 파이, 도넛 차트입니다.

• 폼 카드: 사용자가 대화에 맥락과 방향을 주기 위해 작성하는 폼입니다. 제출하면 값이 다음 프롬프트로 채팅에 다시 전송됩니다.

• 미러링된 웹사이트 폼: 실제 페이지를 가져와 그 폼 중 하나를 카드로 재구성한 다음, submit_web_form을 통해 사용자가 입력한 값으로 실제 웹사이트 폼을 제출합니다.

• 비디오 카드: 짧은 클립을 위한 HTML <video> 플레이어입니다.

• 애니메이션 카드: 직접적인 비디오 URL이 없을 때 모델이 구성한 애니메이션 클립 - 텍스트의 순차 장면, 계단식 불릿 빌드, 스스로 그려지는 간단한 SVG 다이어그램, 논의 중인 데이터 범위로 확대되는 단일 계열 차트 등이 모두 비디오 스타일의 재생/일시정지, 다시보기, 진행 컨트롤을 갖춥니다.

• 표시/숨기기 카드: 모두 표시/모두 숨기기 컨트롤이 있는 접이식 섹션입니다.

• 순차 목록 카드: CSS 카운터를 통해 1., 1.1., 1.1.1.로 번호가 매겨진 중첩 순서 목록입니다.

• 문서 카드: 마크다운 문서(모델이 작성한 가이드 또는 워크스루)를 접이식 섹션, 스타일링된 표, 복사 가능한 코드가 있는 하나의 인터랙티브 카드로 렌더링합니다.

• 코드 투어 카드: 프로젝트를 파일이 주어진 순서대로 소스 파일당 하나의 탭으로 제시합니다(README와 매니페스트가 먼저 올라감). 언어 태그가 붙은 코드와 복사 버튼이 포함됩니다.

• 모델 생성 파일 수집: 대화 초반에 모델이 생성한 로컬 텍스트 파일을 읽고 zip 아카이브의 압축을 풀어, 모델의 산출물을 다시 입력하지 않고 바로 카드에 연결할 수 있습니다.

• 자동 다중 부분 분할: 큰 문서와 프로젝트는 각 부분이 카드 크기 예산을 넘지 않도록 분할되어, 호스트가 과도하게 큰 결과를 잘라내는 일이 없습니다. 각 부분은 자체 카드로 렌더링되며 결과는 다음 부분을 정확히 가져오는 방법을 알려줍니다.

• 참조 가져오기: fetch_reference는 공개 페이지를 가져와 카드 도구에 바로 공급할 수 있는 구조화된 데이터(제목, 텍스트, 표, 이미지, 링크, 폼 사양)를 반환합니다.

• 카드 튜터: 교육용 카드는 호버 후 툴팁을 표시하는 용어를 표시할 수 있고, 모델이 예상한 프롬프트를 보내는 우클릭 컨텍스트 액션을 정의할 수 있습니다.

• 이동 가능한 콘텐츠: 카드 블록은 드래그로 재정렬할 수 있고, 카드 밖으로 드래그하면 블록이 HTML로 전달되며, 모든 카드에는 독립형 HTML을 복사하여 다른 응답이나 파일에 붙여넣을 수 있는 "카드 복사" 버튼이 있습니다.

• 헤더 토글: 모든 카드 헤더에는 카드 자체의 HTML 소스를 코드 패널에 표시하거나 숨기는 </> 버튼과, 그 옆에 카드를 헤더 행까지 접었다가 다시 펼치는 셰브론 버튼이 있습니다.

• 복사 가능한 카드: 모든 카드의 우클릭 메뉴에는 헤더 버튼을 반영하여 독립형 HTML을 복사하는 기본 제공 "카드 복사" 항목이 있습니다. 시각적 배치를 위해 get_insert_bookmarklet은 우클릭 시 떠 있는 "카드 삽입" 항목을 표시하고 복사된 카드를 해당 위치에 주입하는 북마클릿을 반환합니다(페이지 로컬 미리보기, 새로고침 시 사라짐).

Related MCP server: mcp-interactive-ui-server

모델이 이 서버를 호출해야 하는 경우

이 서버는 연구, 교육, 전문 기술, 일반 취미 기술(목공, 예술 등), 전문 주제, 역사, 뉴스 및 관련 주제에 대한 대화에서 카드가 텍스트보다 더 잘 전달될 때마다 자신을 광고합니다.

설치

git clone https://github.com/jhauga/mcp-chat-cards.git
cd mcp-chat-cards
npm install
npm run build

Node.js 18.17 이상이 필요합니다.

Claude Desktop에서 사용

claude_desktop_config.json(설정 > 개발자 > 구성 편집)에 서버를 추가하고, 저장소를 클론한 경로에 맞게 조정합니다:

{
  "mcpServers": {
    "chat-cards": {
      "command": "node",
      "args": ["C:/path/to/mcp-chat-cards/dist/index.js"]
    }
  }
}

저장 후 데스크톱 클라이언트를 다시 시작합니다. 동일한 stdio 명령이 모든 MCP 호스트에서 작동합니다. MCP UI 리소스를 지원하는 호스트에서는 카드가 샌드박스 iframe으로 렌더링됩니다.

도구

예시: create_table_card

{
  "title": "JavaScript array methods",
  "headers": ["Method", "Purpose"],
  "rows": [
    ["map", "Transform each item"],
    ["filter", "Keep matching items"],
    ["reduce", "Fold items into one value"]
  ]
}

출력: 전체 카드 문서를 포함하는 텍스트 요약과 임베디드 리소스 (ui://mcp-chat-cards/<id>, text/html).

예시: create_form_card

{
  "title": "Study preferences",
  "promptTemplate": "Teach {{topic}} with {{style}} examples.",
  "fields": [
    { "name": "topic", "label": "Topic", "required": true },
    { "name": "style", "type": "select", "options": ["practical", "theoretical"] }
  ]
}

사용자가 카드를 제출하면 채워진 템플릿이 다음 프롬프트로 호스트에 게시됩니다. 호스트가 메시지를 소비하지 않으면 카드는 폴백으로 복사 버튼과 함께 프롬프트 텍스트를 표시합니다.

예시: 모델이 생성한 파일의 플러그 앤 플레이

대화 초반에 모델이 작은 프로젝트를 만들어 project.zip과 GUIDE.md 워크스루를 전달했다고 가정해 봅시다. 사용자가 직접 압축을 풀고 읽는 대신, 모델은 두 번의 호출로 이들을 인터랙티브 카드로 바꿉니다:

{ "path": "C:/Users/jane/Downloads/GUIDE.md" }

create_markdown_card에 보내면 전체 가이드가 하나의 카드로 렌더링됩니다: 첫 번째 H1이 제목이 되고, 각 H2 섹션은 표시/숨기기 리빌로 접히며, 표는 카드 스타일링을 받고, 모든 펜스 코드 블록에는 복사 버튼이 생깁니다.

{
  "title": "Project source tour",
  "archivePath": "C:/Users/jane/Downloads/project.zip",
  "intro": "Read the guide card first, then follow these files in order."
}

create_code_tour_card에 보내면 아카이브를 메모리에서 압축 해제하고 텍스트 파일당 하나의 탭을 렌더링하며, README, 매니페스트, 소스 순으로 정렬되고 각각 언어 태그와 복사 버튼이 붙습니다. 명시적 files는 호출자가 준 순서를 유지하므로(README와 매니페스트는 앞으로 올려짐), 의도된 교육 순서 - 데이터 모델, 그다음 오류, 그다음 진입점 - 가 알파벳순 대신 작성된 대로 렌더링됩니다. 빌드 캐시(target/, node_modules/)와 바이너리 항목은 자동으로 건너뜁니다. 모델이 어떤 카드를 만들지 결정하기 전에 내용을 검사해야 할 때는 먼저 unpack_archive 또는 read_local_file을 사용하세요.

문서나 프로젝트가 카드 크기 예산(기본 약 32,000자의 카드 마크업, MCP_CHAT_CARDS_CARD_BUDGET으로 조정 가능)을 초과하면 도구는 자연스러운 경계 - 문서의 경우 H2 섹션, 투어의 경우 전체 파일 - 에서 분할하고 "part: 2로 create_code_tour_card를 다시 호출하세요"와 같은 지침과 함께 1부를 반환합니다. 모델은 모든 부분이 자체 카드로 렌더링될 때까지 호출을 반복하며, 과도하게 큰 단일 파일은 표시되는 공지와 함께 잘립니다.

예산은 파일의 디스크 길이가 아니라 렌더링 후 비용을 기준으로 측정됩니다: 소스는 탭 패널에 HTML 이스케이프되어 단일 <가 네 문자로 바뀌므로, 마크업이 많은 몇 개의 파일은 원시 크기가 시사하는 것보다 훨씬 더 많은 비용이 들 수 있습니다. 완성된 모든 결과는 그다음 호스트의 상한(직렬화된 결과 약 40,000자, MCP_CHAT_CARDS_RESULT_LIMIT으로 조정 가능)에 대해 한 번 더 측정됩니다. 여전히 너무 커서 스스로 분할할 수 없는 카드 - 예를 들어 수천 개의 행이 있는 표 - 는 호스트가 조용히 렌더링을 거부할 과도한 결과 대신 초과분을 명명하는 실행 가능한 오류를 반환합니다.

예시: 미러링된 웹사이트 폼

1. mirror_web_form을 { "url": "https://example.com/newsletter" }와 함께 호출하면 페이지의 가입 폼이 카드로 렌더링됩니다.

2. 사용자가 작성하고 제출하면 카드가 구조화된 페이로드를 채팅에 반환합니다.

3. 모델이 사용자와 값을 검토한 다음 submit_web_form을 페이로드와 함께 호출하여 실제 폼을 제출하고 HTTP 결과를 보고합니다.

카드 렌더링 방식

서버는 호스트가 자동으로 협상하는 두 가지 전달 경로를 지원합니다:

대화에 인라인(MCP Apps, SEP-1865). 서버는 MIME 유형 text/html;profile=mcp-app의 UI 템플릿 리소스 하나를 ui://mcp-chat-cards/card.html에 사전 선언하고, 모든 카드 도구는 _meta.ui.resourceUri를 통해 이를 연결하며 출력 스키마를 선언합니다(호스트는 스키마 없는 도구에서 structuredContent를 제거하여 카드가 그릴 내용을 남기지 않습니다). Apps 확장을 지원하는 호스트(최근 Claude Desktop 빌드 포함)는 템플릿을 샌드박스 iframe으로 채팅에 인라인 렌더링하고, ui/initialize 핸드셰이크를 완료하며, 도구 결과를 전달합니다. 템플릿은 조용히 실패하는 부분에 대해 방어적입니다: 핸드셰이크 응답뿐 아니라 타임아웃에도 ui/notifications/initialized를 알리고(호스트는 알림을 볼 때까지 도구 결과를 보류함), 하나의 고정 중첩 대신 깊이 검색으로 카드 페이로드를 찾고, 모든 페인트 후와 리사이즈 시 ui/notifications/size-changed를 보고하여 iframe이 실제 높이를 갖도록 하며, 호스트의 테마(전체 다크 팔레트 포함)를 채택합니다. 카드 상호작용은 JSON-RPC postMessage를 통해 다시 전달됩니다: 폼 제출과 컨텍스트 액션은 ui/message 요청(다음 대화 프롬프트)이 되고, 링크는 ui/open-link을 거치며, 텔레메트리는 로깅 알림을 사용합니다.

독립형 문서 대체. Apps 확장을 선언하지 않은 클라이언트의 경우 각 결과는 ui://mcp-chat-cards/html/<card-id>에 대한 링크를 전달합니다. 해당 리소스를 읽으면 동일한 카드가 자체 포함 HTML 문서(인라인 CSS 및 JS, 제한적인 Content-Security-Policy, 외부 스크립트 없음)로 반환됩니다. Apps 지원은 없지만 MCP-UI 스타일 렌더링이 있는 호스트는 해당 문서를 샌드박스 패널에 표시합니다. 이때 카드는 MCP-UI 스타일 메시지(prompt, notify, link)를 게시합니다.

이 문서는 의도적으로 도구 결과에 인라인되지 않습니다. 테마와 런타임은 모든 카드에서 바이트 단위로 동일하므로 인라인하면 호출당 약 16KB의 상용구가 반복됩니다. 이는 호출자의 컨텍스트를 밀어내고, 평범한 카드가 호스트의 결과 상한을 초과하여 아무것도 렌더링하지 않는 주된 이유였습니다. 리소스 링크를 따라갈 수 없는 호스트를 위해 MCP_CHAT_CARDS_EMBED_HTML=1을 설정하면 인라인 복사본을 복원할 수 있습니다. 서버는 마지막 24개의 렌더링된 카드를 읽을 수 있도록 유지합니다.

일관된 결과 형태

모든 카드 도구는 카드 종류와 관계없이 동일한 세 가지를 반환합니다.

렌더링 표면

카드는 Claude 데스크톱 앱 사이드바에 인라인으로 렌더링됩니다. 다른 표면(모바일 및 웹)은 텍스트 요약과 구조화된 페이로드를 받지만 카드를 그리지는 않으므로 각 요약은 단독으로도 의미 있게 작성되며 도구는 대화에서도 카드의 결론을 언급하도록 지시됩니다.

텍스트 필드는 일반 텍스트입니다

도구가 받아들이는 모든 텍스트 필드(제목, 레이블, 셀 값, 튜터 팁)는 일반 텍스트이며 서버에서 정확히 한 번 이스케이프됩니다. 호출자는 사전 이스케이프하면 안 됩니다. Predict, Spot & Fix가 아니라 Predict, Spot & Fix를 전달하세요.

입력은 어떤 필드에서도 먼저 디코딩되지 않습니다. &를 전달하는 호출자는 &라는 여섯 문자를 표시하는 카드를 받게 됩니다. HTML, 이스케이프 또는 템플릿을 문서화하는 가이드가 독자에게 보여주려는 것이 바로 그렇기 때문입니다. 규칙은 모든 곳에서 동일하므로 동일한 문자열은 테이블 셀, 탭, 마크다운 테이블 및 코드 샘플에서 동일하게 렌더링됩니다.

원시 HTML은 html이라는 이름의 필드(create_tab_card 및 create_reveal_card 섹션)에서만 허용되며, 여기서는 살균됩니다. 스크립트, 이벤트 핸들러, 프레임, 양식 및 위험한 URL은 제거되고 <b> 및 <i>와 같은 서식은 유지됩니다. 다른 모든 곳( create_markdown_card 문서 내부에 작성된 HTML 포함)에서는 태그가 리터럴 텍스트로 렌더링되므로 서식에는 마크다운 구문을 사용하세요. 이스케이프된 블록 수준 HTML은 형제 요소 사이에 느슨한 텍스트로 버려지는 대신 마크다운 구조가 암시하는 단락으로 감싸지며, <!-- markdownlint-disable --> 지시문은 산문이 아니므로 HTML 주석은 표시되지 않고 제거됩니다.

경로가 해석되는 위치

create_markdown_card(path), create_code_tour_card(archivePath), read_local_file 및 unpack_archive는 모두 이 서버를 실행하는 머신의 파일 시스템에서 경로를 해석합니다. 서버가 원격 브리지를 통해 연결되는 경우 이는 호출자의 샌드박스가 아닙니다. 모델이 자체 측에서 생성한 파일은 여기에 존재하지 않습니다. 이 경우 콘텐츠를 인라인(markdown, files)으로 전달하세요. 잘못된 운영 체제의 경로(예: Windows에서 실행되는 서버로 전송된 /home/demo-user/project.zip)는 존재한 적 없는 드라이브로 해석되는 대신 불일치를 명명하는 오류와 함께 거부됩니다. POSIX 서버로 전송된 Windows 경로와 확장되지 않은 ~/ 경로도 마찬가지입니다. MCP_CHAT_CARDS_FS_ROOT를 설정하여 로컬 읽기를 단일 디렉터리로 제한하세요.

상호 작용 참고 사항 및 제한 사항

• 끌어서 놓기는 한 카드 내에서 블록을 재정렬합니다. 카드 밖으로 블록을 끌면 해당 HTML이 드래그 데이터에 포함됩니다. 다른 응답에 놓으려면 호스트 지원이 필요하며, 데스크톱 채팅 클라이언트는 일반적으로 아직 이를 노출하지 않습니다.

• "카드 복사"는 독립형 HTML 문서를 복사하여 카드를 다른 응답, 파일 또는 브라우저 탭에서 재현할 수 있게 합니다.

• 튜터 도구 설명은 표시된 용어 위에 약 1.2초 동안 마우스를 올리면 나타납니다. 카드는 또한 호스트에 알리므로 모델은 사용자가 탐색하는 동안 후속 조치를 취할 수 있습니다. 각 용어는 카드당 한 번 표시되며(두 용어가 겹치는 경우 가장 긴 용어가 우선), 용어 목록의 중복은 무시되며 코드 샘플, 기본 도구 설명 또는 다른 용어의 팁 내부에서는 표시가 발생하지 않습니다. 일치는 대소문자를 구분하므로 PATH에 대해 작성된 팁은 파일 시스템 path에 붙지 않습니다. 용어에 caseInsensitive: true를 설정하면 모든 대소문자와 일치합니다. create_code_tour_card에 tutorTermsInCode: true를 전달하여 코드를 옵트인하세요.

• 모든 카드 결과는 structuredContent.parts를 { current, total, hasMore }로 전달하므로 모든 카드 유형에서 하나의 완전성 검사가 작동합니다. hasMore가 true인 동안 콘텐츠가 보류되었으며 호출자는 part: current + 1로 동일한 도구를 다시 호출합니다. create_markdown_card와 create_code_tour_card만 분할할 수 있습니다. 다른 모든 카드는 항상 { current: 1, total: 1, hasMore: false }를 보고합니다. 렌더링된 제목은 독자를 위해 사람이 읽을 수 있는 (part 1 of 2) 접미사를 유지합니다.

• 분할 임계값은 호출자가 작성한 입력이 아닌 렌더링된 문자로 측정됩니다. 이스케이프는 소스를 예측할 수 없게 확장합니다. <, >, & 및 따옴표는 각각 4~6자가 되므로 예산보다 훨씬 작아 보이는 페이로드가 이를 초과할 수 있고 더 커 보이는 페이로드는 그렇지 않을 수 있습니다. 입력 크기로 예측하지 말고 parts.hasMore를 읽으세요. H2 제목이 없는 마크다운 문서에는 분할 경계가 없으며 항상 한 부분으로 렌더링됩니다.

• 마우스 오른쪽 버튼 클릭 컨텍스트 작업은 카드별로 모델이 정의합니다. 작업 프롬프트의 {{selection}}은 사용자가 선택한 텍스트로 대체됩니다.

보안

• 로컬 파일 도구(read_local_file, unpack_archive, 문서 및 코드 투어 카드의 경로/아카이브 입력)는 텍스트만 읽고, 크기를 제한하고, 바이너리를 거부하고, 아카이브 추출(항목 수, 파일당, 총 바이트)을 제한합니다. MCP_CHAT_CARDS_FS_ROOT를 설정하여 모든 로컬 읽기를 단일 디렉터리로 제한하세요.

• 나가는 요청은 공용 주소로 해석되는 http(s) URL로 제한됩니다. localhost, RFC 1918, link-local, CGNAT 및 이에 상응하는 IPv6 범위는 차단되고, 리디렉션은 재검증되며, 본문은 크기가 제한되고, 요청은 시간 초과됩니다. 인트라넷 가져오기가 의도적으로 필요한 경우에만 MCP_CHAT_CARDS_ALLOW_PRIVATE=1을 설정하세요.

• 모델 및 사용자가 제공한 모든 텍스트는 HTML 이스케이프됩니다. 가져온 타사 HTML은 살균됩니다(스크립트, 이벤트 핸들러, 프레임, 양식 및 위험한 URL 제거).

• 카드는 제한적인 CSP를 제공하며 외부 스크립트, 스타일시트 또는 글꼴을 로드하지 않습니다.

• submit_web_form은 사용자가 미러링된 양식 카드에 입력했거나 명시적으로 확인한 값으로만 호출해야 합니다.

Claude Desktop에서 카드 디버깅

카드가 마운트되었지만 비어 있으면 실패는 일반적으로 조용하므로 템플릿은 모든 것을 콘솔에 기록합니다.

1. Claude Desktop에서 개발자 모드를 활성화하고(설정, 개발자) 대화의 webview 개발자 도구를 엽니다.

2. 콘솔을 [mcp-chat-cards]로 필터링합니다. 카드가 보내고 받는 모든 JSON-RPC 메시지는 방향(tx/rx)과 함께 기록되므로 누락된 핸드셰이크 응답이나 전달되지 않은 도구 결과가 즉시 표시됩니다.

3. 해당 콘솔에서 window.__mccDebug()를 실행하여 스냅샷을 확인합니다. 템플릿 버전, initialized가 알려졌는지 여부, 카드가 그려졌는지 여부, 렌더링된 카드 HTML 및 마지막 50개의 프로토콜 메시지. 렌더링 문제를 보고할 때 출력을 붙여넣으세요.

보조 포트

extension/ 폴더에는 다른 호스트용 카드 도구의 보조 포트가 포함되어 있습니다. 둘 다 자체 포함되어 있습니다. src/ 또는 dist/에서 가져오지 않으며 MCP 서버는 이들의 영향을 받지 않습니다.

• extension/github/ - chat-cards라는 GitHub Copilot 캔버스 확장입니다. 에이전트는 캔버스 작업을 통해 동일한 카드 종류(탭, 테이블, 차트, 양식, 표시/숨기기, 순차 목록, 마크다운 문서, 비디오)를 구동하며 양식 제출은 프롬프트로 대화에 다시 돌아옵니다. README는 작업 목록, MCP 도구와의 차이점, 폴더가 awesome-copilot 기여 레이아웃에 매핑되는 방식을 다룹니다.

• extension/claude/ - Claude 아티팩트 템플릿: Claude가 카드 사양 블록을 채우고 아티팩트로 게시하는 자체 포함 HTML 페이지 하나. 양식 및 마우스 오른쪽 버튼 클릭 작업은 사용자가 대화에 다시 복사하는 프롬프트를 생성합니다.

개발

npm run build      # compile TypeScript to dist/
npm test           # run the vitest suite (unit + in-memory MCP integration)
npm run coverage   # run tests with V8 coverage
npm run dev        # compile in watch mode

라이선스

MIT. LICENSE를 참조하세요.