feat: MCP 서버 추가 — AI 에이전트용 웹 검사 도구
Node.js + TypeScript MCP 서버 구현: - 5개 도구: inspect_page, inspect_site, get_inspection, get_issues, get_history - 듀얼 트랜스포트: stdio (Claude Desktop) + Streamable HTTP (Docker/원격) - i18n 지원 (영어/한국어) - Docker 통합 (port 3100) + Nginx /mcp 프록시 - Smithery 레지스트리 배포 설정 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
jungwoo choi
234
mcp/src/api-client.ts
Normal file
234
mcp/src/api-client.ts
Normal file
@ -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;
|
||||
}
|
||||
65
mcp/src/i18n/en.ts
Normal file
65
mcp/src/i18n/en.ts
Normal file
@ -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",
|
||||
};
|
||||
23
mcp/src/i18n/index.ts
Normal file
23
mcp/src/i18n/index.ts
Normal file
@ -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;
|
||||
}
|
||||
65
mcp/src/i18n/ko.ts
Normal file
65
mcp/src/i18n/ko.ts
Normal file
@ -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": "전체 레코드",
|
||||
};
|
||||
69
mcp/src/index.ts
Normal file
69
mcp/src/index.ts
Normal file
@ -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);
|
||||
});
|
||||
242
mcp/src/server.ts
Normal file
242
mcp/src/server.ts
Normal file
@ -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;
|
||||
}
|
||||
46
mcp/src/tools/get-history.ts
Normal file
46
mcp/src/tools/get-history.ts
Normal file
@ -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");
|
||||
}
|
||||
122
mcp/src/tools/get-inspection.ts
Normal file
122
mcp/src/tools/get-inspection.ts
Normal file
@ -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");
|
||||
}
|
||||
71
mcp/src/tools/get-issues.ts
Normal file
71
mcp/src/tools/get-issues.ts
Normal file
@ -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");
|
||||
}
|
||||
119
mcp/src/tools/inspect-page.ts
Normal file
119
mcp/src/tools/inspect-page.ts
Normal file
@ -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));
|
||||
}
|
||||
25
mcp/src/tools/inspect-site.ts
Normal file
25
mcp/src/tools/inspect-site.ts
Normal file
@ -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");
|
||||
}
|
||||
Reference in New Issue
Block a user