get_notifications

Retrieve user notifications from USCardForum to monitor replies, mentions, likes, and watched topic updates. Requires authentication.

Instructions

Fetch your notifications. REQUIRES AUTHENTICATION.

Args:
    since_id: Only get notifications newer than this ID (optional)
    only_unread: Only return unread notifications (default: False)
    limit: Maximum number to return (optional)

Must call login() first.

Returns a list of Notification objects with:
- id: Notification ID
- notification_type: Type of notification
- read: Whether read
- topic_id: Related topic
- post_number: Related post
- created_at: When created

Use to:
- Check for new replies to your posts
- See mentions and likes
- Track topic updates you're watching

Input Schema

TableJSON Schema

Name	Required	Description
`since_id`	No	Only get notifications newer than this ID
`only_unread`	No	Only return unread notifications
`limit`	No	Maximum number to return

Implementation Reference

src/uscardforum/server_tools/auth.py:78-119 (handler)

Primary MCP tool handler for 'get_notifications'. Decorated with @mcp.tool(), defines input parameters with descriptions (serving as input schema), and implements logic by calling the client method.

@mcp.tool()
def get_notifications(
    since_id: Annotated[
        int | None,
        Field(default=None, description="Only get notifications newer than this ID"),
    ] = None,
    only_unread: Annotated[
        bool,
        Field(default=False, description="Only return unread notifications"),
    ] = False,
    limit: Annotated[
        int | None,
        Field(default=None, description="Maximum number to return"),
    ] = None,
) -> list[Notification]:
    """
    Fetch your notifications. REQUIRES AUTHENTICATION.

    Args:
        since_id: Only get notifications newer than this ID (optional)
        only_unread: Only return unread notifications (default: False)
        limit: Maximum number to return (optional)

    Must call login() first.

    Returns a list of Notification objects with:
    - id: Notification ID
    - notification_type: Type of notification
    - read: Whether read
    - topic_id: Related topic
    - post_number: Related post
    - created_at: When created

    Use to:
    - Check for new replies to your posts
    - See mentions and likes
    - Track topic updates you're watching
    """
    return get_client().get_notifications(
        since_id=since_id, only_unread=only_unread, limit=limit
    )

src/uscardforum/models/auth.py:66-80 (schema)

Pydantic BaseModel defining the structure of a Notification object, used as the return type (list[Notification]) for the tool.

class Notification(BaseModel):
    """A user notification."""

    id: int = Field(..., description="Notification ID")
    notification_type: int = Field(..., description="Type of notification")
    read: bool = Field(False, description="Whether read")
    created_at: datetime | None = Field(None, description="When created")
    topic_id: int | None = Field(None, description="Related topic ID")
    post_number: int | None = Field(None, description="Related post number")
    slug: str | None = Field(None, description="Topic slug")
    data: dict[str, Any] = Field(default_factory=dict, description="Extra data")

    class Config:
        extra = "ignore"

src/uscardforum/client.py:490-508 (helper)

Client class method that wraps the AuthAPI.get_notifications() call, providing a high-level interface used by the tool handler.

def get_notifications(
    self,
    since_id: int | None = None,
    only_unread: bool = False,
    limit: int | None = None,
) -> list[Notification]:
    """Fetch notifications (requires auth).

    Args:
        since_id: Only notifications after this ID
        only_unread: Only unread notifications
        limit: Maximum notifications to return

    Returns:
        List of notification objects
    """
    return self._auth.get_notifications(
        since_id=since_id, only_unread=only_unread, limit=limit
    )

src/uscardforum/server_tools/__init__.py:52-55 (registration)
Import of get_notifications from auth.py into the server_tools package __init__, making it available for import in server.py and exposing it as part of the tools package.
```
from .auth import (
    login,
    get_current_session,
    get_notifications,
```

src/uscardforum/server.py:15-25 (registration)

Import of get_notifications in the main server entrypoint, ensuring the tool is loaded when the server starts (tools auto-register via decorators).

from uscardforum.server_tools import (
    analyze_user,
    bookmark_post,
    compare_cards,
    find_data_points,
    get_all_topic_posts,
    get_categories,
    get_current_session,
    get_hot_topics,
    get_new_topics,
    get_notifications,

USCardForum MCP Server