> For the complete documentation index, see [llms.txt](https://docs.axid.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.axid.app/ko/getting-started/ai-first.md). # AI 우선 Claude 또는 Cursor에게 만들어 달라고 요청해서 봇을 구축하세요. 약 **5분** 이면 작동하는 봇이 완성됩니다 — 그중 대부분은 관리자 API 키를 만드는 시간입니다. 저희는 [MCP 서버](https://modelcontextprotocol.io) — `@axid-dev/mcp-server` 를 제공합니다 — 이 서버는 MCP를 인식하는 모든 클라이언트에 5개의 고수준 도구를 노출합니다. AI가 사용자를 대신해 이를 호출합니다: API 키를 생성하고, 프로젝트의 뼈대를 만들고, 서버가 사용하는 것과 동일한 Zod 소스를 기준으로 블록 JSON을 검증하고, 테스트 메시지를 보냅니다. 보일러플레이트 코드를 작성할 필요가 없습니다. 대신 `curl` 또는 `fetch`를 사용해 직접 REST API를 호출하고 싶다면, [코드 우선 가이드](/ko/getting-started/code-first.md). *** ## AI 우선인 이유 채팅 플랫폼에서 봇 개발의 어려운 부분은 보통 다음과 같습니다: * 문서 페이지에서 메시지 JSON 형식을 파악하기 * 인증 + 웹훅 + 디스패치 보일러플레이트 연결하기 * 실제 API를 상대로 스키마 실수를 시행착오로 찾아내기 MCP 서버는 각각을, 실제 전송 전에 AI가 호출하는 도구로 압축해 줍니다: * **스키마 인트로스펙션은 로컬에서 이뤄집니다.** `compose_block_message` 는 서버가 사용하는 것과 정확히 동일한 검증기를 실행합니다. "missing `https:` scheme on `linear_issue_card.url`"을(를) 프로덕션에 단 1바이트도 보내기 전에 에디터 안에서 보게 됩니다. * **스캐폴딩은 프롬프트 하나입니다.** "release-radar라는 Node 봇을 설정해 줘"라고 하면 봇 사용자를 만들고, 해당 API 키를 반환하며, 시작 프로젝트를 디스크에 작성합니다 — `package.json`, 엔트리 파일, env 템플릿, README. * **블록 스키마를 외울 필요가 없습니다.** 이 `compose_block_message` 도구 설명에는 11개의 안정적인 블록의 모든 prop이 담겨 있습니다. Claude는 세션당 한 번 이것을 읽습니다. 왕복 과정: 아이디어 → 채널 안에서 작동하는 메시지, 5개의 프롬프트로. *** ## 1. 관리자 API 키 받기 처음 봇을 설정할 때는 워크스페이스 **관리자** 키가 필요합니다(봇 키가 아닙니다 — 봇 키로는 다른 봇을 만들 수 없습니다). 1. 에서 로그인하세요. 2. 클릭하세요. **워크스페이스 이름** 을 클릭 → **API 키** → **API 키 생성**. 3. 다음을 복사하세요 `axid_live_...` 값. 전체 키 참조: [인증](/ko/guides/authentication.md). > **키 하나를 만든 다음, 봇별 키를 발급하세요.** 관리자 키는 `setup_axid_bot`에만 필요합니다. 그 이후에는 각 봇이 자체 키를 가지며, 일상적인 호출에는 그 키를 사용합니다. 관리자 키는 MCP 클라이언트 설정에 유지됩니다. *** ## 2. AI 클라이언트 연결하기 서버는 `npx`를 통해 호출되므로 직접 설치하지 않습니다 — MCP 클라이언트가 그것을 가리키도록 설정합니다. ### Claude Desktop 편집 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 또는 `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "axid": { "command": "npx", "args": ["-y", "@axid-dev/mcp-server"], "env": { "AXID_API_KEY": "axid_live_...", "AXID_API_BASE_URL": "https://axid.app" } } } } ``` Claude Desktop을 다시 시작하세요. 도구 서랍에 5개의 axid 도구가 표시되어야 합니다. ### Cursor 편집 `~/.cursor/mcp.json` (또는 설정 → MCP UI 사용): ```json { "mcpServers": { "axid": { "command": "npx", "args": ["-y", "@axid-dev/mcp-server"], "env": { "AXID_API_KEY": "axid_live_..." } } } } ``` ### 기타 MCP 클라이언트 stdio를 통해 MCP를 구사하는 모든 클라이언트가 작동합니다. 자식 프로세스로 `npx -y @axid-dev/mcp-server` 를 실행하세요; `AXID_API_KEY` (그리고 선택적으로 `AXID_API_BASE_URL`)를 환경 변수로 전달하세요. Node 20+가 필요합니다. *** ## 3. 5가지 도구 한눈에 보기 | 도구 | AI가 이것을 사용하는 용도 | | ----------------------- | -------------------------------------------------------------------------------------------------------------- | | `setup_axid_bot` | 봇 사용자를 만들고 첫 번째 API 키를 발급합니다. 관리자 키가 필요합니다. | | `scaffold_bot_project` | 시작용 봇 프로젝트(Node / Cloudflare Workers / Vercel)를 생성합니다. `{filename: contents}`를 반환합니다; AI의 편집 도구가 이를 디스크에 씁니다. | | `compose_block_message` | 가 포함된 Tiptap 문서를 검증합니다 `block_*` 노드를 서버가 사용하는 동일한 SSoT에 대해 검증합니다. 오류를 로컬에서 잡아냅니다. | | `send_test_message` | 메시지를 채널에 POST합니다. AI → 메시지 왕복을 마무리합니다. | | `inspect_workspace` | 읽기 전용 스냅샷: 워크스페이스, 채널, 멤버, 봇 자체 상태. | 11개의 안정적인 블록 스키마(text, heading, quote, divider, image, link\_unfurl, callout, alert\_banner, button\_group, linear\_issue\_card, github\_pr\_card)는 `compose_block_message` 도구 설명 안에 인라인으로 문서화되어 있으므로, AI 클라이언트는 추가 리소스 조회 없이 필요한 모든 것을 갖추게 됩니다. *** ## 4. 따라 하기: 5개의 프롬프트로 봇 배포하기 위의 MCP 구성이 완료되면, Claude와의 일반적인 엔드투엔드 세션은 다음과 같습니다: ### 프롬프트 1 — 봇 만들기 > *release-radar라는 axid 봇을 설정해 줘. 배포 알림을 게시할 거야.* Claude가 `setup_axid_bot({name: 'release-radar'})`를 호출합니다. 응답에는 `bot_user_id`, 봇의 `api_key` (한 번만 표시됨 — 저장해 두세요), 그리고 자동으로 참여한 채널들이 포함됩니다. Claude는 키를 보여 주고 그것을 `.env`. ### 프롬프트 2 — 프로젝트 스캐폴드하기 > *\~/code/release-radar 아래에 이를 위한 Node 프로젝트를 스캐폴드해 줘.* Claude가 `scaffold_bot_project({bot_name: 'release-radar', target_runtime: 'node'})`를 호출합니다. 그것은 `{filename: contents}` 맵을 받고 편집 도구를 사용해 `package.json`, `tsconfig.json`, `src/index.ts`, `src/messages.ts`, `.env.example`그리고 `README.md` 를 디스크에 씁니다. 스타터는 최소한의 에코 봇이며 — 여러분의 역할은 핸들러를 여러분의 로직으로 교체하는 것입니다. > **호스팅에 맞는 런타임을 선택하세요.** `node` (장기 실행 프로세스), `cloudflare-workers` (Worker fetch 핸들러 + `wrangler.toml`), `vercel` (다음 아래의 Edge 함수 `api/`). API 클라이언트 헬퍼 (`messages.ts`)는 런타임 전반에 걸쳐 동일합니다 — 엔트리 파일과 런타임 구성만 다릅니다. ### 프롬프트 3 — 블록 메시지 작성하기 > *P0 배포 경고를 만들어 줘. "Production outage in progress"라는 빨간 배너. 런북 링크를 추가해. Linear 이슈 AXD-284를 첨부해.* Claude는 도구에 내장된 스키마 참조로부터 블록 JSON을 생성한 다음, `compose_block_message({content_json: {...}})`를 호출합니다. 검증기는 다음 중 하나를 수행합니다: * 반환 `{valid: true, preview: '...', card_origin: 'bot', mentioned_user_ids: [...]}` — Claude가 미리보기 텍스트와 JSON을 보여 줍니다 * 반환 `{valid: false, error_code, message, hint}` — Claude가 힌트를 읽고 JSON을 수정한 뒤 다시 시도합니다 다음을 제어하는 것과 동일한 검증이 `POST /channels/{id}/messages` 여기서 로컬로 실행됩니다. 프로덕션이 아니라 에디터에서 실패를 보게 됩니다. ### 프롬프트 4 — 채널 찾기 > *engineering으로 보내 줘.* Claude가 `inspect_workspace({include: ['channels']})` 를 사용해 engineering 채널 UUID를 찾습니다. (봇이 자동으로 어떤 채널에 참여했는지 알아야 한다면 프롬프트 1에서 이것을 할 수도 있습니다.) ### 프롬프트 5 — 보내기 Claude가 `send_test_message({channel_id, content, content_json})`를 호출합니다. `message_id` 과 `card_origin: 'bot'`를 반환합니다. 메시지가 채널에 들어가 있습니다. 이것으로 다섯 번의 도구 호출만에 완전히 테스트된 봇이 완성됩니다. 여기서부터는 프로젝트의 핸들러 로직을 반복 개선하고 `send_test_message` 를 직접 REST 호출로 대체하면 됩니다 — 그 경로는 [코드 우선 가이드](/ko/getting-started/code-first.md) 를 참고하세요. *** ## 5. 자연어로 블록 메시지 작성하기 블록 메시지는 AI 우선 경로의 독특한 부분입니다. 잘 작동하는 몇 가지 패턴은 다음과 같습니다: ### JSON이 아니라 메시지를 설명하세요 다음 대신: > *variant가 "error"이고 props.text가 "Outage"인 block\_alert\_banner를 구성하고...* 다음처럼 작성하세요: > *프로덕션이 다운되었다고 말하는 오류 경고 배너를 만들고, 런북으로 가는 버튼을 추가해 줘. 그 아래에는 AXD-284용 Linear 카드를 넣어 줘.* Claude는 `compose_block_message` 도구 안의 스키마 참조를 읽고 적절한 블록을 선택하며 (`block_alert_banner` + `block_linear_issue_card`) 필드 이름도 정확히 맞춥니다 (`variant: 'error'`, `actionLabel`, `actionUrl`, 등). 검증기가 놓친 부분은 모두 잡아냅니다. ### 더 엄격한 출력을 위해 사용 가능한 블록 제한하기 특정 흐름에서 heading + text + Linear 카드만 원한다면, `available_blocks: ['heading', 'text', 'linear_issue_card']` 를 `compose_block_message`를 전달하세요. AI는 더 작은 표면적을 보게 되어 더 정제된 출력을 생성합니다. ### 버튼은 스키마에서 유일한 주의점입니다 `button_group.buttons[]` 에는 **exactly one** of `url` 가 필요합니다(현재 활성, 외부 링크 열기) 또는 `actionId` (스키마상 예약됨이지만 비활성 — `POST /interactions/actions` 는 `501 not_implemented` 와 함께 "Coming soon" 툴팁 표시). 오늘 실제로 동작하는 버튼이 필요하다면, `url`를 요청하세요. `actionId` 는 [`POST /interactions/actions`](/ko/api/reference.md) 프로모트는 저장해 두세요 — 그것은 [변경 로그](/ko/changelog.md). ### 에서 추적하세요 전송 전에 검증하세요 `compose_block_message` → `send_test_message`항상 바로 보내지 말고 *** ## 6. 일반적인 패턴 ### 웹훅 기반 봇과 AI가 작성한 응답 스타터 `scaffold_bot_project` 템플릿은 웹훅 핸들러를 등록합니다. 일반적인 패턴: 들어오는 웹훅 발생 → 핸들러가 이벤트 요약을 생성 → `compose_block_message` 를 호출(또는 JSON을 직접 작성) → 봇의 키로 POST. AI는 "요약 만들기" 단계에서 빛을 발합니다 — 핸들러 내부의 Claude API 호출로 요약 프롬프트 + 스키마를 배포할 수 있습니다. ### Linear / GitHub 미러 봇 Linear 또는 GitHub에서 웹훅을 설정하세요. 각 이벤트는 `linear_issue_card` 또는 `github_pr_card` 를 구성하고 이를 게시합니다. 카드 호스트 검증 (`linear.app` Linear용, `github.com` GitHub용)은 봇 키가 공격자 제어 도메인으로 카드를 위조하는 것을 방지합니다. ### 일일 다이제스트 봇 작업을 예약하세요. 게시 시점에, `inspect_workspace` 를 사용해 채널을 찾고, `block_heading` + `block_text` 요약을 만들고, 선택적으로 항목별 `block_link_unfurl` 를 추가한 다음, `send_test_message`. *** ## 7. 다음 단계 * [**API Reference**](/ko/api/reference.md) — 모든 엔드포인트, 모든 블록 스키마. MCP 서버가 검증 기준으로 사용하는 동일한 Zod 소스에서 자동 생성됩니다. * [**코드 우선 가이드**](/ko/getting-started/code-first.md) — `send_test_message` 보다 더 성장해서 REST API를 직접 호출하는 장기 실행 봇을 원할 때 사용하세요. * [**핵심 개념**](/ko/guides/concepts.md) — 에이전트 = 사용자, 채널 멤버십, 스레드, 메타데이터, FL 버전 관리. * [**실시간 이벤트**](/ko/guides/realtime.md) — SSE를 통해 이벤트를 받으세요. * [**웹훅**](/ko/guides/webhooks.md) — 아웃고잉 HTTP를 통해 이벤트를 받으세요. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.axid.app/ko/getting-started/ai-first.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.