콘텐츠로 이동
@aws/nx-plugin
Blog

MCP 서버를 관계형 데이터베이스에 연결

connection 생성기는 TypeScript MCP 서버를 관계형 데이터베이스 프로젝트에 연결하여, createServer와 해당 전송 진입점 내부에서 Prisma 클라이언트를 사용할 수 있도록 합니다.

사전 요구 사항

섹션 제목: “사전 요구 사항”

이 생성기를 사용하기 전에 다음이 필요합니다:

  1. ts#mcp-server 프로젝트
  2. ts#rdb 프로젝트

사용법

섹션 제목: “사용법”

생성기 실행

섹션 제목: “생성기 실행”
  1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
  2. VSCode에서 Nx 콘솔 열기
  3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
  4. 검색 @aws/nx-plugin - connection
  5. 필수 매개변수 입력
    • 클릭 Generate

    MCP 서버 프로젝트를 소스로, 관계형 데이터베이스 프로젝트를 대상으로 선택하세요. 프로젝트에 여러 MCP 서버 컴포넌트가 포함되어 있는 경우, sourceComponent를 지정하여 명확히 구분하세요.

    옵션

    섹션 제목: “옵션”
    매개변수 타입 기본값 설명
    sourceProject 필수 string - 소스 프로젝트
    targetProject 필수 string - 연결할 대상 프로젝트
    sourceComponent string - 연결을 시작할 소스 컴포넌트 (컴포넌트 이름, 소스 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 소스로 명시적으로 선택하려면 '.'을 사용하세요.
    targetComponent string - 연결할 대상 컴포넌트 (컴포넌트 이름, 대상 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 대상으로 명시적으로 선택하려면 '.'을 사용하세요.

    생성기 출력

    섹션 제목: “생성기 출력”

    생성기는 MCP 서버의 소스 디렉토리에 있는 세 개의 파일을 수정합니다:

    • 디렉터리packages/my-service/src/my-mcp
      • server.ts createServer가 { db } 매개변수를 받도록 업데이트됨
      • http.ts const server = createServer({ db }) 위에서 Prisma 클라이언트 생성
      • stdio.ts await createServer({ db }).connect(transport) 전에 Prisma 클라이언트 생성

    또한, <mcp-server-name>-serve-local 타겟이 데이터베이스의 serve-local 타겟에 의존하도록 업데이트됩니다.

    작동 방식

    섹션 제목: “작동 방식”

    서버 정의

    섹션 제목: “서버 정의”

    createServer는 Prisma 클라이언트를 매개변수로 받아 동기적으로 유지되며 클라이언트를 도구와 리소스에 전달할 수 있습니다:

    packages/my-service/src/my-mcp/server.ts
    import { getPrisma as getMyDb } from ':my-scope/my-db';
    

    export const createServer = ({
      myDb,
    }: {
      myDb: Awaited<ReturnType<typeof getMyDb>>;
    }) => {
      const server = new McpServer({ name: 'my-service', version: '1.0.0' });
      // register tools/resources that use myDb
      return server;
    };

    HTTP 전송

    섹션 제목: “HTTP 전송”

    Prisma 클라이언트는 createServer 호출 위의 요청 핸들러 내부에서 생성됩니다:

    packages/my-service/src/my-mcp/http.ts
    import { getPrisma as getMyDb } from ':my-scope/my-db';
    

    app.post('/mcp', async (req, res) => {
      try {
        const myDb = await getMyDb();
        const server = createServer({ myDb });
        // ...
      }
    });

    Stdio 전송

    섹션 제목: “Stdio 전송”

    stdio 전송 진입점에도 동일한 패턴이 적용됩니다:

    packages/my-service/src/my-mcp/stdio.ts
    import { getPrisma as getMyDb } from ':my-scope/my-db';
    

    export const startMcpServer = async () => {
      const transport = new StdioServerTransport();
      const myDb = await getMyDb();
      await createServer({ myDb }).connect(transport);
    };

    다중 데이터베이스

    섹션 제목: “다중 데이터베이스”

    다른 대상으로 생성기를 다시 실행하면 첫 번째 데이터베이스와 함께 두 번째 데이터베이스가 추가됩니다. 둘 다 함께 createServer에 전달됩니다:

    packages/my-service/src/my-mcp/http.ts
    const postgresDb = await getPostgresDb();
    const mySqlDb = await getMySqlDb();
    const server = createServer({ postgresDb, mysqlDb });

    인프라

    섹션 제목: “인프라”

    생성된 MCP 서버 구성은 IGrantable과 IConnectable을 구현하므로, 구성에서 직접 데이터베이스에 대한 네트워크 및 IAM 액세스 권한을 부여할 수 있습니다.

    packages/infra/src/stacks/application-stack.ts
    import { MyDatabase } from ':my-scope/common-constructs';
    

    const db = new MyDatabase(this, 'Db', { vpc, ... });
    const myMcpServer = new MyMcpServer(this, 'MyMcpServer', { vpc, ... });
    

    db.allowDefaultPortFrom(myMcpServer);
    db.grantConnect(myMcpServer);

    allowDefaultPortFrom은 MCP 서버 런타임이 데이터베이스 포트에 도달할 수 있도록 보안 그룹 규칙을 엽니다. grantConnect는 서버의 실행 역할에 IAM rds-db:connect 권한을 부여합니다.

    로컬 개발

    섹션 제목: “로컬 개발”
    Terminal window
    pnpm nx <mcp-server-name>-serve-local <project-name>

    이것은 MCP 서버와 연결된 모든 데이터베이스를 시작합니다. SERVE_LOCAL=true 환경 변수는 각 Prisma 클라이언트가 Aurora 대신 로컬 Docker 데이터베이스에 연결하도록 합니다.