학습 결과: 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 경로가 존재하며, 프론트매터에 제목, 원문 경로, 대응하는 명세 절을 보존합니다. https://topaz.ooo/version.json은 응답하는 버전을 알려 줍니다.
타인을 위해 어시스턴트를 설정하는 경우 해당 URL 하나만 전달하면 설정이 완료됩니다.
도구가 푸는 문제
문서를 수신하는 것만으로도 어시스턴트가 올바른 구문을 작성하게 됩니다. 다만 방금 작성한 프로그램이 실제로 컴파일되는지까지는 알려 주지 못합니다.
생소한 언어를 다루는 어시스턴트는 두 가지 방식을 취합니다. 문서를 읽고 추측하거나, 먼저 작성한 뒤 오류 내역을 정확히 전달받아 수정하는 것입니다. 두 번째 루프는 문서가 부실하더라도 동작하는 코드를 생성합니다. 첫 번째 방식은 컴파일되지 않는 그럴듯한 글을 출력할 뿐입니다. 참조 문서만으로는 첫 번째 루프에 머물게 되며, 검사기를 도입해야 두 번째 루프 전환이 가능해집니다.
공개된 네 도구
| 도구 | 답하는 질문 |
|---|---|
topaz_spec | 이 부분의 정확한 형태는 무엇인가 |
topaz_examples | 이 개념의 검증된 코드를 보여 달라 |
topaz_check | 방금 작성한 코드가 올바른가, 오류가 있다면 정확히 어느 위치인가 |
topaz_run | 무권한 실행 경계에서 이 프로그램이 어떤 결과를 출력하는가 |
topaz_check는 컴파일러가 생성한 진단 결과와 코드, 소스 위치를 변형 없이 그대로 반환합니다. topaz_run은 동일한 검사를 먼저 수행한 후 호출마다 새로운 실행 작업자를 시작합니다. 두 도구 모두 답변을 생성한 툴체인 설치 정보와 컴파일러 옵션을 명시하므로, 어시스턴트는 요약문이 아닌 실제 결과를 바탕으로 자신의 출력을 수정할 수 있습니다.
topaz_check는 선택 입력 profile: "agent-pack"을 받습니다. 프로파일을 지정한 호출은 같은 설치 컴파일러를 에이전트 팩 규칙으로 평가하며, 그 응답은 스키마 topaz.mcp-check-result/v2이고 profile: "agent-pack"을 함께 싣습니다. 프로파일 거부는 각 진단의 data.profileRule에 규칙 이름이 들어가며, profile을 생략하면 기존 topaz.mcp-check-result/v1 응답 그대로입니다.
실행 경계
topaz_run은 호출 시마다 설치된 동일한 토파즈 실행 파일의 숨은 작업자를 새롭게 시작하며, 어떠한 기능도 제공하지 않는 호스트를 사용합니다. 파일 시스템, 네트워크, 탐색, 콜백, 구성 요소 및 폴백 경로는 제공되지 않습니다. 동시 호출은 최대 2개로 제한되며 대기열은 두지 않고, 5초의 실행 시간과 1 MiB의 응답 한도를 적용합니다. 취소되거나 한도를 초과한 작업자는 응답을 반환하기 전에 종료 후 회수합니다. 제출된 소스는 표준 입력으로만 전달되며 기록되거나 보관되지 않습니다.
이 실행 경계는 토파즈가 지원하는 모든 네이티브 타깃에 포함되어 있습니다. 제한이 없는 일반 topaz run 환경은 아니며, 운영체제 샌드박스나 CPU 및 RSS의 hard bound가 적용된 것도 아닙니다. 적대적인 코드를 제출하지 마세요.
기계가 읽는 서술자
클라이언트와 크롤러는 서버 설명을 직접 조회할 수 있습니다.
https://topaz.ooo/mcp.json여기에는 네 가지 도구와 입력, 내장 명령, 리소스 경계, 그리고 설치 후 검사값이 구조화되어 정리되어 있습니다.
현재 상태
토파즈 5.18.1은 네이티브 topaz 실행 파일 내에 MCP 서버와 작업자를 함께 담아서 제공합니다. 토파즈를 설치하면 MCP 서버가 자동으로 포함됩니다. 별도의 아카이브, 체크섬, 서버·작업자·승인 파일 경로는 존재하지 않습니다.
설치하고 연결하기
토파즈를 설치한 후 다음 로컬 stdio 명령을 설정합니다.
{
"command": "topaz",
"args": ["mcp", "serve"]
}연결이 완료되면 클라이언트에는 topaz_spec, topaz_examples, topaz_check, topaz_run 네 가지 도구가 노출되어야 합니다. mcp.json의 verification 블록에는 알려진 참조 절, 예제 개념, 오류가 없는 검사용 소스, 그리고 출력값이 42인 순수 실행 예제가 포함되어 있습니다. 단순히 설정값만 신뢰하지 않고 실제 서버 동작을 검사할 때 이 값을 활용하십시오.
이어갈 준비가 된 시점
정확한 참조를 검색하고 컴파일러 진단 결과를 바탕으로 소스를 고친 뒤, 설치된 무권한 작업자로 순수 프로그램을 실행할 수 있는 상태가 되면 됩니다.
프로그램이 접근할 수 있는 대상과 범위는 상호 운용 개요를, 어시스턴트가 참조하게 될 구문 형태는 문법 한눈에 보기를 참고하십시오.