AI 에이전트와 MCP

어시스턴트를 토파즈에 연결해 문법을 찾고, 코드를 검사하고, 실행 결과를 확인하세요. URL을 읽는 어시스턴트에는 아래 참조 파일을 전달하세요.

도구를 호출하려면 토파즈를 설치하고 로컬 MCP를 지원하는 어시스턴트를 사용하세요. MCP는 어시스턴트가 도구 목록을 찾고 도구를 호출할 때 쓰는 통신 규약입니다.

도구 연결하기

클라이언트의 로컬 MCP 서버 설정에 다음 명령을 추가하세요.

JSON

{
  "command": "topaz",
  "args": ["mcp", "serve"]
}

클라이언트는 설치된 실행 파일을 시작하고 표준 입력과 출력으로 메시지를 주고받습니다. 이 통신 방식을 stdio라고 부릅니다. 토파즈는 지원하는 모든 네이티브 플랫폼에서 서버와 실행 작업자를 함께 제공합니다. 서버를 따로 내려받거나 작업자 경로를 지정할 필요가 없습니다.

연결하면 topaz_spec, topaz_examples, topaz_check, topaz_run이 도구 목록에 나타나야 합니다. topaz를 시작하지 못하면 설치 상태와 클라이언트가 사용하는 실행 파일 경로를 확인하세요.

도구를 호출해 연결 확인하기

다음 표의 도구 이름과 JSON 입력으로 호출하세요. 예상 결과는 mcp.json의 verification에도 있습니다.

도구	입력	응답에서 확인할 내용
`topaz_spec`	`{"section":"The everyday working set"}`	`status`가 `found`이며 요청한 참조 절이 나옴
`topaz_examples`	`{"concept":"function"}`	`status`가 `found`이며 설치된 참조 자료의 함수 예제가 나옴
`topaz_check`	`{"source":"function main() -> int { 42 }\n"}`	`status`가 `clean`이며 `diagnostics`가 비어 있음
`topaz_run`	`{"source":"let answer = 40 + 2\nanswer\n"}`	`status`가 `completed`이며 `value`가 `"42"`임

topaz_check는 문법·이름·타입 진단을 코드와 소스 위치 그대로 반환합니다. status가 diagnostics이면 제출한 소스에서 진단이 가리키는 위치를 고친 뒤 다시 호출하세요. 애플리케이션 동작은 실제 사용할 입력으로도 테스트하세요.

topaz_run은 소스를 검사한 뒤 새 작업자 프로세스를 시작합니다. 검사 응답에서는 toolchain과 compiler_selection을 읽으세요. 실행 응답은 semantic_identity와 execution_identity로 제품과 작업자 정보를 알려 줍니다. 기본 컴파일러는 self입니다. Rust는 비교할 때 --compiler rust로 명시해 고르는 참조 컴파일러입니다. 자세한 내용은 툴체인 상태를 참고하세요.

에이전트 팩 규칙 적용하기

프로필은 소스 검사에 이름이 있는 규칙을 추가합니다. 에이전트 팩 규칙을 쓰려면 topaz_check 입력의 source 옆에 "profile":"agent-pack"을 추가하세요.

응답 스키마는 topaz.mcp-check-result/v2이며 profile: "agent-pack"을 포함합니다. 프로필 규칙이 소스를 거부하면 진단의 data.profileRule에서 규칙 이름을 찾으세요. 프로필 규칙에 맞춰 해당 연산을 고치세요. profile을 생략하면 응답 스키마는 topaz.mcp-check-result/v1입니다.

제출한 코드의 접근 권한 확인하기

신뢰할 수 있는 코드를 제출하세요. 작업자는 호스트 작업을 차단하지만 운영체제 수준의 격리는 제공하지 않습니다.

호출마다 설치된 토파즈 실행 파일에서 새 작업자를 시작합니다. 제출한 코드는 파일 시스템·네트워크 접근, 호스트 탐색, 콜백, 구성 요소 로딩을 사용할 수 없습니다. 실패 시 다른 경로로 실행하는 폴백도 없습니다. 호출끼리 실행 상태를 공유하지 않습니다. 소스는 표준 입력으로 전달하며 기록하거나 보관하지 않습니다.

한도	동작
동시 실행 2개	추가 호출은 대기열 없이 거부
실행당 5초	실제 경과 시간 한도를 넘은 작업자 종료
응답 1 MiB	응답 크기 한도를 넘은 작업자 종료
호출 취소	작업자를 종료하고 프로세스 회수

서버는 종료한 작업자를 회수한 뒤 응답합니다. 결과를 사용하기 전에 응답 상태를 읽으세요. 이 한도는 CPU·메모리 사용량의 강제 상한을 설정하지 않습니다.

URL을 읽는 어시스턴트에 참조 전달하기

토파즈 코드를 쓰기 전에 다음 파일을 읽도록 요청하세요.

https://topaz.ooo/agents.md

파일 구조, 문법, 호스트 접근, 프로필을 설명합니다. Vec<T>, async, try, 클래스 등 지원하지 않는 표기도 나옵니다. 값이 없는 경우에는 지원하는 T | null 표기와 모든 부재를 null로 표현하는 방식을 구분합니다.

어시스턴트가 필요한 자료의 범위에 맞춰 다른 URL도 선택할 수 있습니다.

URL	내용
`https://topaz.ooo/llms.txt`	간략한 문서 색인
`https://topaz.ooo/llms-full.txt`	전체 영문 매뉴얼의 Markdown
`https://topaz.ooo/docs/<slug>.md`	영문 페이지 하나와 머리말 메타데이터의 제목·원문 경로·명세 절
`https://topaz.ooo/version.json`	사이트가 제공하는 버전
`https://topaz.ooo/mcp.json`	도구 입력, 로컬 명령, 실행 한도, 연결 확인값

문법 표기는 문법 한눈에 보기에서 찾으세요. 프로그램을 다른 시스템에 연결하려면 상호 운용 개요로 이어가세요.