AI 조수에게 날씨 데이터 가져오기, 주식 가격 분석 또는 작업 자동화 기능을 부여하는 모습을 상상해 보세요. 모든 작업을 단일 프로토콜을 통해 수행할 수 있습니다. 모델 컨텍스트 프로토콜 (MCP)이 이를 가능하게 하며, 새로운 MCP 프레임워크를 통해 자신의 서버 구축이 그 어느 때보다 쉬워졌습니다.
이 가이드에서는 MCP 프레임워크의 CLI 도구를 사용하여 MCP 서버를 생성하는 방법을 안내해 드리겠습니다. 이전의 MCP 경험은 필요하지 않습니다—기본적인 JavaScript/TypeScript 지식과 호기심만 있으면 됩니다!
MCP 이해하기
설정에 들어가기 전에 MCP가 무엇이며 왜 중요한지 간단히 검토해 보겠습니다:
MCP 개요: 모델 컨텍스트 프로토콜은 AI 모델이 외부 데이터 소스와 상호작용하는 방식을 표준화하기 위해 Anthropic에 의해 만들어진 개방된 사양입니다. 이를 통해 개발자들은 Claude Desktop과 같은 AI 플랫폼과 쉽게 통합할 수 있는 도구를 구축할 수 있습니다.
MCP의 장점: MCP는 도구 개발을 위한 표준화된 프로토콜을 제공함으로써 통합 프로세스를 단순화합니다. 이는 다양한 플랫폼 간의 호환성 문제를 걱정하지 않고 도구를 구축하는 데 집중할 수 있음을 의미합니다.
첫 번째 MCP 서버 구축하기
1단계: 필요한 것들
시작하기 전에 다음이 설치되어 있는지 확인하십시오:
- Node.js (20 이상): 서버는 Node.js에서 구축되므로 설치해야 합니다. 여기에서 다운로드
- TypeScript (5.0 이상): 서버 구축에 사용됩니다.
- npm: 종속성을 처리하는 패키지 관리자입니다.
- MCP 프레임워크: npm을 통해 전역적으로 설치하거나 기존 프로젝트에 추가할 수 있습니다.
- 10분의 인내심: 진심으로, 그렇게 빠릅니다.
2단계: MCP 프레임워크 설치하기
MCP 프레임워크를 시작하는 방법은 두 가지입니다:
옵션 1: MCP CLI 사용하기 (권장)
MCP 서버를 설정하는 가장 쉬운 방법은 CLI를 사용하는 것입니다. 방법은 다음과 같습니다:
# CLI를 전역적으로 설치
npm install -g mcp-framework
# 새 프로젝트 생성
mcp create my-mcp-server
# 프로젝트로 이동
cd my-mcp-server
# 종속성 설치
npm install 이렇게 하면 다음과 같은 사전 구성된 TypeScript, 예제 도구 및 내장 오류 처리를 갖춘 사용 준비 완료된 MCP 서버가 생성됩니다.
이제 새로운 MCP 프로젝트가 준비되었습니다.
옵션 2: 수동 설치 (기존 프로젝트용)
기존 프로젝트에 MCP 프레임워크를 추가하려면 다음 단계를 따르십시오:
MCP 프레임워크 설치:
npm install mcp-framewor기본 서버 생성: src/index.ts 파일 내에서:
import { MCPServer } from "mcp-framework";
const server = new MCPServer();
server.start().catch((error) => {
console.error("서버 오류:", error);
process.exit(1);
}); 3단계: 첫 번째 도구 만들기 (날씨 예제)
서버를 설정했으니 이제 주어진 도시의 날씨 정보를 가져오는 날씨 도구를 만들어봅시다.
새 도구 생성:
MCP CLI를 사용하여 날씨 정보를 위한 새 도구를 만들 수 있습니다:
mcp add tool weather 이렇게 하면 src/tools/WeatherTool.ts라는 파일이 생성됩니다. 또는 직접 그 파일을 수동으로 만들 수도 있습니다. 이제 그 파일을 편집해 봅시다.
날씨 도구 수정하기:
WeatherTool.ts 파일을 열고 다음과 같이 업데이트합니다:
import { MCPTool } from "mcp-framework";
import { z } from "zod";
interface WeatherInput {
city: string;
}
class WeatherTool extends MCPTool<WeatherInput> {
name = "weather";
description = "도시의 날씨 정보를 가져오기";
// Zod를 사용한 스키마 검증
schema = {
city: {
type: z.string(),
description: "도시 이름 (예: 런던)",
},
};
async execute({ city }: WeatherInput) {
// 실제 API 호출로 대체해야 합니다
return {
city,
temperature: 22,
condition: "맑음",
humidity: 45,
};
}
}
export default WeatherTool;이 코드에서는 도시의 날씨를 가져오는 WeatherTool 클래스를 정의합니다. 이 모의 구현은 정적 데이터를 반환하지만, 이를 실제 API 호출로 대체할 수 있습니다.
4단계: MCP 서버 빌드 및 테스트하기
날씨 도구를 수정한 후에는 MCP 서버가 예상대로 작동하는지 확인하기 위해 빌드하고 테스트할 차례입니다. 이를 위해 MCP 검사기를 사용할 것입니다.
프로젝트 빌드하기:
npm run build전송 방법 선택하기: MCP 프레임워크는 두 가지 전송을 지원합니다:
- STDIO 전송: CLI 및 로컬 통합에 가장 적합합니다.
- SSE 전송: 웹 애플리케이션 및 분산 시스템에 이상적입니다.
이 튜토리얼에서는 로컬 테스트에 적합한 STDIO 전송을 사용할 것입니다.
MCP 검사기 시작하기: 다음 명령을 사용하세요:
npx @modelcontextprotocol/inspector dist/index.js 날씨 도구 테스트하기:
날씨 도구를 테스트하려면 weather 도구를 선택하고 "파리"와 같은 도시를 입력하세요.
그런 다음 모의 날씨 데이터를 확인하세요.
5단계: MCP를 실제 날씨 데이터에 연결하기
우리의 날씨 도구를 Open-Meteo의 무료 API를 사용하도록 업그레이드 해봅시다. 이 API는 API 키 없이도 하이퍼 로컬 예보를 제공하는 강력한 대안입니다. 시작하려면 새 도구를 만들고 새로운 이름을 지정하거나 아래의 새 코드로 이전 도구의 코드를 단순히 교체하면 됩니다:
import { MCPTool } from "mcp-framework";
import { z } from "zod";
import axios, { AxiosError } from "axios";
interface WeatherApiInput {
city: string;
}
interface WeatherApiResponse {
city: string;
temperature: number;
condition: string;
humidity: number;
windSpeed: number;
feelsLike: number;
precipitation: number;
}
class WeatherApiTool extends MCPTool<WeatherApiInput> {
name = "weather_api";
description = "Open-Meteo API를 사용하여 도시의 실제 날씨 정보를 가져오기";
private readonly GEOCODING_URL = "https://geocoding-api.open-meteo.com/v1/search";
private readonly WEATHER_URL = "https://api.open-meteo.com/v1/forecast";
schema = {
city: {
type: z.string(),
description: "날씨를 가져올 도시 이름",
},
};
async execute({ city }: WeatherApiInput): Promise<WeatherApiResponse> {
try {
// 첫째, 도시의 좌표를 가져옵니다
const geoResponse = await axios.get(this.GEOCODING_URL, {
params: {
name: city,
count: 1,
language: "en",
format: "json"
}
});
if (!geoResponse.data.results?.length) {
throw new Error(`도시 '${city}'를 찾을 수 없습니다`);
}
const location = geoResponse.data.results[0];
// 그런 다음 좌표를 사용하여 날씨 데이터를 가져옵니다
const weatherResponse = await axios.get(this.WEATHER_URL, {
params: {
latitude: location.latitude,
longitude: location.longitude,
current: ["temperature_2m", "relative_humidity_2m", "apparent_temperature", "precipitation", "weather_code", "wind_speed_10m"],
timezone: "auto"
}
});
const current = weatherResponse.data.current;
// 날씨 코드에 따라 조건 매핑
const condition = this.getWeatherCondition(current.weather_code);
return {
city: location.name,
temperature: Math.round(current.temperature_2m),
condition,
humidity: Math.round(current.relative_humidity_2m),
windSpeed: Math.round(current.wind_speed_10m),
feelsLike: Math.round(current.apparent_temperature),
precipitation: current.precipitation
};
} catch (error: unknown) {
if (error instanceof Error) {
throw new Error(`날씨 데이터 가져오기 실패: ${error.message}`);
}
throw new Error('날씨 데이터 가져오기 실패: 알 수 없는 오류가 발생했습니다');
}
}
private getWeatherCondition(code: number): string {
// WMO 날씨 해석 코드 (https://open-meteo.com/en/docs)
const conditions: Record<number, string> = {
0: "맑은 하늘",
1: "주로 맑음",
2: "부분적으로 흐림",
3: "흐림",
45: "안개",
48: "서리안개",
51: "가벼운 이슬비",
53: "보통 이슬비",
55: "강한 이슬비",
61: "약한 비",
63: "보통 비",
65: "강한 비",
71: "약한 눈",
73: "보통 눈",
75: "강한 눈",
77: "눈 알갱이",
80: "약한 소나기",
81: "보통 소나기",
82: "강한 소나기",
85: "약한 눈소나기",
86: "강한 눈소나기",
95: "천둥번개",
96: "약한 우박을 동반한 천둥번개",
99: "강한 우박을 동반한 천둥번개"
};
return conditions[code] || "알 수 없음";
}
}
export default WeatherApiTool;코드는 약간 길지만 지금은 코드가 작동하도록 하고 MCP 시작의 느낌을 살리는 데 집중하세요. 시간을 내어 이를 예제 가이드를 사용하여 더 복잡한 MCP 구축으로 전환하는 데 도움을 받으세요.
도구를 테스트하려면 간단히 선택하세요:
예를 들어 도시를 입력하세요. "루사카"를 입력하고 결과를 확인하세요:
이 단계에서 대부분의 설정 및 프로젝트 실행의 문제를 해결했기를 바라며, 새 MCP 도구를 테스트하는 것은 전혀 도전이 아닐 것입니다!
Apidog와 함께 작업하기
잊지 마세요 MCP 서버 개발을 Apidog로 강화하세요—API 테스트, 모킹 및 문서를 단순화하는 다용도 도구입니다. 무료 요금제로 가입한 후 프로젝트를 만들어 API 워크플로를 중앙 집중화하세요. 엔드포인트를 가져와 요청을 모니터링하고, 스마트 모의 서버로 응답을 시뮬레이션하며, 숨겨진 버그를 조기에 잡기 위해 테스트를 자동화하세요. Apidog는 디버깅을 간소화하고 도구가 완벽하게 작동하도록 보장하여 강력한 AI 통합을 구축하기 위한 완벽한 동반자가 됩니다.
결론
MCP 서버 구축은 AI 워크플로를 크게 향상시킬 수 있는 간단한 프로세스입니다. Apidog와 같은 도구를 통합함으로써 개발 프로세스를 간소화하고 견고하며 잘 문서화된 API를 보장할 수 있습니다. 웹 서비스 또는 로컬 파일로 작업하든 MCP는 AI 모델과 외부 데이터 소스를 연결하는 표준화된 방법을 제공합니다.
API 개발 워크플로를 다음 단계로 끌어올릴 준비가 되셨나요? 무료로 Apidog를 다운로드하시고 워크플로를 어떻게 변환할 수 있는지 알아보세요!