MCP 서버가 앱과 동기화되지 않는 문제: 이를 방지하는 빌드 게이트 구현

초안

RyTask(오픈 소스 프로젝트 트래커)에 MCP 서버를 추가하면서 저는 하나의 약속을 했습니다. 사용자가 UI에서 할 수 있는 모든 것은 AI 에이전트가 MCP를 통해 수행할 수 있어야 한다는 것입니다. 읽기 전용의 2급 에이전트 접근은 없습니다. 완전한 동등성(Full parity)입니다.

이러한 약속들은 시간이 지나면 무너지는 경향이 있습니다. 새로운 기능을 출시하고, 이를 UI와 REST API에 연결한 다음 MCP 도구는 잊어버립니다. 세 번의 스프린트가 지난 후 당신의 '100% 동등성'은 86% 동등성이 되어 있고, 당신은 그것을 모릅니다. 그래서 저는 동등성을 CI(지속적 통합)가 증명할 수 있는 무언가로 만들었고, 빌드가 실패하도록 했습니다.

시스템의 구조

RyTask의 모든 비즈니스 모듈은 자신이 소유한 기능(capabilities)과 이를 노출하는 MCP 도구들을 하나의 파일에서 선언합니다:

// work-items/module.testplan.ts
export const workItemsTestPlan = {
  capabilities: ['create', 'update', 'assign', 'comment', 'logTime', ...],
...

레지스트리(registry)가 모든 모듈의 도구들을 취합합니다. MCP 서버는 이 동일한 레지스트리를 기반으로 구축되므로, 따로 수동으로 관리하는 목록이 존재하여 동기화되지 않을 염려가 없습니다.

게이트(Gate)

check:mcp-parity는 모든 기능을 순회하며 일치하는 도구가 존재하는지 검증하고, 모든 도구는 실제 기능에 매핑되는지 확인합니다. 쌍이 하나라도 누락되면 CI가 실패합니다:

const missingTool = capabilities.filter(c => !toolFor(c))
const orphanTool  = tools.filter(t => !capabilityFor(t))
if (missingTool.length || orphanTool.length) {
...

현재는 49/49를 보고합니다. 제가 '중복 프로젝트' 기능을 추가하고 도구를 잊어버린 날, 빌드는 빨간색으로 바뀌며 정확히 어떤 도구가 누락되었는지 알려줍니다. 동등성은 더 이상 문서상의 주장이 아니라 불변의 속성(invariant)이 되었습니다.

이 문제가 제 프로젝트를 넘어 중요한 이유

AI 에이전트는 소프트웨어의 실제 사용자가 되어가고 있습니다. 만약 당신의 에이전트 인터페이스가 제품의 수동으로 선별된 하위 집합이라면, 그것은 항상 UI보다 뒤처질 것이며, 사용자들의 에이전트는 인간 사용자가 겪지 않는 벽에 부딪힐 것입니다. 에이전트를 첫급 클라이언트(first-class client)로 취급하고 — 다른 모든 것을 보호하는 것과 동일한 CI의 검증을 받도록 하는 것 — 이 많은 도구들이 결국 나아갈 방향이라고 생각합니다.

RyTask는 몇 가지 다른 불변성(invariant)에 대해서도 동일한 트릭을 수행합니다: 모듈 경계(다른 모듈의 내부 코드를 가져올 수 없음), 멀티테넌시(모든 테넌트 범위 쿼리는 레포지토리 계층에서 호출자 조직(org)으로 자동 제한되며, 테스트는 실제 Postgres를 대상으로 교차 테넌트 격리(cross-tenant isolation)를 검증합니다), 그리고 declared-required 테스트 파일이 단순히 누락된 경우 빌드를 실패시키는 '폐쇄적 테스트' 게이트입니다.

이 모든 것은 오픈 소스(AGPL-3.0)이며, 혼자서 구축했습니다. 게이트가 작동하는 것을 보고 싶다면 레포지토리가 여기 있습니다: github.com/ali-maher-m/RyTask. 이 접근 방식에 대한 피드백을 받고 싶습니다. 특히 실제 제품을 위한 MCP 서버를 구축하고 있는 다른 분들의 의견이 궁금합니다.