읽기 전용 MCP 서버 완성하기: 6개의 도구에서 9개로

이 글은 GitHub Finish-Up-A-Thon Challenge를 위한 제출물입니다.

내가 만든 것

나는 미완성 상태였던 DEV.to용 오픈 소스 MCP (Model Context Protocol) 서버를 가져와서 누락된 나머지 절반을 추가했습니다.

원본 저장소(nickytonline/dev-to-mcp)는 실제 DEV.to 엔지니어가 구축했으며, 6개의 읽기 전용 도구인 get_articles, get_article, get_user, get_tags, get_comments, search_articles를 제공했습니다. 읽기에는 유용하지만, 쓰기에는 무용지물이었습니다.

나는 여기에 3개의 쓰기 도구를 추가하여 확장했습니다:

• create_article: 새로운 기사(초안 또는 게시)를 발행하기 위한 도구
• update_article: 기존 기사를 편집하기 위한 도구
• delete_article: 게시를 취소하기 위한 도구

그 결과, Claude(또는 모든 MCP 클라이언트)가 DEV.to를 CMS (Content Management System)처럼 다룰 수 있게 해주는 완전한 읽기-쓰기 MCP 서버가 탄생했습니다. 이 글 또한 이 서버를 사용하여 작성되고 게시되었습니다.

데모

빌드 후 Claude Desktop의 도구 목록은 다음과 같습니다:

Read-only tools (6):
  Get Articles, Get Article, Get User, Get Tags, Get Comments, Search Articles

...

초안 생성 호출은 다음과 같은 형태를 띱니다:

{
  "tool": "create_article",
  "args": {
...

MCP 서버는 환경 변수(env)에 있는 사용자의 DEVTO_API_KEY를 사용하여 POST https://dev.to/api/articles를 호출하고, 기사 ID를 반환합니다. 그러면 Claude는 즉시 해당 ID를 대상으로 update_article을 호출할 수 있습니다. 브라우저도 필요 없고, 채팅에서 에디터로 복사-붙여넣기를 할 필요도 없습니다.

여정

원본 저장소는 견고했지만 제한적이었습니다. 나는 스스로에게 물었습니다. 왜 읽기만 가능한 MCP 서버를 사용해야 하는가?

설정이 첫 번째 장벽이었습니다. npm 패키지가 게시되지 않아서 npx -y @nickytonline/dev-to-mcp를 실행하면 404 오류가 반환되었습니다. 그다음 npm install -g github:...를 시도했지만, npm이 예상하는 설치 경로에 저장소의 최상위 package.json이 없어서 실패했습니다. 해결 방법은 화려하지 않았습니다. git clone, npm install, npm run build를 수행한 뒤, Claude Desktop의 설정이 로컬의 dist/index.js를 가리키도록 만드는 것이었습니다.

Windows 환경에서의 특이 사항도 있었습니다. Windows용 Claude Desktop은 npx가 아닌 npx.cmd를 사용해야 합니다. 에러 메시지는 단순히 Server disconnected라고만 표시되었습니다. 로그를 확인해 보니, 명령어가 node로 바뀌었음에도 설정 파일에는 여전히 npx 플래그가 남아 있어 bad option: -y라는 오류가 발생하고 있었습니다. 사소한 문제였지만 해결하는 데 두 시간이 걸렸습니다.

읽기 전용 (read-only) 서버가 실행된 후, 실제 마무리 작업은 간단했습니다. 코드베이스는 깔끔한 핸들러 패턴 (handler pattern)을 사용하고 있었습니다. 각 도구 (tool)는 DEV.to API를 호출하고 타입이 지정된 응답 (typed response)을 반환하는 함수였습니다. 저는 새로 추가할 세 개의 도구에 대해서도 동일한 패턴을 따랐습니다.

// 기존 읽기 도구들의 패턴
async function getArticle(id: number) {
  const res = await fetch(`https://dev.to/api/articles/${id}`, {
...

새로운 핸들러들을 MCP 서버의 도구 목록에 등록하고, npm run build로 다시 빌드한 뒤, Claude Desktop을 재시작하면 끝입니다.

기술 스택 (Tech Stack)

• TypeScript: 서버 코드 작성용
• Vite: 빌드 도구 (출력 크기 12.83 kB, 빌드 시간 133ms)
• Model Context Protocol SDK: 서버 스캐폴딩 (scaffolding)용
• DEV.to API v1: 백엔드
• Claude Desktop: MCP 클라이언트

배운 점

두 가지가 기억에 남습니다.

첫째, 다른 사람의 프로젝트를 완성하는 것이 처음부터 시작하는 것보다 빠릅니다. 해당 리포지토리 (repo)에는 이미 타입 (types), 패턴 (patterns), 에러 처리 (error handling), 그리고 테스트 (tests)가 갖춰져 있었습니다. 세 개의 도구를 추가한다는 것은 새로운 형식을 발명하는 것이 아니라 기존의 형식을 맞추는 작업이었습니다. 추가-빌드-테스트로 이어지는 전체 사이클이 30분도 걸리지 않았습니다.

둘째, AI의 도움은 모방할 수 있는 기존 구조가 있을 때 가장 효과적입니다. 저는 Claude Code에 리포지토리 경로를 주고 기존 패턴에 맞는 세 개의 도구를 만들어 달라고 요청했습니다. Claude Code는 코드베이스를 읽고, 핸들러 시그니처 (handler signature)를 식별했으며, 학습 데이터를 통해 DEV.to API 엔드포인트 (endpoints)를 파악하여 첫 번째 빌드에서 바로 작동하는 코드를 생성했습니다. 기존의 읽기 전용 도구들이 참조 모델로 없었다면, 결과물을 얻기 위해 더 많은 반복 작업이 필요했을 것입니다.

다음 단계

MCP 서버에는 아직 개선할 점들이 남아 있습니다:

• 이미지 업로드 불가 (DEV.to는 base64 인라인 방식 또는 외부 URL을 요구함)
• get_followers 또는 get_following 기능 없음
• 댓글 작성/삭제 기능 없음
• 분석 (Analytics) 엔드포인트 없음

이것들은 동일한 패턴을 따르는 작은 추가 사항들입니다. 가장 어려운 부분은 처음 세 가지였습니다.

Repo

쓰기 도구가 포함된 포크된 리포지토리 (forked repo): github.com/glatinone/dev-to-mcp

읽기 전용 기반을 마련해 준 @nickytonline에게 원작자 크레딧을 돌립니다.