MCP 서버 및 클라이언트 예제(TypeScript)

이 프로젝트는 TypeScript와 @modelcontextprotocol/sdk 사용하여 간단한 MCP(Model Context Protocol) 서버와 독립형 MCP 클라이언트를 만들고 상호 작용하는 방법을 보여줍니다.

설정에는 다음이 포함됩니다.

1. my-mcp-greeter-server : 인사말 관련 도구, 리소스, 프롬프트를 제공하는 MCP 서버입니다.
2. my-mcp-client-script : 서버를 시작하고, 서버에 연결하고, 프로그래밍 방식으로 서버의 기능과 상호 작용하는 간단한 명령줄 클라이언트 스크립트입니다.

이 예에서 클라이언트와 서버 간의 통신은 stdio(표준 입출력) 전송 메커니즘을 사용합니다.

프로세스 개요

이 프로젝트는 다음의 주요 단계를 거쳐 구축되었습니다.

1. 서버 개발 : MCP 서비스 공급자 생성.
2. 클라이언트 개발 : 서버의 서비스를 사용하기 위한 스크립트를 만듭니다.
3. 테스트 및 상호작용 : 서버를 시작하고 통신을 시연하는 클라이언트 스크립트를 실행합니다.
4. (선택 사항) 통합 : VS Code 확장 프로그램과 같은 기존 MCP 클라이언트와 서버를 통합하는 방법을 논의합니다.

필수 조건

시작하기 전에 다음 사항이 설치되어 있는지 확인하세요.

• Node.js (v16 이상 권장)
• npm (일반적으로 Node.js에 포함됨)
• 텍스트 편집기 또는 IDE(VS Code 등)
• npx (일반적으로 npm에 포함됨) - MCP Inspector로 테스트하는 데 유용합니다.

1단계: MCP 서버 구축( my-mcp-greeter-server )

1. 프로젝트 설정 :
   • my-mcp-greeter-server 디렉토리를 생성했습니다.
   • npm 프로젝트를 초기화했습니다: npm init -y .
   • 필수 종속성을 설치했습니다: npm install @modelcontextprotocol/sdk zod .
   • 설치된 개발 종속성: npm install -D typescript @types/node .
   • TypeScript 구성이 초기화되었습니다: npx tsc --init .
   • tsconfig.json 구성했습니다(설정: "module": "Node16" , "target": "ES2022" , "outDir": "./build" , "rootDir": "./src" 등).
   • "type": "module" 포함하도록 package.json 업데이트하고 build / start 스크립트를 추가했습니다.
   • 소스 파일 src/index.ts 생성했습니다.
2. 서버 구현( src/index.ts ) :
   • 필수 모듈( McpServer , StdioServerTransport , z )을 가져왔습니다.
   • 서버 name 과 version 에 대한 상수가 정의되어 있습니다.
   • McpServer 인스턴스화하고 이름, 버전을 전달하고 기능(도구, 리소스, 프롬프트)을 선언합니다.
   • 도구( greet ) 정의 : server.tool() 사용하여 클라이언트가 호출할 수 있는 함수를 생성했습니다. 설명을 포함하고, Zod( name , politeness )를 사용하여 입력 매개변수를 정의하고, 개인화된 인사말 문자열을 반환하는 핸들러를 구현했습니다.
   • 리소스( server-info )를 정의했습니다 . 정적 데이터를 노출하기 위해 server.resource() 사용했습니다. 고유 URI( info://greeter/about )를 제공하고, 서버의 이름과 버전을 반환하는 핸들러를 구현했습니다.
   • 프롬프트( suggest-greeting )를 정의했습니다 . server.prompt() 사용하여 재사용 가능한 상호작용 템플릿을 생성했습니다. 설명을 포함하고 LLM 상호작용을 안내하기 위해 미리 정의된 사용자/어시스턴트 메시지 세트를 반환하는 핸들러를 구현했습니다.
   • Stdio Transport 사용 : 통신 방법으로 StdioServerTransport 인스턴스화했습니다.
   • 연결됨 : await server.connect(transport) 호출하여 서버를 준비합니다.
   • 로깅 : 실행 중에 가시성을 확보하기 위해 console.error 문을 추가했습니다. 특히 프로토콜 메시지에 stdout을 사용하는 stdio 전송에 중요합니다.
   • 유지 : 연결 직후 Node.js 프로세스가 즉시 종료되지 않도록 했습니다.
3. 건축 및 수리 :
   • npm run build 실행하여 build 디렉토리에서 TypeScript를 JavaScript로 컴파일합니다.
   • 미리 정의된 상수를 대신 사용하기로 결정하고 서버 버전에 직접 액세스하는 것과 관련된 TypeScript 오류를 수정했습니다.

2단계: MCP 클라이언트 스크립트 빌드( my-mcp-client-script )

1. 프로젝트 설정 :
   • my-mcp-client-script 라는 별도의 디렉토리를 만들었습니다.
   • npm 프로젝트를 초기화했습니다: npm init -y .
   • 필수 종속성을 설치했습니다: npm install @modelcontextprotocol/sdk .
   • 설치된 개발 종속성: npm install -D typescript @types/node .
   • 서버 프로젝트와 유사하게 tsconfig.json 초기화하고 구성했습니다.
   • "type": "module" 및 build / start 스크립트로 package.json 업데이트했습니다.
   • src/client-script.ts 소스 파일을 생성했습니다.
2. 클라이언트 구현( src/client-script.ts ) :
   • 필수 모듈( Client , StdioClientTransport , path , url )을 가져왔습니다.
   • 결정된 서버 경로 : 서버의 컴파일된 index.js 파일에 대한 경로를 계산했습니다(상대 또는 절대).
   • 구성된 Stdio 전송 : command ( node )과 args (서버 스크립트 경로)를 제공하는 StdioClientTransport 인스턴스화했습니다. 클라이언트 전송이 서버 프로세스를 시작하므로 이 구성이 중요합니다.
   • 인스턴스화된 클라이언트 : Client 인스턴스를 생성하고, ID를 부여하고, 도구와 리소스를 사용하려는 의도를 선언합니다.
   • 연결됨 : await client.connect(transport) 호출하여 서버 프로세스를 시작하고 stdio 스트림을 통해 MCP 연결을 설정했습니다.
   • 서버와 상호 작용 :
     • await client.callTool() 사용하여 greet 도구를 호출했습니다.
     • await client.readResource() 사용하여 server-info 리소스를 읽습니다.
     • await client.getPrompt() 사용하여 suggest-greeting 프롬프트를 가져왔습니다.
   • 기록된 결과 : console.log 사용하여 서버로부터 수신된 응답을 표시합니다.
   • 닫힌 연결 : finally 블록에서 await client.close() 사용하여 연결을 깔끔하게 닫고 서버 프로세스를 종료합니다.

3단계: 구축 및 실행

1. 두 프로젝트 모두 빌드 :
   • cd my-mcp-greeter-server && npm run build
   • cd ../my-mcp-client-script && npm run build
2. 클라이언트 실행 :
   • cd my-mcp-client-script
   • npm run start (또는 node build/client-script.js )
   • 클라이언트( console.log )와 서버( console.error )에서 삽입된 출력을 관찰하여 성공적인 통신과 도구/리소스/프롬프트의 실행을 확인했습니다.

역할 설명

• 서버( GreeterServer ) :
  • 서비스 제공 : 특정 기능(인사말 도구, 서버 정보, 프롬프트 템플릿)을 제공합니다.
  • 패시브 리스너(stdio) : 클라이언트가 표준 스트림을 통해 연결할 때까지 기다립니다.
  • 로직 실행 : 클라이언트의 요청에 따라 도구/리소스/프롬프트와 연관된 코드를 실행합니다.
  • 결과 전송 : MCP 사양에 따라 결과를 형식화하여 클라이언트로 다시 전송합니다.
• 클라이언트( client-script.ts ) :
  • 서비스 사용 : 서버가 제공하는 기능을 사용합니다.
  • 개시자(stdio에서) : 서버 프로세스를 시작하고 연결을 설정합니다.
  • 요청 보내기 : 어떤 도구를 호출할지, 어떤 리소스를 읽을지, 어떤 프롬프트를 받을지 결정하고 적절한 MCP 요청을 보냅니다.
  • 결과 수신 : 서버에서 보낸 응답을 처리합니다.
  • 제어 흐름 : 상호작용의 순서를 관리하고 연결을 닫을 시기를 결정합니다.

대화형으로 서버 테스트

클라이언트 스크립트가 프로그래밍 방식의 상호 작용을 테스트하는 동안 MCP 검사기를 사용하여 서버의 기능을 개별적으로 테스트할 수 있습니다.

지엑스피1