mcp-server

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MCP 원인 분석·스펙 검증

MCP 原因分析·规范验证

문제 재현, 최신 스펙과 구현 대조, 불일치 근거 정리, 수정 전/후 Inspector 검증

问题复现、最新规范与实现对照、整理不一致依据、修改前后 Inspector 验证

입력 요구사항 (Ask if missing)

输入要求（缺失时询问）

먼저 아래 3가지만 확인

작업 목적:
```
원인 분석
```
또는
```
스펙 검증
```
대상 코드/서버 위치: repo path, package 이름, 실행 엔트리
런타임/transport:
```
Node(TypeScript)
```
or
```
Python
```
,
```
stdio
```
or
```
SSE/HTTP
```

필요할 때만 아래 항목 추가 확인

재현 절차: 에러 로그, 실패 요청/응답, 기대 동작
점검 대상 Tool/Resource/Prompt 이름
배포 환경/인증 정보(원격 호출 이슈일 때만)

先仅确认以下 3 项

工作目的：
```
原因分析
```
或
```
规范验证
```
目标代码/服务器位置：repo 路径、package 名称、执行入口
运行时/transport：
```
Node(TypeScript)
```
或
```
Python
```
，
```
stdio
```
或
```
SSE/HTTP
```

仅在必要时追加确认以下项目

复现步骤：错误日志、失败请求/响应、预期行为
检查对象 Tool/Resource/Prompt 名称
部署环境/认证信息（仅远程调用问题时）

의사결정 규칙

决策规则

분석과 검증을 구현보다 우선
서버 신규 생성/스캐폴딩은 범위에서 제외
수정이 필요하면 기존 코드 기준 최소 변경으로 진행
확정 사실과 추정 가설 분리 기록

优先进行分析和验证，而非直接实现
新建服务器或 scaffolding 不在范围内
如需修复，基于现有代码进行最小改动
分开记录已确认事实与推测性假设

안전 규칙

安全规则

STDIO 로깅

STDIO 日志

stdio transport에서는 stdout 로그 출력 금지
Node에서는
```
console.log()
```
대신
```
console.error()
```
사용
Python에서는
```
print()
```
대신
```
logging
```
사용

在 stdio transport 中禁止输出 stdout 日志
在 Node 中使用
```
console.error()
```
，而不是
```
console.log()
```
在 Python 中使用
```
logging
```
，而不是
```
print()
```

입력/호출 검증

输入/调用验证

필수 입력 누락 여부 먼저 검증
Tool handler 실행 전 schema 검증 수행
파일 경로 입력에서 path traversal(
```
../
```
) 차단
외부 API 호출에 timeout 강제

首先验证是否缺少必填输入
在执行 Tool handler 前进行 schema 验证
阻止文件路径输入中的 path traversal（
```
../
```
）
对外部 API 调用强制设置 timeout

실행 절차

执行步骤

Step 1. 문제 재현

Step 1. 问题复现

최소 재현 시나리오 정의
실패 지점을 transport, tools, resources, prompts로 분류
재현 결과를
```
확정 사실
```
과
```
추정
```
으로 구분 기록

定义最小复现场景
将失败位置归类为 transport、tools、resources 或 prompts
将复现结果区分为
```
已确认事实
```
和
```
推测
```
并分别记录

Step 2. 최신 스펙 기준 대조

Step 2. 按最新规范进行对照

MCP Specification 먼저 확인
MCP SDKs 문서와 사용 중인 SDK 버전 대조
구현 코드와 스펙을 항목별로 1:1 매핑
- transport 초기화/연결 방식
- ```
tools/list
```
  ,
```
tools/call
```
  요청/응답 구조
- ```
resources/list
```
  ,
```
resources/read
```
  노출/조회 구조
- prompt 등록 이름, argument schema, handler 라우팅
- 응답 포맷
```
content
```
  ,
```
isError
```
불일치 발견 시 영향 범위와 수정 포인트 함께 정리

首先查看 MCP Specification
对照 MCP SDKs文档与正在使用的 SDK 版本
将实现代码与规范逐项进行 1:1 映射
- transport 初始化/连接方式
- ```
tools/list
```
  、
```
tools/call
```
  请求/响应结构
- ```
resources/list
```
  、
```
resources/read
```
  暴露/读取结构
- prompt 注册名称、argument schema、handler 路由
- 响应格式
```
content
```
  、
```
isError
```
发现不一致时，同时整理影响范围和修改点

Step 3. 수정안 정리

Step 3. 整理修改方案

원인별 수정 순서를 우선순위로 정리
각 수정안의 영향 범위와 회귀 위험 명시
테스트 가능한 검증 케이스 함께 제시

按优先级整理各类原因的修改顺序
明确每项修改方案的影响范围和回归风险
同时提出可测试的验证用例

Step 4. Inspector 검증

Step 4. Inspector 验证

수정 전/후 동일 시나리오로 결과 비교
통과/실패 기준을 체크리스트로 기록

使用相同场景比较修改前后的结果
将通过/失败标准记录为检查清单

Resources / Prompts 검증 항목

Resources / Prompts 验证项

```
resources/list
```
가 기대한 리소스를 노출하는지 확인
```
resources/read
```
가 실제 payload를 반환하는지 확인
prompt 등록 이름 충돌 여부 확인
prompt argument schema가 호출 payload와 일치하는지 확인
handler 누락 또는 라우팅 누락 여부 확인

确认
```
resources/list
```
是否暴露预期资源
确认
```
resources/read
```
是否返回实际 payload
检查 prompt 注册名称是否冲突
检查 prompt argument schema 是否与调用 payload 一致
检查是否存在 handler 缺失或路由缺失

Inspector 테스트 체크리스트

Inspector 测试检查清单

서버 실행 및 Inspector 연결 유지 기준을 만족하는가
```
tools/list
```
결과가 기대한 tool 노출 기준을 만족하는가
대표 tool 1개 이상
```
tools/call
```
성공 기준을 만족하는가
응답이
```
content
```
/
```
isError
```
구조 기준을 만족하는가
stdout 무오염 및 프로토콜 유지 기준을 만족하는가
수정 전/후 결과 차이 검증 기준을 만족하는가

是否满足服务器运行及保持 Inspector 连接的标准
```
tools/list
```
结果是否满足预期 tool 暴露标准
是否至少有一个代表性 tool 满足
```
tools/call
```
成功标准
响应是否满足
```
content
```
/
```
isError
```
结构标准
是否满足 stdout 无污染并维持协议的标准
是否满足修改前后结果差异验证的标准

Error 반환 기준

Error 返回标准

아래 조건 중 하나라도 해당하면

isError: true

로 반환

서버 실행 또는 연결 자체가 실패한 경우
필수 입력 누락으로 검증을 진행할 수 없는 경우
스펙 불일치가 확인된 경우
재현 실패로 원인 확정이 불가능한 경우
환경 제약으로 Inspector 테스트를 수행할 수 없는 경우

Error 응답에는 최소한 다음 항목 포함

실패 단계
관측된 증상
필요한 추가 입력 또는 다음 조치

如果满足以下任一条件，则返回

isError: true

服务器运行或连接本身失败
缺少必填输入，无法继续验证
确认存在规范不一致
复现失败，无法确定原因
受环境限制，无法执行 Inspector 测试

Error 响应至少应包含以下项目

失败阶段
观察到的症状
所需的其他输入或下一步操作

출력 계약 (Output Contract)

输出契约（Output Contract）

항상 아래 순서로 결과 정리

문제 요약과 재현 조건
확정 사실 / 추정 가설
스펙 대조 결과(일치/불일치)
수정 포인트와 영향 범위
Inspector 전/후 검증 결과
남은 리스크와 후속 확인 항목

始终按以下顺序整理结果

问题摘要与复现条件
已确认事实/推测性假设
规范对照结果（一致/不一致）
修改点与影响范围
Inspector 修改前后验证结果
剩余风险与后续确认项

Tool 반환 포맷

Tool 返回格式

Success

json

{
  "content": [{ "type": "text", "text": "..." }]
}

json

{
  "content": [{ "type": "text", "text": "..." }]
}

Error

json

{
  "isError": true,
  "content": [{ "type": "text", "text": "..." }]
}

json

{
  "isError": true,
  "content": [{ "type": "text", "text": "..." }]
}