RAG Tool Agent — MCP Server

rag-tool-agent-demo 프로젝트의 기반이 되는 두 도구(FordA 데이터셋 노트에 대한 검색 근거 기반 Q&A와 안전한 산술 계산기)를 제대로 된 Model Context Protocol 서버로 노출합니다. 따라서 MCP 호환 클라이언트라면 — Claude Desktop, MCP를 지원하는 에이전트 하네스, 또는 커스텀 호스트 — 해당 프로젝트 자체 CLI나 rag-tool-api-docker의 Flask HTTP 래퍼를 통해서만 호출하는 대신, 이 도구들을 직접 호출할 수 있습니다.

구체적이고 명확히 지목된 격차를 메우기 위해 만들어졌습니다. 현재 여러 AI 엔지니어/에이전틱 애플리케이션 채용 공고가 MCP(및 관련 에이전트 간/에이전트-UI 프로토콜)에 대한 실무 경험을 명시적으로 요구합니다. 이 프로젝트는 작지만 실제로 동작하고 테스트된 구현물이며, 증거가 뒷받침되지 않는 프로토콜 경험 주장이 아닙니다.

왜 이런 구조로 되어 있나

원래 에이전트는 내부적으로 자체 라우팅을 수행합니다. 들어오는 각 질문에 대해 "calculator" vs. "retrieval" vs. "direct answer"를 결정하는 직접 작성한 if/else입니다. MCP는 이를 뒤집습니다. 클라이언트(LLM/에이전트 호스트)가 각 도구의 이름, 설명, JSON 스키마 매개변수를 읽고 어느 것을 호출할지 결정함으로써 라우팅을 수행합니다. 따라서 이 서버는 원래 라우팅 로직을 재구현하지 않습니다. 두 가지 기본 기능을 독립적으로 호출 가능한 독립형 MCP 도구로 노출하고, 어떤 MCP 클라이언트든 스스로 라우팅하도록 맡깁니다. 이것이 바로 이 프로토콜의 실제 요점입니다. 도구가 한 에이전트의 디스패치 로직에 하드와이어링되는 대신 호스트에 구애받지 않게(host-agnostic) 됩니다.

• search_notes(query: str) -> str — FordA 데이터셋에 대한 소규모 인라인 노트 코퍼스에서 검색 방식으로 조회하는 도구입니다. 원래 에이전트가 사용하는 것과 동일한 [Grounded in N retrieved chunk(s) from ...] 출처 접미사를 붙여 반환하므로, 클라이언트는 근거가 있는 답변과 근거가 없는 답변을 구분할 수 있습니다. 원래 프로젝트의 FAISS/임베딩 인덱스를 다시 만드는 대신 작은 키워드 겹침 랭커를 사용합니다. 이 프로젝트의 요점은 MCP 노출 계층이지 그 작업을 복제하는 것이 아닙니다.

• calculate(expression: str) -> str — 산술 도구로, ast 기반 안전 평가기를 통해 + - * / ()와 숫자 리터럴로만 제한됩니다(임의 입력에 대한 단순 eval()이 아님). 비산술 입력과 __import__('os').system(...) 같은 인젝션 시도를 모두 거부하는 것이 검증되었습니다.

• 공식 mcp Python SDK(FastMCP)로 구축되었습니다. Anthropic이 MCP 서버 구축용으로 공개하는 것과 동일한 SDK입니다.

Related MCP server: NotebookLM MCP Server

실행 방법

pip install -r requirements.txt
python server.py

stdio를 통해 실행됩니다. Claude Desktop 같은 MCP 클라이언트가 서버를 하위 프로세스로 실행하고 통신하는 데 사용하는 표준 로컬 전송 방식입니다. Claude Desktop에서 이 서버를 사용하려면 MCP 서버 설정에 다음을 추가하세요:

{
  "mcpServers": {
    "rag-tool-agent": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

테스트 실행

pytest tests/ -v

11개의 테스트가 모두 통과합니다. 도구 함수를 직접 호출합니다(도구 로직 자체에 대한 유닛 수준 커버리지에는 MCP 전송이 필요하지 않습니다): 근거 기반 검색 답변, 근거 건수 계약, 산술 정확성(원래 에이전트가 직접 문서화한 예제와 일치하는 나눗셈 예제 포함), 비산술 입력 및 인젝션 입력 거부, 0으로 나누기 처리, 설명이 포함된 도구 자체 등록.

단순한 함수가 아니라 실제 MCP 서버로 검증됨

유닛 테스트 외에도 실제 mcp 클라이언트 SDK(ClientSession + stdio_client)를 사용해 엔드투엔드로 검증했습니다. server.py를 실제 하위 프로세스로 실행하고, MCP initialize 핸드셰이크를 완료하고, list_tools()를 호출하고, 실제 프로토콜을 통해 두 도구를 모두 호출했습니다:

TOOLS: ['search_notes', 'calculate']
calculate -> 1320 / (3601 + 1320) = 0.2682381629750051
search_notes -> The FordA dataset is a univariate time-series
  classification dataset... [Grounded in 3 retrieved chunk(s) from
  forda_dataset_notes.md]
calculate(injection) -> Error: could not evaluate "__import__('os')" ...

이로써 서버가 실제 MCP(핸드셰이크, 도구 발견, 도구 호출)를 구사한다는 것이 확인됩니다. 이는 기본 Python 함수가 단독으로 동작한다는 것만을 확인하는 수준이 아닙니다.

다른 두 프로젝트와의 관계

• rag-tool-agent-demo — 원래 CLI 에이전트: LangChain, FAISS, Ollama, LCEL 검색 체인, 계산기 도구, LLM 기반 라우팅.

• rag-tool-api-docker — 해당 에이전트를 Flask HTTP API로 래핑하고 컨테이너화한 것(Docker, 멀티 스테이지 빌드, 비루트 사용자, 헬스 체크)으로, 실행 중인 컨테이너에 실제 HTTP 요청을 보내 검증했습니다.

• 이 프로젝트 — 동일한 기본 기능(검색, 계산기)을 HTTP 대신 MCP로 노출하므로, REST 클라이언트뿐만 아니라 모든 MCP 호스트에서 호출할 수 있습니다.