Skip to content

Commit 34e5f7f

Browse files
committed
feat: MCP 페이지 렌더링 도구 추가
1 parent 001d009 commit 34e5f7f

8 files changed

Lines changed: 216 additions & 27 deletions

File tree

‎infra/server.Dockerfile‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ ENV PATH="${PATH}:/root/.local/bin:" \
1313
UV_CONCURRENT_DOWNLOADS=32 \
1414
UV_LINK_MODE=copy \
1515
UV_PROJECT_ENVIRONMENT="/usr/local" \
16-
UV_PYTHON_DOWNLOADS=0
16+
UV_PYTHON_DOWNLOADS=0 \
17+
PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
1718

1819
# Setup timezone and install system dependencies
1920
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
@@ -27,6 +28,17 @@ RUN --mount=type=cache,target=/root/.cache/uv \
2728
&& rm -rf /var/lib/apt/lists/* \
2829
&& uv sync --no-default-groups --group mcp --frozen
2930

31+
# Bundle Chromium for the MCP `mdx_preview` tool. The browser download is cached
32+
# across builds via a BuildKit cache mount, then copied into the image (cache mounts
33+
# aren't persisted into layers). Kept before `COPY app/` so app-code changes never
34+
# re-trigger it. PLAYWRIGHT_BROWSERS_PATH (set above) is where the runtime looks.
35+
RUN --mount=type=cache,target=/opt/pw-cache \
36+
PLAYWRIGHT_BROWSERS_PATH=/opt/pw-cache playwright install --with-deps chromium \
37+
&& rm -rf /var/lib/apt/lists/* \
38+
&& mkdir -p "$PLAYWRIGHT_BROWSERS_PATH" \
39+
&& cp -a /opt/pw-cache/. "$PLAYWRIGHT_BROWSERS_PATH"/ \
40+
&& chmod -R a+rX "$PLAYWRIGHT_BROWSERS_PATH"
41+
3042
# The nobody user has no writable fontconfig cache dir, which triggers "Fontconfig error: No writable cache directories" on every WeasyPrint render.
3143
# Give it a writable cache path.
3244
ENV XDG_CACHE_HOME=/tmp

‎mcp_app/config.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,4 @@
77
PATH = os.environ.get("MCP_PATH", "/mcp")
88

99
HTTP_TIMEOUT = float(os.environ.get("MCP_HTTP_TIMEOUT", "15"))
10+
BROWSER_TIMEOUT = float(os.environ.get("MCP_BROWSER_TIMEOUT", "30"))

‎mcp_app/mdx_components.py‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,14 @@
77
from httpx import AsyncClient, HTTPError
88

99
from mcp_app import config
10+
from mcp_app.util import require_host
1011

1112
_CACHE_TTL = 300.0
1213
_cache: dict[str, tuple[float, dict]] = {}
1314

1415

1516
async def _fetch(domain: str) -> dict:
16-
if not (host := domain.strip().lower()):
17-
raise ToolError(
18-
"domain 에 프론트엔드 호스트가 필요합니다 (예: 2026.pycon.kr). 도메인 그룹 목록 도구로 유효한 도메인을 확인하세요."
19-
)
20-
17+
host = require_host(domain)
2118
url = f"https://{host}/.well-known/mdx-components.json"
2219
now = monotonic()
2320
if (hit := _cache.get(url)) and hit[0] > now:

‎mcp_app/mdx_preview.py‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
from contextlib import suppress
2+
3+
from fastmcp.exceptions import ToolError
4+
from playwright.async_api import Error as PlaywrightError
5+
from playwright.async_api import TimeoutError as PlaywrightTimeoutError
6+
from playwright.async_api import async_playwright
7+
8+
from mcp_app import config
9+
from mcp_app.util import require_host
10+
11+
_MESSAGE_TYPE = "pyconkr:mdx-preview"
12+
_READY_SELECTOR = "html[data-mdx-preview='ready']"
13+
_CONTENT_SELECTOR = "[data-mdx-preview-content]"
14+
_SETTLE_MS = 600
15+
_TIMEOUT_MS = int(config.BROWSER_TIMEOUT * 1000)
16+
17+
18+
async def render(
19+
domain: str,
20+
sections: list[dict],
21+
*,
22+
title: str | None = None,
23+
page_css: str | None = None,
24+
show_top_title_banner: bool = False,
25+
show_bottom_sponsor_banner: bool = False,
26+
viewport_width: int = 1280,
27+
full_page: bool = True,
28+
html_scope: str = "content",
29+
include_screenshot: bool = True,
30+
) -> dict:
31+
url = f"https://{require_host(domain)}/preview"
32+
33+
async with async_playwright() as pw:
34+
browser = await pw.chromium.launch(headless=True)
35+
try:
36+
page = await (
37+
await browser.new_context(
38+
viewport={"width": max(320, viewport_width), "height": 900},
39+
ignore_https_errors=True, # 로컬 dev(mkcert) 인증서 허용
40+
)
41+
).new_page()
42+
try:
43+
await page.goto(url, wait_until="domcontentloaded", timeout=_TIMEOUT_MS)
44+
await page.wait_for_selector(_READY_SELECTOR, timeout=_TIMEOUT_MS)
45+
except PlaywrightTimeoutError as exc:
46+
msg = f"{domain} 의 미리보기 라우트 접근 실패. 해당 프론트엔드에 /preview 라우트가 있는지, domain 이 올바른지 확인하세요."
47+
raise ToolError(msg) from exc
48+
await page.evaluate(
49+
f"(payload) => window.postMessage({{ type: {_MESSAGE_TYPE!r}, payload }}, window.location.origin)",
50+
{
51+
"css": page_css,
52+
"title": title,
53+
"show_top_title_banner": show_top_title_banner,
54+
"show_bottom_sponsor_banner": show_bottom_sponsor_banner,
55+
"sections": sections,
56+
},
57+
)
58+
await page.wait_for_selector(_CONTENT_SELECTOR, timeout=_TIMEOUT_MS)
59+
with suppress(PlaywrightTimeoutError):
60+
await page.wait_for_load_state("networkidle", timeout=_TIMEOUT_MS)
61+
await page.wait_for_timeout(_SETTLE_MS)
62+
63+
if html_scope == "document":
64+
html = await page.content()
65+
else:
66+
node = await page.query_selector(_CONTENT_SELECTOR)
67+
html = await node.evaluate("el => el.outerHTML") if node else ""
68+
69+
screenshot = await page.screenshot(full_page=full_page, type="png") if include_screenshot else None
70+
except PlaywrightError as exc:
71+
raise ToolError(f"미리보기 렌더링에 실패했습니다: {exc}") from exc
72+
finally:
73+
await browser.close()
74+
75+
return {"url": url, "html": html, "screenshot_png": screenshot}

‎mcp_app/server.py‎

Lines changed: 60 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
from __future__ import annotations
2-
31
import httpx
42
from fastmcp import Context, FastMCP
53
from fastmcp.exceptions import ToolError
@@ -9,35 +7,36 @@
97
OpenAPIResourceTemplate,
108
OpenAPITool,
119
)
10+
from fastmcp.tools.base import ToolResult
1211
from fastmcp.utilities.openapi import HTTPRoute
12+
from fastmcp.utilities.types import Image
13+
from mcp.types import TextContent
1314

1415
from mcp_app import config
1516
from mcp_app import mdx_components as mdx
17+
from mcp_app import mdx_preview as preview
1618
from mcp_app.auth import ADMIN_TAG, AUTH_KEY, AuthMiddleware, AuthState, CurrentAuth
1719
from mcp_app.routes import ROUTE_MAPS, lookup
1820

1921
LANG_KEY = "language"
2022
_SUPPORTED_LANGS = ("ko", "en")
2123
_GUIDANCE_ADMIN = (
22-
"공개 도구 + 어드민 도구(CMS 페이지·사이트맵 쓰기, 대시보드 통계, 주문·상품·카테고리 조회)를 사용할 수 있습니다. "
23-
"쓰기 시 생성/수정 도구의 입력 스키마를 참고하세요 — 각 필드에 x-ui-schema(위젯; markdown 여부), "
24-
"x-translation({of,language}; *_ko/*_en 매핑), x-relation({model,many}; FK/M2M 대상)이 붙습니다. "
25-
"관계 필드 값은 해당 리소스의 choices 도구로 유효 id 를 확인해 채우세요. "
26-
"CMS 본문(섹션 body)은 Markdown 이 아니라 MDX 입니다 — 사용 가능한 컴포넌트와 props 는 `mdx_components` 도구로 확인하세요. "
27-
"컴포넌트 목록은 프론트엔드 도메인(앱)마다 다르므로, 먼저 `도메인 그룹 목록`으로 해당 페이지의 "
28-
"domain_group → 실제 도메인(예: 2026.pycon.kr)을 확인한 뒤 그 도메인으로 호출하세요."
24+
"공개+어드민 도구(CMS 페이지·사이트맵 쓰기, 대시보드, 주문·상품·카테고리 읽기)를 쓸 수 있습니다. "
25+
"쓰기 전 입력 스키마의 x-ui-schema(위젯), x-translation(*_ko/*_en), x-relation(FK/M2M 대상)을 확인하고, "
26+
"관계 필드는 choices 도구로 유효 id 를 채우세요. "
27+
"CMS 섹션 body 는 MDX — 컴포넌트·props 는 `mdx_components`, 미리보기는 `mdx_preview` "
28+
"(둘 다 domain 인자: `도메인 그룹 목록`의 실제 호스트, 예 2026.pycon.kr)."
2929
)
3030
_GUIDANCE_PUBLIC = (
3131
"공개 도구(후원사·발표·이벤트 조회)를 사용할 수 있습니다. 더 많은 기능이 필요하면 유효한 토큰으로 다시 연결하세요."
3232
)
3333

3434

3535
def _customize_component(route: HTTPRoute, component: OpenAPITool | OpenAPIResource | OpenAPIResourceTemplate) -> None:
36-
method, path = route.method.upper(), route.path
37-
if (doc := lookup(method, path)) is None:
36+
if (doc := lookup(route.method.upper(), route.path)) is None:
3837
return
3938
component.title = doc.summary
40-
component.description = "\n\n".join(filter(None, [doc.description, f"호출: {method} {path}"]))
39+
component.description = doc.description
4140

4241

4342
async def _forward_headers(request: httpx.Request) -> None:
@@ -53,9 +52,8 @@ def build() -> FastMCP:
5352
mcp = FastMCP.from_openapi(
5453
name="pyconkr",
5554
instructions=(
56-
"PyCon Korea(파이콘 한국 — 한국에서 열리는 Python 언어 컨퍼런스)의 MCP 서버입니다. "
57-
"먼저 `auth_status` 로 사용 가능한 기능을 확인하세요. "
58-
"응답 언어는 `set_language` 로 바꿀 수 있습니다(`ko`=한국어 기본, `en`=영어)."
55+
"PyCon Korea(파이콘 한국) MCP 서버. 먼저 `auth_status` 로 가능한 기능을 확인하세요. "
56+
"응답 언어는 `set_language`(ko=기본/en)."
5957
),
6058
route_maps=ROUTE_MAPS,
6159
mcp_component_fn=_customize_component,
@@ -97,11 +95,8 @@ async def set_language(language: str, ctx: Context) -> dict:
9795
@mcp.tool(
9896
title="MDX 컴포넌트 조회",
9997
description=(
100-
"CMS 본문(MDX)에서 쓸 수 있는 컴포넌트와 props 를 조회한다. 컴포넌트 집합은 프론트엔드 도메인(앱)마다 다르므로 "
101-
"`도메인 그룹 목록`으로 확인한 실제 호스트를 domain 에 넣는다(예: 2026.pycon.kr). "
102-
"component 를 비우면 목록(이름·group·요약), 채우면 그 컴포넌트의 props 상세를 반환한다. "
103-
"group(mui|common|shop)으로 목록을 좁힐 수 있다. "
104-
"Mui__* 컴포넌트는 props 설명이 없으니 응답의 muiVersion 기준 MUI 공식 문서를 참고한다."
98+
"CMS 본문(MDX)에 쓸 수 있는 컴포넌트·props 조회. domain 은 `도메인 그룹 목록`의 실제 호스트(예: 2026.pycon.kr). "
99+
"component 를 비우면 목록, 채우면 props 상세. group(mui|common|shop)으로 필터."
105100
),
106101
tags={ADMIN_TAG},
107102
)
@@ -110,4 +105,49 @@ async def mdx_components(domain: str, component: str | None = None, group: str |
110105
return await mdx.detail(domain, component)
111106
return await mdx.compact(domain, group)
112107

108+
@mcp.tool(
109+
title="MDX 렌더링 미리보기",
110+
description=(
111+
"작성한 MDX 를 실제 프론트(domain)에서 렌더해 HTML+스크린샷 반환(페이지·섹션 생성 없이). "
112+
"domain 은 `도메인 그룹 목록`의 실제 호스트(예: 2026.pycon.kr), mdx 는 섹션 본문. "
113+
"html_scope=content(기본)|document. 그 외 파라미터로 CSS·제목·배너·뷰포트·캡처 범위를 조정."
114+
),
115+
tags={ADMIN_TAG},
116+
)
117+
async def mdx_preview(
118+
domain: str,
119+
mdx: str,
120+
section_css: str | None = None,
121+
page_css: str | None = None,
122+
title: str | None = None,
123+
show_top_title_banner: bool = False,
124+
show_bottom_sponsor_banner: bool = False,
125+
viewport_width: int = 1280,
126+
full_page: bool = True,
127+
html_scope: str = "content",
128+
include_screenshot: bool = True,
129+
) -> ToolResult:
130+
if html_scope not in ("content", "document"):
131+
raise ToolError("html_scope 는 content 또는 document 여야 합니다.")
132+
result = await preview.render(
133+
domain,
134+
[{"id": "preview", "css": section_css, "body": mdx}],
135+
title=title,
136+
page_css=page_css,
137+
show_top_title_banner=show_top_title_banner,
138+
show_bottom_sponsor_banner=show_bottom_sponsor_banner,
139+
viewport_width=viewport_width,
140+
full_page=full_page,
141+
html_scope=html_scope,
142+
include_screenshot=include_screenshot,
143+
)
144+
blocks: list = []
145+
if result.get("screenshot_png"):
146+
blocks.append(Image(data=result["screenshot_png"], format="png").to_image_content())
147+
blocks.append(TextContent(type="text", text=result["html"]))
148+
return ToolResult(
149+
content=blocks,
150+
structured_content={"url": result["url"], "scope": html_scope},
151+
)
152+
113153
return mcp

‎mcp_app/util.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
from fastmcp.exceptions import ToolError
2+
3+
4+
def require_host(domain: str) -> str:
5+
if host := domain.strip().strip("/").lower():
6+
return host
7+
8+
raise ToolError(
9+
"domain 에 프론트엔드 호스트가 필요합니다 (예: 2026.pycon.kr). 도메인 그룹 목록 도구로 유효한 도메인을 확인하세요."
10+
)

‎pyproject.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ dependencies = [
5252
[dependency-groups]
5353
mcp = [
5454
"fastmcp>=3.4.2",
55+
"playwright>=1.49.0",
5556
]
5657
dev = [
5758
"django-stubs[compatible-mypy]>=6.0.4",

0 commit comments

Comments
 (0)