Loads environment variables from .env files for server configuration, enabling customization of transport types, HTTP settings, authentication, and logging options.
Provides HTTP request utilities through the 'serviceRequest' function in httpUtils.ts, supporting authenticated API requests with OAuth2 or API key authentication, retries, and response validation.
Implements the HTTP transport layer using Express to handle POST requests to the /mcp endpoint, process JSON-RPC messages, and support stateless request handling.
공식 TypeScript SDK를 사용하여 모델 컨텍스트 프로토콜(MCP) 서버를 구현하기 위한 템플릿 프로젝트인 MCP-SERVER-TEMPLATE 에 오신 것을 환영합니다. 이 프로젝트는 HTTP 및 표준 I/O(stdio)와 같은 다양한 전송 메커니즘을 지원하여 상태 비저장 및 상태 저장 MCP 서버를 구축하기 위한 기반을 제공합니다.
이 프로젝트 MCP-SERVER-TEMPLATE 는 공식 SDK를 사용하여 모델 컨텍스트 프로토콜(MCP) 서버를 구축하기 위한 TypeScript 기반 시작 템플릿입니다. 이 서버는 사용자 쿼리와 도구 실행 간의 인터페이스 역할을 하여 AI 어시스턴트와 외부 시스템이 도구를 동적으로 호출하고, 프롬프트를 해석하고, 리소스를 모듈화되고 확장 가능한 방식으로 관리할 수 있도록 합니다.
execute 함수.env 및 런타임 구성 파일을 통해 쉽게 조정 가능:이 템플릿은 다음과 같은 경우에 적합합니다.
LLM 툴체인을 프로토타입으로 제작하든, 독점 시스템과 통합하든, 확장 가능한 프로덕션 MCP 어시스턴트 백엔드를 준비하든, 이 프로젝트는 확장이 가능하고 철저히 구성된 솔루션을 제공합니다.
package.json 에 정의된 대로 프로덕션 종속성(예: @modelcontextprotocol/sdk , express , axios )과 개발 종속성(예: typescript , ts-node , jest )이 모두 설치됩니다.@modelcontextprotocol/sdk 패키지(버전 ^1.10.1 )가 설치되어 있는지 확인하세요.이 프로젝트는 src/core/config/ 에 있는 환경 변수와 두 개의 주요 파일을 통해 관리되는 구성 시스템을 사용합니다. 설정은 ConfigService 와 runtimeConfig 에 정의되어 있어 전송 유형, 로깅 및 외부 API 통합을 사용자 지정할 수 있습니다.
runtimeConfig.ts 에서 dotenv 통해 로드됨):TRANSPORT_TYPE : 전송 메커니즘을 설정합니다( 'http' 또는 'stdio' , 기본값: 'stdio' ).HTTP_PORT : HTTP 서버의 포트(기본값: 3000 ).HTTP_HOST : HTTP 서버의 호스트(기본값: localhost ).SESSION_SUPPORT : 세션 지원을 활성화/비활성화합니다(기본값: 'true' ).LOG_LEVEL : 로깅 수준(예: 'info' , 'debug' , 기본값: 'info' ).MCP_INSPECTOR_PORT : MCP 검사기용 포트(기본값: 6274 )..env 파일에서 환경 변수를 설정합니다.
서버는 src/index.ts 진입점을 통해 시작되며, 종속성 주입과 구성 설정을 사용하여 초기화 및 시작 프로세스를 조율합니다.
index.ts``dotenv 사용하여 환경 변수를 로드하여 구성 설정(예: TRANSPORT_TYPE , HTTP_PORT )이 사용 가능한지 확인합니다.createDependencies 사용하여 logger 및 ConfigService 와 같은 공유 종속성을 설정합니다.HttpTransport 또는 StdioTransport )은 TRANSPORT_TYPE 설정에 따라 runtimeConfig 통해 구성됩니다.MCPServer 인스턴스를 생성합니다.tsc 실행되어 컴파일된 JavaScript 파일이 있는 dist/ 폴더가 생성됩니다.node dist/index.js 실행합니다.http 의 경우, 서버는 http://localhost:3000/mcp 에서 수신합니다(포트와 호스트는 HTTP_PORT 및 HTTP_HOST 통해 구성 가능).stdio 의 경우, 서버는 콘솔에서 읽고 씁니다.ts-node 사용하여 TypeScript로 서버를 직접 실행합니다.ts-node src/index.ts 실행되어 빌드 단계 없이 더 빠른 반복이 가능합니다.runtimeConfig 설정이 올바르게 설정되었는지 확인하세요.LOG_LEVEL 로 제어)를 확인하세요.이 프로젝트에는 자동화된 테스트와 MCP 검사기를 사용하여 서버를 테스트하고, 동작을 디버깅하고, 기능을 검증하는 여러 스크립트가 포함되어 있습니다.
Jest를 사용하여 단위 테스트를 실행하여 개별 구성 요소의 기능을 확인합니다.
이 명령은 jest 실행하여 프로젝트에 정의된 모든 테스트(예: 테스트 도구, 유틸리티 또는 서버 로직)를 실행합니다. TypeScript 지원을 위해 테스트 파일에 Jest와 ts-jest 설정되어 있는지 확인하세요.
MCP 서버의 기본 기능을 검증하기 위해 HTTP 전송에 대한 테스트 스크립트가 제공됩니다.
src/scripts/testHttpTransport.js )tools/list 요청을 서버로 전송하고 응답을 검증하여 HTTP 전송을 테스트합니다.axios 사용하여 HTTP POST 요청을 서버로 보냅니다.method: 'tools/list' , id: 1 및 적절한 헤더를 사용하여 http://localhost:3000/mcp 에 JSON-RPC 2.0 요청을 보냅니다.jsonrpc: '2.0' )을 준수합니다.id 요청과 일치합니다( id: 1 ).tools 키가 포함된 result 필드가 포함되어 있습니다.TRANSPORT_TYPE``'http' 로 설정하여 실행 중인지 확인하세요.ts-node src/scripts/testHttpTransport.ts 실행합니다.하나의 명령으로 서버를 시작하고 HTTP 테스트를 실행하려면:
이렇게 하면 npm run start & npm run test:http 실행되어 백그라운드에서 서버를 시작하고 즉시 HTTP 테스트 스크립트를 실행합니다.
http://localhost:3000/mcp 에서 실행된다고 가정합니다. HTTP_PORT 또는 HTTP_HOST 다른 경우 스크립트에서 endpoint 조정하세요.CalculatorTool 과 같은 도구가 tools/list 응답에서 표시되도록 등록되어 있는지 확인하세요.MCP Inspector는 MCP 서버를 디버깅하고 모니터링하기 위한 강력한 도구로, 서버 상태와 상호 작용을 검사할 수 있는 웹 UI를 제공합니다.
src/scripts/mcpInspectorScript.ts )child_process 사용하여 mcp-inspector 프로세스를 생성하고 브라우저를 여는 명령을 실행합니다.axios 사용하여 MCP Inspector 웹 UI에 접속할 수 있는지 확인합니다.createDependencies() 를 통해 종속성 주입을 활용하여 포트 구성을 위한 ConfigService 접근합니다.npx mcp-inspector node dist/index.js 사용하여 mcp-inspector 프로세스를 생성하고 콘솔 출력을 위해 stdio를 상속합니다.waitUntilInspectorIsReady 구현합니다(기본 포트: 6274 , MCP_INSPECTOR_PORT 통해 구성 가능). 재시도(20회 시도, 500ms 지연)가 가능합니다.openstartxdg-openhttp://localhost:6274 (또는 구성된 포트)http://localhost:6277npm run build 실행하여 dist/index.js 생성합니다).ts-node src/scripts/start-mcp-inspector.ts 실행됩니다.하나의 명령으로 프로젝트를 빌드하고 MCP 검사기를 실행하려면 다음을 수행합니다.
이렇게 하면 npm run build && npm run mcp:inspector 실행되어 검사기를 시작하기 전에 프로젝트가 컴파일되었는지 확인합니다.
MCP_INSPECTOR_PORT 다른 서비스에서 사용되고 있지 않은지 확인하세요.이 프로젝트에서는 Prettier를 사용하여 모든 파일에서 일관된 코드 형식을 유지합니다.
프로젝트의 모든 파일을 포맷하려면:
이렇게 하면 prettier --write . 가 실행되어 지원되는 모든 파일(예: .ts , .js , .json )을 자동으로 포맷합니다.
모든 파일이 Prettier 서식 규칙을 준수하는지 확인하려면:
이렇게 하면 prettier --check . 실행되어 서식 규칙을 수정하지 않고도 해당 규칙에 맞지 않는 파일을 보고합니다.
src/core/config/configService.ts : 서버 구성을 관리하는 클래스인 ConfigService 구현합니다. 전송 유형, HTTP 서버 설정, 로깅 수준, API URL(예: MealDB), 인증 자격 증명 및 MCP 검사기 포트에 대한 기본값을 사용하여 환경 변수에서 설정을 로드합니다.runtimeConfig.ts : dotenv 사용하여 환경 변수를 로드하는 런타임 구성을 정의합니다. 전송 구성( transportType , port)과 인증 전략( authStrategy , tokenSecret , username , password )을 설정합니다.src/core/dependencies/dependencies.ts : Dependencies 인터페이스를 사용하여 종속성 주입을 구현하고, Winston을 사용하는 logger 와 ConfigService 인스턴스를 제공합니다. createDependencies 함수는 transportType ( stdio 의 경우 stderr, 기타의 경우 stdout, 그리고 파일 로그의 경우 combined.log )을 기반으로 로깅 전송을 동적으로 구성하고, 전역적으로 사용할 수 있도록 싱글턴 logger 내보냅니다.src/core/server/transports/http/server.ts : Express를 사용하는 상태 비저장 HTTP 전송인 HttpTransport 구현합니다. POST /mcp 요청을 처리하고, 선택적 Bearer 토큰 인증을 사용하여 JSON-RPC 메시지를 처리하고, 응답을 ResponseMap 에 저장하고, 비동기 응답 전송을 지원합니다. 로깅 및 구성을 위해 종속성 주입된 Dependencies 사용합니다.stdio/server.ts : SDK의 StdioServerTransport 사용하는 전송 방식인 StdioTransport StdioTransport 구현합니다. stdin/stdout 통신을 관리하고, 전송을 시작 및 종료하며, 종속성이 주입된 Dependencies 통해 오류 로깅과 함께 메시지 전송을 처리합니다.baseTransport.ts : SDK의 Transport 인터페이스를 확장하여 BaseTransport 인터페이스와 추상 AbstractTransport 클래스를 정의합니다. 전송 구현을 위한 메서드( start , send , close , isRunning )와 이벤트 핸들러( onmessage , onerror , onclose )를 지정하여 HttpTransport 와 StdioTransport 에 대한 공통 계약을 제공합니다.transportFactory.ts : TransportConfig 유형(예: 'http' 또는 'stdio' )을 기반으로 HttpTransport 또는 StdioTransport 인스턴스를 생성하는 정적 클래스인 TransportFactory 구현합니다. Dependencies 사용한 종속성 주입을 사용하여 로깅 및 구성을 제공하며, 지원되지 않는 전송 유형에 대해서는 오류를 발생시킵니다.mcpServer.ts : MCP SDK의 Server 전송( HttpTransport 또는 StdioTransport )과 통합하는 핵심 서버 클래스인 MCPServer 구현합니다. 서버를 초기화하고, ToolRegistry 사용하여 RequestHandler 설정하고, 전송을 연결하고, 로깅을 위해 종속성이 주입된 Dependencies 사용하여 메시지 전달, 오류 및 응답을 처리합니다.requestHandler.ts : MCP SDK를 사용하여 tools/list 및 tools/call 요청에 대한 처리기를 등록하는 RequestHandler 구현합니다. 사용 가능한 도구를 나열하고 Zod를 통해 검증된 인수를 사용하여 도구 호출을 실행하며, 인증 토큰을 지원하고 유효하지 않은 도구( ToolNotFoundError ) 또는 인수( ValidationError )에 대한 오류를 발생시킵니다. 로깅에는 종속성이 주입된 Dependencies 사용합니다.src/core/toolManagement/toolFactory.ts : Dependencies 사용한 의존성 주입을 통해 도구(예: calculatorTool )의 인스턴스를 생성하는 클래스인 ToolFactory 구현합니다. 제네릭 ToolConstructor 타입을 정의하고 로깅을 통해 인스턴스 생성 오류를 처리합니다.toolRegistry.ts : 도구 등록 및 검색을 관리하는 클래스인 ToolRegistry 구현합니다. ToolFactory 사용하여 toolClasses 에서 도구를 인스턴스화하고, 이를 Map 에 저장하며, 도구의 메타데이터(이름, 설명, 입력 스키마)를 사용하여 도구를 등록, 가져오기 및 나열하는 메서드를 제공합니다. 종속성이 주입된 Dependencies 통해 로딩 상태 및 오류를 기록합니다.errors.ts : 도구 관리를 위한 사용자 정의 오류 클래스를 정의합니다. 여기에는 요청된 도구가 등록되지 않았을 때 발생하는 ToolNotFoundError 와 Zod를 통한 도구 인수의 유효성 검사가 실패했을 때 발생하는 ValidationError 가 포함됩니다.types.ts : 전송 및 인증 구성을 위한 TypeScript 유형을 정의합니다. TransportType ( 'stdio' , 'sse' , 'http' ), TransportConfig (SSE 또는 HTTP 및 인증 옵션 포함), SSETransportConfig (포트, CORS, 인증), HttpStreamTransportConfig (포트, 응답 모드, CORS, 세션, 재개 가능성, 인증), AuthConfig (전략, 자격 증명)를 포함합니다.src/prompts/ : 프롬프트 템플릿을 위한 디렉토리(현재 비어 있으며, 향후 구현을 위해 예약됨).src/resources/ : 리소스 관리를 위한 디렉토리(현재 비어 있으며, 향후 구현을 위해 예약됨).src/scripts/testHttpTransport.js : tools/list 요청을 보내고 응답을 검증하여 기본 기능을 검증하는 HTTP 전송을 위한 테스트 스크립트입니다.mcpInspectorScript.ts : MCP Inspector를 실행하고, 웹 UI가 준비될 때까지 기다린 후, MCP 서버 디버깅을 위해 브라우저에서 여는 스크립트입니다. 종속성 주입을 사용하여 포트 구성을 위한 ConfigService 에 접근하고, 플랫폼별 브라우저 열기를 처리합니다.src/tools/types/ITool.ts : 도구에 대한 ITool 인터페이스를 정의하며, name , description , schema (Zod 유형), jsonSchema , 그리고 JSON-RPC CallToolRequest 처리를 위한 execute 메서드를 지정합니다. 도구 구현에 대한 Dependencies 내보냅니다.baseTool.ts : 보일러플레이트를 줄이고 Dependencies 사용하여 종속성 주입을 처리하고 zod-to-json-schema 사용하여 Zod 스키마를 JSON 스키마로 자동 변환하여 내성, 문서화 및 UI 생성을 수행하는 추상 BaseTool 클래스를 구현합니다.index.ts : ToolRegistry 에서 동적으로 로딩할 수 있도록 도구 생성자(예: CalculatorTool ) 배열로 toolClasses 내보내므로 새 도구로 쉽게 확장할 수 있습니다.calculatorTool.ts : Zod를 통한 입력 검증, 오류 처리(예: HttpError 사용한 0으로 나누기) 및 종속성 주입 Dependencies 통한 로깅을 통해 기본 산술 연산( add , subtract , multiply , divide )을 수행하는 구체적인 도구인 CalculatorTool 구현합니다.utils/httpUtils.ts : 인증된 HTTP 요청(OAuth2 또는 API 키)을 생성하고 재시도 및 시간 초과 처리를 위한 serviceRequest , OAuth2 토큰을 가져오고 캐싱하는 getAuthToken , 쿼리 문자열을 생성하는 buildQueryString , 응답 검증을 위한 validateResponse 등 HTTP 작업을 위한 유틸리티 함수를 제공합니다. 구성을 위해 ConfigService 와 통합됩니다.index.ts : 도구 및 기타 구성 요소에서 사용할 유틸리티 함수를 내보냅니다.src/index.ts : MCP 서버를 시작하는 진입점입니다. dotenv 사용하여 환경 변수를 로드하고, createDependencies 사용하여 종속성을 초기화하고, runtimeConfig 의 전송 방식을 사용하여 MCPServer 인스턴스를 생성하고, 서버를 비동기적으로 시작하며, 로깅 및 종료를 통해 치명적인 오류를 처리합니다.MCPServer 설정에서 핸들러가 등록되고 기능이 설정되었는지 확인합니다( RequestHandler 통해).MCPServer 재사용하는 것을 고려하되, 철저하게 테스트하십시오..env 파일에 올바르게 설정되었는지 또는 프로세스에 직접 전달되었는지 확인하세요.ConfigService 로그를 확인하세요.LOG_LEVEL 환경 변수가 예상 수준(예: 'info' , 'debug' )과 일치하는지 확인합니다.stdio 전송의 경우, 로그가 의도한 대로 stderr로 전송되는지 확인하세요. 파일 기반 로그의 경우 combined.log 확인하세요.HttpTransport 의 경우 포트를 사용할 수 있는지, 충돌하는 서비스가 실행되고 있지 않은지 확인하세요.StdioTransport 의 경우, 메시지가 처리되지 않으면 stdin/stdout의 가용성을 확인하세요.TransportFactory 실패하면 TRANSPORT_TYPE 구성에서 지원되는 유형( 'http' 또는 'stdio' )과 일치하는지 확인합니다.tools/list 또는 tools/call 요청이 실패하면 등록된 도구에 대한 ToolRegistry 확인하세요.ValidationError 방지하기 위해 CallToolRequestSchema 의 스키마에 대해 도구 인수를 검증합니다.src/tools/index.ts 에 있는 toolClasses 에 유효한 도구 구현이 포함되어 있는지 확인하세요.ToolFactory 로그에서 인스턴스화 오류를 확인하고 Dependencies 제대로 주입되었는지 확인하세요.MCP_INSPECTOR_PORT (기본값: 6274 )가 사용 중이 아닌지 확인하세요.npm run build 실행하여 dist/index.js 가 있는지 확인하세요.serviceRequest 실패하면 ConfigService 에서 authType , authEndpoint , clientId , clientSecret 또는 apiKey 설정을 확인합니다.validateResponse 로 응답 스키마를 검증합니다.testHttpTransport.js 스크립트가 실패하면 서버가 TRANSPORT_TYPE='http' 로 실행 중이고 http://localhost:3000/mcp 에서 수신 대기 중인지 확인하세요.endpoint 와 일치하는지 확인합니다( HTTP_PORT 또는 HTTP_HOST 가 다른 경우 조정).ToolRegistry 에 등록된 도구가 있는지 확인하세요. tools 배열이 비어 있으면 도구 로딩 문제가 있을 수 있습니다.npm test 실패하면 TypeScript 지원을 위해 ts-jest 로 Jest가 올바르게 구성되었는지 확인하고 테스트 파일이 있는지 확인하세요.npm run mcp:inspector 또는 npm run mcp:dev 실패하면 @modelcontextprotocol/inspector 설치되어 있고 서버가 컴파일되었는지( dist/index.js 있는지) 확인하세요.npm run format:check 문제가 보고되면 npm run format 실행하여 자동으로 서식을 수정하거나 Prettier의 규칙에 맞게 파일을 수동으로 조정하세요.GitHub 저장소에 이슈나 풀 리퀘스트를 자유롭게 제출하세요. 서버 구현 개선, 새로운 기능 추가, 성능 최적화에 대한 기여를 환영합니다!
이 프로젝트는 ISC 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.
@modelcontextprotocol/sdk 사용하여 빌드됨This server cannot be installed
여러 전송 방법을 지원하는 모듈형 아키텍처를 통해 AI 어시스턴트가 도구를 동적으로 호출하고, 프롬프트를 해석하고, 리소스를 관리할 수 있도록 하는 모델 컨텍스트 프로토콜 서버를 구축하기 위한 TypeScript 기반 스타터 템플릿입니다.