mcp-agent-toolkit

라이브 데모: 아직 배포되지 않음 — agent.build-with-deepak.com에 예정. 이 저장소는 완성되어 있으며 로컬에서 검증되었습니다(빌드, 린트, 25개의 단위 테스트 — 실제 MCP 프로토콜 왕복 포함 — 및 5개의 e2e 테스트). 아직 라이브 Ollama/Postgres에 배포되거나 실행되지 않았습니다. 상태를 참조하세요.

문제

대부분의 "AI 에이전트" 데모는 자율성으로 위장한 단일 숨겨진 도구 호출입니다. 이 프로젝트는 그 작동 방식을 보여줍니다: 세 가지 실제 도구(읽기 전용 PostgreSQL 커머스 데이터베이스, 실시간 날씨 API, 계산기)를 가진 Model Context Protocol 에이전트가 실제로 그 중 여러 개가 필요한 질문에 답합니다("두바이 고객의 총 매출, 그리고 그곳의 날씨는?"). 모든 도구 호출, 인수, 결과, 지연 시간, 그리고 중요한 것은 실패와 그로부터 모델이 회복하는 과정이 발생하는 대로 화면에 스트리밍됩니다.

Related MCP server: MCP Tool Server

사용해 보기

데모 계정으로 계속은 실제 API에 대해 실제 2시간 세션을 발행합니다 — 동일한 에이전트, 동일한 도구, 동일한 데이터. 샘플 데이터베이스는 공유되고 읽기 전용이므로 데모 세션에는 사용자별 정리가 필요 없습니다: 방문자가 수행하는 어떤 작업도 쓸 수 없습니다. 등록(사용자별 영구 데이터)은 진행 중입니다. 등록 버튼과 POST /api/auth/register(501)는 모두 정직하게 그렇게 말합니다.

아키텍처

flowchart TB
    subgraph Browser
        UI[Angular SPA<br/>login → live tool-call timeline]
    end

    subgraph VPS -- host nginx, TLS
        Nginx[nginx :443]
    end

    subgraph "Docker Compose stack"
        Web[web container]
        subgraph API [api container — NestJS]
            Loop[Agent loop]
            Client[MCP Client]
            Server[MCP Server]
        end
        PG[(PostgreSQL<br/>sample dataset<br/>mcp_readonly role)]
    end

    Ollama[Ollama llama3.1 — on the VPS]
    Meteo[Open-Meteo API]

    UI -->|HTTPS| Nginx --> Web -->|/api/*| Loop
    Loop -->|chat + tools| Ollama
    Loop -->|listTools / callTool| Client
    Client <-->|MCP protocol, in-memory transport| Server
    Server -->|query_database| PG
    Server -->|get_weather| Meteo
    Server -->|calculate| Server

루프: 모델은 질문과 MCP에서 발견된 도구 스키마를 받습니다 → 도구 호출을 생성합니다 → 각 호출은 MCP 클라이언트를 통해 실행됩니다 → 결과(오류 포함)는 모델로 돌아갑니다 → 산문으로 답하거나 단계 상한(기본 6)에 도달할 때까지 반복합니다. 모든 홉은 SSE 이벤트입니다.

주요 결정 및 트레이드오프

하나의 프로세스에 실제 MCP 서버와 클라이언트. 도구는 단순 함수일 수 있었지만 프로토콜 경계가 핵심입니다. 에이전트 루프는 오직 MCP 클라이언트와만 통신합니다: listTools()로 도구를 발견하고 callTool()로 호출하며, stdio 또는 HTTP를 통한 외부 서버에 대해 호출하는 것과 정확히 동일합니다. 이 프로세스에서 도구를 이동하는 것은 전송 라인 하나를 변경하는 것이지 에이전트를 변경하는 것이 아닙니다. 인메모리 전송은 단일 VPS 데모에 추가 포트와 하위 프로세스 감독이 없도록 유지하면서 SDK는 양방향으로 스키마를 검증합니다 — 그리고 단위 테스트 스위트는 그 실제 핸드셰이크를 목(mock)이 아닌 실제로 실행합니다.

SQL 인젝션은 엣지 케이스가 아니라 기본 상태로 취급됩니다. 에이전트는 낯선 사람의 자연어 질문에서 SQL을 작성합니다 — 이는 구조적으로 신뢰할 수 없는 입력입니다. 두 계층: 앱 측 가드(sql-guard.ts: 주석 제거, 단일 문, SELECT/WITH 전용, set_config가 set이 아님을 아는 키워드 차단 목록, 결과를 100행으로 제한하는 하위 쿼리 래핑)는 모델이 조치할 수 있는 메시지로 빠르게 실패합니다. 그 아래에서 쿼리는 전용 mcp_readonly Postgres 역할로 실행됩니다 — SELECT 전용 권한, default_transaction_read_only=on, 5초 문 제한 시간 — 가드에 버그가 있어도 유지됩니다. 가드 자체의 테스트는 허용된 어휘적 한계를 문서화합니다.

도구 오류는 실패로 표시되지 않고 모델에 피드백됩니다. 실패한 도구 호출은 isError 결과로 반환되어 대화에 도구 출력으로 들어갑니다. 모델은 오류를 읽고 SQL을 수정하거나 다른 도시를 선택한 후 재시도합니다 — UI는 정확히 그 점을 주석으로 표시합니다("오류는 모델로 돌아갑니다 — 다음 단계를 지켜보세요"). 회복을 관찰하는 것은 결코 실패하지 않는 것보다 엔지니어링 증거로서 더 가치가 있습니다.

계산기는 eval이 아닌 60줄 파서입니다. LLM이 작성한 표현식을 JavaScript 평가자에 전달하면 계산기가 코드 실행 도구로 변합니다. 명시적 문법을 가진 재귀 하강은 지루하지만 올바른 대안입니다. 테스트에는 1 + 1; process.exit()가 포함됩니다.

루프 단계는 비스트리밍이며, 타임라인이 스트림입니다. 모델 응답이 도구 호출인지 최종 답변인지는 완료되었을 때만 알 수 있으며, 도구 호출 응답은 짧습니다. 실제로 흥미로운 것 — 도구 호출과 결과가 발생하는 대로 — 가 스트리밍됩니다. 최종 산문 답변은 하나의 이벤트로 도착합니다. (형제 라우터 데모와 동일한 SSE-over-POST 전송 결정, 동일한 이유.)

날씨는 Open-Meteo 사용. 무료이고 키가 없습니다: 타사 API 키가 있는 무인 공개 데모는 누출을 기다리는 사고이자 청구서가 쌓일 대기입니다. 트레이드오프 — SLA 없음 — 는 날씨 도구 중단 자체가 오류 처리 경로의 라이브 데모이므로 허용 가능합니다.

고정 ID를 가진 고정 샘플 데이터셋. 시딩은 ON CONFLICT DO NOTHING을 사용하므로 모든 부팅이 중복을 축적하는 대신 동일한 15명의 고객 / 12개의 제품 / 32개의 주문으로 수렴합니다. 도시는 DB + 날씨 질문이 자연스럽게 구성되도록 선택되었습니다(두바이, 뉴델리, 런던…).

데이터베이스 설정 및 재설정

스키마, 샘플 데이터 및 mcp_readonly 역할의 권한은 apps/api/db/schema.sql에 있으며, 모든 API 부팅 시 멱등적으로 적용됩니다. 역할 자체(MCP_READONLY_PASSWORD의 비밀번호)는 CREATE ROLE이 매개변수화된 비밀번호를 받을 수 없기 때문에 db.service.ts에서 생성됩니다. pnpm db:reset은 샘플 테이블을 삭제합니다. 다음 부팅 시 모든 것이 다시 생성됩니다. 의도적으로 일상적인 데모 데이터 정리는 없습니다 — 방문자는 쓸 수 없습니다.

100배 규모에서 변경할 사항

인메모리 MCP 전송이 가장 먼저 이동합니다: 실제 멀티테넌트 도구 서버는 별도의 서비스(stdio 하위 프로세스 또는 HTTP)로 실행되며, 프로토콜 경계에서 도구별 인증 및 감사 로깅이 있습니다 — 이 코드베이스는 이미 그 교체를 위해 형성되어 있습니다. 에이전트 루프는 영구 대화(세션으로 키가 지정된 conversations 테이블 — 등록된 계정의 자연스러운 첫 번째 기능), 독립적인 호출이 있는 경우 병렬 도구 실행, 단계 상한과 함께 토큰 예산 상한을 얻게 됩니다. 그리고 SQL 도구는 원시 SELECT 노출을 완전히 중단합니다: 규모가 커지면 명명된 매개변수화된 쿼리 템플릿을 게시하고 모델이 매개변수를 채우도록 합니다 — 여기의 가드 + 읽기 전용 역할 패턴은 그 아이디어의 데모 크기 버전이지 대체물이 아닙니다.

로컬 설정

Node 22+, pnpm; 전체 경험을 위해서는 Postgres와 도구 지원 모델이 있는 Ollama(ollama pull llama3.1:8b — 일반 llama3는 도구 호출을 안정적으로 생성하지 않습니다).

corepack enable && pnpm install
pnpm dev:api   # :3000
pnpm dev:web   # :4200, proxies /api → :3000

게이트 검사:

pnpm --filter api build && pnpm --filter api lint && pnpm --filter api test && pnpm --filter api test:e2e
pnpm --filter web build && pnpm --filter web test

VPS에 배포

1. cp .env.example .env — POSTGRES_PASSWORD, MCP_READONLY_PASSWORD, JWT_SECRET을 설정합니다(compose는 이들 없이는 시작을 거부합니다). VPS에서 ollama list가 llama3.1:8b를 표시하는지 확인합니다.

2. docker compose up -d --build — 웹은 127.0.0.1:8092에만 바인딩됩니다.

3. nginx/agent.build-with-deepak.com.conf를 호스트 nginx에 설치한 다음 certbot --nginx -d agent.build-with-deepak.com을 실행합니다.

4. GET /api/health는 인증되지 않은 활성 프로브입니다.

상태

• SDK의 인메모리 전송을 통한 실제 MCP 서버 + 클라이언트, 세 가지 도구, 테스트로 검증된 프로토콜 왕복

• 실시간 SSE 도구 호출 타임라인, 오류 복구 피드백, 단계 상한이 있는 에이전트 루프

• 2계층 SQL 보호(가드 + 전용 읽기 전용 Postgres 역할)

• 데모 계정 인증 엔드 투 엔드; 등록 = 정직한 501 곧 제공 예정

• 빌드, 린트, 모든 테스트 통과(API: 25 단위 + 5 e2e; 웹: 6)

• 라이브 Ollama/Postgres에 아직 실행되지 않음 — 이 환경에는 둘 다 없었습니다. 특히 에이전트 루프의 Ollama 도구 호출 경로는 실제 llama3.1 실행이 필요합니다.

• 아직 배포되지 않음

• 등록/영구 계정 — 진행 중(설계상 데모 우선)