chore: dist/ 를 .gitignore에 추가, 캐시에서 제거

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.gitignore

@@ -2,6 +2,7 @@
 __pycache__/
 *.pyc
 node_modules/
+dist/
 .next/
 .DS_Store
 backups/

docker-compose.yml

@@ -78,6 +78,27 @@ services:
     networks:
       - app-network
 
+  # ===================
+  # MCP Server
+  # ===================
+  mcp:
+    build:
+      context: ./mcp
+      dockerfile: Dockerfile
+    container_name: web-inspector-mcp
+    restart: unless-stopped
+    ports:
+      - "${MCP_PORT:-3100}:3100"
+    environment:
+      - TRANSPORT=http
+      - API_URL=http://backend:8000
+      - PORT=3100
+      - LANGUAGE=${MCP_LANGUAGE:-en}
+    depends_on:
+      - backend
+    networks:
+      - app-network
+
 volumes:
   mongodb_data:
   redis_data:

mcp/Dockerfile

@@ -0,0 +1,16 @@
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm ci
+COPY tsconfig.json ./
+COPY src/ ./src/
+RUN npm run build
+
+FROM node:20-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package.json package-lock.json* ./
+RUN npm ci --omit=dev
+COPY --from=builder /app/dist ./dist
+EXPOSE 3100
+CMD ["node", "dist/index.js"]

mcp/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "web-inspector-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Web Inspector — inspect web pages for HTML/CSS, accessibility (WCAG/KWCAG), SEO, and performance/security",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "web-inspector-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "web-inspector",
+    "accessibility",
+    "wcag",
+    "kwcag",
+    "seo",
+    "html"
+  ],
+  "author": "yakenator",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "express": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

mcp/smithery.yaml

@@ -0,0 +1,24 @@
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties:
+      apiUrl:
+        type: string
+        description: "Web Inspector API base URL"
+        default: "https://web-inspector.yakenator.io"
+      language:
+        type: string
+        description: "Default language (en or ko)"
+        enum: ["en", "ko"]
+        default: "en"
+  commandFunction: |-
+    (config) => ({
+      command: "node",
+      args: ["dist/index.js"],
+      env: {
+        API_URL: config.apiUrl || "https://web-inspector.yakenator.io",
+        LANGUAGE: config.language || "en",
+        TRANSPORT: "stdio"
+      }
+    })

mcp/src/api-client.ts

@@ -0,0 +1,234 @@
+/**
+ * REST API client for Web Inspector backend.
+ * Uses native fetch (Node 20+) with AbortController timeout.
+ */
+
+const DEFAULT_TIMEOUT = 120_000; // 120 seconds
+
+export class ApiClient {
+  constructor(private baseUrl: string) {
+    // Strip trailing slash
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+  }
+
+  // ── Single-page inspection ──────────────────────────────
+
+  async startInspection(
+    url: string,
+    accessibilityStandard?: string,
+  ): Promise<{ inspection_id: string; status: string }> {
+    const body: Record<string, unknown> = { url };
+    if (accessibilityStandard) body.accessibility_standard = accessibilityStandard;
+    return this.post("/api/inspections", body);
+  }
+
+  async getInspection(inspectionId: string): Promise<InspectionResult> {
+    return this.get(`/api/inspections/${inspectionId}`);
+  }
+
+  async getIssues(
+    inspectionId: string,
+    category?: string,
+    severity?: string,
+  ): Promise<IssuesResult> {
+    const params = new URLSearchParams();
+    if (category) params.set("category", category);
+    if (severity) params.set("severity", severity);
+    const qs = params.toString();
+    return this.get(`/api/inspections/${inspectionId}/issues${qs ? `?${qs}` : ""}`);
+  }
+
+  async getInspections(
+    url?: string,
+    limit = 10,
+  ): Promise<InspectionsListResult> {
+    const params = new URLSearchParams({ limit: String(limit) });
+    if (url) params.set("url", url);
+    return this.get(`/api/inspections?${params.toString()}`);
+  }
+
+  // ── Site-wide inspection ────────────────────────────────
+
+  async startSiteInspection(
+    url: string,
+    maxPages?: number,
+    maxDepth?: number,
+    accessibilityStandard?: string,
+  ): Promise<{ site_inspection_id: string; status: string }> {
+    const body: Record<string, unknown> = { url };
+    if (maxPages !== undefined) body.max_pages = maxPages;
+    if (maxDepth !== undefined) body.max_depth = maxDepth;
+    if (accessibilityStandard) body.accessibility_standard = accessibilityStandard;
+    return this.post("/api/site-inspections", body);
+  }
+
+  async getSiteInspection(siteInspectionId: string): Promise<SiteInspectionResult> {
+    return this.get(`/api/site-inspections/${siteInspectionId}`);
+  }
+
+  async getSiteInspections(limit = 10): Promise<SiteInspectionsListResult> {
+    return this.get(`/api/site-inspections?limit=${limit}`);
+  }
+
+  // ── HTTP helpers ────────────────────────────────────────
+
+  private async get<T>(path: string): Promise<T> {
+    return this.request("GET", path);
+  }
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    return this.request("POST", path, body);
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
+
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: body ? { "Content-Type": "application/json" } : undefined,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`API ${method} ${path} failed: ${res.status} ${text}`);
+      }
+
+      return (await res.json()) as T;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+// ── Response types ──────────────────────────────────────
+
+export interface Issue {
+  code: string;
+  category: string;
+  severity: "critical" | "major" | "minor" | "info";
+  message: string;
+  element?: string;
+  line?: number;
+  suggestion: string;
+  wcag_criterion?: string;
+  kwcag_criterion?: string;
+  kwcag_name?: string;
+  kwcag_principle?: string;
+}
+
+export interface CategoryResult {
+  score: number;
+  grade: string;
+  total_issues: number;
+  critical: number;
+  major: number;
+  minor: number;
+  info: number;
+  issues: Issue[];
+  wcag_level?: string;
+}
+
+export interface InspectionResult {
+  inspection_id: string;
+  url: string;
+  status: "running" | "completed" | "error";
+  created_at: string;
+  completed_at?: string;
+  duration_seconds?: number;
+  overall_score: number;
+  grade: string;
+  accessibility_standard?: string;
+  categories: {
+    html_css: CategoryResult;
+    accessibility: CategoryResult;
+    seo: CategoryResult;
+    performance_security: CategoryResult;
+  };
+  summary: {
+    total_issues: number;
+    critical: number;
+    major: number;
+    minor: number;
+    info: number;
+  };
+}
+
+export interface IssuesResult {
+  inspection_id: string;
+  total: number;
+  filters: Record<string, string | null>;
+  issues: Issue[];
+}
+
+export interface InspectionsListResult {
+  items: Array<{
+    inspection_id: string;
+    url: string;
+    created_at: string;
+    overall_score: number;
+    grade: string;
+    total_issues: number;
+  }>;
+  total: number;
+  page: number;
+  limit: number;
+  total_pages: number;
+}
+
+export interface SiteInspectionResult {
+  site_inspection_id: string;
+  root_url: string;
+  domain: string;
+  status: "crawling" | "inspecting" | "completed" | "error";
+  created_at: string;
+  completed_at?: string;
+  config: {
+    max_pages: number;
+    max_depth: number;
+    concurrency: number;
+    accessibility_standard: string;
+  };
+  discovered_pages: Array<{
+    url: string;
+    depth: number;
+    parent_url?: string;
+    inspection_id?: string;
+    status: string;
+    title?: string;
+    overall_score?: number;
+    grade?: string;
+  }>;
+  aggregate_scores?: {
+    overall_score: number;
+    grade: string;
+    html_css: number;
+    accessibility: number;
+    seo: number;
+    performance_security: number;
+    total_issues: number;
+    pages_inspected: number;
+    pages_total: number;
+  };
+}
+
+export interface SiteInspectionsListResult {
+  items: Array<{
+    site_inspection_id: string;
+    root_url: string;
+    domain: string;
+    status: string;
+    created_at: string;
+    pages_total: number;
+    pages_inspected: number;
+    overall_score?: number;
+    grade?: string;
+  }>;
+  total: number;
+  page: number;
+  limit: number;
+  total_pages: number;
+}

mcp/src/i18n/en.ts

@@ -0,0 +1,65 @@
+export const en: Record<string, string> = {
+  // --- Tool descriptions ---
+  "inspect_page.description":
+    "Inspect a single web page for HTML/CSS quality, accessibility (WCAG/KWCAG), SEO, and performance/security. Returns scores, grades, and top issues. Takes 10-30 seconds.",
+  "inspect_page.param.url":
+    "The URL of the web page to inspect (must start with http:// or https://)",
+  "inspect_page.param.standard":
+    "Accessibility standard to check against (default: wcag_2.1_aa)",
+  "inspect_site.description":
+    "Start a site-wide crawl and inspection. Crawls links from the root URL and inspects each page. Returns a site_inspection_id for tracking. Use get_inspection to check results later.",
+  "inspect_site.param.url": "Root URL of the site to crawl and inspect",
+  "inspect_site.param.max_pages":
+    "Maximum number of pages to crawl (default: 20, max: 500, 0: unlimited)",
+  "inspect_site.param.max_depth":
+    "Maximum link depth to crawl (default: 2, max: 3)",
+  "get_inspection.description":
+    "Get detailed inspection results by inspection ID. Works for both single-page and site inspections.",
+  "get_inspection.param.id":
+    "The inspection_id or site_inspection_id to retrieve",
+  "get_issues.description":
+    "Get a filtered list of issues found during an inspection. Filter by category and/or severity.",
+  "get_issues.param.id": "The inspection_id to get issues for",
+  "get_issues.param.category":
+    "Filter by category: html_css, accessibility, seo, or performance_security",
+  "get_issues.param.severity":
+    "Filter by severity: critical, major, minor, or info",
+  "get_history.description":
+    "List recent inspection history. Optionally filter by URL substring.",
+  "get_history.param.url": "Optional URL substring to filter results",
+  "get_history.param.limit": "Number of results to return (default: 10)",
+  "common.param.language": "Response language: 'en' for English, 'ko' for Korean",
+
+  // --- Result formatting ---
+  "result.title": "Web Inspection Result",
+  "result.overall_score": "Overall Score",
+  "result.duration": "Duration",
+  "result.standard": "Standard",
+  "result.category_scores": "Category Scores",
+  "result.category": "Category",
+  "result.score": "Score",
+  "result.grade": "Grade",
+  "result.issues": "Issues",
+  "result.issue_summary": "Issue Summary",
+  "result.total": "Total",
+  "result.top_issues": "Top Issues (Critical/Major)",
+  "result.message": "Message",
+  "result.element": "Element",
+  "result.suggestion": "Suggestion",
+  "result.severity": "Severity",
+  "result.more_issues_hint":
+    "Use `get_issues` with inspection_id '{inspectionId}' to see all issues with filtering.",
+
+  // --- Tool responses ---
+  "inspect_page.timeout":
+    "Inspection timed out for {url}. Inspection ID: {inspectionId}. Try get_inspection later.",
+  "inspect_site.started": "Site inspection started successfully.",
+  "inspect_site.follow_up_hint":
+    "The crawl is running in the background. Use `get_inspection` with ID '{id}' to check the result after a few minutes.",
+  "get_inspection.not_found": "Inspection '{id}' not found.",
+  "get_issues.title": "Issue List",
+  "get_issues.total": "Total Issues",
+  "get_issues.filters": "Filters",
+  "get_history.title": "Inspection History",
+  "get_history.total": "Total Records",
+};

mcp/src/i18n/index.ts

@@ -0,0 +1,23 @@
+import { en } from "./en.js";
+import { ko } from "./ko.js";
+
+const messages: Record<string, Record<string, string>> = { en, ko };
+
+/**
+ * Translate a key with optional interpolation.
+ * Usage: t("inspect_page.description", "ko")
+ *        t("result.title", "en", { url: "..." })
+ */
+export function t(
+  key: string,
+  lang: "en" | "ko",
+  params?: Record<string, string | number>,
+): string {
+  let text = messages[lang]?.[key] || messages["en"]?.[key] || key;
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      text = text.replace(new RegExp(`\\{${k}\\}`, "g"), String(v));
+    }
+  }
+  return text;
+}

mcp/src/i18n/ko.ts

@@ -0,0 +1,65 @@
+export const ko: Record<string, string> = {
+  // --- 도구 설명 ---
+  "inspect_page.description":
+    "단일 웹 페이지의 HTML/CSS 품질, 접근성(WCAG/KWCAG), SEO, 성능/보안을 검사합니다. 점수, 등급, 주요 이슈를 반환합니다. 10-30초 소요.",
+  "inspect_page.param.url":
+    "검사할 웹 페이지 URL (http:// 또는 https://로 시작)",
+  "inspect_page.param.standard":
+    "접근성 검사 표준 (기본값: wcag_2.1_aa)",
+  "inspect_site.description":
+    "사이트 전체 크롤링 및 검사를 시작합니다. 루트 URL에서 링크를 따라가며 각 페이지를 검사합니다. site_inspection_id를 반환하며, get_inspection으로 결과를 확인할 수 있습니다.",
+  "inspect_site.param.url": "크롤링 및 검사할 사이트의 루트 URL",
+  "inspect_site.param.max_pages":
+    "최대 크롤링 페이지 수 (기본값: 20, 최대: 500, 0: 무제한)",
+  "inspect_site.param.max_depth":
+    "최대 크롤링 깊이 (기본값: 2, 최대: 3)",
+  "get_inspection.description":
+    "검사 ID로 상세 결과를 조회합니다. 단일 페이지 및 사이트 검사 모두 지원.",
+  "get_inspection.param.id":
+    "조회할 inspection_id 또는 site_inspection_id",
+  "get_issues.description":
+    "검사에서 발견된 이슈 목록을 필터링하여 조회합니다. 카테고리 및 심각도로 필터링 가능.",
+  "get_issues.param.id": "이슈를 조회할 inspection_id",
+  "get_issues.param.category":
+    "카테고리 필터: html_css, accessibility, seo, performance_security",
+  "get_issues.param.severity":
+    "심각도 필터: critical, major, minor, info",
+  "get_history.description":
+    "최근 검사 이력을 조회합니다. URL로 필터링 가능.",
+  "get_history.param.url": "결과를 필터링할 URL (부분 문자열)",
+  "get_history.param.limit": "반환할 결과 수 (기본값: 10)",
+  "common.param.language": "응답 언어: 'en' 영어, 'ko' 한국어",
+
+  // --- 결과 포맷 ---
+  "result.title": "웹 검사 결과",
+  "result.overall_score": "종합 점수",
+  "result.duration": "소요 시간",
+  "result.standard": "검사 표준",
+  "result.category_scores": "카테고리별 점수",
+  "result.category": "카테고리",
+  "result.score": "점수",
+  "result.grade": "등급",
+  "result.issues": "이슈",
+  "result.issue_summary": "이슈 요약",
+  "result.total": "전체",
+  "result.top_issues": "주요 이슈 (Critical/Major)",
+  "result.message": "메시지",
+  "result.element": "요소",
+  "result.suggestion": "개선 제안",
+  "result.severity": "심각도",
+  "result.more_issues_hint":
+    "`get_issues` 도구에 inspection_id '{inspectionId}'를 사용하여 모든 이슈를 필터링해서 확인할 수 있습니다.",
+
+  // --- 도구 응답 ---
+  "inspect_page.timeout":
+    "{url} 검사가 시간 초과되었습니다. Inspection ID: {inspectionId}. 나중에 get_inspection으로 확인해 보세요.",
+  "inspect_site.started": "사이트 검사가 성공적으로 시작되었습니다.",
+  "inspect_site.follow_up_hint":
+    "크롤링이 백그라운드에서 실행 중입니다. 몇 분 후 `get_inspection`에 ID '{id}'를 사용하여 결과를 확인하세요.",
+  "get_inspection.not_found": "검사 '{id}'를 찾을 수 없습니다.",
+  "get_issues.title": "이슈 목록",
+  "get_issues.total": "전체 이슈 수",
+  "get_issues.filters": "필터",
+  "get_history.title": "검사 이력",
+  "get_history.total": "전체 레코드",
+};

mcp/src/index.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import { createServer } from "./server.js";
+
+type Lang = "en" | "ko";
+
+const TRANSPORT = process.env.TRANSPORT || "stdio";
+const API_URL = process.env.API_URL || "http://localhost:8011";
+const PORT = parseInt(process.env.PORT || "3100", 10);
+const LANGUAGE = (process.env.LANGUAGE || "en") as Lang;
+
+async function main() {
+  const server = createServer(API_URL, LANGUAGE);
+
+  if (TRANSPORT === "http") {
+    await startHttp(server, PORT);
+  } else {
+    await startStdio(server);
+  }
+}
+
+async function startStdio(server: ReturnType<typeof createServer>) {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`[web-inspector-mcp] stdio mode, API: ${API_URL}`);
+}
+
+async function startHttp(server: ReturnType<typeof createServer>, port: number) {
+  const app = express();
+  app.use(express.json());
+
+  app.post("/mcp", async (req, res) => {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
+    res.on("close", () => {
+      transport.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  });
+
+  app.get("/mcp", async (req, res) => {
+    res.writeHead(405).end(JSON.stringify({ error: "Use POST for MCP requests" }));
+  });
+
+  app.delete("/mcp", async (req, res) => {
+    res.writeHead(405).end(JSON.stringify({ error: "Session management not supported" }));
+  });
+
+  // Health check
+  app.get("/health", (_req, res) => {
+    res.json({ status: "ok", transport: "http", api_url: API_URL });
+  });
+
+  app.listen(port, () => {
+    console.error(
+      `[web-inspector-mcp] HTTP mode on port ${port}, API: ${API_URL}`,
+    );
+  });
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

mcp/src/server.ts

@@ -0,0 +1,242 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { ApiClient } from "./api-client.js";
+import { t } from "./i18n/index.js";
+import { inspectPage } from "./tools/inspect-page.js";
+import { inspectSite } from "./tools/inspect-site.js";
+import { getInspection } from "./tools/get-inspection.js";
+import { getIssues } from "./tools/get-issues.js";
+import { getHistory } from "./tools/get-history.js";
+
+type Lang = "en" | "ko";
+
+const STANDARDS = [
+  "wcag_2.0_a",
+  "wcag_2.0_aa",
+  "wcag_2.1_aa",
+  "wcag_2.2_aa",
+  "kwcag_2.1",
+  "kwcag_2.2",
+] as const;
+
+export function createServer(apiUrl: string, defaultLang: Lang): Server {
+  const client = new ApiClient(apiUrl);
+
+  const server = new Server(
+    { name: "web-inspector-mcp", version: "1.0.0" },
+    { capabilities: { tools: {} } },
+  );
+
+  // ── List tools ──────────────────────────────────────────
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: "inspect_page",
+        description: t("inspect_page.description", defaultLang),
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            url: {
+              type: "string",
+              description: t("inspect_page.param.url", defaultLang),
+            },
+            accessibility_standard: {
+              type: "string",
+              enum: STANDARDS,
+              description: t("inspect_page.param.standard", defaultLang),
+            },
+            language: {
+              type: "string",
+              enum: ["en", "ko"],
+              description: t("common.param.language", defaultLang),
+            },
+          },
+          required: ["url"],
+        },
+      },
+      {
+        name: "inspect_site",
+        description: t("inspect_site.description", defaultLang),
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            url: {
+              type: "string",
+              description: t("inspect_site.param.url", defaultLang),
+            },
+            max_pages: {
+              type: "number",
+              description: t("inspect_site.param.max_pages", defaultLang),
+            },
+            max_depth: {
+              type: "number",
+              description: t("inspect_site.param.max_depth", defaultLang),
+            },
+            accessibility_standard: {
+              type: "string",
+              enum: STANDARDS,
+              description: t("inspect_page.param.standard", defaultLang),
+            },
+            language: {
+              type: "string",
+              enum: ["en", "ko"],
+              description: t("common.param.language", defaultLang),
+            },
+          },
+          required: ["url"],
+        },
+      },
+      {
+        name: "get_inspection",
+        description: t("get_inspection.description", defaultLang),
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            id: {
+              type: "string",
+              description: t("get_inspection.param.id", defaultLang),
+            },
+            language: {
+              type: "string",
+              enum: ["en", "ko"],
+              description: t("common.param.language", defaultLang),
+            },
+          },
+          required: ["id"],
+        },
+      },
+      {
+        name: "get_issues",
+        description: t("get_issues.description", defaultLang),
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            id: {
+              type: "string",
+              description: t("get_issues.param.id", defaultLang),
+            },
+            category: {
+              type: "string",
+              enum: [
+                "html_css",
+                "accessibility",
+                "seo",
+                "performance_security",
+              ],
+              description: t("get_issues.param.category", defaultLang),
+            },
+            severity: {
+              type: "string",
+              enum: ["critical", "major", "minor", "info"],
+              description: t("get_issues.param.severity", defaultLang),
+            },
+            language: {
+              type: "string",
+              enum: ["en", "ko"],
+              description: t("common.param.language", defaultLang),
+            },
+          },
+          required: ["id"],
+        },
+      },
+      {
+        name: "get_history",
+        description: t("get_history.description", defaultLang),
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            url: {
+              type: "string",
+              description: t("get_history.param.url", defaultLang),
+            },
+            limit: {
+              type: "number",
+              description: t("get_history.param.limit", defaultLang),
+            },
+            language: {
+              type: "string",
+              enum: ["en", "ko"],
+              description: t("common.param.language", defaultLang),
+            },
+          },
+        },
+      },
+    ],
+  }));
+
+  // ── Call tool ────────────────────────────────────────────
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    const lang: Lang = (args.language as Lang) || defaultLang;
+
+    try {
+      let text: string;
+
+      switch (name) {
+        case "inspect_page":
+          text = await inspectPage(
+            client,
+            args.url as string,
+            lang,
+            args.accessibility_standard as string | undefined,
+          );
+          break;
+
+        case "inspect_site":
+          text = await inspectSite(
+            client,
+            args.url as string,
+            lang,
+            args.max_pages as number | undefined,
+            args.max_depth as number | undefined,
+            args.accessibility_standard as string | undefined,
+          );
+          break;
+
+        case "get_inspection":
+          text = await getInspection(client, args.id as string, lang);
+          break;
+
+        case "get_issues":
+          text = await getIssues(
+            client,
+            args.id as string,
+            lang,
+            args.category as string | undefined,
+            args.severity as string | undefined,
+          );
+          break;
+
+        case "get_history":
+          text = await getHistory(
+            client,
+            lang,
+            args.url as string | undefined,
+            args.limit as number | undefined,
+          );
+          break;
+
+        default:
+          return {
+            content: [{ type: "text", text: `Unknown tool: ${name}` }],
+            isError: true,
+          };
+      }
+
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+      };
+    }
+  });
+
+  return server;
+}

mcp/src/tools/get-history.ts

@@ -0,0 +1,46 @@
+import { ApiClient } from "../api-client.js";
+import { t } from "../i18n/index.js";
+
+export async function getHistory(
+  client: ApiClient,
+  lang: "en" | "ko",
+  url?: string,
+  limit?: number,
+): Promise<string> {
+  const result = await client.getInspections(url, limit || 10);
+
+  const lines: string[] = [];
+  lines.push(`# ${t("get_history.title", lang)}`);
+  lines.push(`**${t("get_history.total", lang)}**: ${result.total}`);
+  if (url) {
+    lines.push(`**Filter**: ${url}`);
+  }
+  lines.push("");
+
+  if (result.items.length === 0) {
+    lines.push("No inspection records found.");
+    return lines.join("\n");
+  }
+
+  lines.push("| # | URL | Score | Grade | Issues | Date |");
+  lines.push("|---|---|---|---|---|---|");
+
+  for (let i = 0; i < result.items.length; i++) {
+    const item = result.items[i];
+    const date = item.created_at.split("T")[0];
+    const urlShort =
+      item.url.length > 50 ? item.url.slice(0, 47) + "..." : item.url;
+    lines.push(
+      `| ${i + 1} | ${urlShort} | ${item.overall_score} | ${item.grade} | ${item.total_issues} | ${date} |`,
+    );
+  }
+  lines.push("");
+
+  // Include inspection IDs for follow-up
+  lines.push("## Inspection IDs");
+  for (const item of result.items) {
+    lines.push(`- ${item.url}: \`${item.inspection_id}\``);
+  }
+
+  return lines.join("\n");
+}

mcp/src/tools/get-inspection.ts

@@ -0,0 +1,122 @@
+import { ApiClient, type InspectionResult, type SiteInspectionResult } from "../api-client.js";
+import { t } from "../i18n/index.js";
+
+export async function getInspection(
+  client: ApiClient,
+  id: string,
+  lang: "en" | "ko",
+): Promise<string> {
+  // Try single-page first, then site inspection
+  try {
+    const r = await client.getInspection(id);
+    return formatSingleResult(r, lang);
+  } catch {
+    // Might be a site inspection ID
+  }
+
+  try {
+    const r = await client.getSiteInspection(id);
+    return formatSiteResult(r, lang);
+  } catch {
+    return t("get_inspection.not_found", lang, { id });
+  }
+}
+
+function formatSingleResult(r: InspectionResult, lang: "en" | "ko"): string {
+  const lines: string[] = [];
+  const duration = r.duration_seconds
+    ? `${r.duration_seconds.toFixed(1)}s`
+    : "—";
+
+  lines.push(`# ${t("result.title", lang)}`);
+  lines.push(`**URL**: ${r.url}`);
+  lines.push(`**Status**: ${r.status}`);
+  lines.push(`**Inspection ID**: ${r.inspection_id}`);
+
+  if (r.status !== "completed") {
+    return lines.join("\n");
+  }
+
+  lines.push(
+    `**${t("result.overall_score", lang)}**: ${r.overall_score}/100 (${r.grade})`,
+  );
+  lines.push(`**${t("result.duration", lang)}**: ${duration}`);
+  if (r.accessibility_standard) {
+    lines.push(`**${t("result.standard", lang)}**: ${r.accessibility_standard}`);
+  }
+  lines.push("");
+
+  // Category scores
+  lines.push(`## ${t("result.category_scores", lang)}`);
+  lines.push(
+    `| ${t("result.category", lang)} | ${t("result.score", lang)} | ${t("result.grade", lang)} | ${t("result.issues", lang)} |`,
+  );
+  lines.push("|---|---|---|---|");
+
+  for (const [key, label] of [
+    ["html_css", "HTML/CSS"],
+    ["accessibility", "Accessibility"],
+    ["seo", "SEO"],
+    ["performance_security", "Performance/Security"],
+  ] as const) {
+    const cat = r.categories[key];
+    if (!cat) continue;
+    lines.push(
+      `| ${label} | ${cat.score} | ${cat.grade} | ${cat.total_issues} |`,
+    );
+  }
+  lines.push("");
+
+  lines.push(
+    `> ${t("result.more_issues_hint", lang, { inspectionId: r.inspection_id })}`,
+  );
+
+  return lines.join("\n");
+}
+
+function formatSiteResult(r: SiteInspectionResult, lang: "en" | "ko"): string {
+  const lines: string[] = [];
+
+  lines.push(`# Site ${t("result.title", lang)}`);
+  lines.push(`**Root URL**: ${r.root_url}`);
+  lines.push(`**Domain**: ${r.domain}`);
+  lines.push(`**Status**: ${r.status}`);
+  lines.push(`**Site Inspection ID**: ${r.site_inspection_id}`);
+
+  if (r.aggregate_scores) {
+    const a = r.aggregate_scores;
+    lines.push("");
+    lines.push(
+      `**${t("result.overall_score", lang)}**: ${a.overall_score}/100 (${a.grade})`,
+    );
+    lines.push(`**Pages**: ${a.pages_inspected}/${a.pages_total}`);
+    lines.push("");
+
+    lines.push(`## ${t("result.category_scores", lang)}`);
+    lines.push(
+      `| ${t("result.category", lang)} | ${t("result.score", lang)} |`,
+    );
+    lines.push("|---|---|");
+    lines.push(`| HTML/CSS | ${a.html_css} |`);
+    lines.push(`| Accessibility | ${a.accessibility} |`);
+    lines.push(`| SEO | ${a.seo} |`);
+    lines.push(`| Performance/Security | ${a.performance_security} |`);
+    lines.push("");
+    lines.push(`**Total Issues**: ${a.total_issues}`);
+  }
+
+  // Page list
+  if (r.discovered_pages.length > 0) {
+    lines.push("");
+    lines.push("## Pages");
+    lines.push("| URL | Score | Grade | Status |");
+    lines.push("|---|---|---|---|");
+    for (const p of r.discovered_pages) {
+      const score = p.overall_score !== undefined ? String(p.overall_score) : "—";
+      const grade = p.grade || "—";
+      lines.push(`| ${p.url} | ${score} | ${grade} | ${p.status} |`);
+    }
+  }
+
+  return lines.join("\n");
+}

mcp/src/tools/get-issues.ts

@@ -0,0 +1,71 @@
+import { ApiClient } from "../api-client.js";
+import { t } from "../i18n/index.js";
+
+export async function getIssues(
+  client: ApiClient,
+  id: string,
+  lang: "en" | "ko",
+  category?: string,
+  severity?: string,
+): Promise<string> {
+  const result = await client.getIssues(id, category, severity);
+
+  const lines: string[] = [];
+  lines.push(`# ${t("get_issues.title", lang)}`);
+  lines.push(`**Inspection ID**: ${result.inspection_id}`);
+  lines.push(`**${t("get_issues.total", lang)}**: ${result.total}`);
+
+  // Show applied filters
+  const activeFilters = Object.entries(result.filters)
+    .filter(([, v]) => v)
+    .map(([k, v]) => `${k}: ${v}`)
+    .join(", ");
+  if (activeFilters) {
+    lines.push(`**${t("get_issues.filters", lang)}**: ${activeFilters}`);
+  }
+  lines.push("");
+
+  if (result.issues.length === 0) {
+    lines.push("No issues found.");
+    return lines.join("\n");
+  }
+
+  // Issue table
+  lines.push(
+    `| # | ${t("result.severity", lang)} | Code | ${t("result.category", lang)} | ${t("result.message", lang)} |`,
+  );
+  lines.push("|---|---|---|---|---|");
+
+  for (let i = 0; i < result.issues.length; i++) {
+    const issue = result.issues[i];
+    const msg =
+      issue.message.length > 80
+        ? issue.message.slice(0, 77) + "..."
+        : issue.message;
+    lines.push(
+      `| ${i + 1} | ${issue.severity} | ${issue.code} | ${issue.category} | ${msg} |`,
+    );
+  }
+  lines.push("");
+
+  // Detailed view for first 10
+  const detailCount = Math.min(result.issues.length, 10);
+  lines.push("## Details");
+  for (let i = 0; i < detailCount; i++) {
+    const issue = result.issues[i];
+    lines.push(`### ${i + 1}. [${issue.severity.toUpperCase()}] ${issue.code}`);
+    lines.push(`- **${t("result.message", lang)}**: ${issue.message}`);
+    if (issue.element) {
+      lines.push(`- **${t("result.element", lang)}**: \`${issue.element}\``);
+    }
+    lines.push(`- **${t("result.suggestion", lang)}**: ${issue.suggestion}`);
+    if (issue.kwcag_criterion) {
+      lines.push(`- **KWCAG**: ${issue.kwcag_criterion} ${issue.kwcag_name || ""}`);
+    } else if (issue.wcag_criterion) {
+      lines.push(`- **WCAG**: ${issue.wcag_criterion}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

mcp/src/tools/inspect-page.ts

@@ -0,0 +1,119 @@
+import { ApiClient, type InspectionResult } from "../api-client.js";
+import { t } from "../i18n/index.js";
+
+const POLL_INTERVAL = 2_000; // 2 seconds
+const MAX_POLLS = 60; // 120 seconds total
+
+export async function inspectPage(
+  client: ApiClient,
+  url: string,
+  lang: "en" | "ko",
+  standard?: string,
+): Promise<string> {
+  // 1. Start inspection
+  const { inspection_id } = await client.startInspection(url, standard);
+
+  // 2. Poll until completion
+  let result: InspectionResult | null = null;
+  for (let i = 0; i < MAX_POLLS; i++) {
+    await sleep(POLL_INTERVAL);
+    const data = await client.getInspection(inspection_id);
+    if (data.status === "completed") {
+      result = data;
+      break;
+    }
+    if (data.status === "error") {
+      throw new Error(`Inspection failed for ${url}`);
+    }
+  }
+
+  // 3. Timeout — return partial info
+  if (!result) {
+    return t("inspect_page.timeout", lang, { url, inspectionId: inspection_id });
+  }
+
+  // 4. Format result as markdown
+  return formatResult(result, lang);
+}
+
+function formatResult(r: InspectionResult, lang: "en" | "ko"): string {
+  const lines: string[] = [];
+  const duration = r.duration_seconds
+    ? `${r.duration_seconds.toFixed(1)}s`
+    : "—";
+
+  lines.push(`# ${t("result.title", lang)}`);
+  lines.push(`**URL**: ${r.url}`);
+  lines.push(
+    `**${t("result.overall_score", lang)}**: ${r.overall_score}/100 (${r.grade})`,
+  );
+  lines.push(`**${t("result.duration", lang)}**: ${duration}`);
+  if (r.accessibility_standard) {
+    lines.push(`**${t("result.standard", lang)}**: ${r.accessibility_standard}`);
+  }
+  lines.push("");
+
+  // Category scores table
+  lines.push(`## ${t("result.category_scores", lang)}`);
+  lines.push(
+    `| ${t("result.category", lang)} | ${t("result.score", lang)} | ${t("result.grade", lang)} | ${t("result.issues", lang)} |`,
+  );
+  lines.push("|---|---|---|---|");
+
+  const catNames: Array<[string, string]> = [
+    ["html_css", "HTML/CSS"],
+    ["accessibility", "Accessibility"],
+    ["seo", "SEO"],
+    ["performance_security", "Performance/Security"],
+  ];
+
+  for (const [key, label] of catNames) {
+    const cat = r.categories[key as keyof typeof r.categories];
+    if (!cat) continue;
+    const issueStr = `${cat.total_issues} (C:${cat.critical} M:${cat.major} m:${cat.minor} i:${cat.info})`;
+    lines.push(`| ${label} | ${cat.score} | ${cat.grade} | ${issueStr} |`);
+  }
+  lines.push("");
+
+  // Issue summary
+  const s = r.summary;
+  lines.push(`## ${t("result.issue_summary", lang)}`);
+  lines.push(
+    `**${t("result.total", lang)}**: ${s.total_issues} (Critical: ${s.critical}, Major: ${s.major}, Minor: ${s.minor}, Info: ${s.info})`,
+  );
+  lines.push("");
+
+  // Top issues (critical + major, max 5)
+  const topIssues = collectTopIssues(r, 5);
+  if (topIssues.length > 0) {
+    lines.push(`## ${t("result.top_issues", lang)}`);
+    for (const issue of topIssues) {
+      const sevLabel = issue.severity.toUpperCase();
+      lines.push(`### [${sevLabel}] ${issue.code}`);
+      lines.push(`- **${t("result.message", lang)}**: ${issue.message}`);
+      if (issue.element) {
+        lines.push(`- **${t("result.element", lang)}**: \`${issue.element}\``);
+      }
+      lines.push(`- **${t("result.suggestion", lang)}**: ${issue.suggestion}`);
+      lines.push("");
+    }
+  }
+
+  // Hint for more issues
+  lines.push(
+    `> ${t("result.more_issues_hint", lang, { inspectionId: r.inspection_id })}`,
+  );
+
+  return lines.join("\n");
+}
+
+function collectTopIssues(r: InspectionResult, max: number) {
+  const all = Object.values(r.categories).flatMap((cat) => cat.issues);
+  return all
+    .filter((i) => i.severity === "critical" || i.severity === "major")
+    .slice(0, max);
+}
+
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

mcp/src/tools/inspect-site.ts

@@ -0,0 +1,25 @@
+import { ApiClient } from "../api-client.js";
+import { t } from "../i18n/index.js";
+
+export async function inspectSite(
+  client: ApiClient,
+  url: string,
+  lang: "en" | "ko",
+  maxPages?: number,
+  maxDepth?: number,
+  standard?: string,
+): Promise<string> {
+  const result = await client.startSiteInspection(url, maxPages, maxDepth, standard);
+
+  const lines: string[] = [];
+  lines.push(`# ${t("inspect_site.started", lang)}`);
+  lines.push(`**URL**: ${url}`);
+  lines.push(`**Site Inspection ID**: ${result.site_inspection_id}`);
+  lines.push(`**Status**: ${result.status}`);
+  lines.push("");
+  lines.push(
+    `> ${t("inspect_site.follow_up_hint", lang, { id: result.site_inspection_id })}`,
+  );
+
+  return lines.join("\n");
+}

mcp/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

nginx/nginx.conf

@@ -6,12 +6,29 @@ upstream backend {
     server backend:8000;
 }
 
+upstream mcp {
+    server mcp:3100;
+}
+
 server {
     listen 80;
     server_name web-inspector.yakenator.io;
 
     client_max_body_size 10M;
 
+    # MCP 엔드포인트 (Streamable HTTP)
+    location /mcp {
+        proxy_pass http://mcp;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 180s;
+        proxy_buffering off;
+        proxy_cache off;
+        add_header X-Accel-Buffering no;
+    }
+
     # API 요청 → Backend
     location /api/ {
         proxy_pass http://backend;