nitrocloudofficial/nitrostack 딥다이브
— MCP 서버를 위한 "NestJS", 데코레이터로 짓는 AI 도구 서버 프레임워크

1프로젝트 한 줄 요약

nitrocloudofficial/nitrostack(줄여서 NitroStack)은 공식 MCP SDK로 도구 서버를 맨손으로 짤 때 반복되는 배관(트랜스포트 연결·세션 관리·인증·검증·핸들러 등록)을, NestJS 스타일 데코레이터와 DI 컨테이너로 감싸 없애 주는 TypeScript 프레임워크다. 저장소가 내건 한 줄은 이것 — "The enterprise-grade TypeScript framework for building production-ready MCP servers. Decorators. Dependency Injection. Widgets."(프로덕션급 MCP 서버를 만드는 엔터프라이즈 등급 TypeScript 프레임워크. 데코레이터. 의존성 주입. 위젯).

핵심은 "SDK는 라이브러리, NitroStack은 프레임워크"라는 포지셔닝이다. 개발자는 트랜스포트나 요청 라우팅을 신경 쓰지 않고, 함수 하나에 @Tool 데코레이터만 붙이면 그게 곧 에이전트가 호출할 수 있는 MCP 도구가 된다. 여기에 @Module·@Injectable(DI), @UseGuards(인증 게이트), @Widget(채팅창 안 React UI)까지 얹혀 있어, "비즈니스 로직만 쓰면 나머지는 프레임워크가"라는 NestJS의 개발 경험을 MCP 세계로 그대로 옮겨 왔다.

2왜 지금 주목받는가

NitroStack이 4개월 남짓 만에 별 1,100+를 모으며 트렌딩에 오른 이유는 타이밍이다. 2025년 이후 MCP가 사실상 "AI 도구 연결의 표준"으로 자리 잡으면서 수많은 팀이 MCP 서버를 짜기 시작했는데, 정작 그걸 구조적으로 만들 "프레임워크"는 비어 있었다. FastMCP 같은 도구가 있었지만 대체로 "함수 등록 래퍼" 수준이었다. NitroStack은 여기서 한참 더 나아가 NestJS급 애플리케이션 프레임워크를 자처했다.

주목 포인트 1 — "MCP 서버는 많은데, 프레임워크는 없었다"

공식 @modelcontextprotocol/sdk는 훌륭하지만 라이브러리다 — 트랜스포트, 요청 핸들러 같은 원시 재료를 준다. 서버를 진지하게 만들려면 인증·세션·검증·라우팅을 매번 손으로 배선해야 한다. NitroStack은 그 반복 배관을 애플리케이션 계층으로 흡수했다. 웹 개발에서 "Express(라이브러리) 위에 NestJS(프레임워크)"가 등장한 것과 정확히 같은 구도를, MCP 세계에서 재현했다. MCP 서버 수요가 폭발하는 시점에 나온 "프레임워크 공백을 메우는" 포지션이 트렌딩의 동력이다.

주목 포인트 2 — 인증과 위젯이라는 "실전 미들 마일"

장난감 MCP 서버는 쉽다. 문제는 프로덕션에 필요한 "미들 마일" — 인증, 세션, 리치 UI다. NitroStack은 이 셋을 정면으로 판다. OAuth 2.1 + PKCE를 명명된 RFC 기준으로 구현한 건 오픈소스에서 드문 "읽을 만한 참조 구현"이고, 위젯은 도구 결과를 ChatGPT/MCP 클라이언트 안에서 인터랙티브 카드로 그린다(text/html+skybridge MIME, CSP 샌드박싱). "AI가 도구를 쓰는" 워크플로가 단순 텍스트를 넘어 UI로 확장되는 지금, 정확히 그 지점을 겨냥한다.

3기술 스택 전체 지도

NitroStack은 typescript/packages/ 아래에 3개의 독립 배포 패키지를 둔 모노레포다. 그런데 흥미로운 결정이 하나 있다 — turbo·nx·lerna·pnpm-workspace 같은 모노레포 도구가 전혀 없고, 루트 package.json에 workspaces 필드조차 없다. 빌드 스크립트가 각 패키지로 cd해 순차로 tsc를 돌리는 "손빌드" 방식이다. 언어는 TypeScript 5.7.2, 전면 ESM("type":"module"), 타깃 ES2022, 그리고 데코레이터 시스템의 심장인 experimentalDecorators + emitDecoratorMetadata가 켜져 있다.

코어 @nitrostack/core — 프레임워크의 심장

순수 tsc로 빌드한다(번들러 없음). 진짜 일은 여기서 다 벌어진다. 런타임 의존성이 제법 많은데, 각각이 프레임워크의 한 축을 담당한다.

peerDependency로 @modelcontextprotocol/ext-apps >=0.1.0(MCP Apps / 위젯)를 요구한다.

CLI @nitrostack/cli — 스캐폴딩과 개발 경험

프로젝트를 만들고(init) 핫리로드로 돌리고(dev) esbuild로 사용자 프로젝트를 번들한다(build). 여기에 한 가지 주의점이 숨어 있다 — PostHog 텔레메트리가 내장돼 있어 사용 데이터를 외부로 보낸다.

위젯 @nitrostack/widgets · 테스트 · 트랜스포트

위젯 SDK는 React ^18 || ^19를 peer로 받고(개발은 React 19), @modelcontextprotocol/ext-apps를 함께 요구한다. 테스트는 코어·CLI 전반에서 Jest 29.7 + ts-jest를 ESM 모드(NODE_OPTIONS=--experimental-vm-modules)로 돌리며 — 69개 테스트 파일·약 697개 케이스·263개 describe로 실제 커버리지가 있다(스텁 아님). 트랜스포트는 server.ts 기준 세 가지다.

모드는 NODE_ENV로 자동 선택된다(development→stdio, production→stdio+HTTP 이중). MCP_TRANSPORT_TYPE 환경변수로 강제 지정도 가능하다.

4아키텍처 심화 분석

NitroStack의 생애는 McpApplicationFactory.create(AppModule) 한 줄에서 시작한다. 이 팩토리가 데코레이터로 심어 둔 메타데이터를 reflect-metadata로 읽어 애플리케이션을 조립한다. 아래는 생태계 4계층과 부트스트랩 흐름이다.

실제 요청이 들어오면 NestJS와 판박이인 파이프라인을 탄다. core/src/core/tool.ts에서 확인되는 도구 호출 생명주기는 이렇다.

구체적으로는 guard.canActivate(context)가 실행을 통과시킬지 결정하고(약 159행), executeWithInterceptors가 executeWithPipes를 감싸며, 그 안에서 pipe.transform(...)이 핸들러 앞에 실행된다. 여기에 @Cache({ttl})·@RateLimit(...)·@HealthCheck 같은 횡단 관심사 데코레이터가 더 끼어든다. 아래는 이 프레임워크를 떠받치는 네 가지 핵심 설계다.

설계 ① 데코레이터 + reflect-metadata 레지스트리

@Tool·@Resource·@Prompt·@Widget·@Controller·@InitialTool이 클래스에 Reflect.defineMetadata로 메타데이터를 심고, 부트스트랩 때 extractTools/extractResources/extractPrompts가 그걸 되읽어 등록한다. @Controller('github')는 도구 이름에 접두사를 붙여(create_issue → github_create_issue) 자동으로 DI에 등록한다.

// NestJS를 아는 사람에겐 낯익은 그림 — @Tool이 곧 MCP 도구
@Controller('github')                 // 도구 이름에 github_ 접두사
export class GithubTools {
  constructor(private gh: GithubService) {}  // DI 주입

  @Tool({ description: '이슈를 생성한다' })
  async create_issue(input: CreateIssueInput, ctx: ExecutionContext) {
    ctx.logger.info('creating issue');
    return await this.gh.create(input);   // → github_create_issue 로 노출
  }
}

설계 ② DI 컨테이너 + 모듈 시스템

di/container.ts의 컨테이너가 @Injectable·@Inject로 의존성을 해결하고, 싱글턴/트랜지언트/스코프드 생명주기를 관리한다(lifecycle.ts). 애플리케이션은 @Module({ imports, providers })로 조립하며, ConfigModule.forRoot()·JWTModule·ApiKeyModule·OAuthModule 같은 기능 모듈을 가져다 쓴다. OnModuleInit·OnApplicationBootstrap 같은 생명주기 훅도 NestJS 그대로다.

설계 ③ 진짜 OAuth 2.1 인증 서브시스템

auth/ 디렉토리(약 3,500줄 + 11개 테스트 파일)는 이 저장소에서 가장 값진 참조 구현이다. simple-jwt · token-store · token-validation · pkce · secure-secret · server-metadata · api-key · client · middleware로 나뉘어, OAuth 2.1의 리소스 서버 + 권한 서버를 명명된 RFC 기준으로 구현한다.

설계 ④ 위젯 브리지 + MCP Tasks(비동기 도구)

위젯 브리지(widget-mcp-meta.ts·ui-next/·widgets/)는 도구 결과에 OpenAI Apps SDK와 MCP Apps 두 규격의 UI 메타데이터를 병합한다 — CSP 허용목록, widgetDomain, prefersBorder 등을 얹고, Next.js 라우트가 실제 UI를 렌더한다(OpenAI 쪽은 text/html+skybridge MIME + openai/widget* 메타). MCP Tasks(task.ts, 556줄)는 TaskManager/TaskContext로 상태 머신을 굴려 오래 걸리는 비동기 도구를 지원한다(도구별 taskSupport: 'forbidden'|'optional'|'required').

5디렉토리 구조 해부

클론 직후의 구조다. 전체 371개 추적 파일, TypeScript 38,398줄. 공개 저장소는 단일 스쿼시 스냅샷 커밋(7d63f9e, "Versions Updated", 2026-07-14)이라 실제 개발 이력은 보이지 않는다 — 내부 모노레포의 "릴리스 미러"로 읽힌다.

모든 서브시스템에 __tests__/가 나란히 붙어 있다. 이 저장소를 읽을 때 지적 핵심은 두 곳 — core/src/core/(프레임워크 배관)와 core/src/auth/(OAuth 구현)다.

6학습 포인트

NitroStack이 학습 표본으로 훌륭한 이유는 프레임워크 설계·TypeScript 데코레이터·의존성 주입·MCP 프로토콜·OAuth 2.1·대규모 테스트·AI 네이티브 UI가 한 저장소에 모여 있기 때문이다. 관심사별로 짚어 보자.

① NestJS를 밑바닥부터 재구현한 표본

DI 컨테이너, 모듈 그래프, 데코레이터 메타데이터 레지스트리, 가드/파이프/인터셉터/필터 파이프라인 — NestJS의 개념들이 어떻게 실제로 도는지를 읽기 좋은 크기(코어 24K줄)로 재현해 놨다. NestJS를 "쓸 줄만" 아는 사람이 "어떻게 만들어졌나"로 넘어가기에 이상적인 교재다. 프레임워크를 직접 짜 보고 싶은 사람에게 특히.

② TypeScript 데코레이터 + reflect-metadata 실전

@Tool 하나가 어떻게 "런타임에 발견되는 MCP 도구"가 되는지 — 메타데이터 프로그래밍의 실제 사례다. tsconfig가 요구하는 정확한 플래그(experimentalDecorators·emitDecoratorMetadata)와 reflect-metadata 임포트가 왜 필요한지 몸으로 배운다. 데코레이터가 "마법"이 아니라 "메타데이터 저장 + 부트스트랩 때 되읽기"임을 깨닫는 순간이 온다.

③ MCP 프로토콜을 깊이 있게

도구/리소스/프롬프트가 와이어(전송선) 위에서 어떻게 표현되는지, 그리고 세 가지 트랜스포트(stdio, 세션·재개 가능한 Streamable HTTP, 레거시 SSE)가 어떻게 다른지. MCP 서버를 진지하게 만들려는 사람에게 "SDK만으론 안 보이던 전체 그림"을 준다.

④ 제대로 된 OAuth 2.1 참조 구현

auth/는 PKCE·동적 클라이언트 등록·토큰 검토·보호 리소스 메타데이터를 명명된 RFC 기준으로 구현한 드문 "읽을 수 있는" 코드다. MCP와 무관하게, OAuth 2.1이 실제로 어떻게 돌아가는지 배우려는 사람에게 값진 자료.

⑤ Zod ↔ JSON Schema 브리징 · 대규모 테스트

타입 안전한 도구 입출력을 위해 zod-to-json-schema로 Zod 스키마를 MCP가 요구하는 JSON Schema로 변환하는 패턴. 그리고 697개 Jest 케이스를 ESM 모드로 돌리는 것 자체가, 데코레이터가 잔뜩 낀 코드를 어떻게 테스트하는지에 대한 좋은 연구감이다.

⑥ AI 네이티브 UI — 채팅창 안의 React

도구 결과를 ChatGPT/MCP 클라이언트 안에서 렌더되는 React 위젯으로 만드는 법(OpenAI Apps SDK + MCP Apps 호환, CSP 샌드박싱). "AI가 텍스트를 넘어 UI를 반환하는" 다음 세대 인터페이스를 미리 만져 볼 수 있다.

7시스템 요구사항 · 설치

NitroStack은 특별한 하드웨어가 필요 없다 — stdio MCP 서버는 가볍다. 다만 Node 버전 요구가 문서마다 엇갈린다(§10 함정 참조). 안전하게 README를 따르자.

# 1) 새 MCP 서버 프로젝트 만들기 (계산기 스타터)
npx @nitrostack/cli init my-server
cd my-server
npm run dev            # 핫리로드 개발 서버(stdio)

# 2) 프레임워크만 직접 설치해서 쓰기
npm install @nitrostack/core
npm install @nitrostack/widgets   # 채팅창 위젯을 쓸 때(React + Next.js)

MCP 클라이언트(Claude Desktop 등) 설정은 이렇게 붙인다.

{
  "mcpServers": {
    "my-server": { "command": "node", "args": ["dist/index.js"] }
  }
}

# 기여/개발 (저장소 루트 → typescript/)
git clone https://github.com/nitrocloudofficial/nitrostack && cd nitrostack/typescript
npm install
npm run build          # 각 패키지로 cd 해서 tsc 순차 실행(모노레포 도구 없음)
NODE_OPTIONS=--experimental-vm-modules npm test   # Jest(ESM), 약 697 케이스

8직접 해볼 수 있는 실습 과제

@Controller('math')
export class MathTools {
  @Tool({ description: '두 수를 더한다' })
  add(input: { a: number; b: number }) {
    return { sum: input.a + input.b };
  }
}

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

저장소 & 배포
· GitHub: github.com/nitrocloudofficial/nitrostack (Apache-2.0, 별 1,172)
· npm 코어: @nitrostack/core (v1.0.13) · @nitrostack/cli (v1.0.14) · @nitrostack/widgets (v1.0.8)

프로젝트 사이트(문서 · 스튜디오)
· 홈: nitrostack.ai · 문서: docs.nitrostack.ai · 블로그: blog.nitrostack.ai
· NitroStudio(비공개 데스크톱 앱): nitrostack.ai/studio
· 커뮤니티: Discord · X @nitrostackai · YouTube @nitrostackai

저장소 내 핵심 코드/문서
· typescript/packages/core/src/core/(server·tool·app-decorator·transports) · .../auth/(OAuth 2.1) · .../ui-next/(위젯) · docs/(마크다운 66개) · templates/typescript-starter|oauth|pizzaz

상위 표준
· MCP: modelcontextprotocol.io · Streamable HTTP(2025-06-18 스펙) · OpenAI Apps SDK · @modelcontextprotocol/sdk(Anthropic PBC, MIT)