DEV.to를 AI 도구로 변환하기: 나만의 MCP 서버 구축하기

만약 당신의 AI 어시스턴트가 브라우저 탭 사이에서 콘텐츠를 복사할 필요 없이, 당신의 DEV Community 게시물을 나열하고, 기사를 검토하며, 새로운 초안을 준비할 수 있다면 어떨까요?

그것이 바로 **Model Context Protocol (MCP)**가 가능하게 하는 워크플로우입니다. 이 튜토리얼에서는 DEV.to MCP 통합이 어떻게 작동하는지, 어떻게 안전하게 테스트하는지, 그리고 TypeScript를 사용하여 직접 작은 버전을 어떻게 구축하는지 배우게 됩니다.

중요한 안전 규칙이 먼저 있습니다:

기본적으로 어시스턴트가 **초안 (drafts)**을 작성하도록 하세요. 게시 (Publishing)는 항상 명시적인 결정이어야 합니다.

우리가 구축할 것

우리의 MCP 서버는 MCP 호환 AI 클라이언트와 DEV/Forem API 사이에 위치하게 됩니다:

AI assistant
     |
     | MCP tool call
...

우리는 세 가지 도구 (tools)를 노출할 것입니다:

list_my_articles — 게시되었거나 게시되지 않은 포스트를 가져옵니다.
get_article — ID를 통해 기사를 검토합니다.
create_article_draft — Markdown을 게시되지 않은 초안으로 저장합니다.

MCP 서버는 도구 (tools), 리소스 (resources), 그리고 프롬프트 (prompts)를 노출할 수 있습니다. 각 작업이 명시적인 입력을 가지고 외부 API를 호출할 수 있기 때문에, 여기서는 도구 (tools)가 적절한 기본 단위 (primitive)입니다.

사전 요구 사항

다음이 필요합니다:

최신 Node.js 설치
DEV Community 계정
계정 설정에서 가져온 DEV API 키
MCP 호환 클라이언트

프로젝트를 생성하고 공식 TypeScript SDK를 설치하세요:

mkdir devto-mcp
cd devto-mcp
npm init -y
...

package.json에 "type": "module"과 빌드 명령어를 추가하세요:

{
  "type": "module",
  "scripts": {
...

최소한의 tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
...

API 키를 코드에서 분리하기

키를 환경 변수 (environment variable)에 저장하세요:

export DEVTO_API_KEY="your-key-here"

PowerShell의 경우:

$env:DEVTO_API_KEY = "your-key-here"

키를 커밋하거나, 프롬프트에 넣거나, 도구로부터 반환하지 마세요. MCP 서버는 환경으로부터 직접 키를 읽어야 합니다.

DEV는 현재 API v1을 권장합니다. 요청은 api-key 헤더와 다음 미디어 타입을 사용합니다:

application/vnd.forem.api-v1+json

서버 생성 (Create the server)

src/index.ts 파일을 생성합니다:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
...

이 헬퍼(helper)는 인증 (authentication), API 버전 관리 (versioning), 그리고 에러 핸들링 (error handling)을 중앙 집중화합니다. 또한 모든 도구 (tool)가 헤더를 서로 다르게 구현하는 것을 방지합니다.

도구 1: 내 포스트 목록 가져오기 (list your posts)

인증된 API는 게시된(published), 게시되지 않은(unpublished), 그리고 모든 기사(articles)를 위한 별도의 엔드포인트 (endpoint)를 제공합니다.

server.tool(
  "list_my_articles",
  "인증된 DEV 사용자가 소유한 기사 목록을 가져옵니다",
...

사용자 이름을 추측하는 것보다 인증된 /articles/me/* 엔드포인트를 사용하는 것이 더 좋습니다. 또한 이를 통해 공개 프로필 엔드포인트에서는 할 수 없는 초안 (drafts) 검색도 서버가 수행할 수 있습니다.

도구 2: 기사 검사하기 (inspect an article)

server.tool(
  "get_article",
  "숫자 ID를 통해 DEV 기사를 가져옵니다",
...

구조화된 JSON을 텍스트로 반환하는 방식은 간단하며 다양한 클라이언트 (client)에서 작동합니다. 프로덕션 (production) 서버의 경우, 대상 클라이언트가 지원한다면 구조화된 콘텐츠를 추가로 제공할 수도 있습니다.

도구 3: 초안만 생성하기 (create drafts only)

이 튜토리얼에서 가장 중요한 도구입니다:

server.tool(
  "create_article_draft",
  "게시되지 않은 DEV 기사 초안을 생성합니다",
...

이 도구는 published 인자를 받지 않는다는 점에 주목하세요. 이 도구는 항상 published: false를 전송합니다.

이는 의도적인 기능 설계 (capability design)입니다. "게시하지 말아 주세요"라고 말하는 프롬프트 (prompt)는, 단순히 게시를 할 수 없는 도구보다 힘이 약합니다. 나중에 게시 기능을 추가한다면, 명확한 이름을 가진 별도의 도구로 만들고 클라이언트 워크플로 (workflow)에서 사용자의 명시적인 승인을 요구하도록 만드세요.

STDIO 트랜스포트 시작하기 (Start the STDIO transport)

다음 코드로 파일을 완성합니다:

const transport = new StdioServerTransport();
await server.connect(transport);

그 다음 빌드합니다:

npm run build

STDIO 서버의 경우, console.log()를 사용하지 마세요. 표준 출력 (Standard output)은 MCP 프로토콜 메시지를 전달하므로, 일반적인 로그가 연결을 손상시킬 수 있습니다. 진단용으로는 console.error()를 사용하세요.

MCP 클라이언트에 연결하기

정확한 설정 파일은 클라이언트에 따라 다르지만, 프로세스 정의는 보통 다음과 같은 형태를 가집니다:

{
  "mcpServers": {
    "devto": {
...

클라이언트가 지원하는 경우, 시크릿 매니저 (Secret manager) 또는 상속된 환경 변수 (Environment variable)를 사용하는 것이 좋습니다. 키 (Key)가 포함된 일반 설정 파일은 절대로 커밋해서는 안 됩니다.

클라이언트를 재시작하고 다음 도구들이 나타나는지 확인하세요:

list_my_articles
get_article
create_article_draft

안전한 엔드 투 엔드 (End-to-end) 테스트

다음 프롬프트를 시도해 보세요:

내가 발행한 DEV 기사들을 나열해줘. 그런 다음 이 MCP 통합에 관한 짧은 튜토리얼을 준비해서 초안으로 저장해줘. 발행은 하지 마.

어시스턴트 (Assistant)는 다음과 같이 동작해야 합니다:

list_my_articles 호출;
결과를 컨텍스트 (Context)로 사용;
마크다운 (Markdown) 초안 작성;
create_article_draft 호출;
새로운 기사 ID 또는 편집 URL 반환.

DEV 대시보드를 열고 초안을 수동으로 검토하세요. 발행하기 전에 제목, 태그, 링크, 코드 블록 및 내용을 확인하세요.

프로덕션 (Production) 개선 사항

이 최소한의 구현은 유용하지만, 공개적인 MCP 서버라면 다음과 같은 기능을 추가해야 합니다:

페이지네이션 (Pagination) 제어 및 응답 크기 제한;
일시적인 오류에 대한 타임아웃 (Timeout) 및 재시도 (Retry) 처리;
요청 헤더나 시크릿을 유출하지 않는 명확한 에러 메시지;
태그 및 기사 길이에 대한 입력 유효성 검사 (Input validation);
모킹된 (Mocked) HTTP 응답을 사용한 테스트;
소유권을 확인하는 초안 업데이트 도구;
속도 제한 (Rate-limit) 인지;
읽기 및 쓰기 권한의 분리;
파괴적이거나 공개적인 작업에 대한 확인 경계 (Confirmation boundaries).

또한, 제목과 ID 요약만으로 충분한 경우 기사 본문 전체를 반환하는 것은 피해야 합니다. 도구의 응답 크기가 작을수록 노이즈가 줄어들고 어시스턴트의 다음 의사결정이 쉬워집니다.

이 실험이 보여주는 것

MCP는 단순히 AI에게 "더 많은 도구"를 제공하는 것에 관한 것이 아닙니다. 그것은 자연어 의도 (natural-language intent)와 실제 시스템 사이의 통제된 인터페이스를 설계하는 것에 관한 것입니다.

DEV.to의 경우, 이는 다음을 의미합니다:

API 키가 서버 내부에 유지됩니다.
입력값이 검증됩니다.
어시스턴트는 당신이 노출한 기능 (capabilities)만을 전달받습니다.
공개적인 동작 (public actions)을 되돌릴 수 있는 초안 동작 (reversible draft actions)과 분리할 수 있습니다.
사용자가 최종 편집자로 남습니다.

훌륭한 통합은 안전한 경로를 쉬운 경로로 만듭니다. 읽기 기능부터 시작하세요. 초안 생성 기능을 추가하세요. 동작을 검토하세요. 그런 다음 공개 콘텐츠를 게시하거나 업데이트하는 것을 고려하십시오.

References

만약 당신만의 DEV.to MCP 서버를 구축한다면, 당신이 어떤 도구들을 노출하고 어떤 동작들을 의도적으로 제외했는지 꼭 듣고 싶습니다.

Insights