개요: MCP 프로토콜의 세 가지 기본 요소
에서 첫 번째 기사 이 시리즈의 우리는 모델 컨텍스트 프로토콜(MCP) 및 호스트/클라이언트/서버 아키텍처. 이제 자세히 분석해 볼 차례입니다. 세 가지 기본 요소 MCP 서버가 노출할 수 있는 내용은 다음과 같습니다. 도구, 자원 e 프롬프트.
각 기본 요소는 AI와 외부 세계 간의 상호 작용에서 뚜렷한 역할을 합니다. 차이점을 이해하고, 효과적인 MCP 서버를 설계하려면 각각의 사용 사례와 내부 구조가 중요합니다. 그리고 잘 구조화되어 있습니다. 이 기사에서는 이론과 검증 체계를 살펴보겠습니다. 조드, JSON-RPC 페이로드 및 TypeScript 핸들러, 프로젝트의 구체적인 예 분석 Tech-MCP.
이 기사에서 배울 내용
- 도구, 리소스 및 프롬프트의 차이점: 역할, 제어 및 사용 사례
- Zod 유효성 검사 및 비동기 처리기를 사용하여 도구를 정의하는 방법
- URI 템플릿 및 읽기 전용 데이터를 사용하여 리소스를 노출하는 방법
- 매개변수화되고 재사용 가능한 프롬프트를 만드는 방법
- 각 기본 요소에 대한 JSON-RPC 페이로드 형식
- 검색부터 종료까지 MCP 세션의 수명주기
- 도구 설명 및 명명 규칙에 대한 모범 사례
세 가지 기본 요소 비교
각 기본 요소에 대해 자세히 알아보기 전에 개요를 살펴보는 것이 유용합니다. 그들의 근본적인 차이점. 각 기본 요소는 특정 요구에 응답합니다. MCP 생태계에서:
MCP 기본 요소 요약
| 원어 | 역할 | 누가 통제하는가 | 부작용 | Esempio |
|---|---|---|---|---|
| 도구 | AI가 호출할 수 있는 기능 | AI가 자율적으로 결정 | 예(상태를 변경할 수 있음) | create-sprint, analyze-diff |
| 자원 | 읽기 위해 액세스 가능한 데이터 | 호스트 애플리케이션 | 아니요(읽기 전용) | sprint://{id}, file:///config |
| 프롬프트 | 재사용 가능한 사전 정의된 템플릿 | 사용자가 선택 | 아니요(메시지 생성) | sprint-review, code-analysis |
이러한 구별은 중요합니다. 도구 이는 프로토콜의 운영 핵심입니다. 르 자원 그들은 맥락과 데이터를 제공합니다. 프롬프트 그들은 AI를 운전한다 구조화된 작업. 각 기본 요소를 자세히 살펴보겠습니다.
1. 도구: AI가 호출할 수 있는 기능
I 도구 이는 MCP 상호 작용의 핵심을 나타냅니다. AI가 할 수 있는 기능은 이렇습니다. 현실 세계에서 구체적인 행동을 수행하기 위해 대화 중에 자신에게 전화를 겁니다. 단순한 API 호출과 달리 MCP 도구는 매개변수를 명시적으로 선언합니다. 입력된 스키마를 사용하면 AI가 이해할 수 있습니다. 언제 e ~처럼 그를 불러내십시오.
도구의 기본 기능
- AI가 언제 전화할지 결정: 대화의 맥락에 따라 언어 모델은 호출할 도구와 매개변수를 자동으로 선택합니다.
- Zod로 입력한 매개변수: 각 도구는 Zod 스키마를 사용하여 입력을 선언하여 런타임 시 자동 유효성 검사를 보장합니다.
- 구조화된 결과: 결과는 항상 다음의 배열입니다.
content유형으로text,imageoresource - 부작용이 있을 수 있습니다.: 파일 생성, 데이터베이스에 쓰기, 외부 API 호출, 알림 보내기
- 컴포저블: AI는 여러 도구를 순차적으로 결합하여 복잡한 작업을 완료할 수 있습니다.
TypeScript 도구 분석
도구 등록은 고유 이름, 고유 이름, AI, Zod 매개변수 체계 및 비동기 처리기에 대한 설명입니다. 여기에 예가 있습니다 프로젝트에서 완료 Tech-MCP:
import { z } from 'zod';
server.tool(
'create-sprint', // Nome univoco del tool
'Create a new sprint with a name, date range, and goals. ' +
'Returns the created sprint object with id, status, and dates. ' +
'Use this when the user wants to start planning a new iteration.',
{ // Schema parametri (Zod)
name: z.string().describe('Sprint name, e.g. Sprint-15'),
startDate: z.string().describe('Start date in ISO format'),
endDate: z.string().describe('End date in ISO format'),
goals: z.array(z.string()).describe('List of sprint goals'),
},
async ({ name, startDate, endDate, goals }) => { // Handler
const sprint = store.createSprint({
name,
startDate,
endDate,
goals
});
return {
content: [{
type: 'text',
text: JSON.stringify(sprint, null, 2)
}]
};
}
);
검증을 위해 왜 Zod를 사용하나요?
조드 포괄적인 유형 안전성을 제공하는 TypeScript 우선 검증 라이브러리 컴파일 타임에, 런타임에 유효성 검사를 수행합니다. MCP SDK는 Zod 스키마를 자동으로 변환합니다. 안으로 JSON 스키마, AI가 도구의 매개변수를 이해하는 데 사용하는 형식입니다. 이는 Zod 스키마를 선언함으로써 다음을 얻을 수 있음을 의미합니다. 입력의 자동 유효성 검사 TypeScript의 AI 및 유형 추론을 위한 문서 생성이 모두 하나로 이루어집니다. 정의.
도구의 응답 형식
각 도구 핸들러는 배열이 포함된 객체를 반환해야 합니다. content. 모든 요소
배열에는 type 이는 콘텐츠의 형식을 나타냅니다.
// Risposta testuale (più comune)
return {
content: [{
type: 'text',
text: 'Sprint creato con successo: Sprint-15 (ID: 42)'
}]
};
// Risposta con immagine
return {
content: [{
type: 'image',
data: base64EncodedImage,
mimeType: 'image/png'
}]
};
// Risposta con errore
return {
content: [{
type: 'text',
text: 'Errore: sprint non trovato'
}],
isError: true
};
Tech-MCP 프로젝트의 도구 범주
프로젝트에서 Tech-MCP, 85개 이상의 도구는 수행하는 작업 유형에 따라 기능 범주로 구성됩니다.
작업 유형에 따른 도구 분류
| 범주 | 예제 도구 | 효과 | 설명 |
|---|---|---|---|
| 창조 | create-sprint, save-snippet |
그들은 데이터베이스에 씁니다 | 새로운 영구 엔터티를 생성합니다. |
| 독서 | get-sprint, search-snippets |
읽기 전용 | 기존 데이터를 복구합니다. |
| 복수 | analyze-diff, find-bottlenecks |
부작용 없음 | 입력을 처리하고 통찰력을 생성합니다. |
| 세대 | generate-unit-tests, generate-compose |
그들은 산출물을 생산합니다 | 코드, 구성, 템플릿을 생성합니다. |
| 모니터링 | list-pipelines, get-budget-status |
외부 상태를 읽습니다. | 외부 시스템의 상태를 확인합니다. |
2. 리소스: 읽을 수 있는 데이터
Le 자원 그것들은 두 번째 MCP 프리미티브입니다. 애플리케이션이 호스팅하는 데이터를 나타냅니다. AI에 대한 컨텍스트를 읽고 제공할 수 있습니다. 도구와 달리 리소스는 호출되지 않습니다. AI에서 직접: 그리고 언제, 무엇을 할지 결정하는 호스트 애플리케이션(Claude Desktop, Cursor 등) 대화의 맥락에서 리소스가 로드됩니다.
자원의 기본 특성
- URI로 식별됨: 각 리소스에는 다음과 같은 고유 식별자가 있습니다.
file:///path/to/file,db://schema/tableosprint://{id} - 응용 프로그램에 필요합니다.: AI가 결정하는 도구와 달리 리소스 및 호스트 애플리케이션이 액세스를 제어합니다.
- 읽기 전용: 리소스는 서버의 상태를 수정하지 않으며 데이터 제공에만 사용됩니다.
- URI 템플릿을 지원합니다.: 파라메트릭 리소스의 경우 다음과 같은 템플릿을 정의할 수 있습니다.
sprint://{id} - 명시적 MIME 유형: 각 리소스는 콘텐츠 유형(
application/json,text/plain, 등.)
URI 템플릿을 사용한 리소스 정의
스프린트의 세부 정보를 노출하는 파라메트릭 리소스를 정의하는 방법입니다. 귀하의 ID로 식별됩니다:
server.resource(
'sprint://{id}', // URI template
'Get sprint details by ID', // Descrizione
async (uri) => { // Handler
const id = extractIdFromUri(uri);
const sprint = store.getSprint(id);
if (!sprint) {
throw new Error(`Sprint ${id} not found`);
}
return {
contents: [{
uri: uri.href,
mimeType: 'application/json',
text: JSON.stringify(sprint, null, 2)
}]
};
}
);
정적 자원과 동적 자원
MCP 리소스는 두 가지 범주로 나뉩니다. 공전 e 역학. 정적 리소스는 고정된 URI를 가지며 항상 동일한 엔드포인트에서 데이터를 반환합니다. 동적 리소스는 URI 템플릿을 사용하여 매개변수를 허용합니다.
// Resource statica: URI fisso, dati globali
server.resource(
'config://app-settings',
'Application configuration settings',
async (uri) => {
return {
contents: [{
uri: uri.href,
mimeType: 'application/json',
text: JSON.stringify(config.getAll())
}]
};
}
);
// Resource dinamica: URI template con parametro
server.resource(
'user://{userId}/profile',
'User profile data',
async (uri) => {
const userId = extractParam(uri, 'userId');
const profile = await db.getProfile(userId);
return {
contents: [{
uri: uri.href,
mimeType: 'application/json',
text: JSON.stringify(profile)
}]
};
}
);
리소스에 대한 JSON-RPC 페이로드
호스트 애플리케이션이 리소스를 요청하면 MCP 프로토콜은 두 가지 JSON-RPC 방법을 사용합니다.
resources/list 사용 가능한 자원을 발견하기 위해 e resources/read
그 내용을 읽으려면.
// Richiesta: elenco delle resources disponibili
{ "method": "resources/list" }
// Risposta del server
{
"resources": [
{
"uri": "config://app-settings",
"name": "App Settings",
"mimeType": "application/json"
}
],
"resourceTemplates": [
{
"uriTemplate": "sprint://{id}",
"name": "Sprint Details",
"mimeType": "application/json"
}
]
}
// Richiesta: lettura di una resource specifica
{ "method": "resources/read",
"params": { "uri": "sprint://42" } }
// Risposta del server
{
"contents": [{
"uri": "sprint://42",
"mimeType": "application/json",
"text": "{ \"id\": 42, \"name\": \"Sprint-15\" }"
}]
}
Tech-MCP 프로젝트에 대한 참고 사항
프로젝트에서 Tech-MCP, 데이터와의 상호작용은 주로 i를 통해 발생합니다. 도구. 리소스는 프로젝트 구성을 노출하는 등 향후 개발을 위해 계획되어 있습니다. AI에 대한 읽기 전용 컨텍스트인 데이터베이스 스키마 또는 API 문서.
3. 프롬프트: 재사용 가능한 미리 정의된 템플릿
I 프롬프트 그것들은 세 번째 MCP 프리미티브입니다. 이는 다음을 안내하는 사전 정의된 템플릿을 나타냅니다. 복잡하고 구조화된 작업을 실행하는 AI. AI가 결정하는 도구와 달리 리소스(애플리케이션이 결정하는 위치), 프롬프트는 다음과 같습니다. 사용자가 선택한 에 대한 특정 워크플로를 시작합니다.
프롬프트의 기본 기능
- 그들은 AI를 운전한다: 특정 목표를 향해 언어 모델을 지시하는 구조화된 지침을 제공합니다.
- 그들은 주장을 받아들인다: 사용자 입력으로 매개변수화 가능
- 도구와 결합 가능: 프롬프트는 AI에게 순서대로 호출할 일련의 도구를 제안할 수 있습니다.
- 재사용 가능: 일단 정의되면, 다른 매개변수를 사용하여 다른 대화에서 사용할 수 있습니다.
- 사용자가 선택한: AI가 아닌 활성화할 프롬프트를 사용자가 선택합니다.
인수가 포함된 프롬프트 정의
MCP 프롬프트는 이름, 설명, 인수 목록 및 함수로 정의됩니다. AI에 보낼 메시지를 생성합니다.
server.prompt(
'sprint-review', // Nome univoco
'Generate a comprehensive sprint review report', // Descrizione
[ // Argomenti
{
name: 'sprintId',
description: 'ID of the sprint to review',
required: true
},
{
name: 'format',
description: 'Output format: summary, detailed, or metrics-only',
required: false
}
],
async ({ sprintId, format }) => ({ // Handler
messages: [{
role: 'user',
content: {
type: 'text',
text: `Analizza lo sprint ${sprintId} con i seguenti passaggi:
1. Usa il tool get-sprint per recuperare i dati dello sprint
2. Usa calculate-velocity per calcolare la velocity del team
3. Usa get-sprint-stories per l'elenco delle storie completate
4. Genera un report in formato ${format || 'detailed'} con:
- Obiettivi raggiunti vs pianificati
- Velocity e trend rispetto agli sprint precedenti
- Storie completate e non completate
- Raccomandazioni per il prossimo sprint`
}
}]
}))
);
프롬프트용 JSON-RPC 페이로드
다른 기본 요소와 마찬가지로 프롬프트는 검색을 위해 전용 JSON-RPC 방법을 사용합니다. 그리고 호출:
// Discovery: elenco dei prompts disponibili
{ "method": "prompts/list" }
// Risposta del server
{
"prompts": [
{
"name": "sprint-review",
"description": "Generate a comprehensive sprint review report",
"arguments": [
{
"name": "sprintId",
"description": "ID of the sprint to review",
"required": true
},
{
"name": "format",
"description": "Output format: summary, detailed, or metrics-only",
"required": false
}
]
}
]
}
// Invocazione di un prompt
{ "method": "prompts/get",
"params": {
"name": "sprint-review",
"arguments": { "sprintId": "42", "format": "detailed" }
}
}
// Risposta: messaggi generati dal prompt
{
"messages": [{
"role": "user",
"content": {
"type": "text",
"text": "Analizza lo sprint 42 con i seguenti passaggi..."
}
}]
}
도구를 조정하라는 메시지
프롬프트의 진정한 힘은 복잡한 시퀀스를 조율하는 데 사용될 때 나타납니다. 도구의. 잘 설계된 프롬프트는 다단계 작업 흐름을 통해 AI를 안내할 수 있습니다.
server.prompt(
'full-code-review',
'Perform a comprehensive code review workflow',
[
{ name: 'filePath', description: 'Path to the file to review', required: true },
{ name: 'language', description: 'Programming language', required: true }
],
async ({ filePath, language }) => ({
messages: [{
role: 'user',
content: {
type: 'text',
text: `Esegui una code review completa del file ${filePath} (${language}):
STEP 1 - Analisi statica:
Usa analyze-diff per identificare problemi nel codice
STEP 2 - Generazione test:
Usa generate-unit-tests per creare test per le funzioni trovate
STEP 3 - Verifica stile:
Controlla che il codice segua le convenzioni del progetto
STEP 4 - Report finale:
Genera un report con: problemi trovati, test suggeriti,
miglioramenti proposti, severity di ogni issue`
}
}]
}))
);
참고: Tech-MCP 프로젝트의 프롬프트
리소스와 마찬가지로 프로젝트도 Tech-MCP 현재는 i를 사용하고 있습니다 도구 주요 프리미티브로. 향후 개발에 대한 프롬프트가 계획되어 있습니다. 스프린트 검토, 온보딩 등 반복되는 시나리오에 대해 사전 정의된 워크플로를 만드는 것을 목표로 합니다. 신규 개발자 및 팀 성과 분석.
AI가 도구를 선택하는 방법: 설명의 역할
MCP 서버가 클라이언트에 등록되면 다음을 통해 사용 가능한 도구 목록이 표시됩니다.
방법 tools/list. 각 도구에 대해 AI는 세 가지 주요 정보를 받습니다.
- 이름: 고유 식별자(예:
create-sprint) - 설명: 도구가 수행하는 작업을 설명하는 자연어 텍스트
- 매개변수 체계: 유형 및 설명이 포함된 입력 매개변수의 구조
La 설명 그리고 가장 중요한 요소: 잘 작성된 설명은 AI가 이해하다 언제 도구를 사용하고, 무엇 결과적으로 기대하다 e 어느 것에서 시나리오 그리고 그것을 호출하는 것이 적절합니다.
도구 설명에 대한 모범 사례
OTTIMO (spiega cosa fa, cosa ritorna, quando usarlo):
"Create a new sprint with a name, date range, and goals.
Returns the created sprint object with id, name, dates, status.
Use this when the user wants to start planning a new iteration."
BUONO (spiega cosa fa e gli input):
"Create a new sprint with a name, date range, and goals"
VAGO (l'AI potrebbe non capire quando usarlo):
"Sprint creation tool"
효과적인 설명을 위한 체크리스트
| 요소 | 요구 | Esempio |
|---|---|---|
| 행동 | 도구의 기능은 무엇인가요? | "새 스프린트 생성..." |
| 입력 | 어떤 매개변수가 필요합니까? | "...이름, 기간, 목표 포함" |
| 출력 | 무엇이 돌아오나요? | "ID가 있는 생성된 스프린트 개체를 반환합니다..." |
| 문맥 | 언제 사용하나요? | "사용자가 새로운 반복을 계획하고 싶을 때 사용하세요" |
MCP 세션의 수명주기
각 MCP 상호 작용은 4단계로 구성된 수명 주기를 따릅니다. 이것을 이해하십시오 흐름은 모든 시나리오에서 올바르게 작동하는 서버를 설계하는 데 필수적입니다.
[1] INIZIALIZZAZIONE
Client --> Server: initialize (versione protocollo, capabilities)
Server --> Client: capabilities (tool list, resource templates, prompts)
[2] DISCOVERY
Client --> Server: tools/list
Server --> Client: [{ name, description, inputSchema }, ...]
Client --> Server: resources/list
Server --> Client: [{ uri, name, mimeType }, ...]
Client --> Server: prompts/list
Server --> Client: [{ name, description, arguments }, ...]
[3] UTILIZZO (ripetuto N volte durante la sessione)
Client --> Server: tools/call { name, arguments }
Server --> Client: { content: [...] }
Client --> Server: resources/read { uri }
Server --> Client: { contents: [...] }
Client --> Server: prompts/get { name, arguments }
Server --> Client: { messages: [...] }
[4] CHIUSURA
Client --> Server: close
단계의 세부 사항
- 초기화: 클라이언트는 프로토콜 버전과 해당 기능을 보냅니다. 서버는 자신이 지원하는 기본 요소(도구, 리소스, 프롬프트)와 자체 기본 요소를 선언하여 응답합니다. 기능(알림, 로깅 등).
- 발견: 클라이언트는 서버에 쿼리하여 사용 가능한 모든 기본 요소를 검색합니다. 이 단계는 결정을 내리는 데 필요한 정보를 AI에 제공하기 때문에 기본입니다. 어떤 도구를 사용할지.
- 용법: 세션 동안 N번 반복되는 작동 단계입니다. 클라이언트 도구를 호출하고, 리소스를 읽고, 순서와 조합에 관계없이 프롬프트를 트리거할 수 있습니다.
- 폐쇄: 클라이언트가 세션 종료 신호를 보냅니다. 서버가 리소스를 해제합니다. 연결을 닫습니다.
Zod를 사용한 매개변수 검증: 고급 예
Zod는 매개변수에 대한 정확한 패턴을 정의할 수 있는 광범위한 유효성 검사기를 제공합니다. 도구의. 프로젝트에 사용된 몇 가지 고급 패턴은 다음과 같습니다. Tech-MCP:
import { z } from 'zod';
// Schema con enum e valori opzionali
const createTaskSchema = {
title: z.string().min(1).max(200)
.describe('Task title'),
priority: z.enum(['low', 'medium', 'high', 'critical'])
.describe('Task priority level'),
assignee: z.string().optional()
.describe('Username of the assignee'),
labels: z.array(z.string()).default([])
.describe('List of labels to apply'),
estimate: z.number().positive().optional()
.describe('Estimated hours to complete'),
};
// Schema con oggetti nested
const deployConfigSchema = {
environment: z.enum(['staging', 'production']),
version: z.string().regex(/^\d+\.\d+\.\d+$/),
options: z.object({
rollback: z.boolean().default(true),
healthCheck: z.boolean().default(true),
notifySlack: z.boolean().default(false),
}).optional(),
};
// Schema con union types
const searchSchema = {
query: z.string().min(1),
scope: z.union([
z.literal('code'),
z.literal('docs'),
z.literal('issues'),
z.literal('all'),
]).default('all'),
limit: z.number().int().min(1).max(100).default(20),
};
기본 요소 간의 상호 작용: 완전한 예
세 가지 MCP 기본 요소는 독립적으로 작동하지 않습니다. 실제 시나리오에서는 워크플로 시너지 방식으로 세 가지 기본 요소를 모두 결합할 수 있습니다.
- 사용자가 프롬프트를 선택합니다.: 매개변수가 포함된 "Sprint Review"
sprintId: 42 - 프롬프트에서 지침을 생성합니다.: 메시지는 AI가 특정 도구를 사용하도록 제안합니다.
- AI가 도구를 호출합니다.: 부르다
get-sprint,calculate-velocity,get-sprint-stories - 애플리케이션이 리소스를 로드합니다.: 컨텍스트로 추가
config://team-settings - AI가 보고서를 생성합니다: 수집된 모든 데이터를 하나의 구조화된 보고서로 결합합니다.
이러한 구성 가능성은 MCP 프로토콜의 강점 중 하나입니다. 복잡하고 명확한 워크플로에서 특정 역할을 수행합니다.
결론
세 가지 MCP 프리미티브 - 도구, 자원 e 프롬프트 -- 프로토콜의 기본 어휘를 구성합니다. 각 기본 요소에는 고유한 역할이 있습니다. 도구는 작업을 수행하고 리소스는 데이터를 제공하며 프롬프트는 구조화된 작업에서 AI를 안내합니다.
검증 조드 유형 안전성과 자동 문서화를 보장하는 동시에 MCP 세션 수명주기는 클라이언트와 서버 간의 질서 있고 예측 가능한 상호 작용을 보장합니다. 기본 요소 간의 구성 가능성을 통해 다음에서 시작하여 복잡한 워크플로를 구축할 수 있습니다. 간단하고 잘 정의된 빌딩 블록.
다음 글에서는 좀 더 자세히 알아보겠습니다.모노레포 아키텍처 그리고 나 프로젝트 패턴 에 사용 Tech-MCP: 단일 저장소에 31개의 MCP 서버를 구성하고 Turborepo로 공유 종속성을 관리하는 방법 그리고 pnpm을 사용하여 재사용성과 유지 관리성을 극대화하도록 코드를 구성합니다.
모든 예제가 포함된 전체 코드는 저장소에서 사용할 수 있습니다. GitHub의 Tech-MCP.