MCP 도구

tuckit MCP 서버는 /mcp에서 열한 개 도구를 제공합니다. 언제 어느 걸 쓰는지는 매일의 흐름 쪽에 있습니다.

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

한눈에

도구	무엇을 하나
`get_project_state`	시작점. 보드 전체 요약과 호출자 정보
`list_areas`	영역 이름과 id
`create_area`	영역 추가
`list_slices`	카드 검색과 필터
`get_slice`	카드 하나 전체를 마크다운으로
`create_slice`	카드 만들기
`update_slice`	고치기, 영역에 넣기, 순서 바꾸기, 판정하기
`add_note`	기록 남기기
`list_bites`	카드의 단계 목록
`add_bites`	단계 추가
`update_bite`	단계 하나 진행

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

읽기

`get_project_state`

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

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

caller(user_email, org_slug, org_name), org, 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, 그리고 끝난 단계에 [x]가 붙은 ## Steps.

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

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

`list_bites`

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

순서대로 단계와 각각의 상태를 돌려줍니다.

쓰기

`create_area`

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

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

`create_slice`

인자	타입	비고
`title`	string	필수
`area_id`	int \| `''`, 선택	비우면 Inbox에 들어갑니다
`spec`	string, 선택	뭘 만들 건지
`constraints`	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`	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가 계속 지켜야 할 경고고, 기록이 실제로 있었던 일입니다.

`add_bites`

인자	타입	비고
`slice_id`	int	필수
`bites`	object[]	`{ title, body?, status? }`, 순서대로 붙습니다

카드에 spec이 채워진 다음에 하세요. spec은 있는데 단계가 없으면 needs_steps로 읽히고, 단계를 넣으면 executing으로 넘어갑니다.

`update_bite`

인자	타입	비고
`bite_id`	int	필수
`title`, `body`	string, 선택
`status`	string, 선택	`todo`, `doing`, `done`, `dropped`
`after_id` / `before_id`	int, 선택	순서 변경

마지막에 몰아서 하지 말고 진행하면서 그때그때 체크하세요. 사람도 다음 세션도 일이 어디까지 왔는지 그걸로 봅니다. 그리고 마지막 하나를 체크하면 카드가 알아서 ready_to_ship으로 갑니다.

도구로 만들지 않은 것

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