학습 결과: URL을 받아올 수 있거나 도구를 쓸 수 있는 어시스턴트를 이 언어에 연결합니다.
선행 학습: 첫 절은 필요 없습니다. MCP 서버는 첫 프로그램의 방법대로 도구를 설치해야 합니다.
한 번의 요청부터
URL은 받아올 수 있지만 도구가 설정되지 않은 어시스턴트에게 가장 넓게 통하는 표면은 스스로 완결된 파일 하나입니다.
https://topaz.ooo/agents.md파일의 생김새와 형태, 호스트·제품 프로필 경계, 그리고 다른 언어를 이미 아는 모델에게 가장 중요한 존재하지 않는 형태 목록이 들어 있습니다. Vec<T>, async, try, 클래스 문법을 피하고 null을 모든 없음의 표현처럼 쓰지 말라고 알려 주면서, 지원되는 데이터 경계 형태인 T | null은 그대로 구분합니다. 이런 차이를 이름으로 짚어 주면 자신 있게 추측한 코드가 잘못된 소스가 되는 일을 줄일 수 있습니다.
기계용 표면이 둘 더 있습니다. https://topaz.ooo/llms.txt는 현재 모든 페이지의 색인이고, https://topaz.ooo/version.json은 어느 버전이 답하는지 알려 줍니다.
다른 사람을 위해 어시스턴트를 설정한다면 저 URL 하나를 주는 것이 설정의 전부입니다.
도구가 푸는 문제
받아 오기만 해도 어시스턴트가 올바른 형태를 쓰게 됩니다. 다만 방금 쓴 프로그램이 실제로 컴파일되는지는 알려 주지 못합니다.
처음 보는 언어를 쓰는 어시스턴트는 둘 중 하나를 합니다. 문서를 읽고 짐작하거나, 일단 쓰고 무엇이 틀렸는지 정확히 듣고 고치거나. 두 번째 순환은 문서가 부실해도 동작하는 코드를 냅니다. 첫 번째는 컴파일되지 않는 그럴듯한 글을 냅니다. 참조 문서만으로는 첫 번째 순환에 머물고, 검사기가 두 번째로 옮겨 줍니다.
도구 넷
| 도구 | 답하는 질문 |
|---|---|
topaz_spec | 이 부분의 정확한 형태가 무엇인가 |
topaz_examples | 이 개념의 검증된 코드를 보여 달라 |
topaz_check | 방금 쓴 게 맞는가, 틀렸다면 정확히 어디인가 |
topaz_run | 실제로 무엇을 출력하는가 |
결과를 바꾸도록 설계한 도구는 topaz_check입니다. 계획된 서버는 검사기가 낸 진단과 코드와 소스 위치를 손대지 않고 그대로 돌려줍니다. 어시스턴트는 풀어 쓴 요약 대신 정확한 증거를 보고 자기 출력을 고칠 수 있습니다.
실행에서 무엇을 격리해야 하는가
토파즈는 관찰 가능한 효과를 호스트 또는 제품 프로필 경계로 보냅니다. 그래서 아무 기능도 주지 않는 실행 호스트를 만들기 좋지만, 평범한 네이티브 CLI가 저절로 샌드박스가 되는 것은 아닙니다. 네이티브 실행에는 파일과 입출력 연산이 열릴 수 있습니다.
따라서 계획된 topaz_run에는 서로 독립된 장벽이 둘 필요합니다. 먼저 아무 기능도 주지 않는다고 검증된 토파즈 호스트를 사용하고, 그 위에서 네트워크와 자식 프로세스를 막고 제출된 임시 소스만 보이게 하는 운영체제 샌드박스를 적용합니다. 제한 없는 평범한 topaz run은 서버의 실행 경계로 쓸 수 없습니다.
격리만으로 자원 사용까지 제한되지는 않습니다. 제출된 프로그램은 무한히 돌거나 메모리를 할당하거나 출력을 쏟아낼 수 있으므로, 실행마다 벽시계 시간과 메모리와 출력 상한을 두고 자식 프로세스를 남기지 않아야 합니다.
제출된 소스를 보관하거나 기록하지 않고 호출 사이에 상태를 남기지 않는 것도 설계의 필수 조건입니다. 아직 존재하지 않는 서버가 이미 지키고 있다는 주장은 아닙니다.
기계가 읽는 서술자
클라이언트와 크롤러는 서버 설명을 직접 읽을 수 있습니다.
https://topaz.ooo/mcp.json계획된 도구 목록과 입력, 언어 버전, 필수 안전 경계가 구조화된 형태로 들어 있습니다. 서버가 배포되면 실제 도구 목록은 이 서술자와 같아야 합니다. 서버와 어긋나는 서술자는 없느니만 못합니다.
현재 상태
서술자는 "status": "planned"로 공개돼 있고 서버 자체는 아직 배포되지 않았습니다. 배포하려면 패키징된 서버가 격리와 자원 차단 검사를 통과해야 하며, 이 언어를 한 번도 본 적 없는 어시스턴트가 서버만 가지고 두 번째 시도에 작은 프로그램을 검사하고 실행하는 사용성 검사도 통과해야 합니다. 그때 상태를 바꾸고 이 페이지에 클라이언트 설정 블록을 붙입니다.
이어갈 준비가 된 시점
계획된 도구 넷이 각각 무엇에 답하는지 말할 수 있고, 실행에 왜 언어의 호스트 경계와 별도의 운영체제·자원 격리가 모두 필요한지 설명할 수 있으면 됩니다.
프로그램이 무엇에 닿을 수 있고 없는지는 상호 운용 개요를, 어시스턴트가 찾아보게 될 형태들은 문법 한눈에 보기를 보세요.