이 페이지는 토파즈 v5.17을 설명합니다. 현재 문서로 판단하기 전에 /version.json의 version 값을 5.17과 대조하세요.
학습 결과: URL을 받아올 수 있거나 도구를 쓸 수 있는 어시스턴트를 이 언어에 연결합니다.
선행 학습: 첫 절은 필요 없습니다. MCP 서버를 쓰려면 첫 프로그램의 안내대로 도구 모음을 설치해야 합니다.
한 번의 요청부터
URL은 받아올 수 있지만 도구는 설정되지 않은 어시스턴트라면, 가장 널리 통하는 표면은 그 자체로 완결된 파일 하나입니다.
https://topaz.ooo/agents.md여기에는 파일의 생김새와 형태, 호스트·제품 프로필 경계, 그리고 다른 언어를 이미 아는 모델에게 가장 중요한 존재하지 않는 형태 목록이 들어 있습니다. Vec<T>, async, try, 클래스 문법을 피하고 null을 모든 없음의 표현처럼 쓰지 말라고 알려 주면서, 지원되는 데이터 경계 형태인 T | null은 그대로 구분합니다. 이런 차이를 이름으로 짚어 주면 자신 있게 추측한 코드가 잘못된 소스가 되는 일을 줄일 수 있습니다.
기계가 읽기 좋은 표면도 함께 제공합니다. https://topaz.ooo/llms.txt는
간결한 색인이고, https://topaz.ooo/llms-full.txt에는 영문 설명서 전체가
마크다운으로 들어 있습니다. 영문 페이지마다
https://topaz.ooo/docs/<slug>.md 경로도 있으며, 제목과 원문 경로,
대응하는 명세 절을 frontmatter에 보존합니다.
https://topaz.ooo/version.json은 어느 버전이 답하는지 알려 줍니다.
다른 사람을 위해 어시스턴트를 설정한다면 저 URL 하나만 건네면 설정은 끝입니다.
도구가 푸는 문제
받아 오기만 해도 어시스턴트가 올바른 형태를 쓰게 됩니다. 다만 방금 쓴 프로그램이 실제로 컴파일되는지는 알려 주지 못합니다.
낯선 언어를 쓰는 어시스턴트는 둘 중 하나를 합니다. 문서를 읽고 짐작하거나, 일단 쓰고 무엇이 틀렸는지 정확히 듣고 고치거나. 두 번째 순환은 문서가 부실해도 동작하는 코드를 냅니다. 첫 번째는 컴파일되지 않는 그럴듯한 글을 냅니다. 참조 문서만으로는 첫 번째 순환에 머물고, 검사기가 두 번째로 옮겨 줍니다.
공개된 도구 셋
| 도구 | 답하는 질문 |
|---|---|
topaz_spec | 이 부분의 정확한 형태가 무엇인가 |
topaz_examples | 이 개념의 검증된 코드를 보여 달라 |
topaz_check | 방금 쓴 게 맞는가, 틀렸다면 정확히 어디인가 |
결과를 바꾸도록 설계한 도구는 topaz_check입니다. 공개된 네이티브
패키지는 검사기가 낸 진단과 그 코드, 소스 위치를 손대지 않고 그대로
돌려주며, 어떤 설치 도구 모음과 컴파일러 선택이 답했는지도 정확히
밝힙니다. 어시스턴트는 풀어 쓴 요약 대신 정확한 증거를 보고 자기 출력을
고칠 수 있습니다.
아직 실행 도구가 없는 이유
토파즈는 관찰 가능한 효과를 호스트 또는 제품 프로필 경계로 보냅니다. 그래서 아무 기능도 주지 않는 실행 호스트를 만들기 좋지만, 평범한 네이티브 CLI가 저절로 샌드박스가 되는 것은 아닙니다. 네이티브 실행에는 파일과 입출력 연산이 열릴 수 있습니다.
따라서 topaz_run은 아직 제공하지 않습니다. 이 도구를 공개하려면 아무 기능도 주지 않는다고 검증된 토파즈 호스트와, 네트워크와 자식 프로세스를 막고 제출된 임시 소스만 보이게 하는 운영체제 샌드박스가 각각 필요합니다. 제한 없는 평범한 topaz run은 서버의 실행 경계로 쓸 수 없습니다.
격리한다고 자원 사용까지 제한되지는 않습니다. 제출된 프로그램은 무한히 돌거나 메모리를 할당하거나 출력을 쏟아낼 수 있으므로, 실행마다 벽시계 시간·메모리·출력 상한을 두고 자식 프로세스를 남기지 않아야 합니다.
도구 셋은 제출된 프로그램을 실행하지 않습니다. 검사할 때는 크기가 제한된 소스를 매번 새 언어 서버 프로세스의 표준 입력으로만 보내고, 소스를 보관하거나 기록하지 않으며 호출 사이에 문서 상태를 남기지 않습니다.
기계가 읽는 서술자
클라이언트와 크롤러는 서버 설명을 직접 읽을 수 있습니다.
https://topaz.ooo/mcp.json여기에는 구현된 도구 셋과 그 입력, 독립 네이티브 배포판의 정확한 명령, 언어 버전, 검사 전용 안전 경계가 구조화된 형태로 들어 있습니다. topaz_run은 제공하지 않는다고 표시하고, 아직 없는 격리 경계도 함께 밝힙니다.
현재 상태
topaz-mcp 0.1.1은
공개 소스와 릴리스 저장소에서
받을 수 있습니다. 첫 네이티브 패키지는 Apple Silicon Mac을 지원하며
설치된 토파즈 5.16 컴파일러가 필요합니다. 토파즈 5.17이 나왔다고 이 독립
버전 패키지의 식별자를 조용히 바꾸지는 않습니다. 다음 MCP 버전은 내장 참조
집합과 네이티브 패키지를 현재 언어 권위에 맞춰 다시 빌드하고 검증한 뒤에만
5.17을 표시할 수 있습니다. 기계용 서술자는 세 검사 전용 도구를 사용할 수
있다고 표시하고, topaz_run은 계속 제공하지 않는다고 명시합니다.
설치된 한정 Lispex 평가기가 생겨도 이 경계는 달라지지 않습니다. 그 명령은 임의로 제출한 토파즈 소스가 아니라, 고정된 Lispex 제품 계약 하나를 실행합니다.
설치하고 연결하기
0.1.1 릴리스에서 아카이브와 체크섬 파일을 받은 뒤, 압축을 풀기 전에 아카이브를 검증합니다.
shasum -a 256 -c SHA256SUMS
tar -xzf topaz-mcp-0.1.1-aarch64-apple-darwin.tar.gz
아카이브의 SHA-256은
a5c58d66024d5583c8dfd1a16b8f45905cb1fc1837b0c20c58f24c37068e5135입니다.
압축을 푼 서버와 설치된 토파즈 실행 파일의 절대 경로로 로컬 stdio MCP
연결을 설정합니다.
{
"command": "/absolute/path/to/topaz-mcp",
"args": ["serve", "--topaz", "/absolute/path/to/topaz", "--compiler", "self"]
}
연결이 끝나면 클라이언트에는 topaz_spec, topaz_examples,
topaz_check 세 도구만 보여야 합니다.
mcp.json의 verification 블록에는 알려진
참조 절과 예제 개념, 오류 없는 소스 검사가 들어 있습니다. 설정만 믿지
않고 실제로 연결된 서버를 확인할 때 이 값을 사용합니다.
실행 가능한 배포판은 그보다 뒤의 별도 제품입니다. 실행에 필요한 두 격리 장벽과 사용성 검사를 모두 통과한 뒤에만 공개합니다. 사용성 검사는 이 언어를 처음 보는 어시스턴트가 그 서버만 가지고 두 번째 시도에 작은 프로그램을 검사하고 실행하는지 확인합니다.
이어갈 준비가 된 시점
준비된 도구 셋이 각각 무엇에 답하는지, 유용한 검사 전용 패키지가 왜 topaz_run 없이도 공개될 수 있는지, 앞으로 실행하려면 왜 언어 호스트 경계와 별도의 운영체제·자원 격리가 여전히 모두 필요한지 설명할 수 있으면 됩니다.
프로그램이 무엇에 닿을 수 있고 없는지는 상호 운용 개요를, 어시스턴트가 찾아보게 될 형태들은 문법 한눈에 보기를 보세요.