.gif&blockId=11b00c82-b138-8050-a58b-dcbceda2ef8f)
도구(Tools)
: 애플리케이션이 외부 데이터 소스나 시스템과 상호작용할 때 호출할 수 있는 함수 또는 작업 단위
•
AI 모델이 외부 시스템과 상호작용하고 실제 작업을 수행할 수 있게 된다.
•
MCP 서버에서는 이러한 도구들을 미리 정의하여, LLM이 특정 작업(예: 파일 읽기/쓰기, 데이터베이스 쿼리, 버전 관리 연동 등)을 수행할 필요가 있을 때 해당 도구를 호출하도록 지원한다.
•
기본적으로 모델 중심 제어를 위해 설계되었으며, AI 모델이 컨텍스트를 이해하고 자동으로 도구를 찾아 호출할 수 있다.
단, 신뢰성과 안전성을 위해 실제 도구 실행 시에는 항상 사용자의 승인이 필요
주요 특징
모듈화 및 확장성
•
다양한 외부 데이터 소스 및 기능을 각기 다른 도구로 분리하여 제공
•
필요에 따라 새로운 도구를 추가하거나 기존 도구를 수정할 수 있다.
→ 별도의 커스텀 통합 작업 없이도 기능 확장이 가능하다.
동적 작업 수행
•
LLM은 자신의 응답 생성 과정 중에 특정 도구를 호출하여, 사전 학습된 지식 외에 최신 데이터나 특정 작업 결과를 반영할 수 있다.
파일 시스템 MCP 서버의 경우 파일을 읽거나 저장하는 도구를 제공하여 LLM이 실시간으로 해당 데이터를 활용할 수 있다.
도구 구현
타입스크립트
파이썬
도구 작업
기능 선언
•
tools 기능을 선언
{
"capabilities": {
"tools": {
"listChanged": true
}
}
}
TypeScript
복사
◦
여기서 listChanged는 이 서버가 도구 목록 변경 알림을 지원하는지를 나타낸다.
도구 정의 구조
{
"name": "도구_이름",
"description": "도구에 대한 설명",
"inputSchema": {
"type": "object",
"properties": {
"매개변수1": {
"type": "string",
"description": "매개변수 설명"
}
},
"required": ["필수_매개변수_목록"]
}
}
TypeScript
복사
주요 프로토콜 메시지
도구 목록 조회 (tools/list)
•
요청:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
JSON
복사
•
응답:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{
"name": "example_tool",
"description": "Example tool",
"inputSchema": {
"type": "object",
"properties": {
"param": {
"type": "string"
}
}
}
}
]
}
}
JSON
복사
도구 실행 (tools/call)
•
요청:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "example_tool",
"arguments": {
"param": "value"
}
}
}
JSON
복사
•
응답:
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [{
"type": "text",
"text": "Tool execution result"
}],
"isError": false
}
}
TypeScript
복사
도구 유형과 예제
1. 시스템 도구
로컬 시스템과 상호 작용하는 도구
•
시스템 리소스나 파일 시스템과 상호작용
{
name: "execute_command",
description: "Run a shell command",
inputSchema: {
type: "object",
properties: {
command: { type: "string" },
args: { type: "array", items: { type: "string" } }
}
}
}
TypeScript
복사
2. API 도구
외부 API와 통합하는 도구
•
외부 API를 래핑
{
name: "github_create_issue",
description: "Create a GitHub issue",
inputSchema: {
type: "object",
properties: {
title: { type: "string" },
body: { type: "string" },
labels: { type: "array", items: { type: "string" } }
}
}
}
Python
복사
3. 데이터 처리 도구
데이터를 변환하거나 분석하는 도구
•
데이터 처리
{
name: "analyze_csv",
description: "Analyze a CSV file",
inputSchema: {
type: "object",
properties: {
filepath: { type: "string" },
operations: {
type: "array",
items: {
enum: ["sum", "average", "count"]
}
}
}
}
}
Python
복사
오류 처리
•
도구 오류는 MCP 프로토콜 수준 오류가 아닌 결과 객체 내에서 보고되어야 한다.
•
이를 통해 LLM이 오류를 보고 잠재적으로 처리할 수 있다.
•
도구에서 오류가 발생하면:
1.
결과 isErrortrue에 설정
2.
content 배열 에 오류 세부 정보를 포함.
•
도구에 대한 올바른 오류 처리의 예시
타입스크립트
파이썬
프로토콜 오류
•
일반적인 통신 오류나 잘못된 요청은 JSON-RPC 오류로 처리:
{
"jsonrpc": "2.0",
"id": 3,
"error": {
"code": -32602,
"message": "Invalid tool name"
}
}
JSON
복사
도구 실행 오류
•
도구 실행 중 발생하는 오류는 결과 객체에 포함하여 반환:
{
"jsonrpc": "2.0",
"id": 4,
"result": {
"content": [{
"type": "text",
"text": "Failed to read file: Permission denied"
}],
"isError":true}
}
JSON
복사
테스트 도구
MCP 도구에 대한 포괄적인 테스트 전략은 다음을 포함해야 한다.
•
기능 테스트
: 도구가 유효한 입력으로 올바르게 실행되는지 확인하고 잘못된 입력을 적절히 처리
•
통합 테스트
: 실제 종속성과 모의 종속성을 모두 사용하여 외부 시스템과의 테스트 도구 상호 작용
•
보안 테스트
: 인증, 권한 부여, 입력 정리 및 속도 제한을 검증
•
성능 테스트
: 부하, 시간 초과 처리 및 리소스 정리 시 동작 확인
•
오류 처리
: 도구가 MCP 프로토콜을 통해 오류를 적절히 보고하고 리소스를 정리하도록 보장
모범 사례
•
명확하고 설명이 포함된 이름과 설명 제공
•
매개변수에 대한 자세한 JSON 스키마 정의 사용
•
도구 설명에 예제를 포함하여 모델이 도구를 어떻게 사용해야 하는지 설명
•
적절한 오류 처리 및 유효성 검사 구현
•
긴 작업에 진행 상황 보고 사용
•
도구 작업을 집중적이고 원자적으로 유지
•
예상 반환 값 구조 문서화
•
적절한 타임아웃 구현
•
리소스 집약적인 작업에 대해 속도 제한 고려
•
디버깅 및 모니터링을 위한 도구 사용량 기록
보안 고려 사항
입력 유효성 검사
•
스키마에 대해 모든 매개변수의 유효성 검사
•
파일 경로 및 시스템 명령 살균하기
•
URL 및 외부 식별자 유효성 검사
•
매개변수 크기 및 범위 확인
•
명령어 삽입 방지
액세스 제어
•
필요한 경우 인증 구현
•
적절한 권한 확인 사용
•
도구 사용 감사
•
요금 제한 요청
•
남용을 막기 위한 모니터링
오류 처리
•
내부 오류를 고객에게 노출X
•
보안 관련 오류 로그
•
타임아웃을 적절히 처리하기
•
오류 발생 후 리소스 정리
•
반환 값 유효성 검사
