mcp-tool-validator

name	mcp-tool-validator
description	MCP Tool 구현 코드를 검증하고 리뷰. 트리거: "MCP 도구 검증", "MCP 코드 리뷰", "Tool 구현 확인", "registerTool 리뷰", "MCP 패턴 검사", "플러그인 검증", "MCP 검수"

MCP Tool Validator

MCP 도구 구현 코드를 검증하고 개선점을 제안하는 스킬.

검증 워크플로우

1. 대상 코드 읽기
2. 체크리스트 항목별 검증
3. 검증 보고서 출력

검증 체크리스트

1. 스키마 검증

항목	검증 내용
describe()	모든 파라미터에 설명이 있는가?
기본값	optional() 필드에 default() 제공되는가?
타입 제약	min(), max(), enum() 등 제약 조건 적절한가?
Zod import	zod 올바르게 import하는가?

// ❌ 나쁜 예
inputSchema: {
  chain: z.string(),
  amount: z.string(),
}

// ✅ 좋은 예
inputSchema: {
  chain: z.string().describe("Chain ID or name (e.g., 'cosmoshub-4', 'cosmos')"),
  amount: z.string().describe("Amount with denom (e.g., '1 ATOM', '1.5')"),
}

2. 응답 구조 검증

항목	검증 내용
JSON 형식	JSON.stringify(data, null, 2) 사용하는가?
일관된 구조	status, data, error 필드 일관성
isError	에러 시 isError: true 반환하는가?
suggestedActions	조회 결과에 다음 액션 제안 포함하는가?

// ✅ 좋은 응답 구조
return {
  content: [{
    type: "text",
    text: JSON.stringify({
      status: "success",
      data: { /* ... */ },
      suggestedActions: [
        { tool: "delegate", reason: "Stake to earn rewards", priority: 1 },
      ],
    }, null, 2),
  }],
};

3. 에러 처리 검증

항목	검증 내용
try-catch	비동기 작업이 try-catch로 감싸져 있는가?
에러 분류	classifyError() 사용하는가?
복구 제안	에러에 suggestion, retryAction 포함하는가?
Setup Required	설정 필요 시 에러 대신 안내 반환하는가?

// ✅ 좋은 에러 처리
try {
  const result = await riskyOperation();
  return { content: [/* ... */] };
} catch (error) {
  const classified = classifyError(error);
  return {
    content: [{
      type: "text",
      text: JSON.stringify({
        isError: true,
        category: classified.category,
        message: classified.message,
        suggestion: classified.suggestion,
      }, null, 2),
    }],
    isError: true,
  };
}

4. Tool Annotations 검증

Annotation	사용 시점
readOnlyHint: true	상태 변경 없는 조회 도구
destructiveHint: true	삭제, 전송 등 위험한 작업
idempotentHint: true	반복 호출해도 동일 결과
openWorldHint: true	블록체인/외부 API 호출

// ✅ Query Tool
annotations: { readOnlyHint: true, idempotentHint: true }

// ✅ Transaction Tool
annotations: { destructiveHint: true, openWorldHint: true }

5. Confirmation Flow 검증 (상태 변경 도구)

항목	검증 내용
토큰 발급	storePending() 사용하는가?
Preview	실행 전 미리보기 정보 제공하는가?
TTL	토큰 만료 시간 명시하는가?
분리	생성/실행이 별도 도구로 분리되어 있는가?

// ✅ 올바른 Confirmation Flow
return {
  content: [{
    type: "text",
    text: JSON.stringify({
      status: "pending_confirmation",
      confirmationToken: token,
      expiresIn: "5 minutes",
      preview: { from, to, amount, fee },
      instructions: "Use confirm-action to execute.",
    }, null, 2),
  }],
};

6. Progress 알림 검증

항목	검증 내용
장시간 작업	Progress 알림 구현되어 있는가?
progressToken	extra._meta?.progressToken 확인하는가?
단계	작업 단계별 메시지 제공하는가?

7. 타입 안전성 검증

항목	검증 내용
as const	리터럴 타입에 as const 사용하는가?
타입 단언	불필요한 as 사용 없는가?
null 체크	optional 값에 null 체크 있는가?

// ❌ 나쁜 예
role: "user",
type: "text",

// ✅ 좋은 예
role: "user" as const,
type: "text" as const,

프로젝트 특화 검증

KeplrPlugin 패턴

// ✅ 올바른 플러그인 구조
const myPlugin: KeplrPlugin = {
  name: "my-plugin",
  register(server, store) {
    server.registerTool("my-tool", { ... }, async (args) => {
      const client = await store.getClientFor("cosmos");
      // ...
    });
  },
};

export default myPlugin;

Store 접근 패턴

// ✅ 올바른 Store 사용
const activeAccount = store.getState().activeAccount;
if (!activeAccount) {
  return createSetupRequiredResponse({ attemptedAction: "get-balances" });
}

검증 보고서 형식

검증 완료 후 다음 형식으로 보고서 출력:

## MCP Tool 검증 보고서: {tool-name}

### ✅ 통과 항목
- [x] 스키마에 describe() 있음
- [x] JSON 응답 구조 일관됨
- [x] 에러 처리 try-catch 있음
- [x] Tool Annotations 적절함

### ⚠️ 개선 권장
- [ ] suggestedActions 추가 권장
- [ ] Progress 알림 구현 권장

### ❌ 필수 수정
- [ ] 에러 시 isError: true 누락
- [ ] Confirmation Flow 미구현

### 코드 수정 제안
\`\`\`typescript
// 수정 전
return { content: [...] };

// 수정 후
return { content: [...], isError: true };
\`\`\`

심각도 분류

레벨	설명	예시
❌ 필수	반드시 수정 필요	에러 처리 누락, 보안 문제
⚠️ 권장	개선하면 좋음	describe() 누락, suggestedActions 미구현
💡 제안	선택적 개선	코드 스타일, 명명 규칙

참조 파일

• examples.md - 좋은 구현 예제
• project-patterns.md - 프로젝트 패턴