컨텐츠로 건너뛰기
@aws/nx-plugin
Blog

ts#mcp-서버

TypeScript MCP 서버 생성기

대형 언어 모델(LLM)에 컨텍스트를 제공하기 위한 TypeScript 모델 컨텍스트 프로토콜(MCP) 서버를 생성합니다.

MCP란?

모델 컨텍스트 프로토콜(MCP)은 AI 어시스턴트가 외부 도구 및 리소스와 상호 작용할 수 있도록 하는 개방형 표준입니다. LLM이 다음을 일관된 방식으로 수행할 수 있도록 지원합니다:

  • 작업 수행 또는 정보 검색을 위한 도구(함수) 실행
  • 컨텍스트 또는 데이터를 제공하는 리소스 접근

사용 방법

MCP 서버 생성

TypeScript MCP 서버를 두 가지 방법으로 생성할 수 있습니다:

  1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
  2. VSCode에서 Nx 콘솔 열기
  3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
  4. 검색 @aws/nx-plugin - ts#mcp-server
  5. 필수 매개변수 입력
    • 클릭 Generate

    옵션

    매개변수 타입 기본값 설명
    name 필수 string - MCP server project name.
    directory string packages Parent directory where the MCP server is placed.
    subDirectory string - The sub directory the MCP server is placed in. By default this is the MCP server project name.

    생성기 출력 결과

    생성기는 다음 프로젝트 파일들을 생성합니다:

    • 디렉터리packages/<name>/
      • README.md MCP 서버 사용 설명서
      • project.json 빌드, 번들 및 개발 타겟을 포함한 Nx 프로젝트 설정
      • 디렉터리src/
        • index.ts MCP 서버 진입점
        • server.ts 도구 및 리소스를 정의하는 메인 서버
        • global.d.ts 마크다운 파일 임포트를 위한 TypeScript 타입 선언
        • 디렉터리resources/
          • example-context.md MCP 서버 리소스로 사용되는 예시 마크다운 파일

    MCP 서버 작업 방법

    도구 추가

    도구는 AI 어시스턴트가 호출할 수 있는 동작 수행 함수입니다. server.ts 파일에 새 도구를 추가할 수 있습니다:

    server.tool("toolName",
      { param1: z.string(), param2: z.number() }, // Zod를 사용한 입력 스키마
      async ({ param1, param2 }) => {
        // 도구 구현
        return {
          content: [{ type: "text", text: "Result" }]
        };
      }
    );

    리소스 추가

    리소스는 AI 어시스턴트에 컨텍스트를 제공합니다. 파일에서 정적 리소스를 추가하거나 동적 리소스를 생성할 수 있습니다:

    // 파일에서 정적 리소스 임포트
    import exampleContext from './resources/example-context.md';
    

    server.resource('resource-name', 'example://resource', async (uri) => ({
      contents: [{ uri: uri.href, text: exampleContext }],
    }));
    

    // 동적 리소스
    server.resource('dynamic-resource', 'dynamic://resource', async (uri) => {
      const data = await fetchSomeData();
      return {
        contents: [{ uri: uri.href, text: data }],
      };
    });

    AI 어시스턴트와 연동 설정

    MCP 서버를 AI 어시스턴트와 사용하려면 먼저 번들링해야 합니다:

    Terminal window
    pnpm nx run your-mcp-server:bundle

    이렇게 하면 dist/packages/your-mcp-server/bundle/index.js 경로에 번들 버전이 생성됩니다(디렉토리 설정에 따라 경로가 다를 수 있음).

    설정 파일

    MCP를 지원하는 대부분의 AI 어시스턴트는 유사한 설정 방식을 사용합니다. MCP 서버 세부 정보가 포함된 설정 파일을 생성하거나 업데이트해야 합니다:

    {
      "mcpServers": {
        "your-mcp-server": {
          "command": "node",
          "args": [
            "/path/to/workspace/dist/packages/your-mcp-server/bundle/index.js"
          ],
          "transportType": "stdio"
        }
      }
    }

    /path/to/workspace/dist/packages/your-mcp-server/bundle/index.js를 실제 번들링된 MCP 서버 경로로 교체하세요.

    어시스턴트별 설정

    특정 AI 어시스턴트와의 MCP 연동 설정은 다음 문서를 참조하세요:

    개발 워크플로우

    빌드 타겟

    이 생성기는 TypeScript 프로젝트 생성기를 기반으로 하며 해당 타겟을 상속받으며 다음과 같은 추가 타겟을 제공합니다:

    번들

    bundle 타겟은 esbuild를 사용하여 AI 어시스턴트와 함께 사용할 수 있는 단일 JavaScript 번들 파일을 생성합니다:

    Terminal window
    pnpm nx run your-mcp-server:bundle

    이렇게 하면 dist/packages/your-mcp-server/bundle/index.js 경로에 번들 버전이 생성됩니다(디렉토리 설정에 따라 경로가 다를 수 있음).

    개발

    dev 타겟은 프로젝트 변경 사항을 감지하고 자동으로 번들을 재빌드합니다:

    Terminal window
    pnpm nx run your-mcp-server:dev

    개발 중에 사용하면 AI 어시스턴트가 최신 MCP 서버 버전을 사용하도록 보장합니다.