Migration to FastMCP 2 (#162)

---------

Co-authored-by: Simba Khadder <[email protected]>

Author: simba-git

.gitignore

@@ -61,6 +61,9 @@ local_settings.py
 db.sqlite3
 db.sqlite3-journal
 
+# Example database files
+shop.db
+
 # Flask stuff:
 instance/
 .webassets-cache

README.md

@@ -39,17 +39,23 @@ Transform your existing SQLAlchemy models into an AI-navigable API:
 
 ```python
 from enrichmcp import EnrichMCP
-from enrichmcp.sqlalchemy import include_sqlalchemy_models, sqlalchemy_lifespan, EnrichSQLAlchemyMixin
+from enrichmcp.sqlalchemy import (
+    include_sqlalchemy_models,
+    sqlalchemy_lifespan,
+    EnrichSQLAlchemyMixin,
+)
 from sqlalchemy import ForeignKey
 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")
 
+
 # Add the mixin to your declarative base
 class Base(DeclarativeBase, EnrichSQLAlchemyMixin):
     pass
 
+
 class User(Base):
     """User account."""
 
@@ -58,17 +64,25 @@ class User(Base):
     id: Mapped[int] = mapped_column(primary_key=True, info={"description": "Unique user ID"})
     email: Mapped[str] = mapped_column(unique=True, info={"description": "Email address"})
     status: Mapped[str] = mapped_column(default="active", info={"description": "Account status"})
-    orders: Mapped[list["Order"]] = relationship(back_populates="user", info={"description": "All orders for this user"})
+    orders: Mapped[list["Order"]] = relationship(
+        back_populates="user", info={"description": "All orders for this user"}
+    )
+
 
 class Order(Base):
     """Customer order."""
 
     __tablename__ = "orders"
 
     id: Mapped[int] = mapped_column(primary_key=True, info={"description": "Order ID"})
-    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), info={"description": "Owner user ID"})
+    user_id: Mapped[int] = mapped_column(
+        ForeignKey("users.id"), info={"description": "Owner user ID"}
+    )
     total: Mapped[float] = mapped_column(info={"description": "Order total"})
-    user: Mapped[User] = relationship(back_populates="orders", info={"description": "User who placed the order"})
+    user: Mapped[User] = relationship(
+        back_populates="orders", info={"description": "User who placed the order"}
+    )
+
 
 # That's it! Create your MCP app
 app = EnrichMCP(
@@ -100,52 +114,54 @@ import httpx
 app = EnrichMCP("API Gateway", "Wrapper around existing REST APIs")
 http = httpx.AsyncClient(base_url="https://api.example.com")
 
-@app.entity
+
+@app.entity()
 class Customer(EnrichModel):
     """Customer in our CRM system."""
 
     id: int = Field(description="Unique customer ID")
     email: str = Field(description="Primary contact email")
-    tier: Literal["free", "pro", "enterprise"] = Field(
-        description="Subscription tier"
-    )
+    tier: Literal["free", "pro", "enterprise"] = Field(description="Subscription tier")
 
     # Define navigable relationships
     orders: list["Order"] = Relationship(description="Customer's purchase history")
 
-@app.entity
+
+@app.entity()
 class Order(EnrichModel):
     """Customer order from our e-commerce platform."""
 
     id: int = Field(description="Order ID")
     customer_id: int = Field(description="Associated customer")
     total: float = Field(description="Order total in USD")
-    status: Literal["pending", "shipped", "delivered"] = Field(
-        description="Order status"
-    )
+    status: Literal["pending", "shipped", "delivered"] = Field(description="Order status")
 
     customer: Customer = Relationship(description="Customer who placed this order")
 
+
 # Define how to fetch data
-@app.retrieve
+@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())
 
+
 # Define relationship resolvers
 @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()]
 
+
 @Order.customer.resolver
 async def get_order_customer(order_id: int) -> Customer:
     """Fetch the customer for an order."""
     response = await http.get(f"/api/orders/{order_id}/customer")
     return Customer(**response.json())
 
+
 app.run()
 ```
 
@@ -163,7 +179,8 @@ app = EnrichMCP("Analytics Platform", "Custom analytics API")
 
 db = ...  # your database connection
 
-@app.entity
+
+@app.entity()
 class User(EnrichModel):
     """User with computed analytics fields."""
 
@@ -179,7 +196,8 @@ class User(EnrichModel):
     orders: list["Order"] = Relationship(description="Purchase history")
     segments: list["Segment"] = Relationship(description="Marketing segments")
 
-@app.entity
+
+@app.entity()
 class Segment(EnrichModel):
     """Dynamic user segment for marketing."""
 
@@ -188,14 +206,15 @@ class Segment(EnrichModel):
     users: list[User] = Relationship(description="Users in this segment")
 
 
-@app.entity
+@app.entity()
 class Order(EnrichModel):
     """Simplified order record."""
 
     id: int = Field(description="Order ID")
     user_id: int = Field(description="Owner user ID")
     total: Decimal = Field(description="Order total")
 
+
 @User.orders.resolver
 async def list_user_orders(user_id: int) -> list[Order]:
     """Fetch orders for a user."""
@@ -205,6 +224,7 @@ async def list_user_orders(user_id: int) -> list[Order]:
     )
     return [Order(**row) for row in rows]
 
+
 @User.segments.resolver
 async def list_user_segments(user_id: int) -> list[Segment]:
     """Fetch segments that include the user."""
@@ -214,6 +234,7 @@ async def list_user_segments(user_id: int) -> list[Segment]:
     )
     return [Segment(**row) for row in rows]
 
+
 @Segment.users.resolver
 async def list_segment_users(name: str) -> list[User]:
     """List users in a segment."""
@@ -223,12 +244,11 @@ async def list_segment_users(name: str) -> list[User]:
     )
     return [User(**row) for row in rows]
 
+
 # Complex resource with business logic
-@app.retrieve
+@app.retrieve()
 async def find_high_value_at_risk_users(
-    lifetime_value_min: Decimal = 1000,
-    churn_risk_min: float = 0.7,
-    limit: int = 100
+    lifetime_value_min: Decimal = 1000, churn_risk_min: float = 0.7, limit: int = 100
 ) -> list[User]:
     """Find valuable customers likely to churn."""
     users = await db.query(
@@ -238,20 +258,21 @@ async def find_high_value_at_risk_users(
         ORDER BY lifetime_value DESC
         LIMIT ?
         """,
-        lifetime_value_min, churn_risk_min, limit
+        lifetime_value_min,
+        churn_risk_min,
+        limit,
     )
     return [User(**u) for u in users]
 
+
 # Async computed field resolver
 @User.lifetime_value.resolver
 async def calculate_lifetime_value(user_id: int) -> Decimal:
     """Calculate total revenue from user's orders."""
-    total = await db.query_single(
-        "SELECT SUM(total) FROM orders WHERE user_id = ?",
-        user_id
-    )
+    total = await db.query_single("SELECT SUM(total) FROM orders WHERE user_id = ?", user_id)
     return Decimal(str(total or 0))
 
+
 # ML-powered field
 @User.churn_risk.resolver
 async def predict_churn_risk(user_id: int) -> float:
@@ -261,6 +282,7 @@ async def predict_churn_risk(user_id: int) -> float:
     model = ctx.get("ml_models")["churn"]
     return float(model.predict_proba(features)[0][1])
 
+
 app.run()
 ```
 
@@ -291,7 +313,7 @@ products = await orders[0].products()
 Full Pydantic validation on every interaction:
 
 ```python
-@app.entity
+@app.entity()
 class Order(EnrichModel):
     total: float = Field(ge=0, description="Must be positive")
     email: EmailStr = Field(description="Customer email")
@@ -305,22 +327,22 @@ Fields are immutable by default. Mark them as mutable and use
 auto-generated patch models for updates:
 
 ```python
-@app.entity
+@app.entity()
 class Customer(EnrichModel):
     id: int = Field(description="ID")
     email: str = Field(json_schema_extra={"mutable": True}, description="Email")
 
-@app.create
-async def create_customer(email: str) -> Customer:
-    ...
 
-@app.update
-async def update_customer(cid: int, patch: Customer.PatchModel) -> Customer:
-    ...
+@app.create()
+async def create_customer(email: str) -> Customer: ...
+
 
-@app.delete
-async def delete_customer(cid: int) -> bool:
-    ...
+@app.update()
+async def update_customer(cid: int, patch: Customer.PatchModel) -> Customer: ...
+
+
+@app.delete()
+async def delete_customer(cid: int) -> bool: ...
 ```
 
 ### 📄 Pagination Built-in
@@ -330,18 +352,11 @@ Handle large datasets elegantly:
 ```python
 from enrichmcp import PageResult
 
-@app.retrieve
-async def list_orders(
-    page: int = 1,
-    page_size: int = 50
-) -> PageResult[Order]:
+
+@app.retrieve()
+async def list_orders(page: int = 1, page_size: int = 50) -> PageResult[Order]:
     orders, total = await db.get_orders_page(page, page_size)
-    return PageResult.create(
-        items=orders,
-        page=page,
-        page_size=page_size,
-        total_items=total
-    )
+    return PageResult.create(items=orders, page=page, page_size=page_size, total_items=total)
 ```
 
 See the [Pagination Guide](https://featureform.github.io/enrichmcp/pagination) for more examples.
@@ -354,13 +369,15 @@ Pass auth, database connections, or any context:
 from pydantic import Field
 from enrichmcp import EnrichModel
 
+
 class UserProfile(EnrichModel):
     """User profile information."""
 
     user_id: int = Field(description="User ID")
     bio: str | None = Field(default=None, description="Short bio")
 
-@app.retrieve
+
+@app.retrieve()
 async def get_user_profile(user_id: int) -> UserProfile:
     ctx = app.get_context()
     # Access context provided by MCP client
@@ -375,10 +392,10 @@ async def get_user_profile(user_id: int) -> UserProfile:
 Reduce API overhead by storing results in a per-request, per-user, or global cache:
 
 ```python
-
-@app.retrieve
+@app.retrieve()
 async def get_customer(cid: int) -> Customer:
     ctx = app.get_context()
+
     async def fetch() -> Customer:
         return await db.get_customer(cid)
 
@@ -392,7 +409,8 @@ Provide examples and metadata for tool parameters using `EnrichParameter`:
 ```python
 from enrichmcp import EnrichParameter
 
-@app.retrieve
+
+@app.retrieve()
 async def greet_user(name: str = EnrichParameter(description="user name", examples=["bob"])) -> str:
     return f"Hello {name}"
 ```

backup/__init__.py

@@ -1,5 +1,4 @@
-"""
-enrichmcp - A Python-first Framework for Exposing Structured Data to AI Agents.
+"""enrichmcp - A Python-first Framework for Exposing Structured Data to AI Agents.
 
 Powered by Pydantic & the Model-Context Protocol.
 """

docs/api.md

@@ -21,7 +21,7 @@ from enrichmcp import EnrichModel
 from pydantic import Field
 
 
-@app.entity
+@app.entity()
 class User(EnrichModel):
     id: int = Field(description="User ID")
     name: str = Field(description="Username")
@@ -38,8 +38,8 @@ class User(EnrichModel):
     orders: list["Order"] = Relationship(description="User's orders")
 ```
 
-### [EnrichContext](api/context.md)
-Context object with request scoped utilities including caching.
+### [Context](api/context.md)
+FastMCP's Context object with request scoped utilities including logging, progress reporting, and lifespan context access.
 
 ### [EnrichParameter](api/parameter.md)
 Attach metadata like descriptions and examples to function parameters.
@@ -53,10 +53,10 @@ Currently uses standard Python exceptions and Pydantic validation.
 ## Key Concepts
 
 ### Entity Registration
-Entities must be registered with the app using the `@app.entity` decorator:
+Entities must be registered with the app using the `@app.entity()` decorator:
 
 ```python
-@app.entity
+@app.entity()
 class Product(EnrichModel):
     """Product in our catalog."""
 
@@ -78,7 +78,7 @@ async def get_user_orders(user_id: int) -> list["Order"]:
 Resources are the entry points for AI agents:
 
 ```python
-@app.retrieve
+@app.retrieve()
 async def list_users() -> list[User]:
     """List all users in the system."""
     return fetch_all_users()