DevTools MCP

Model Context Protocol을 처음부터 온전히 배우기 위해 만든 작은 개발자 유틸리티 MCP 서버입니다. 서버 구현, 로컬 테스트, 기존 MCP 사용, 공개 배포, Smithery 게시까지 다룹니다.

1. 개요

DevTools MCP는 Model Context Protocol을 통해 네 가지 작은 개발 도구를 제공합니다: 오류 메시지 설명, JSON 검증/포맷팅, 설명으로부터 정규식 생성, LLM(Groq)을 이용한 텍스트 요약입니다. 최소한의 TypeScript/Vite 대시보드를 통해 브라우저에서 이 도구들을 테스트할 수 있으며, 실제 MCP 클라이언트로 연결됩니다.

Related MCP server: Log Analyzer MCP

2. MCP를 사용하는 이유

MCP는 LLM 호스트(Claude Desktop, IDE, 에이전트)가 도구를 발견하고 호출하는 방식을 표준화합니다. 모든 프로젝트가 각자 독자적인 도구 호출 API를 만들 필요가 없습니다. 단순히 MCP라는 이름표만 붙인 REST API가 아니라 실제 MCP 서버를 구축하는 것이 이 프로젝트의 주요 학습 목표였습니다.

3. 아키텍처

MCP Client
    |
MCP Protocol
    |
DevTools MCP Server
    |-- explain_error    (local/deterministic)
    |-- format_json      (local/deterministic)
    |-- generate_regex   (local/deterministic)
    `-- summarize_text
            |
        Groq API
            |
        GPT-OSS 120B

서버(server/server.py)는 mcp.server.MCPServer(MCP Python SDK v2)로 구현되었습니다. 로컬 테스트에서는 stdio(MCP Inspector, Client(mcp))로 실행되고, 원격 또는 브라우저 접근에는 Streamable HTTP(/mcp)로 실행됩니다. TypeScript 프론트엔드(frontend/)는 진정한 MCP 클라이언트입니다. @modelcontextprotocol/sdk의 Client와 StreamableHTTPClientTransport를 사용하여 서버와 직접 통신하며, 직접 만든 REST 브리지가 아닌, 서버에서 CORS가 활성화된 Streamable HTTP를 통해 통신합니다.

4. 도구

5. 프로젝트 구조

devtools-mcp/
├── server/
│   ├── server.py               # MCPServer + tool registration + ASGI app
│   ├── tools.py                # explain_error / format_json / generate_regex logic
│   ├── ai.py                   # Groq-backed summarize_text logic
│   └── tests/
│       └── test_server.py      # pytest suite using the SDK's in-memory Client
├── frontend/
│   ├── index.html
│   ├── src/
│   │   ├── main.ts             # real MCP client (StreamableHTTPClientTransport)
│   │   └── style.css
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts
├── .env.example
├── .gitignore
├── requirements.txt
├── render.yaml                 # optional Render Blueprint
├── README.md
└── EXISTING_MCP_EXPERIENCE.md

6. 사전 요구 사항

• 파이썬 3.10+

• Node.js 18+ 및 npm (프론트엔드 및 npx를 통한 MCP Inspector 실행에 필요)

• Groq의 API 키 (summarize_text에만 필요)

• (선택, 배포용) Render 계정 및 Smithery 계정

7. 설치

git clone <this-repo>
cd devtools-mcp
python3 -m venv .venv
. .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

8. 환경 변수

.env.example 파일을 .env로 복사하고 필요한 값을 지정하세요:

GROQ_API_KEY=            # required for summarize_text
GROQ_MODEL=openai/gpt-oss-120b
MCP_ALLOWED_HOSTS=        # only needed when deployed behind a real hostname
MCP_ALLOWED_ORIGINS=      # comma-separated browser origins allowed via CORS

.env 파일은 git에서 무시됩니다. 실제 시크릿을 커밋하지 마세요.

9. 로컬 설정

로컬 MCP 클라이언트용(기본값) Stdio:

python -m server.server

로컬 전용 프론트엔드 또는 HTTP 기반 MCP 클라이언트용 Streamable HTTP:

uvicorn server.server:app --host 127.0.0.1 --port 8000

MCP_ALLOWED_HOSTS는 로컬에서 설정하지 않아도 됩니다. SDK에 내장된 호스트 검증 보호가 127.0.0.1/localhost를 자동으로 처리하기 때문입니다. 상태 확인: curl http://127.0.0.1:8000/health.

10. MCP Inspector 테스트

# Against stdio:
uv run mcp dev server/server.py     # requires uv; or: npx @modelcontextprotocol/inspector
# Against a running Streamable HTTP server:
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8000/mcp --method tools/list

로컬 Streamable HTTP 서버에 대해 실행했으며, 네 가지 도구 모두 나열되고 올바른 입력/출력 스키마를 가지고 있는지 확인했습니다(정확한 테스트 결과는 아래 "테스트" 참조).

11. 프론트엔드 설정

cd frontend
npm install
npm run dev          # http://localhost:5173

실행 중인 대시보드에서 서버 URL 필드를 MCP 서버의 /mcp 엔드포인트(기본값 http://localhost:8000/mcp)로 지정하고, Connect를 클릭한 다음 도구를 선택하고 양식을 작성하고 Run을 클릭합니다. 로컬 사용 시 CORS가 허용되도록 MCP_ALLOWED_ORIGINS=http://localhost:5173으로 백엔드를 시작합니다.

프로덕션 빌드: npm run build(frontend/dist/에 출력).

12. Groq 설정

1. console.groq.com에서 API 키를 생성합니다.

2. .env 파일 또는 배포 플랫폼의 환경 변수에 GROQ_API_KEY(선택 항목으로 GROQ_MODEL, 기본값 openai/gpt-oss-120b)를 설정합니다.

3. 이 프로젝트에서는 다른 LLM 공급자를 사용하지 않습니다.

13. 기존 MCP 사용 경험

기존 MCP 서버(Context7)를 사용하는 데 필요한 시연 내용은 EXISTING_MCP_EXPERIENCE.md에서 확인할 수 있습니다. 그것이 무엇인지, 어떻게 연결되었는지, 실행된 실제 쿼리, 그리고 배운 점이 무엇인지 확인할 수 있습니다.

14. Render 배포

Render의 원시 Python 런타임을 사용합니다(Docker 불필요).

대시보드 설정:

1. 이 저장소를 GitHub에 푸시합니다.

2. Render에서: New → Web Service → 저장소를 연결합니다.

3. 런타임: Python 3. 빌드 명령: pip install -r requirements.txt. 시작 명령: uvicorn server.server:app --host 0.0.0.0 --port $PORT.

4. 환경 변수 설정: GROQ_API_KEY, GROQ_MODEL, MCP_ALLOWED_HOSTS=<your-service>.onrender.com,<your-service>.onrender.com:*, 그리고 MCP_ALLOWED_ORIGINS=<your-frontend-origin>(프론트엔드를 함께 배포할 경우).

5. 배포하면 MCP 엔드포인트는 https://<your-service>.onrender.com/mcp가 됩니다.

동일한 설정을 위해 render.yaml Blueprint가 편의를 위해 포함되어 있습니다.

수동 확인 단계 필요: 실제 배포에는 Render 계정이 필요하며, 이 작성 환경의 일부로 될 수행되지 않았습니다. 수동 단계에 대한 자세한 내용은 완료 보고를 참조하세요.

15. Smithery 배포

현재 Smithery CLI는 이미 호스팅된 원격 MCP 서버 URL을 직접 배포하는 것을 지원합니다(이 방식에는 Docker/컨테이너 패키징이 불필요):

npm install -g smithery
smithery auth login
smithery mcp publish "https://<your-service>.onrender.com/mcp" -n "<your-org>/devtools-mcp"

배포 후 네 가지 도구가 노출되는지 확인:

smithery mcp add "https://<your-service>.onrender.com/mcp" --id devtools-mcp
smithery tool list devtools-mcp

수동 단계 필요: 이 방법은 먼저 Smithery 계정과 외부에서 접근 가능한 실제 Render 배포가 필요합니다. 이 과정은 이 실행 환경의 일부로 수행되지 않았습니다.

16. 공개 MCP 사용

배포 후, 어떤 Streamable HTTP MCP 클라이언트든 다음에 연결할 수 있습니다:

https://<your-service>.onrender.com/mcp

다음은 SDK의 Client를 사용한 예입니다:

from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async with streamable_http_client("https://<your-service>.onrender.com/mcp") as (r, w, _):
    async with Client(r, w) as client:
        await client.initialize()
        print(await client.list_tools())

17. 테스트

실제 실행 환경:

pytest server/tests/ -v

결과: 11개 성공 - 도구 디스커버리; 유효, 잘못된 형식, 빈 값의 format_json 입력;및 짝수와 일치하는 듯한 대응 및 불일치 explain_error 패턴(빈 입력 포함); 알려진 패턴(정규식 일치 여부 실시간 확인)과 일치하지 않는 설명에 대한 generate_regex; GROQ_API_KEY 누락 및 빈 입력에 대한 summarize_text .

또한 실제로는 (pytest 외부 수동 실행) 다음과 같이 실행했습니다.

• uvicorn server.server:app이 성공적으로 시작되었고, /health는 {"status":"ok",...}를 반환했습니다.

• /mcp에 대한 초기 initialize JSON-RPC POST 요청이 200을 반환했습니다.

• 실제 MCP Inspector CLI(npx @modelcontextprotocol/inspector --cli)가 Streamable HTTP를 통해 연결되어, 올바른 스키마로 네 가지 도구를 모두 나열하고 generate_regex, explain_error, format_json(유효 / 유효하지 않은 JSON 모두) 그리고 summarize_text를 성공적으로 호출했습니다. summarize_text는 실제 해당 환경에서 Groq API 키가 없었기 때문에 누락된 API 키 오류를 올바르게 보고했습니다.

• 전송 보안 확인: 위조된 Host 헤더가 있는 요청이 예상대로 421 Misdirected Request를 받았습니다.

• CORS 사전 요청 확인: OPTIONS /mcp 요청에 Origin: http://localhost:5173이 있는 경우, MCP_ALLOWED_ORIGINS가 설정되면서 올바른 access-control-* 헤더로 200을 반환했습니다.

• 프론트엔드: npx tsc --noEmit 오류 없이 통과했고, npm run build 성공 후 frontend/dist/를 생성했습니다.

검증되지 않은 항목: 실제 Groq API 키가 있는 실제 summarize_text 호출, Render 배포 자체, Smithery 배포/리포지토리 목록. 이는 이 환경에서 사용할 수 없는 외부 계정/자격 증명이 필요합니다.

18. 제한 사항

• summarize_text는 오류 발생 경로에 대해서만 엔드 투 엔드로 테스트되었습니다. 실제 Groq 자격 증명 없이 호출되지 않습니다.

• Render 배포와 Smithery 배포는 본인의 계정이 필요한 수동 단계(섹션 18-19 참조)가 있으며, 여기서는 수행되지 않았습니다.

• explain_error와 generate_regex는 LLM이 아닌 소규모의 직접 작성한 패턴 라이브러리를 사용합니다. 의도적으로 단순하고 결정적이며, 모든 가능한 오류나 패턴 설명을 인식하지는 못합니다.

• 프론트엔드는 인증이 없으며, 프로젝트의 명시적 "계정/인증 없음" 범위에 따라 로컬/데모 목적으로만 사용합니다.

19. 학습 결과

• MCP가 무엇인가 – "LLM에 컨텍스트/동작 제공"과 "LLM과의 상호 작용"을 분리하는 표준 프로토콜입니다. 이처럼 한 번 구축한 서버는 어떤 호환 클라이언트에서도 작동합니다.

• 호스트/클라이언트/서버 – 호스트는 LLM 애플리케이션(Claude, 브라우저 대시보드 다음의 애플리케이션)이고, 클라이언트는 그 안에서 MCP를 말하는 구성 요소(예: SDK의 Client, 프론트엔드의 StreamableHTTPClientTransport 기반 클라이언트)이며, 서버는 우리가 만든 부분입니다. 서버는 모델에 직접 통신하지 않습니다.

• 도구/리소스/프롬프트 – 도구는 모델이 제어된 호출(예: LLM이 format_json을 호출); 리소스는 애플리케이션이 제어하는 데이터 로드; 프롬프트는 사용자가 호출하게끔 하는 템플릿입니다. 이 프로젝트에서는 도구만 필요했습니다.

• 도구 발견과 호출 – 클라이언트는 사용 가능한 도구 정보(이름, 설명, JSON 스키마 입력/출력, 모두 파이썬 타입 힌트와 docstring에서 자동 생성)를 tools/list로 확인하고, 그다음 tools/call로 이름과 인자를 지정해 호출합니다.

• MCP가 REST API보다 나은 점 – REST API는 클라이언트마다 맞춤 통합이 필요하지만, MCP 서버는 자신의 능력과 스키마를 직접 설명하므로 애플리케이션 코드를 추가하지 않아도 MCP를 인지하는 모든 호스트에서 사용할 수 있습니다. 실제로 동일한 서버를 수정 없이 MCP Inspector와 자체 구축한 프론트엔드 클라이언트 모두에 연결해 확인했습니다.

• LLM이 들어가는 곳 – 그 추가적인 곳은 summarize_text 하나뿐이고, 그곳에서 Groq를 호출합니다. 서버의 나머지는 완전 결정적인 코드이며 "MCP 서버"와 "AI 애플리케이션"이 동일한 것이 아님을 보여줍니다.

• 배포의 현실 – Streamable HTTP 서버는 안전을 위해 기본적으로 host/origin 할로우 리스트를 localhost로만 한정하며, 실제 호스트명으로 작동하는 배포 후에는 이를 명시적으로 개방해야 합니다(예: TransportSecuritySettings 설정). 실제로 421이 발생하고 그것을 수정하는 과정으로 확인했습니다.