todo-mcp

TODO.md를 저장소로 사용하는 MCP 서버입니다. 파일을 직접 읽고, 편집하고, diff할 수 있습니다. 쓰기는 바이트 범위 스플라이스(byte-range splice)로 이루어지므로, 파일은 계속 사용자 소유로 남습니다. 손으로 작성한 표, 탭 들여쓰기, 작업 본문 밖의 모든 산문은 절대 다시 직렬화되지 않습니다.

MCP 클라이언트에는 stdio로 말하고, 그 외에는 Streamable HTTP로 말합니다.

크레딧

CalamityAdam/mcp-todo를 기반으로 했으며, 원래 스캐폴드를 제공했습니다. 즉, createTodoMcpServer 팩토리 구조와 Express Streamable HTTP 래퍼, 세션 처리를 제공했습니다.

그 외에는 거의 남은 것이 없습니다. 그 버전은 할 일을 ~/.mcp-todos.json의 JSON blob에 번호가 매겨진 레코드로 저장했고, { id, title, done }을 다루는 세 가지 도구가 있었습니다. 이 버전은 저장소를 마크다운 문서로 바꾸고, 숫자형 ID를 슬러그(slug)로 바꾸고, 상태, 영역, 참조 이동 경로, 날짜가 적힌 로그 기록, 전체 텍스트 검색, 중복 감지를 추가하여 도구 표면을 일곱 개로 늘렸습니다. 두 프로젝트는 더 이상 한 구현을 공유하지 않습니다.

업스트림에는 LICENSE 파일이 없고 package.json에서 ISC 라이선스를 선언하고 있습니다. 이 저장소도 ISC를 이어받습니다.

설치

클론 없이 GitHub에서 바로 실행하세요:

npx github:adrianhardy/todo-mcp

변경 사항을 push하고 나면, npx --ignore-existing github:adrianhardy/todo-mcp를 사용해 반영하면 됩니다.

평소에 쓰는 용도라면 한 번 설치하고 잊어버리세요:

npm i -g github:adrianhardy/todo-mcp
todo-mcp

어느 쪽이든 설치 시점에 prepare 스크립트가 소스에서 빌드하므로 dist/는 커밋되지 않습니다. Node 20 이상입니다.

사용법

todo-mcp는 기본적으로 HTTP 서버로 시작합니다. 사용자가 터미널에서 실행할 때는 그게 더 실용적이기 때문입니다. 대신 MCP_STDIO=1을 설정하면 stdio로 말합니다. MCP 클라이언트가 하위 프로세스로 실행할 때는 이 방식이 필요합니다.

MCP 클라이언트에서

{
  "mcpServers": {
    "todo": {
      "command": "npx",
      "args": ["-y", "github:adrianhardy/todo-mcp"],
      "env": { "MCP_STDIO": "1" }
    }
  }
}

글로벌 설치를 사용하면 그 부분은 "command": "todo-mcp"가 되고, env 블록은 그대로입니다.

작업 디렉터리가 어떤 파일을 쓸지 결정합니다. TODO_FILE은 프로세스의 cwd(작업 디렉터리)를 기준으로 해석되고, 기본값은 TODO.md입니다. 그래서 프로젝트 안에서 시작한 클라이언트는 그 프로젝트의 할 일 목록을 편집합니다. 서버가 실제 시작되는 의해 어디서 시작되어도 상관없고 항상 같은 목록을 쓰고 싶다면 TODO_FILE을 절대 경로로 설정하세요.

HTTP로

PORT=8080 TODO_MCP_TOKEN=$(openssl rand -hex 32) todo-mcp

• POST /mcp - JSON-RPC 요청

• GET /mcp - 서버 알림용 SSE 스트림

• DELETE /mcp - 세션 종료

TODO_MCP_TOKEN을 설정하면 이 세 메서드 모두 Authorization: Bearer <token>이 필요합니다. 설정하지 않은 채로 두면 인증이 꺼지는데, 로컬호스트에서는 허용되고 그 외에서는 아무 데서나 열지 말아야 합니다.

구성

.env 파일이 있으면 그 파일을 읽습니다. .env.example 참고하세요.

저장

TODO.md는 그냥 JSON blob이 아니라 저장소 자체입니다. 파일 곧 기록입니다. 사람이 읽을 수 있고, 손으로 편집할 수 있고, git에서 diff할 수 있습니다.

작업 하나는 ## 섹션입니다. 서버가 관리하는 필드는 헤딩 바로 아래 주석 블록에 들어 있고, 그 아래 내용은 사람이 소유한 prose입니다.

## Feature Idea version two: the new widget which tracks things

<!-- todo
id: feature-idea-version-two
area: inventory
status: next
refs: [./src/do_stuff.ts, ClassName.Method, OtherClassName]
created: 2026-08-19
updated: 2026-08-22
-->

**Next step:** close the ledger. ClassName.Method uses 0.25 and it needs 17.2%.

**Already known:** ...

### Log

- 2026-08-22 Slab_Wall_1x3 not started; parade places 24 of those to every 6 of the 3x3.

ID는 숫자가 아니라 slug입니다. 그래서 재정렬이나 삭제에도 살아남습니다. 파일의 순서가 곧 순서이기 때문에, 별도의 priority 필드가 없는 겁니다.

쓰기는 byte-range 스플라이스입니다. 수정은 자기 illus가 소유한 구간만 다시 씁니다. 손으로 만든 표, 탭 들여쓰기, 작업 섹션 밖의 어떤 prose도 다시 serialized는 없고, 따라서 다시 포맷되거나 손실될 일이 없습니다. 핸들러는 lock으로 강제 직렬화합니다. 왜냐하면 두 개의 번째가 서로 얽히며 읽기-수정-쓰기를 하면, 이제 않는 시점의 오프셋에 스플라이스하는 게 될 테니까요.

설계

• list는 짧게 줄입니다. list_todos는 한 줄 by index만 반환하고 작업 본문을 반환하지 않습니다. get_todo는 한 섹션 전체를 반환합니다. q나 ref가 의도된 경로이고, 목록을 통째로 나열하는 것은 예외적인 경우입니다.

• 캡처에는 필드 하나만. title만 필수이고, 새 작업의 상태 기본값은 captured입니다. 무언가 발견한 사실을 일단 기록할 때 그 자리에서 영역(area)과 다음 단계를 요구하는 그런 인터페이스는 실제로 쓰이지 않습니다. 그러니 처음에 발견 그대로 기록해야 이 파일이 존재할 가치가 (유지됩니다. triage로 나중에 captured를 open/next/parked/someday로 옮기면 됩니다.

상태 값

도구

• list_todos - 한 줄로 줄인 목록; area, status, ref, q, limit

• get_todo - 작업 하나의 전체 마크다운. 본문 포함

• add_todo - 작업 하나를 캡처; title만 필요. 가능한 중복도 알려줍니다

• update_todo - 어떤 필드든 수정; 전달한 것만 그 부분이 다시 쓰는

• append_note - 작업의 로그에 본문에 날짜가 적힌 불릿 하나 추가

• set_status - 작업을 분기/triage 단계로 단계로 옮기기

• remove_todo - 작업과 본문을 삭제합니다. set_status done을 먼저 권장

리소스

• todos://list - open 작업들을 한 줄 목록으로 보여줌

아키텍처

• src/todo.ts - markdown 저장소: 파싱, byte-range 패치, 쿼리, 중복 제거

• src/server.ts - MCP 도구 표면. import 시 부작용 없는 순수 팩토리

• src/http.ts - Streamable HTTP transport, auth, 그리고 세션 map

• src/cli.ts - todo-mcp binary. transport를 선택하고 시작