MCP TypeScript Starter

MCP TypeScript Starter는 TypeScript로 Model Context Protocol 서버를 구축하기 위한 프로덕션을 고려한 기반입니다. 하나의 타입이 지정된 예제 도구, stdio 및 Streamable HTTP 전송, 엄격한 검증, 테스트, 강화된 컨테이너, 그리고 자동화된 GHCR 게시를 포함합니다.

이 저장소를 클론하고 예제 도메인을 교체한 다음 실제 MCP 서버에 필요한 인프라를 유지하세요.

Navigation

• 이 스타터 사용하기

• 소개

• 기능

• MCP 도구

• 기술 스택

• 설치

• 구성

• MCP 클라이언트 설정

• 스타터 사용자 지정

• 검증

• 제한 사항

• 기여

• 라이선스

Related MCP server: mcp-server-http-streamable

이 스타터 사용하기

GitHub에서 Use this template을 클릭하여 독립된 Git 히스토리를 가진 새 MCP 서버를 만드세요. 생성 후에는 스타터 사용자 지정에 따라 예제 도구를 교체하고 프로젝트 식별 정보를 업데이트하세요.

풀 리퀘스트를 통해 개선 사항을 다시 기여하려면 이 저장소를 포크하세요. 변경 사항을 제출하기 전에 기여를 참조하세요.

이 스타터가 도움이 되었다면 저장소에 스타를 남기는 것을 고려해 주세요. 다른 TypeScript 개발자들이 프로젝트를 발견하는 데 도움이 됩니다.

소개

이 스타터는 검증된 MCP 도구 정의에서 클라이언트가 볼 수 있는 구조화된 결과까지의 전체 경로를 보여줍니다. 서버는 사용자 지정 서버 프레임워크 대신 최신 모듈식 MCP TypeScript SDK와 Hono의 웹 표준 HTTP 모델을 사용합니다.

기본 stdio 전송은 서버를 자식 프로세스로 실행하는 로컬 클라이언트를 위한 것입니다. Streamable HTTP는 상태가 없으며 각 요청에 대해 새 MCP 서버를 만들므로 공유 세션 저장소 없이 복제할 수 있습니다.

예제는 제한된 인메모리 작업을 수행합니다. 원격 측정, 애플리케이션 데이터베이스, 영구 저장소, 인증 또는 외부 서비스 의존성은 없습니다.

기능

• 엄격한 Zod 입력 및 출력 스키마로 도구를 등록합니다.

• 사람이 읽을 수 있는 콘텐츠와 타입이 지정된 구조화된 콘텐츠를 모두 반환합니다.

• 정확한 MCP 안전 주석을 포함합니다.

• stdio 및 상태 없는 Streamable HTTP를 지원합니다.

• DNS 리바인딩에 대비한 Host 및 Origin 검증과 함께 Hono를 사용합니다.

• 기본적으로 HTTP를 루프백에 바인딩하고 다른 인터페이스에는 허용 목록을 요구합니다.

• 도구 입력과 HTTP 요청 본문을 제한합니다.

• stdio 모드에서 stdout을 MCP 프로토콜 메시지 전용으로 유지합니다.

• SIGINT 및 SIGTERM을 멱등성 있는 정상 종료로 처리합니다.

• 읽기 전용 루트 파일시스템을 지원하는 비루트 컨테이너로 실행됩니다.

• 구성, stdio 연결, MCP 동작, Hono 라우트 및 실제 HTTP 트래픽을 테스트합니다.

• 품질 검사를 통과한 경우에만 다중 아키텍처 이미지를 게시합니다.

MCP 도구

echo

검증된 메시지와 선택적 문자열 메타데이터를 그대로 반환합니다. 비즈니스 도메인을 만들지 않고도 저장소가 MCP 스키마, 등록, 주석 및 결과를 가르칠 수 있도록 의도적으로 단순하게 유지됩니다.

예제 입력:

{
  "message": "Hello, MCP!",
  "metadata": {
    "source": "example-client"
  }
}

예제 구조화된 출력:

{
  "message": "Hello, MCP!",
  "metadata": {
    "source": "example-client"
  }
}

메시지는 10,000자로 제한됩니다. 메타데이터는 최대 20개 항목을 허용하며 키는 64자, 값은 1,024자로 제한됩니다.

기술 스택

• Node.js 24+

• 엄격한 프로젝트 규칙을 적용하는 TypeScript

• Model Context Protocol TypeScript SDK 2

• Hono

• Zod

• Vitest

• pnpm

• Docker

설치

사전 요구 사항

• 로컬 개발을 위한 Node.js 24+ 및 pnpm 11.

• 컨테이너 배포를 위한 Docker 및 Docker Compose.

Docker Compose

권장되는 HTTP 배포는 게시된 다중 아키텍처 이미지를 사용합니다:

ghcr.io/lukegskw/mcp-typescript-starter:latest

Compose 예제를 다운로드하고 클라이언트가 사용할 호스트 이름을 제공하세요:

curl -O https://raw.githubusercontent.com/lukegskw/mcp-typescript-starter/main/compose.example.yaml
export MCP_ALLOWED_HOSTS='mcp.example.internal'
docker compose -f compose.example.yaml up -d

Streamable HTTP 및 상태 확인 엔드포인트는 다음 주소에서 사용할 수 있습니다:

http://<host>:3000/mcp
http://<host>:3000/healthz

다른 호스트 포트를 게시하려면 MCP_PUBLISHED_PORT를 설정하세요. 애플리케이션은 컨테이너 내부에서 계속 포트 3000을 사용합니다.

latest 태그는 기본 브랜치의 최신 성공 빌드를 따릅니다. 통제된 배포와 롤백을 위해 버전 또는 변경 불가능한 sha-* 태그를 사용하세요.

Docker run

docker run -d \
  --name mcp-typescript-starter \
  --restart unless-stopped \
  --read-only \
  --user 10001:10001 \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /tmp:size=16m,mode=1777 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_ALLOWED_HOSTS=127.0.0.1,localhost,mcp.example.internal \
  -p 3000:3000 \
  ghcr.io/lukegskw/mcp-typescript-starter:latest

소스에서 컨테이너 빌드

git clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
docker buildx build --load -t mcp-typescript-starter:local .

로컬 Node.js 설치

git clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
pnpm install --frozen-lockfile
pnpm build
pnpm start -- --transport stdio

로컬 Streamable HTTP 개발의 경우:

MCP_TRANSPORT=streamable-http pnpm dev

구성

--transport 명령줄 옵션은 MCP_TRANSPORT를 재정의합니다. MCP_ALLOWED_HOSTS에는 URL이 아닌 호스트 이름이 포함됩니다. 합법적인 클라이언트와 상태 확인이 사용하는 모든 호스트 이름을 포함하세요.

서버 예제 구성에는 비밀이 없습니다. 도메인 자격 증명은 MCP 도구 인수나 커밋된 파일이 아닌 배포 플랫폼 또는 환경을 통해 추가하세요.

MCP 클라이언트 설정

Streamable HTTP 서버 정의를 허용하는 클라이언트의 경우:

mcp_servers:
  starter:
    url: http://127.0.0.1:3000/mcp

로컬 stdio 서버를 실행하는 클라이언트의 경우:

{
  "mcpServers": {
    "starter": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-typescript-starter/dist/main.js",
        "--transport",
        "stdio"
      ]
    }
  }
}

로컬 클라이언트가 stdio를 통해 컨테이너를 실행하게 하려면 docker run -i --rm을 사용하고 이미지 이름 뒤에 --transport stdio를 전달하세요. 클라이언트가 표준 입력과 출력을 통해 MCP 메시지를 교환할 수 있도록 -i가 필요합니다.

클라이언트 구성 형식은 서로 다릅니다. 정확한 스키마는 클라이언트 문서를 참조하고 서버 정의를 변경한 후 클라이언트를 다시 시작하거나 다시 로드하세요.

스타터 사용자 지정

주요 확장 지점은 의도적으로 직접적입니다:

1. src/tools/echo.ts를 복사하거나 교체하세요.

2. 핸들러를 작성하기 전에 엄격한 입력 및 출력 스키마를 정의하세요.

3. src/server.ts에 도구를 등록하세요.

4. MCP 동작 테스트와 도메인 통합 테스트를 추가하세요.

5. 패키지 이름, 서버 식별 정보, 이미지 참조 및 README 내용을 교체하세요.

도구 모듈이 자체 스키마와 핸들러를 담당하도록 유지하세요. 전송 모듈은 도메인 도구와 독립적으로 유지하세요. 실제 동작에 필요한 경우에만 서비스나 영속성을 도입하세요.

검증

전체 저장소 테스트 스위트를 실행하세요:

pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm test:integration
pnpm build

컨테이너 변경의 경우:

docker buildx build --load -t mcp-typescript-starter:test .

마지막으로 MCP 클라이언트를 연결하고 echo가 나열되며 텍스트와 구조화된 콘텐츠를 모두 반환하는지 확인하세요. HTTP 모드에서는 /healthz가 {"status":"ok"}를 보고하는지 확인하세요.

제한 사항

• 예제는 하나의 도구만 노출하며 리소스나 프롬프트는 없습니다.

• Streamable HTTP에는 인증이 없습니다. 루프백, 신뢰할 수 있는 LAN, VPN, 프라이빗 컨테이너 네트워크 또는 인증된 리버스 프록시로 제한하세요.

• Host 및 Origin 허용 목록은 특정 유형의 DNS 리바인딩 공격을 방지하지만 호출자를 인증하지는 않습니다.

• HTTP 서버는 상태가 없으며 공유 영속성이나 분산 조정을 포함하지 않습니다.

• 속도 제한, 추적, 메트릭 및 도메인별 로깅은 포함되지 않습니다.

• 이 저장소는 게시된 npm 라이브러리가 아닌 소스 스타터입니다.

HTTP 전송을 노출하거나 보안 문제를 보고하기 전에 SECURITY.md를 검토하세요.

기여

기여는 환영합니다. 풀 리퀘스트를 열기 전에:

pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
docker buildx build --load -t mcp-typescript-starter:test .

변경 사항은 엄격한 타입 지정, 제한된 검증, 구조화된 MCP 결과, stdout 프로토콜 순수성, 안전한 HTTP 기본값, 결정적 테스트 및 사용자에게 보이는 동작에 대한 문서를 유지해야 합니다. 구체적인 사용 사례 없이 추상화를 추가하지 마세요.

라이선스

MIT. LICENSE를 참조하세요.