1- from __future__ import annotations
2-
31import httpx
42from fastmcp import Context , FastMCP
53from fastmcp .exceptions import ToolError
97 OpenAPIResourceTemplate ,
108 OpenAPITool ,
119)
10+ from fastmcp .tools .base import ToolResult
1211from fastmcp .utilities .openapi import HTTPRoute
12+ from fastmcp .utilities .types import Image
13+ from mcp .types import TextContent
1314
1415from mcp_app import config
1516from mcp_app import mdx_components as mdx
17+ from mcp_app import mdx_preview as preview
1618from mcp_app .auth import ADMIN_TAG , AUTH_KEY , AuthMiddleware , AuthState , CurrentAuth
1719from mcp_app .routes import ROUTE_MAPS , lookup
1820
1921LANG_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
3535def _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
4342async 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
0 commit comments