EnrichMCP

EnrichMCP can automatically transform existing SQLAlchemy models into an AI-navigable API.

To use this feature:

1. Add EnrichSQLAlchemyMixin to your DeclarativeBase.
2. Use the info parameter in mapped_column or relationship to provide descriptions that help the AI understand the schema.
3. Initialize the EnrichMCP app using sqlalchemy_lifespan to manage the database connection and lifecycle.
4. Register your models with the app using include_sqlalchemy_models(app, Base).

This enables tools like explore_data_model(), automatic filtering (e.g., list_users(status='active')), and relationship navigation (e.g., user.orders).

from enrichmcp import EnrichMCP
from enrichmcp.sqlalchemy import (
    include_sqlalchemy_models,
    sqlalchemy_lifespan,
    EnrichSQLAlchemyMixin,
)
from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship

engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")

class Base(DeclarativeBase, EnrichSQLAlchemyMixin):
    pass

class User(Base):
    """User account."""
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True, info={"description": "Unique user ID"})
    orders: Mapped[list["Order"]] = relationship(
        back_populates="user", info={"description": "All orders for this user"}
    )

class Order(Base):
    """Customer order."""
    __tablename__ = "orders"
    user_id: Mapped[int] = mapped_column(info={"description": "Owner user ID"})
    user: Mapped[User] = relationship(back_populates="orders")

app = EnrichMCP(
    "E-commerce Data",
    "API generated from SQLAlchemy models",
    lifespan=sqlalchemy_lifespan(Base, engine, cleanup_db_file=True),
)
include_sqlalchemy_models(app, Base)

if __name__ == "__main__":
    app.run()

You can wrap existing REST APIs by defining entities that inherit from EnrichModel.

Key components:

• @app.entity(): Decorator to define a data model (entity) that the AI can interact with.
• Relationship: Used within an EnrichModel to define navigable links between entities (e.g., a Customer has many Orders).
• @app.retrieve(): Decorator used to define how to fetch a specific entity by its ID or other parameters.
• @Entity.relationship.resolver: Decorator used to define the logic for fetching related data when an AI agent navigates a relationship.

This approach allows AI agents to traverse your API as if it were a local graph of objects.

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

app = EnrichMCP("API Gateway", "Wrapper around existing REST APIs")
http = httpx.AsyncClient(base_url="https://api.example.com")

@app.entity()
class Customer(EnrichModel):
    id: int = Field(description="Unique customer ID")
    orders: list["Order"] = Relationship(description="Customer's purchase history")

@app.entity()
class Order(EnrichModel):
    id: int = Field(description="Order ID")
    customer: Customer = Relationship(description="Customer who placed this order")

@app.retrieve()
async def get_customer(customer_id: int) -> Customer:
    """Fetch customer from CRM API."""
    response = await http.get(f"/api/customers/{customer_id}")
    return Customer(**response.json())

@Customer.orders.resolver
async def get_customer_orders(customer_id: int) -> list[Order]:
    """Fetch orders for a customer."""
    response = await http.get(f"/api/customers/{customer_id}/orders")
    return [Order(**order) for order in response.json()]

app.run()

If you need to write generic utility functions (like an exporter) that can handle both page-based and cursor-based pagination, use the PaginatedResult protocol.

By using result.get_next_params(), your loop can automatically update its parameters for the next iteration regardless of whether the underlying implementation uses pages or cursors.

from enrichmcp import PaginatedResult
from typing import Callable, Awaitable, TypeVar

T = TypeVar("T")

async def export_paginated_data(
    fetcher: Callable[..., Awaitable[PaginatedResult[T]]], **initial_params
) -> list[T]:
    """Export all pages of data."""
    all_items = []
    params = initial_params.copy()

    while True:
        result = await fetcher(**params)
        all_items.extend(result.items)

        if not result.has_next:
            break

        # Works for both page and cursor pagination
        params.update(result.get_next_params())

    return all_items

To create links between entities (e.g., an Author having many Books), use the Relationship type within your EnrichModel. This allows the API to navigate between related data points.

from enrichmcp import EnrichModel, Relationship

class Author(EnrichModel):
    # ... fields ...
    books: list["Book"] = Relationship(description="Books written by this author")

class Book(EnrichModel):
    # ... fields ...
    author: Author = Relationship(description="Author of this book")

@app.entity()
class Author(EnrichModel):
    """Represents a book author."""

    id: int = Field(description="Author ID")
    name: str = Field(description="Author's full name")
    bio: str = Field(description="Short biography")
    birth_date: date = Field(description="Date of birth")

    # Relationship to books
    books: list["Book"] = Relationship(description="Books written by this author")

EnrichMCP transforms your data models into an MCP (Model Context Protocol) API designed specifically for AI agents. It works through a structured lifecycle:

1. Model Definition: You define Pydantic models decorated with @app.entity(). These models are self-describing, meaning they include rich descriptions that AI agents can use to understand the schema.
2. Relationship Mapping: You connect entities using Relationship. This allows AI agents to perform natural data traversal (e.g., moving from a Customer to their Orders).
3. Data Resolution: You implement @Relationship.resolver methods to provide the actual logic for fetching related data from your database or external service.
4. Resource Exposure: You define entry points using @app.retrieve(), which allows agents to access specific records.
5. Agent Interaction: Once running, AI agents can call explore_data_model() to discover the schema, use resources to access data, and follow relationships to traverse the data graph.