타입스크립트 MCP 서버

대형 언어 모델(LLM)에 컨텍스트를 제공하기 위한 TypeScript Model Context Protocol (MCP) 서버 생성하기

MCP란?

Model Context Protocol (MCP)는 AI 어시스턴트가 외부 도구 및 리소스와 상호작용할 수 있도록 하는 개방형 표준입니다. LLM이 다음을 수행할 수 있는 일관된 방식을 제공합니다:

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

사용 방법

MCP 서버 생성

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

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#mcp-server

yarn

yarn nx g @aws/nx-plugin:ts#mcp-server

npm

npx nx g @aws/nx-plugin:ts#mcp-server

bun

bunx nx g @aws/nx-plugin:ts#mcp-server

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

pnpm nx g @aws/nx-plugin:ts#mcp-server --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#mcp-server --dry-run

npm

npx nx g @aws/nx-plugin:ts#mcp-server --dry-run

bun

bunx nx g @aws/nx-plugin:ts#mcp-server --dry-run

팁

먼저 MCP 서버를 추가할 프로젝트를 생성하기 위해 ts#project 생성기를 사용하세요.

옵션

매개변수	타입	기본값	설명
project 필수	string	-	The project to add an MCP server to
name	string	-	The name of your MCP server (default: mcp-server)

생성기 출력

생성기는 기존 TypeScript 프로젝트에 다음 파일들을 추가합니다:

• 디렉터리your-project/

  • 디렉터리src/

    • 디렉터리mcp-server/ (사용자 지정 이름 지정 시 변경됨)

      • index.ts MCP 서버 진입점
      • server.ts 메인 서버 정의
      • 디렉터리tools/

        • add.ts 샘플 도구
      • 디렉터리resources/

        • sample-guidance.ts 샘플 리소스
  • package.json bin 항목 및 MCP 종속성 추가됨
  • project.json MCP 서버 실행 타겟 업데이트됨

MCP 서버 작업하기

도구 추가

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

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

리소스 추가

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

const exampleContext = '반환할 컨텍스트 내용';

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 어시스턴트는 유사한 구성 방식을 사용합니다. MCP 서버 세부 정보가 포함된 설정 파일을 생성하거나 업데이트해야 합니다:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/path/to/your-mcp-server/index.ts"]
    }
  }
}

주의

서버 연결 시 ENOENT npx와 같은 오류가 발생하면 터미널에서 which npx를 실행해 얻을 수 있는 npx의 전체 경로를 지정해야 할 수 있습니다.

핫 리로드

MCP 서버를 개발하는 동안 --watch 플래그를 구성하면 AI 어시스턴트가 항상 최신 버전의 도구/리소스를 인식합니다:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "--watch", "/path/to/your-mcp-server/index.ts"]
    }
  }
}

참고

새 도구나 리소스를 추가한 경우 AI 어시스턴트에서 MCP 서버를 새로고침해야 할 수 있습니다.

어시스턴트별 구성

특정 AI 어시스턴트와 MCP를 구성하려면 다음 문서를 참조하세요:

• Amazon Q Developer
• Cline
• Cursor
• Claude Code
• Roo Code

팁

Amazon Q Developer와 같은 일부 AI 어시스턴트는 특정 프로젝트와 관련된 MCP 서버를 정의할 때 특히 유용한 워크스페이스 수준의 MCP 서버 구성을 지정할 수 있습니다.

MCP 서버 실행

MCP 서버를 테스트하고 사용하는 가장 쉬운 방법은 AI 어시스턴트와 연동하는 것입니다(위 참조). 하지만 STDIO 전송에서 Streamable HTTP 전송으로 전환할 때 유용할 수 있는 <your-server-name>-serve 타겟을 사용해 서버를 실행할 수도 있습니다.

pnpm

pnpm nx run your-project:your-server-name-serve

yarn

yarn nx run your-project:your-server-name-serve

npm

npx nx run your-project:your-server-name-serve

bun

bunx nx run your-project:your-server-name-serve

이 명령어는 파일 변경 시 서버를 자동으로 재시작하는 tsx --watch를 사용합니다.