Claude Code의 잘못된 추측에 지쳐서 직접 만든 MCP 툴킷

AI 코딩 에이전트(AI coding agents)는 유용하지만, 여전히 한 가지 짜증 나는 습관이 있습니다.

바로 추측을 한다는 것입니다.

당신이 다음과 같이 합리적인 질문을 던졌다고 가정해 봅시다.

“데이터베이스에 삽입하기 전에 사용자 입력을 검증하는 곳이 어디인가요?”

그러면 에이전트는 어디를 찾아봐야 할지 아는 대신, 파일을 하나씩 읽기 시작합니다.

작은 프로젝트라면 괜찮습니다.

하지만 80,000줄 이상의 코드, 여러 명의 엔지니어, 오래된 결정 사항들, 이름이 절반쯤 바뀐 폴더들, 그리고 수년간 쌓인 컨텍스트(context)가 있는 실제 프로덕션 코드베이스(production codebase)에서는 상황이 빠르게 엉망이 됩니다.

에이전트는 몇 개의 파일을 읽다가 컨텍스트 제한(context limits)에 걸리고, 자신감 있게 들리지만 코드베이스의 잘못된 부분을 가리키는 답변을 내놓습니다.

저는 이에 지쳐서 이를 해결하기 위한 오픈 소스 MCP 툴킷(MCP toolkit)을 만들었습니다.

내가 만든 것

저는 AI 코딩 에이전트가 필요한 요소들에 직접 접근할 수 있도록 네 가지 Model Context Protocol 서버 모음인 MCP Server Toolkit을 만들었습니다.

• 당신의 코드베이스 (codebase)
• 당신의 데이터베이스 (database)
• 당신의 문서 (docs)
• 당신의 git 히스토리 (git history)

저장소(Repo):

https://github.com/naveenayalla1-CS50/mcp-server-toolkit

목표는 간단합니다.

에이전트가 추측하게 만들지 마세요. 어디를 찾아봐야 할지 아는 도구를 제공하세요.

왜 MCP인가?

Model Context Protocol, 즉 MCP는 AI 에이전트가 표준화된 방식으로 외부 도구를 호출할 수 있게 해줍니다.

에이전트가 무작위로 파일을 읽으며 적절한 컨텍스트가 맞기를 바라는 대신, 다음과 같이 목적에 맞게 제작된 도구를 호출할 수 있습니다.

search_code("validate user input")

그러면 파일 경로, 줄 번호, 그리고 관련 컨텍스트를 돌려받을 수 있습니다.

이는 대규모 코드베이스에서 잘못된 추측을 줄이고, 낭비되는 토큰(tokens)을 줄이며, 훨씬 더 나은 답변을 얻을 수 있음을 의미합니다.

네 가지 서버

1. mcp-code-search

당신의 리포지토리(repo) 전체를 검색하여 파일 경로, 줄 번호 및 주변 컨텍스트와 함께 관련 일치 항목을 반환합니다.

예시:

당신: sendEmail을 호출하는 모든 위치를 찾아줘

에이전트가 search_code("sendEmail")를 호출함
...

또한 에이전트가 실제로 필요한 파일만 조사할 수 있도록 타겟팅된 read_file 및 list_files 도구도 포함되어 있습니다.

2. mcp-database

에이전트가 자연어로 읽기 전용 (read-only) 데이터베이스 질문을 할 수 있게 해줍니다.

예시:

사용자: 지난 7일 동안 가입한 사용자는 몇 명인가요?

에이전트 실행:
...

Postgres와 SQLite를 지원합니다.

데이터베이스 서버는 **기본적으로 읽기 전용 (read-only)**입니다. 쓰기 작업을 원한다면 명시적으로 쓰기 가능 (writable) 모드를 활성화해야 합니다.

이 기본 설정은 매우 중요합니다. 개발자가 의도적으로 허용하지 않는 한, 에이전트가 쓰기 권한을 가지고 운영 데이터 (production data) 근처에 가는 것을 원치 않았기 때문입니다.

3. mcp-docs

임베딩 (embedding) 설정이나 외부 API 없이 Markdown 문서 폴더를 인덱싱 (indexing)합니다.

내부 문서, 런북 (runbooks), API 레퍼런스 (API references), 또는 프로젝트 노트에 연결할 수 있습니다.

예시:

사용자: 배포 롤백 (rolling back)에 대해 우리 런북에는 뭐라고 되어 있나요?

에이전트가 search_docs("rollback deployment") 호출
...

로컬에서 작동하며 문서를 어디로도 전송하지 않습니다.

4. mcp-git

에이전트가 git 히스토리 (history), 디프 (diffs), 블레임 (blame), 그리고 브랜치 (branches)를 쿼리 (query)할 수 있게 해줍니다.

이는 에이전트가 코드가 무엇을 하는지뿐만 아니라, 왜 변경되었는지까지 이해해야 할 때 유용합니다.

예시:

사용자: 이 검증 로직은 왜 추가되었나요?

에이전트가 해당 파일에 대한 git blame 및 최근 커밋 (commits)을 확인합니다.

설치 (Install)

가장 빠르게 시작하는 방법은 다음과 같습니다:

npx mcp-server-toolkit@latest init

이를 통해 대화형 설정이 시작됩니다.

원하는 서버를 선택하고, 데이터베이스 서버를 사용하는 경우 DATABASE_URL을 제공하면 Claude Code, Cursor, Windsurf 또는 기타 MCP 호환 클라이언트를 위한 설정을 생성합니다.

수동 Claude 설정 예시:

{
  "servers": {
    "code-search": {
...

MCP 호환 클라이언트를 재시작하면 도구들을 사용할 수 있습니다.

제작 이유 (Why I Made It)

이 프로젝트는 매우 구체적인 좌절감에서 시작되었습니다.

AI 코딩 에이전트들은 점점 좋아지고 있지만, 정답이 거대한 저장소 (repo) 안에 파묻혀 있을 때는 여전히 어려움을 겪습니다.

문제는 항상 추론 (reasoning) 때문만은 아닙니다.

많은 경우, 문제는 검색 (retrieval)에 있습니다.

에이전트는 단순히 어디를 찾아봐야 할지 모르는 것입니다.

MCP 서버는 에이전트에게 집중된 도구들을 제공함으로써 이 문제를 해결하는 데 도움을 줍니다:

기존 방식:
무작위 파일 읽기 → 추측 → 어쩌면 정답을 맞힘

...

이것이 실제 코드베이스 (codebases)를 위한 훨씬 더 나은 워크플로우 (workflow)입니다.

자신만의 서버 구축하기

새로운 MCP 서버를 더 쉽게 구축할 수 있도록 @mcp-toolkit/core도 추가했습니다.

간단한 서버는 다음과 같은 모습입니다:

import { createServer, tool, z } from '@mcp-toolkit/core';

const server = createServer({
...

다음 명령어로 새로운 서버의 스캐폴딩 (scaffold)을 생성할 수 있습니다:

npm run new-server -- my-server-name

배운 점

이것을 구축하면서 몇 가지 눈에 띄는 점이 있었습니다:

MCP TypeScript SDK는 견고합니다.
제 시간의 대부분은 프로토콜 (protocol) 배관 작업이 아니라 실제 도구 로직 (tool logic)에 사용되었습니다.

읽기 전용 (Read-only) 기본 설정이 중요합니다.
특히 데이터베이스 (database) 접근 시에 그렇습니다. 에이전트 (agents)가 실수로 쓰기 권한을 가져서는 안 됩니다.

Zod는 도구 입력 검증 (tool input validation)에 매우 효과적입니다.
에이전트가 잘못된 입력 형태를 전달할 때, 에러 메시지가 충분히 명확하여 스스로 수정할 수 있습니다.

로드맵 (Roadmap)

현재 버전에는 다음이 포함되어 있습니다:

• 코드 검색 (Code search)
• 데이터베이스 (Database)
• 문서 (Docs)
• Git

다음으로는 다음 사항들을 고려하고 있습니다:

• Notion
• Linear/Jira
• 등록된 도구들을 위한 작은 웹 UI
• 커스텀 MCP 서버를 위한 더 많은 예시

기여 (Contributions)는 언제나 환영합니다.

사용해 보기

GitHub:

https://github.com/naveenayalla1-CS50/mcp-server-toolkit

설치:

npx mcp-server-toolkit@latest init

직접 사용해 보신다면 피드백, 이슈 (issues), 또는 PR (Pull Requests)을 부탁드립니다.

특히 대규모 저장소 (repo)에서 Claude Code, Cursor, Windsurf 또는 다른 MCP 호환 코딩 에이전트 (coding agent)를 사용 중이시라면 더욱 환영합니다.