MCP 도구

tuckit MCP 서버가 /mcp에서 제공하는 도구들입니다. 언제 어느 걸 쓰는지는 매일의 흐름 쪽에 있습니다.

쓰시는 AI가 보여주는 도구 목록이 기준입니다. 이 페이지와 다르면 그쪽을 믿으세요. 서버가 자기 자신을 설명하는 쪽이니까요.

한눈에

도구	무엇을 하나
`get_project_state`	시작점. 보드 전체 요약과 호출자 정보
`list_areas`	영역 이름과 id
`create_area`	영역 추가
`list_slices`	카드 검색과 필터
`get_slice`	카드 하나 전체를 마크다운으로
`create_slice`	카드 만들기
`update_slice`	고치기, 영역에 넣기, 순서 바꾸기, 판정하기
`add_note`	기록 남기기
`append_decision`	어떻게 정했는지 기록에 한 편 붙이기
`record_verification`	실제로 본 것을 적기

용어는 화면에 보이는 것들과 이렇게 대응합니다. 도구 이름의 slice는 화면의 카드, area는 영역입니다.

읽기

`get_project_state`

여기서 시작합니다. 한 번 호출하면 호출자 정보, 워크스페이스, 보관되지 않은 모든 영역을 끝난 것과 할 것으로 나눠서, 그리고 Inbox 개수를 줍니다.

인자	타입	비고
`area_id`	int, 선택	영역 하나로 좁힘

caller(user_email, workspace_slug, workspace_name), workspace, inbox(open_count와 최근 열 개), 그리고 각 영역의 shipped[], roadmap[], 개수를 담은 areas[]를 돌려줍니다.

inbox는 아직 영역이 없는 카드를 셉니다. 중요하다고는 판단했는데 어디 속하는지는 아직 정하지 않은 것들입니다. 별도의 물건이 아니라 그냥 카드입니다.

`list_areas`

인자 없음. 보관되지 않은 모든 영역의 id, name, slug를 돌려줍니다.

카드를 영역에 넣기 전에 먼저 호출하세요. 쓰는 도구가 받는 게 영역 id인데, AI가 추측하면 실패하거나 비슷한 이름의 영역을 하나 더 만듭니다.

`list_slices`

검색과 필터. 인자는 전부 선택입니다.

인자	타입	비고
`area_id`	int \| `''`, 선택	생략하면 Inbox 포함 워크스페이스 전체, `''`면 Inbox만
`status`	string, 선택	`open`, `shipped`, `dropped`
`tag`	string, 선택
`query`	string, 선택	제목과 `spec` 본문 검색
`assignee`	string, 선택	`'me'` 또는 이메일
`limit`	int, 선택	기본 50

각 행에 계산된 stage가 붙어 있어서, 카드를 열지 않고도 다음에 뭐가 필요한지 볼 수 있습니다.

area_id 인자는 뜻이 세 가지고 섞기 쉽습니다. 생략하면 전체 검색. ''면 Inbox만, 즉 영역이 없고 아직 안 끝난 카드들이고, get_project_state가 센 것과 정확히 같은 집합입니다. 숫자를 주면 그 영역으로 좁힙니다.

영역에 한 번도 안 들어간 채로 끝났거나 취소된 카드는 Inbox를 벗어난 상태라서 area_id=''로는 안 나옵니다. 그런 걸 찾으려면 area_id를 생략하고 status를 주세요.

`get_slice`

카드 하나를 마크다운으로 돌려줍니다. 제목, Status:, Stage:, 그다음 spec, ## Constraints, ## Done when, ## Decisions.

인자	타입	비고
`slice`	int \| string	내부 id 또는 `ACME-42` 같은 번호
`with_activity`	bool, 선택	기록까지 같이

일에 손대기 전에 이걸 읽으세요. 진행 상황은 Status:가 아니라 Stage: 줄에 있습니다.

쓰기

`create_area`

인자	타입	비고
`name`	string	필수
`description`	string, 선택

영역은 오래 갑니다. 먼저 list_areas로 확인하세요. backend라는 영역이 하나 더 생기면 보드가 갈라지는데, 몇 주 동안 아무도 눈치를 못 챕니다.

`create_slice`

인자	타입	비고
`title`	string	필수
`area_id`	int \| `''`, 선택	비우면 Inbox에 들어갑니다
`spec`	string, 선택	뭘 만들 건지
`constraints`	string, 선택	지뢰, 지켜야 할 것
`done_when`	string, 선택	무엇을 봐야 이게 끝났다고 할 수 있나
`status`	string, 선택	기본 `open`
`tags`	string[], 선택
`assignee`	string, 선택	`'me'` 또는 이메일
`external_key`	string, 선택	같은 키면 새로 만들지 않고 고칩니다
`after_id` / `before_id`	int, 선택	다른 카드 기준 위치

아직 생각이 안 끝난 일이면 spec을 비워두세요. 비어 있는 게 needs_design으로 읽히는 근거입니다. 대충 한 줄 채워두면 다음에 이걸 잡는 쪽에는 정해진 일처럼 보입니다.

자동화에서는 external_key가 핵심입니다. 같은 키를 주면 새 카드를 만드는 대신 있던 걸 고치기 때문에 다시 돌려도 안전합니다.

`update_slice`

안 준 필드는 그대로 둡니다.

인자	타입	비고
`slice_id`	int	필수. 내부 id
`title`, `spec`, `constraints`, `done_when`	string, 선택
`area_id`	int \| `''`, 선택	id를 주면 그 영역으로, `''`면 Inbox로
`status`	string, 선택	`open`, `shipped`, `dropped`. 판정만
`tags`	string[], 선택
`assignee`	string, 선택	`''`로 비우기, `'me'`, 또는 이메일
`after_id` / `before_id`	int, 선택	순서 변경

영역에 넣고 빼는 건 양방향 다 되고, 어느 쪽도 되돌릴 수 없는 동작이 아닙니다.

status는 판정만 담습니다. 여기서 진행 상황을 읽지 마세요. 진행 상황은 list_slices와 get_slice가 둘 다 주는 stage에 있습니다.

`add_note`

인자	타입	비고
`slice`	int \| string	내부 id 또는 번호
`body`	string	필수

카드의 기록에 한 줄 붙입니다. 기록은 지나간 일입니다. 뭘 시도했고, 뭐가 막혔고, 어디에 올렸는지. spec이 뭘 만들 건지고, constraints가 계속 지켜야 할 경고고, 기록이 실제로 있었던 일입니다.

`append_decision`

인자	타입	비고
`slice_id`	int	필수
`body`	string	필수

카드의 결정 기록에 한 편을 붙입니다. 날짜와 누가 썼는지는 서버가 찍으므로 본문에는 판단만 적으면 됩니다. 무엇을 골랐고, 왜 골랐고, 무엇을 버렸고, 이 결정이 무엇에 기대고 있는지.

붙이기만 합니다. 이 기록을 통째로 고치는 도구는 없고, 그건 일부러 그렇게 둔 것입니다. spec은 지금 참인 것이라 일이 움직이면 같이 고쳐지고, 이 기록은 그때 어떻게 여기까지 왔는지의 스냅샷이라 고쳐지면 안 됩니다.

`record_verification`

인자	타입	비고
`slice_id`	int	필수
`evidence`	string	실제로 본 것. 빈 문자열을 주면 취소됩니다

확인한 것을 적고 시각을 찍습니다. 그 시각이 카드를 ready_to_ship으로 옮기고, 이게 비어 있으면 화면에서 카드를 shipped로 넘길 수 없습니다.

돌린 명령이 아니라 본 것을 적으세요. pytest -q는 명령이고, “만료된 토큰이 성공 응답 안의 에러가 아니라 HTTP 401로 왔다”는 관찰입니다. 둘 중 틀린 것으로 밝혀질 수 있는 건 후자뿐입니다.

이건 증명이 아니라 주장입니다. tuckit은 남의 테스트를 돌려줄 수 없고 적힌 내용을 심사하지도 않습니다. tuckit이 하는 일은 아무도 주장을 적지 않은 동안 되돌릴 수 없는 버튼을 열지 않는 것뿐입니다.

evidence에 빈 문자열을 주면 취소되고 카드가 executing으로 돌아갑니다. 적어둔 것이 더는 참이 아니게 된 순간 그렇게 하세요.

도구로 만들지 않은 것

stage를 설정하는 도구는 없습니다. 계산되는 값이니까요. 가볍게 적어둔 걸 무거운 물건으로 승격시키는 도구도 없습니다. 물건이 한 종류뿐이니까요. 단계 목록도 없습니다. 아무도 안 읽었으니까요. 그리고 대신 “끝냈다”고 표시해주는 도구도 없습니다. 그건 update_slice에 status를 명시적으로 주는 것이고, 사람이 그렇게 말한 다음에 해야 합니다.