EnrichMCP

AI 에이전트를 위한 ORM - 데이터 모델을 시맨틱 (semantic) MCP 레이어로 변환하세요

EnrichMCP는 AI 에이전트가 데이터를 이해하고 탐색할 수 있도록 돕는 Python 프레임워크입니다. MCP (Model Context Protocol)를 기반으로 구축되었으며, 데이터 모델을 타입이 지정되고 발견 가능한 (discoverable) 도구로 변환하는 시맨틱 (semantic) 레이어를 추가합니다. 이는 마치 AI를 위한 ORM과 같습니다.

EnrichMCP란 무엇인가요?

AI 에이전트를 위한 SQLAlchemy라고 생각하면 됩니다. EnrichMCP는 다음을 자동으로 수행합니다:

• 데이터 모델로부터 타입이 지정된 도구 (typed tools) 생성
• 엔티티 간의 관계 처리 (users → orders → products)
• AI 에이전트가 데이터 구조를 이해할 수 있도록 스키마 발견 (schema discovery) 제공
• Pydantic 모델을 통한 모든 입출력 검증 (validation)
• 데이터베이스, API 또는 커스텀 로직 등 모든 백엔드와 연동 가능

설치 (Installation)

pip install enrichmcp

# SQLAlchemy 지원 포함 시
...

코드 보기

옵션 1: SQLAlchemy 모델이 있는 경우 (30초)

기존 SQLAlchemy 모델을 AI가 탐색 가능한 API로 변환하세요:

from enrichmcp import EnrichMCP
from enrichmcp.sqlalchemy import (
    include_sqlalchemy_models,
...

이제 AI 에이전트는 다음을 수행할 수 있습니다:

• explore_data_model() - 전체 스키마 이해
• list_users(status='active') - 필터를 사용한 쿼리
• get_user(id=123) - 특정 레코드 가져오기
• 관계 탐색: user.orders → order.user

옵션 2: REST API가 있는 경우 (2분)

기존 API를 시맨틱 이해 능력을 갖춘 형태로 래핑(wrap)하세요:

from typing import Literal
from enrichmcp import EnrichMCP, EnrichModel, Relationship
from pydantic import Field
...

옵션 3: 완전한 제어를 원하는 경우 (5분)

커스텀 로직을 사용하여 완전한 데이터 레이어를 구축하세요:

from enrichmcp import EnrichMCP, EnrichModel, Relationship
from datetime import datetime
from decimal import Decimal
...

주요 기능 (Key Features)

🔍 자동 스키마 탐색 (Automatic Schema Discovery)

AI 에이전트는 단 한 번의 호출로 전체 데이터 모델을 탐색합니다:

schema = await explore_data_model()
# 엔티티(entities), 필드(fields), 타입(types) 및 관계(relationships)를 포함한 전체 스키마를 반환합니다.

🔗 관계 탐색 (Relationship Navigation)

관계를 한 번만 정의하면, AI 에이전트가 자연스럽게 탐색합니다:

# AI는 다음과 같이 탐색할 수 있습니다: user → orders → products → categories
user = await get_user(123)
orders = await user.orders()  # 자동 리졸버 (Automatic resolver)
...

🛡️ 타입 안정성 및 검증 (Type Safety & Validation)

모든 상호작용에 대해 완전한 Pydantic 검증을 수행합니다:

@app.entity()
class Order(EnrichModel):
    total: float = Field(ge=0, description="Must be positive")
...

describe_model()은 이러한 허용된 값들을 나열하여 에이전트가 유효한 옵션을 알 수 있도록 합니다.

✏️ 가변성 및 CRUD (Mutability & CRUD)

필드는 기본적으로 불변(immutable)입니다. 필드를 가변(mutable)으로 표시하고, 업데이트를 위해 자동 생성된 패치 모델(patch models)을 사용하세요:

@app.entity()
class Customer(EnrichModel):
    id: int = Field(description="ID")
...

📄 내장된 페이지네이션 (Pagination Built-in)

대규모 데이터셋을 우아하게 처리하세요:

from enrichmcp import PageResult

@app.retrieve()
...

더 많은 예시는 Pagination Guide를 참조하세요.

🔐 컨텍스트 및 인증 (Context & Authentication)

인증(auth), 데이터베이스 연결 또는 기타 컨텍스트를 전달하세요:

from pydantic import Field
from enrichmcp import EnrichModel

...

⚡ 요청 캐싱 (Request Caching)

결과를 요청별(per-request), 사용자별(per-user) 또는 전역(global) 캐시에 저장하여 API 오버헤드를 줄이세요:

@app.retrieve()
async def get_customer(cid: int) -> Customer:
    ctx = app.get_context()
...

🧭 파라미터 힌트 (Parameter Hints)

EnrichParameter를 사용하여 도구 파라미터에 대한 예시와 메타데이터를 제공하세요:

from enrichmcp import EnrichParameter

@app.retrieve()
...

도구 설명(Tool descriptions)에는 파라미터 타입, 설명 및 예시가 포함됩니다.

🌐 HTTP & SSE 지원

표준 출력(기본값), SSE 또는 HTTP를 통해 API를 제공할 수 있습니다:

app.run()  # stdio 기본값
app.run(transport="streamable-http")

왜 EnrichMCP인가?

EnrichMCP는 MCP 위에 세 가지 핵심 계층을 추가합니다:

1. 시맨틱 계층 (Semantic Layer) - AI 에이전트가 데이터의 구조뿐만 아니라 데이터의 의미를 이해합니다.
2. 데이터 계층 (Data Layer) - 검증(Validation) 및 관계(Relationships)를 포함한 타입 안전(Type-safe) 모델을 제공합니다.
3. 제어 계층 (Control Layer) - 인증(Authentication), 페이지네이션(Pagination) 및 비즈니스 로직을 관리합니다.

결과적으로: AI 에이전트가 개발자가 ORM을 사용하는 것처럼 자연스럽게 귀하의 데이터와 함께 작업할 수 있습니다.

서버 측 LLM 샘플링 (Server-Side LLM Sampling)

EnrichMCP는 MCP의 샘플링 (sampling) 기능을 통해 언어 모델의 완성을 요청할 수 있습니다. 어떤 리소스에서든 ctx.ask_llm() 또는 ctx.sampling() 별칭을 호출하면, 연결된 클라이언트가 LLM을 선택하고 사용 비용을 지불합니다. model_preferences, allow_tools, max_tokens와 같은 옵션을 사용하여 동작을 조정할 수 있습니다. 자세한 내용은 docs/server_side_llm.md를 참조하세요.

예제 (Examples)

examples 디렉토리를 확인해 보세요:

• hello_world - 가장 최소 단위의 EnrichMCP 앱
• hello_world_http - streamable HTTP를 사용하는 HTTP 예제
• shop_api - 페이지네이션 및 필터가 포함된 인메모리(In-memory) 쇼핑 API
• shop_api_sqlite - SQLite 기반 버전
• shop_api_gateway - FastAPI 앞단의 게이트웨이로서의 EnrichMCP
• sqlalchemy_shop - SQLAlchemy 모델로부터 자동 생성된 API
• mutable_crud - 가변 필드(Mutable fields) 및 CRUD 데코레이터 시연
• caching - ContextCache 사용 시연
• basic_memory - FileMemoryStore를 사용하는 간단한 메모 작성 API
• openai_chat_agent - MCP 예제를 위한 대화형 채팅 클라이언트

문서 (Documentation)

• 📖 전체 문서 (Full Documentation)
• 🚀 시작 가이드 (Getting Started Guide)
• 🔧 API 레퍼런스 (API Reference)

기여하기 (Contributing)

기여를 환영합니다! 자세한 내용은 CONTRIBUTING.md를 참조하세요.

개발 환경 설정 (Development Setup)

이 저장소는 Python 3.11 이상의 버전을 요구합니다. Makefile에는 가상 환경 (Virtual Environment)을 생성하고 테스트를 실행하는 명령어가 포함되어 있습니다:

make setup            # .venv 생성 및 의존성 설치
source .venv/bin/activate
make test             # 테스트 스위트 (Test Suite) 실행

이를 통해 모든 개발용 추가 패키지 (Development Extras)와 프리 커밋 훅 (Pre-commit Hooks)이 설치되어, make lint 또는 make docs와 같은 명령어를 즉시 사용할 수 있습니다.

라이선스 (License)

Apache 2.0 - LICENSE를 참조하세요.

---

Featureform 제작 • MCP Protocol