인공지능 에이전트 연동

Claude Code나 Claude Desktop 같은 인공지능 에이전트에 NodeCrypto를 등록하면 자연어로 암호 워크플로우를 구축할 수 있다. 에이전트가 노드 카탈로그를 조회하고 워크플로우 초안을 작성한 뒤 테스트 벡터로 검증하여 .ncw 파일로 저장하면, 사용자는 웹앱에서 해당 파일을 열어 캔버스 위에서 확인하고 검토한다.

• NodeCrypto는 에이전트가 사용자 컴퓨터 안에서 실행하는 경량 로컬 프로그램(MCP 서버)으로 동작한다. 외부 네트워크 연결을 맺지 않으며 네트워크 포트도 열지 않는다.
• 요구 사항: Node.js 20 이상 및 MCP 호환 인공지능 에이전트.
• 에이전트에게는 5가지 도구가 제공된다: guide(작성 지침), catalog(노드 조회), validate(유효성 검사), run(실행 및 기댓값 비교), expand(.ncw 파일 저장).

설치 및 등록

모든 MCP 클라이언트는 동일한 서버 실행 명령을 사용한다: 명령어 npx, 인자 -y @curealls/nodecrypto mcp. 클라이언트마다 설정을 기록하는 위치만 다르다.

Claude Code

터미널 명령 한 줄로 서버를 등록한다. -- 뒤의 부분이 서버를 실행하는 명령이다.

claude mcp add --transport stdio nodecrypto -- npx -y @curealls/nodecrypto mcp

• 기본 범위(local)는 현재 프로젝트에만 등록한다. 모든 프로젝트에서 사용하려면 --scope user를 추가하고, 프로젝트의 .mcp.json 파일에 저장해 팀과 공유하려면 --scope project를 추가한다.
• claude mcp list를 실행하여 nodecrypto가 Connected 상태로 표시되는지 확인한다. Claude Code 대화창 안에서는 /mcp 명령으로도 확인할 수 있다.

Claude Desktop

1. Claude 메뉴에서 설정(Settings)을 열고 "Developer" 탭으로 이동한 뒤 "Edit Config"를 클릭한다. 그러면 claude_desktop_config.json 파일이 열린다(Windows: %APPDATA%\Claude\claude_desktop_config.json, macOS: ~/Library/Application Support/Claude/claude_desktop_config.json).
2. 아래 설정을 추가한다. 파일에 이미 mcpServers 객체가 있다면 그 안에 nodecrypto 항목만 추가한다.

{
  "mcpServers": {
    "nodecrypto": {
      "command": "npx",
      "args": ["-y", "@curealls/nodecrypto", "mcp"]
    }
  }
}

3. Claude Desktop을 완전히 종료(Quit)한 뒤 다시 실행한다. 채팅 입력창 왼쪽 아래의 "Add files, connectors, and more" 버튼을 누르고 커넥터 설정을 열면 nodecrypto 도구를 확인할 수 있다.

VS Code, Cursor 및 기타 클라이언트

사용 중인 클라이언트의 MCP 설정 파일에 동일한 명령을 추가한다. 파일 경로와 최상위 JSON 키는 클라이언트마다 다르다.

VS Code 예시:

{
  "servers": {
    "nodecrypto": {
      "command": "npx",
      "args": ["-y", "@curealls/nodecrypto", "mcp"]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 구조를 사용한다. 그 외 MCP 클라이언트에서도 "표준 입출력(stdio) 서버: 명령어 npx, 인자 -y @curealls/nodecrypto mcp"를 등록하는 항목을 찾아 입력한다.

Windows 환경 주의사항

• 먼저 터미널에서 node --version이 20 이상으로 출력되는지, 그리고 npx -y @curealls/nodecrypto --version이 정상 실행되는지 확인한다. 사용자 환경에서 이 명령이 동작해야 에이전트도 서버를 실행할 수 있다.
• JSON 설정 파일에 파일 경로를 적을 때는 백슬래시를 \\로 이스케이프한다(예: C:\\Users\\me\\workflows).
• npx를 찾을 수 없다는 에러와 함께 서버 시작에 실패한다면 아래 문제 해결을 참고한다.

연결 확인

에이전트에게 다음과 같이 질문해 본다:

에이전트가 nodecrypto의 catalog 도구를 호출하고 symmetric-aes-encrypt 같은 노드를 보여주면 정상 연결된 것이다. 에이전트가 처음 도구를 호출할 때 실행 권한을 물으면 승인한다.

사용 예시

에이전트는 일반적으로 다음 5단계를 거쳐 작업을 수행한다:

1. guide: 워크플로우 작성 지침을 읽는다.
2. catalog: 노드 종류나 포트 이름을 추측하지 않고 필요한 노드를 검색하여 정확한 포트 및 파라미터 정의를 조회한다.
3. validate: 초안 워크플로우의 구조적 오류나 타입 불일치를 검사하고 수정한다.
4. run: 워크플로우를 실행하고 출력값을 테스트 벡터 기댓값(expect)과 비교한다.
5. expand: 검증이 끝난 워크플로우를 .ncw 파일로 저장하고 저장된 파일 경로를 알려준다.

에이전트는 보통 어떤 RFC 절이나 테스트 벡터를 사용했는지, 왜 특정 파라미터 값을 선택했는지를 각 노드의 메모로 기록하므로 캔버스에서 워크플로우를 훨씬 쉽게 검토할 수 있다.

워크플로우 저장 및 열기

파일 저장 위치

• 기본 출력 폴더는 사용자 홈 디렉터리 아래의 nodecrypto-workflows이다(폴더가 없으면 자동 생성됨). 파일 이름은 워크플로우 이름에 .ncw 확장자를 붙여서 결정된다.
• 기본 폴더 변경: 서버 인자에 --out-dir <폴더>를 추가하거나(예: "args": ["-y", "@curealls/nodecrypto", "mcp", "--out-dir", "D:\\workflows"]) NODECRYPTO_OUT_DIR 환경 변수를 설정한다. 둘 다 설정된 경우 --out-dir가 우선한다.
• 실제 사용 시에는 에이전트가 스스로 저장 경로를 지정하는 경우가 많다. 에이전트가 현재 열려 있는 프로젝트 워크스페이스의 절대 경로를 알고 있으면 기본 폴더 대신 해당 프로젝트 폴더에 저장하곤 한다. 기본 폴더에 저장하고 싶다면 "경로를 지정하지 말고 기본 위치에 저장해줘"라고 요청한다.
• 요청별 경로 지정: "D:\work\hmac.ncw로 저장해줘"처럼 요청하면 에이전트가 해당 경로에 정확히 저장한다. 확장자는 .ncw만 허용된다.
• 저장이 완료되면 에이전트가 절대 파일 경로를 알려준다. 경로를 말해주지 않으면 "저장된 파일의 전체 경로가 어디야?"라고 물어본다.

기존 파일 덮어쓰기

같은 이름의 파일이 이미 존재하면 기본적으로 덮어쓴다. 기존 파일을 덮어쓰고 싶지 않다면 프롬프트에 "파일이 이미 있으면 덮어쓰지 말고 알려줘"라고 덧붙인다. 그러면 에이전트가 overwrite: false 옵션으로 expand를 호출하여 파일이 이미 존재할 때 저장을 중단하고 알려준다.

웹앱에서 열기

1. NodeCrypto 웹앱(https://nodecrypto.dev/)을 연다.
2. 메뉴에서 "File > Open"을 클릭하고 저장된 .ncw 파일을 선택한다.
3. 새 탭에 워크플로우가 열린다. 파일로 연 탭은 아직 브라우저 저장소에 영구 저장된 상태가 아니므로, 워크스페이스에 사본을 보관하려면 "Save As"를 사용한다.

웹앱은 인공지능 에이전트와 직접 통신하지 않으며, .ncw 파일이 둘 사이의 매개체 역할을 한다.

보안 주의사항

• 에이전트가 생성한 워크플로우를 무조건 신뢰하지 않는다. 웹앱 캔버스에서 모든 노드, 배선, 파라미터를 직접 눈으로 확인하고 노드 메모에 기록된 근거를 검토한다.
• 기댓값 비교(expect) 통과는 테스트 벡터 자체가 올바를 때만 의미가 있다. 테스트 벡터의 출처(RFC 절 번호 등)를 확인한다.
• 클라이언트의 도구 호출 승인 프롬프트를 켜 둔다. 특히 디스크에 파일을 쓰고 기본 덮어쓰기를 수행하는 expand를 승인하기 전에 대상 경로를 확인한다.

문제 해결