MCP 보일러플레이트

MCP 보일러플레이트: 모델 컨텍스트 프로토콜 서버

이 서버는 글로벌 보일러플레이트 용도로 모델 컨텍스트 프로토콜(MCP)을 구현합니다. 모델 컨텍스트 프로토콜을 사용하여 AI 모델을 다양한 데이터 소스 및 도구에 연결하는 표준화된 방식을 제공합니다.

특징

MCP Server-Sent Events(SSE) 전송을 구현합니다.
맞춤형 MCP 서버를 구축하기 위한 견고한 구조를 제공합니다.
적절한 유형 정의가 포함된 예제 도구가 포함되어 있습니다.
API 키를 통한 보안 인증
다양한 심각도 수준의 로깅 기능
여러 클라이언트 연결에 대한 세션 관리
SIGINT 및 SIGTERM 신호에 대한 우아한 종료 처리

도구

현재 서버에는 다음과 같은 예제 도구가 포함되어 있습니다.

calculator : 기본적인 산술 연산(덧셈, 뺄셈, 곱셈, 나눗셈)을 수행합니다.

사용자 정의 도구를 추가하는 방법에 대한 자세한 내용은 보일러플레이트 확장 섹션을 확인하세요.

구성

서버 설정은 src/config.ts 에 중앙 집중화되어 있습니다. 이를 통해 여러 파일을 수정하지 않고도 설정을 쉽게 조정할 수 있습니다.

지엑스피1

SSE 시간 초과 문제 해결

MCP 연결에서 "본문 시간 초과 오류"가 발생하는 경우:

keepaliveInterval 줄여 더 자주 keepalive 메시지를 보냅니다(예: 15000ms).
추가 연결 안정성을 위해 usePingEvents 활성화되어 있는지 확인하세요.
프록시 서버를 사용하는 경우 프록시 시간 초과가 있는지 확인하세요.

설정

종속성 설치:

npm install

다음 변수를 사용하여 .env 파일을 만듭니다.

PORT=4005
API_KEY=your_api_key

프로젝트를 빌드하세요:

npm run build

서버를 시작합니다:

npm run start:sse

개발

# Start in development mode with hot reloading
npm run start

# Start with PM2 for production
npm run start:pm2

# Development mode with nodemon
npm run dev

API 엔드포인트

/health : 서버 상태 및 버전을 반환하는 상태 확인 엔드포인트
/sse : MCP 연결을 설정하기 위한 SSE 엔드포인트(API 키 필요)
/messages : 클라이언트-서버 통신을 위한 메시지 처리 엔드포인트

MCP 구성

이 서버에 MCP를 연결하려면 다음 구성을 추가하세요.

{
  "mcpServers": {
    "mcp-server": {
      "url": "http://localhost:4005/sse?API_KEY={{your_api_key_here}}"
    }
  }
}

보일러플레이트 확장

사용자 정의 도구 추가

MCP 서버에 새 도구를 추가하려면 다음 단계를 따르세요.

도구 핸들러를 생성하세요 .
- src/tools.ts 파일에 새 도구 핸들러를 추가하거나 src/tools 디렉토리에 새 파일을 만듭니다.
- 도구는 ToolHandler 인터페이스를 따라야 합니다.
도구 구성 :
- src/tools.ts 의 toolConfigs 배열에 도구 구성을 추가합니다.
- 도구의 이름, 설명, 입력 스키마 및 핸들러를 정의합니다.
도구 내보내기 및 등록 :
- 별도의 파일을 생성한 경우 핸들러를 내보내고 src/tools.ts 로 가져옵니다.
- 도구가 toolConfigs 배열에 제대로 등록되었는지 확인하세요.

예:

// In src/tools.ts (adding directly to the toolConfigs array)
{
  name: "myTool",
  description: "My tool description",
  inputSchema: {
    type: "object" as const,
    properties: {},
    required: [],
  },
  handler: async () => {
    return createSuccessResult({ result: "Tool result" });
  },
}

오류 처리

서버는 포괄적인 오류 처리를 구현합니다.

모든 작업은 try/catch 블록으로 묶입니다.
매개변수 및 입력에 대한 적절한 검증
더 나은 디버깅을 위한 적절한 오류 메시지
표준화된 오류 및 성공 응답을 생성하기 위한 도우미 기능

보안 고려 사항

모든 연결에 대한 API 키 인증
모든 매개변수에 대한 유형 검증
하드코딩된 민감한 정보 없음
정보 유출을 방지하기 위한 적절한 오류 처리
세션 기반 전송 관리

MCP 프로토콜 기능

이 보일러플레이트는 핵심 MCP 기능을 지원합니다.

도구: 적절한 매개변수 검증을 통해 도구를 나열하고 호출합니다.
로깅: 다양한 심각도 수준(디버그, 정보, 알림, 경고, 오류, 중요, 경고, 긴급)
서버 구성: 이름, 버전 및 기능

세션 관리

서버는 다음을 통해 클라이언트 세션을 관리합니다.

각 클라이언트 연결에 대한 고유 세션 ID
세션 ID를 통한 활성 전송 추적
연결이 끊긴 세션의 자동 정리
연결 상태 추적

추가 자료

특허

이 프로젝트는 MIT 라이선스 에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

MCP Boilerplate

Integrations