Unsplash-MCP-Server: High-Res API Powerhouse for Developers

unsplash-mcp-server

모델 컨텍스트 프로토콜(MCP) 서버 개발 가이드: LLM을 위한 강력한 도구 구축

목차

1. MCP 서버 소개
2. 핵심 서버 아키텍처
3. 첫 번째 MCP 서버 구축하기
4. 기능 노출하기
   * 도구 정의 및 구현
   * 리소스 관리
   * 프롬프트 생성 및 공유
5. 고급 서버 기능
   * 샘플링
   * 루트
   * 스트리밍 응답
   * 진행 상황 보고
   * 리소스 구독
   * 다중 서버 협업
   * 성능 최적화
6. 보안 및 모범 사례
7. 문제 해결 및 리소스
8. 예시 구현

1. MCP 서버 소개

모델 컨텍스트 프로토콜(MCP)이란?

모델 컨텍스트 프로토콜(MCP)은 대형 언어 모델(LLM) 애플리케이션(클라이언트)과 외부 서비스(서버) 간의 상호작용을 촉진하는 표준화된 통신 프로토콜입니다. 이러한 서버는 맥락 정보, 도구 및 리소스를 제공합니다. MCP는 관심사의 분리를 명확하게 하여 LLM 애플리케이션이 데이터 검색, 외부 API 액세스 및 특수 계산과 같은 작업을 전담하는 서버에 위임할 수 있도록 합니다.

MCP 생태계에서 서버의 역할

서버는 MCP 생태계의 중추로, LLM 애플리케이션과 외부 세계 간의 중개자 역할을 합니다. 서버는 다음과 같은 다양한 기능을 제공할 수 있습니다:

• 실시간 데이터 제공: 데이터베이스, API 또는 다른 출처에서 정보를 가져옵니다.
• 특수 도구 노출: 이미지 처리, 코드 실행, 데이터 분석과 같은 기능을 제공합니다.
• 프롬프트 관리 및 공유: 미리 정의된 프롬프트 또는 프롬프트 템플릿을 저장하고 제공합니다.
• 외부 시스템과의 연결: 다른 애플리케이션, 서비스 또는 플랫폼과 통합합니다.

MCP 서버 구현의 이점

MCP 서버를 구현하는 것에는 여러 가지 이점이 있습니다:

• 확장성: LLM 애플리케이션의 핵심 코드를 수정하지 않고도 새로운 기능을 쉽게 추가할 수 있습니다.
• 모듈화: 특수 기능을 독립적이고 재사용 가능한 구성 요소로 개발하고 유지 관리할 수 있습니다.
• 상호 운용성: 다른 LLM 애플리케이션들이 동일한 맥락 소스와 도구를 공유할 수 있게 합니다.
• 확장성: 워크로드를 분산하고 복잡한 작업을 효율적으로 처리할 수 있습니다.
• 혁신: LLM의 힘을 활용하여 독특한 기능과 통합을 개발하는 데 집중할 수 있습니다.

서버와 클라이언트: 관계 이해하기

MCP 아키텍처에서:

• 클라이언트 는 일반적으로 LLM 애플리케이션(Claude Desktop, VS Code 또는 맞춤 애플리케이션)으로, 서버에 연결하고 서비스를 요청하는 역할을 합니다.
• 서버 는 클라이언트의 요청을 처리하고 응답을 제공하는 독립적인 프로세스로, 도구, 리소스 및 프롬프트와 같은 기능을 노출합니다.

하나의 클라이언트는 여러 서버에 연결할 수 있고, 하나의 서버는 여러 클라이언트를 지원할 수 있습니다. 이 다대다 관계는 유연하고 강력한 통합을 가능하게 합니다.

2. 핵심 서버 아키텍처

MCP 서버의 핵심 구성 요소

MCP 서버는 여러 핵심 구성 요소들이 함께 작동하는 시스템입니다:

1. 프로토콜 계층: 이 계층은 메시지 프레이밍, 요청/응답 연결, 알림 처리 등 고수준의 통신 패턴을 처리합니다. Protocol, Client, Server와 같은 클래스들이 포함됩니다.
2. 전송 계층: 이 계층은 클라이언트와 서버 간의 실제 통신을 관리합니다. MCP는 Stdio와 HTTP(Server-Sent Events(SSE))와 같은 여러 전송 메커니즘을 지원합니다. 모든 전송은 메시지 교환을 위해 JSON-RPC 2.0을 사용합니다.
3. 기능(Capabilities): 서버가 할 수 있는 일들을 정의합니다. 기능은 도구(실행 가능한 함수), 리소스(데이터 소스) 및 프롬프트(LLM을 위한 미리 정의된 텍스트 입력)가 포함됩니다.

프로토콜의 기본 원칙

MCP는 클라이언트-서버 아키텍처를 기반으로 구축되었습니다. LLM 애플리케이션(호스트)은 연결을 시작합니다. 클라이언트는 호스트 애플리케이션 내에서 서버와 1:1 연결을 유지합니다. 서버는 클라이언트에게 맥락, 도구 및 프롬프트를 제공합니다.

서버 생애 주기: 연결, 교환, 종료

MCP 연결의 생애 주기는 세 가지 주요 단계로 구성됩니다:

1. 초기화:

* 클라이언트는 `initialize` 요청을 보내며, 프로토콜 버전과 기능을 포함합니다.
* 서버는 자신의 프로토콜 버전과 기능을 응답으로 보냅니다.
* 클라이언트는 `initialized` 알림을 보내 이를 확인합니다.
* 이후 정상적인 메시지 교환이 시작됩니다.

2. 메시지 교환: 초기화 후, 클라이언트와 서버는 다음과 같은 패턴을 사용하여 메시지를 교환합니다:

* **요청-응답:** 한쪽에서 요청을 보내면 다른 쪽이 응답을 보냅니다.
* **알림:** 한쪽에서 메시지를 보냅니다(응답은 없습니다).

3. 종료: 연결은 여러 방법으로 종료될 수 있습니다:

* `close()` 메서드를 통한 정상 종료.
* 전송 연결 종료.
* 오류 발생 시 종료.

메시지 형식과 전송

MCP는 메시지 형식으로 JSON-RPC 2.0을 사용합니다. 주요 메시지 유형은 세 가지입니다:

1. 요청(Requests): 응답을 기대하는 메시지로, method와 선택적 params를 포함합니다.

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "method_name",
  "params": { "key": "value" }
}

2. 응답(Responses): 요청에 대한 응답으로, result(성공 시) 또는 error(실패 시)를 포함합니다.

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": { "key": "value" }
}

3. 알림(Notifications): 응답을 기대하지 않는 1방향 메시지입니다. method와 선택적 params를 포함합니다.

{
  "jsonrpc": "2.0",
  "method": "method_name",
  "params": { "key": "value" }
}

전송 방식

MCP는 여러 전송 메커니즘을 지원합니다. 기본적으로 두 가지 전송이 제공됩니다:

1. 표준 입력/출력 (stdio): 이 전송은 표준 입력과 출력을 사용하며, 로컬 통합 및 명령줄 도구에 적합합니다.

서버 예시:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new McpServer({
  name: "example-server",
  version: "1.0.0"
}, { capabilities: {} });

const transport = new StdioServerTransport();
await server.connect(transport);

클라이언트 예시:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client({
  name: "example-client",
  version: "1.0.0"
}, { capabilities: {} });

const transport = new StdioClientTransport({
  command: "./server", // 서버 실행 파일 경로
  args: ["--option", "value"] // 선택적 인수
});
await client.connect(transport);

2. 서버-전송 이벤트(SSE): 이 전송은 HTTP POST 요청을 클라이언트-서버 통신에 사용하고, 서버-클라이언트 스트리밍을 위해 Server-Sent Events를 사용합니다.

서버 예시:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
import express, { Response } from 'express';

const server = new McpServer({
  name: "example-server",
  version: "1.0.0"
}, { capabilities: {} });

const app = express();
app.use(express.json());

app.get("/sse", async (req, res) => {
  const transport = new SSEServerTransport("/messages", res as Response);
  await server.connect(transport);
  app.locals.transport = transport;
});

app.post("/messages", async (req, res) => {
  const transport = app.locals.transport;
  await transport.handlePostMessage(req, res);
});

app.listen(3000, () => {
  console.log('Server listening on port 3000');
});

클라이언트 예시:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

const client = new Client({
  name: "example-client",
  version: "1.0.0"
}, { capabilities: {} });

const transport = new SSEClientTransport(
  new URL("http://localhost:3000/sse")
);
await client.connect(transport);

커스텀 전송

MCP는 커스텀 전송 구현을 지원합니다. 커스텀 전송은 Transport 인터페이스를 구현해야 합니다.

interface Transport {
  start(): Promise<void>;
  send(message: JSONRPCMessage): Promise<void>;
  close(): Promise<void>;
  onclose?: () => void;
  onerror?: (error: Error) => void;
  onmessage?: (message: JSONRPCMessage) => void;
}

오류 처리

전송 구현은 연결 오류, 메시지 파싱 오류, 프로토콜 오류, 네트워크 시간 초과 및 리소스 정리를 처리해야 합니다. 예시:

class ExampleTransport implements Transport {
  onclose?: () => void;
  onerror?: (error: Error) => void;
  onmessage?: (message: JSONRPCMessage) => void;

  async start() {
    try {
      // 연결 로직
    } catch (error) {
      this.onerror?.(new Error(`Failed to connect: ${error}`));
      throw error;
    }
  }

  async send(message: JSONRPCMessage) {
    try {
      // 전송 로직
    } catch (error) {
      this.onerror?.(new Error(`Failed to send message: ${error}`));
      throw error;
    }
  }
  
  async close(): Promise<void> {
    // 종료 로직
  }
}

3. 첫 번째 MCP 서버 구축하기

이 섹션은 TypeScript SDK를 사용하여 기본 MCP 서버를 만드는 과정을 안내합니다.

개발 환경 설정

1. Node.js와 npm 설치: Node.js(버전 18 이상)와 npm(Node Package Manager)을 시스템에 설치하십시오.
2. 프로젝트 디렉토리 생성:

mkdir my-mcp-server
cd my-mcp-server

3. Node.js 프로젝트 초기화:

npm init -y

4. MCP TypeScript SDK 설치:

npm install @modelcontextprotocol/sdk

5. TypeScript 및 기타 의존성 설치:

npm install typescript zod

6. tsconfig.json 파일 생성:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "outDir": "./build"
  },
  "include": ["src/**/*"]
}

7. src 디렉토리 및 index.ts 파일 생성:

mkdir src
touch src/index.ts

SDK 선택

@modelcontextprotocol/sdk는 TypeScript로 MCP 서버를 구축하는 데 편리한 방법을 제공합니다. 프로토콜 세부 사항을 처리하므로 서버의 기능 구현에 집중할 수 있습니다.

서버 인터페이스 구현

간단한 입력을 반환하는 서버를 만들겠습니다. src/index.ts 파일에 다음 내용을 작성합니다:

#!/usr/bin/env node

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

// MCP 서버 인스턴스 생성
const server = new McpServer({
  name: 'EchoServer',
  version: '1.0.0',
});

// 입력을 그대로 되돌려주는 도구 추가
server.tool(
  'echo',
  { message: z.string() }, // 입력 스키마 정의
  async ({ message }) => ({
    content: [{ type: 'text', text: `Echo: ${message}` }],
  })
);

// 전송 방식 생성 (이번 예시에서는 stdio 사용)
const transport = new StdioServerTransport();

// 서버와 전송 연결
await server.connect(transport);

연결 및 인증 처리

이 간단한 예에서는 StdioServerTransport를 사용하여 연결을 자동으로 처리합니다. 더 복잡한 시나리오에서는 다른 전송 메커니즘을 사용할 때 커스텀 연결 처리 및 인증을 구현해야 할 수 있습니다.

클라이언트 요청 처리

server.tool() 메서드는 서버가 처리할 "echo"라는 도구를 정의합니다. 두 번째 인수는 { message: z.string() }로 zod 라이브러리를 사용하여 도구의 예상 입력 스키마를 정의합니다. 세 번째 인수는 비동기 함수로 입력을 받아 결과를 반환합니다. McpServer는 자동으로 클라이언트의 요청을 적절한 도구로 라우팅합니다.

이 서버를 실행하려면:

1. TypeScript 코드 컴파일:

npx tsc

2. 컴파일된 JavaScript 실행:

node build/index.js

package.json의 scripts 섹션에 다음을 추가하십시오:

"scripts": {
  "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
  "start": "node build/index.js"
}

이제 npm run build와 npm start를 실행할 수 있습니다. ./build/index.js를 실행하고 JSON-RPC 2.0 메시지를 입력하여 테스트할 수 있습니다.

echo 도구로 유효한 JSON-RPC 2.0 메시지 예시:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "echo", "arguments": { "message": "Hello, world!" } }
}