Enhance MCP logging and add unread message tool

Add MCP support for replying to posts

backend/src/main/java/com/openisle/controller/CommentController.java

@@ -1,11 +1,13 @@
 package com.openisle.controller;
 
+import com.openisle.dto.CommentContextDto;
 import com.openisle.dto.CommentDto;
 import com.openisle.dto.CommentRequest;
 import com.openisle.dto.PostChangeLogDto;
 import com.openisle.dto.TimelineItemDto;
 import com.openisle.mapper.CommentMapper;
 import com.openisle.mapper.PostChangeLogMapper;
+import com.openisle.mapper.PostMapper;
 import com.openisle.model.Comment;
 import com.openisle.model.CommentSort;
 import com.openisle.service.*;
@@ -40,6 +42,7 @@ public class CommentController {
   private final PointService pointService;
   private final PostChangeLogService changeLogService;
   private final PostChangeLogMapper postChangeLogMapper;
+  private final PostMapper postMapper;
 
   @Value("${app.captcha.enabled:false}")
   private boolean captchaEnabled;
@@ -184,6 +187,37 @@ public class CommentController {
     return itemDtoList;
   }
 
+  @GetMapping("/comments/{commentId}/context")
+  @Operation(
+    summary = "Comment context",
+    description = "Get a comment along with its previous comments and related post"
+  )
+  @ApiResponse(
+    responseCode = "200",
+    description = "Comment context",
+    content = @Content(schema = @Schema(implementation = CommentContextDto.class))
+  )
+  public ResponseEntity<CommentContextDto> getCommentContext(@PathVariable Long commentId) {
+    log.debug("getCommentContext called for comment {}", commentId);
+    Comment comment = commentService.getComment(commentId);
+    CommentContextDto dto = new CommentContextDto();
+    dto.setPost(postMapper.toSummaryDto(comment.getPost()));
+    dto.setTargetComment(commentMapper.toDtoWithReplies(comment));
+    dto.setPreviousComments(
+      commentService
+        .getCommentsBefore(comment)
+        .stream()
+        .map(commentMapper::toDtoWithReplies)
+        .collect(Collectors.toList())
+    );
+    log.debug(
+      "getCommentContext returning {} previous comments for comment {}",
+      dto.getPreviousComments().size(),
+      commentId
+    );
+    return ResponseEntity.ok(dto);
+  }
+
   @DeleteMapping("/comments/{id}")
   @Operation(summary = "Delete comment", description = "Delete a comment")
   @ApiResponse(responseCode = "200", description = "Deleted")

backend/src/main/java/com/openisle/controller/PostController.java

@@ -224,6 +224,26 @@ public class PostController {
       .collect(Collectors.toList());
   }
 
+  @GetMapping("/recent")
+  @Operation(
+    summary = "Recent posts",
+    description = "List posts created within the specified number of minutes"
+  )
+  @ApiResponse(
+    responseCode = "200",
+    description = "Recent posts",
+    content = @Content(
+      array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))
+    )
+  )
+  public List<PostSummaryDto> recentPosts(@RequestParam("minutes") int minutes) {
+    return postService
+      .listRecentPosts(minutes)
+      .stream()
+      .map(postMapper::toSummaryDto)
+      .collect(Collectors.toList());
+  }
+
   @GetMapping("/ranking")
   @Operation(summary = "Ranking posts", description = "List posts by view rankings")
   @ApiResponse(

backend/src/main/java/com/openisle/dto/CommentContextDto.java

@@ -0,0 +1,15 @@
+package com.openisle.dto;
+
+import java.util.List;
+import lombok.Data;
+
+/**
+ * DTO representing the context of a comment including its post and previous comments.
+ */
+@Data
+public class CommentContextDto {
+
+  private PostSummaryDto post;
+  private CommentDto targetComment;
+  private List<CommentDto> previousComments;
+}

backend/src/main/java/com/openisle/repository/CommentRepository.java

@@ -3,6 +3,7 @@ package com.openisle.repository;
 import com.openisle.model.Comment;
 import com.openisle.model.Post;
 import com.openisle.model.User;
+import java.time.LocalDateTime;
 import java.util.List;
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.jpa.repository.JpaRepository;
@@ -10,6 +11,10 @@ import org.springframework.data.jpa.repository.JpaRepository;
 public interface CommentRepository extends JpaRepository<Comment, Long> {
   List<Comment> findByPostAndParentIsNullOrderByCreatedAtAsc(Post post);
   List<Comment> findByParentOrderByCreatedAtAsc(Comment parent);
+  List<Comment> findByPostAndCreatedAtLessThanOrderByCreatedAtAsc(
+    Post post,
+    LocalDateTime createdAt
+  );
   List<Comment> findByAuthorOrderByCreatedAtDesc(User author, Pageable pageable);
   List<Comment> findByContentContainingIgnoreCase(String keyword);
 

backend/src/main/java/com/openisle/repository/PostRepository.java

@@ -19,6 +19,10 @@ public interface PostRepository extends JpaRepository<Post, Long> {
   List<Post> findByStatusOrderByCreatedAtDesc(PostStatus status, Pageable pageable);
   List<Post> findByStatusOrderByViewsDesc(PostStatus status);
   List<Post> findByStatusOrderByViewsDesc(PostStatus status, Pageable pageable);
+  List<Post> findByStatusAndCreatedAtGreaterThanEqualOrderByCreatedAtDesc(
+    PostStatus status,
+    LocalDateTime createdAt
+  );
   List<Post> findByAuthorAndStatusOrderByCreatedAtDesc(
     User author,
     PostStatus status,

backend/src/main/java/com/openisle/service/CommentService.java

@@ -266,6 +266,27 @@ public class CommentService {
     return replies;
   }
 
+  public Comment getComment(Long commentId) {
+    log.debug("getComment called for id {}", commentId);
+    return commentRepository
+      .findById(commentId)
+      .orElseThrow(() -> new com.openisle.exception.NotFoundException("Comment not found"));
+  }
+
+  public List<Comment> getCommentsBefore(Comment comment) {
+    log.debug("getCommentsBefore called for comment {}", comment.getId());
+    List<Comment> comments = commentRepository.findByPostAndCreatedAtLessThanOrderByCreatedAtAsc(
+      comment.getPost(),
+      comment.getCreatedAt()
+    );
+    log.debug(
+      "getCommentsBefore returning {} comments for comment {}",
+      comments.size(),
+      comment.getId()
+    );
+    return comments;
+  }
+
   public List<Comment> getRecentCommentsByUser(String username, int limit) {
     log.debug("getRecentCommentsByUser called for user {} with limit {}", username, limit);
     User user = userRepository

backend/src/main/java/com/openisle/service/PostService.java

@@ -770,6 +770,18 @@ public class PostService {
     return listPostsByCategories(null, null, null);
   }
 
+  public List<Post> listRecentPosts(int minutes) {
+    if (minutes <= 0) {
+      throw new IllegalArgumentException("Minutes must be positive");
+    }
+    LocalDateTime since = LocalDateTime.now().minusMinutes(minutes);
+    List<Post> posts = postRepository.findByStatusAndCreatedAtGreaterThanEqualOrderByCreatedAtDesc(
+      PostStatus.PUBLISHED,
+      since
+    );
+    return sortByPinnedAndCreated(posts);
+  }
+
   public List<Post> listPostsByViews(Integer page, Integer pageSize) {
     return listPostsByViews(null, null, page, pageSize);
   }

mcp/README.md

@@ -31,7 +31,11 @@ By default the server listens on port `8085` and serves MCP over Streamable HTTP
 | Tool | Description |
 | --- | --- |
 | `search` | Perform a global search against the OpenIsle backend. |
+| `reply_to_post` | Create a new comment on a post using a JWT token. |
+| `reply_to_comment` | Reply to an existing comment using a JWT token. |
+| `recent_posts` | Retrieve posts created within the last *N* minutes. |
 
-The tool returns structured data describing each search hit including highlighted snippets when
-provided by the backend.
+The tools return structured data mirroring the backend DTOs, including highlighted snippets for
+search results, the full comment payload for post replies and comment replies, and detailed
+metadata for recent posts.
 

mcp/src/openisle_mcp/config.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from functools import lru_cache
 from typing import Literal
 
-from pydantic import Field
+from pydantic import Field, SecretStr
 from pydantic.networks import AnyHttpUrl
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
@@ -36,6 +36,20 @@ class Settings(BaseSettings):
         gt=0,
         description="Timeout (seconds) for backend search requests.",
     )
+    access_token: SecretStr | None = Field(
+        default=None,
+        description=(
+            "Optional JWT bearer token used for authenticated backend calls. "
+            "When set, tools that support authentication will use this token "
+            "automatically unless an explicit token override is provided."
+        ),
+    )
+    log_level: str = Field(
+        "INFO",
+        description=(
+            "Logging level for the MCP server (e.g. DEBUG, INFO, WARNING)."
+        ),
+    )
 
     model_config = SettingsConfigDict(
         env_prefix="OPENISLE_MCP_",

mcp/src/openisle_mcp/schemas.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from datetime import datetime
+from typing import Any, Optional
 
 from pydantic import BaseModel, Field, ConfigDict
 
@@ -53,3 +54,280 @@ class SearchResponse(BaseModel):
         description="Ordered collection of search results.",
     )
 
+
+class AuthorInfo(BaseModel):
+    """Summary of a post or comment author."""
+
+    id: Optional[int] = Field(default=None, description="Author identifier.")
+    username: Optional[str] = Field(default=None, description="Author username.")
+    avatar: Optional[str] = Field(default=None, description="URL of the author's avatar.")
+    display_medal: Optional[str] = Field(
+        default=None,
+        alias="displayMedal",
+        description="Medal displayed next to the author, when available.",
+    )
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class CategoryInfo(BaseModel):
+    """Basic information about a post category."""
+
+    id: Optional[int] = Field(default=None, description="Category identifier.")
+    name: Optional[str] = Field(default=None, description="Category name.")
+    description: Optional[str] = Field(
+        default=None, description="Human friendly description of the category."
+    )
+    icon: Optional[str] = Field(default=None, description="Icon URL associated with the category.")
+    small_icon: Optional[str] = Field(
+        default=None,
+        alias="smallIcon",
+        description="Compact icon URL for the category.",
+    )
+    count: Optional[int] = Field(default=None, description="Number of posts within the category.")
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class TagInfo(BaseModel):
+    """Details for a tag assigned to a post."""
+
+    id: Optional[int] = Field(default=None, description="Tag identifier.")
+    name: Optional[str] = Field(default=None, description="Tag name.")
+    description: Optional[str] = Field(default=None, description="Description of the tag.")
+    icon: Optional[str] = Field(default=None, description="Icon URL for the tag.")
+    small_icon: Optional[str] = Field(
+        default=None,
+        alias="smallIcon",
+        description="Compact icon URL for the tag.",
+    )
+    created_at: Optional[datetime] = Field(
+        default=None,
+        alias="createdAt",
+        description="When the tag was created.",
+    )
+    count: Optional[int] = Field(default=None, description="Number of posts using the tag.")
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class ReactionInfo(BaseModel):
+    """Representation of a reaction on a post or comment."""
+
+    id: Optional[int] = Field(default=None, description="Reaction identifier.")
+    type: Optional[str] = Field(default=None, description="Reaction type (emoji, like, etc.).")
+    user: Optional[str] = Field(default=None, description="Username of the reacting user.")
+    post_id: Optional[int] = Field(
+        default=None,
+        alias="postId",
+        description="Related post identifier when applicable.",
+    )
+    comment_id: Optional[int] = Field(
+        default=None,
+        alias="commentId",
+        description="Related comment identifier when applicable.",
+    )
+    message_id: Optional[int] = Field(
+        default=None,
+        alias="messageId",
+        description="Related message identifier when applicable.",
+    )
+    reward: Optional[int] = Field(default=None, description="Reward granted for the reaction, if any.")
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class CommentData(BaseModel):
+    """Comment information returned by the backend."""
+
+    id: Optional[int] = Field(default=None, description="Comment identifier.")
+    content: Optional[str] = Field(default=None, description="Markdown content of the comment.")
+    created_at: Optional[datetime] = Field(
+        default=None,
+        alias="createdAt",
+        description="Timestamp when the comment was created.",
+    )
+    pinned_at: Optional[datetime] = Field(
+        default=None,
+        alias="pinnedAt",
+        description="Timestamp when the comment was pinned, if applicable.",
+    )
+    author: Optional[AuthorInfo] = Field(default=None, description="Author of the comment.")
+    replies: list["CommentData"] = Field(
+        default_factory=list,
+        description="Nested replies associated with the comment.",
+    )
+    reactions: list[ReactionInfo] = Field(
+        default_factory=list,
+        description="Reactions applied to the comment.",
+    )
+    reward: Optional[int] = Field(default=None, description="Reward gained by posting the comment.")
+    point_reward: Optional[int] = Field(
+        default=None,
+        alias="pointReward",
+        description="Points rewarded for the comment.",
+    )
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class CommentReplyResult(BaseModel):
+    """Structured response returned when replying to a comment."""
+
+    comment: CommentData = Field(description="Reply comment returned by the backend.")
+
+
+class CommentCreateResult(BaseModel):
+    """Structured response returned when creating a comment on a post."""
+
+    comment: CommentData = Field(description="Comment returned by the backend.")
+
+
+class PostSummary(BaseModel):
+    """Summary information for a post."""
+
+    id: Optional[int] = Field(default=None, description="Post identifier.")
+    title: Optional[str] = Field(default=None, description="Title of the post.")
+    content: Optional[str] = Field(default=None, description="Excerpt or content of the post.")
+    created_at: Optional[datetime] = Field(
+        default=None,
+        alias="createdAt",
+        description="When the post was created.",
+    )
+    author: Optional[AuthorInfo] = Field(default=None, description="Author who created the post.")
+    category: Optional[CategoryInfo] = Field(default=None, description="Category of the post.")
+    tags: list[TagInfo] = Field(default_factory=list, description="Tags assigned to the post.")
+    views: Optional[int] = Field(default=None, description="Total view count for the post.")
+    comment_count: Optional[int] = Field(
+        default=None,
+        alias="commentCount",
+        description="Number of comments on the post.",
+    )
+    status: Optional[str] = Field(default=None, description="Workflow status of the post.")
+    pinned_at: Optional[datetime] = Field(
+        default=None,
+        alias="pinnedAt",
+        description="When the post was pinned, if ever.",
+    )
+    last_reply_at: Optional[datetime] = Field(
+        default=None,
+        alias="lastReplyAt",
+        description="Timestamp of the most recent reply.",
+    )
+    reactions: list[ReactionInfo] = Field(
+        default_factory=list,
+        description="Reactions received by the post.",
+    )
+    participants: list[AuthorInfo] = Field(
+        default_factory=list,
+        description="Users participating in the discussion.",
+    )
+    subscribed: Optional[bool] = Field(
+        default=None,
+        description="Whether the current user is subscribed to the post.",
+    )
+    reward: Optional[int] = Field(default=None, description="Reward granted for the post.")
+    point_reward: Optional[int] = Field(
+        default=None,
+        alias="pointReward",
+        description="Points granted for the post.",
+    )
+    type: Optional[str] = Field(default=None, description="Type of the post.")
+    lottery: Optional[dict[str, Any]] = Field(
+        default=None, description="Lottery information for the post."
+    )
+    poll: Optional[dict[str, Any]] = Field(
+        default=None, description="Poll information for the post."
+    )
+    rss_excluded: Optional[bool] = Field(
+        default=None,
+        alias="rssExcluded",
+        description="Whether the post is excluded from RSS feeds.",
+    )
+    closed: Optional[bool] = Field(default=None, description="Whether the post is closed for replies.")
+    visible_scope: Optional[str] = Field(
+        default=None,
+        alias="visibleScope",
+        description="Visibility scope configuration for the post.",
+    )
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class RecentPostsResponse(BaseModel):
+    """Structured response for the recent posts tool."""
+
+    minutes: int = Field(description="Time window, in minutes, used for the query.")
+    total: int = Field(description="Number of posts returned by the backend.")
+    posts: list[PostSummary] = Field(
+        default_factory=list,
+        description="Posts created within the requested time window.",
+    )
+
+
+CommentData.model_rebuild()
+
+
+class PostDetail(PostSummary):
+    """Detailed information for a single post, including comments."""
+
+    comments: list[CommentData] = Field(
+        default_factory=list,
+        description="Comments that belong to the post.",
+    )
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class NotificationData(BaseModel):
+    """Unread notification payload returned by the backend."""
+
+    id: Optional[int] = Field(default=None, description="Notification identifier.")
+    type: Optional[str] = Field(default=None, description="Type of the notification.")
+    post: Optional[PostSummary] = Field(
+        default=None, description="Post associated with the notification if applicable."
+    )
+    comment: Optional[CommentData] = Field(
+        default=None, description="Comment referenced by the notification when available."
+    )
+    parent_comment: Optional[CommentData] = Field(
+        default=None,
+        alias="parentComment",
+        description="Parent comment for nested replies, when present.",
+    )
+    from_user: Optional[AuthorInfo] = Field(
+        default=None,
+        alias="fromUser",
+        description="User who triggered the notification.",
+    )
+    reaction_type: Optional[str] = Field(
+        default=None,
+        alias="reactionType",
+        description="Reaction type for reaction-based notifications.",
+    )
+    content: Optional[str] = Field(
+        default=None, description="Additional content or message for the notification."
+    )
+    approved: Optional[bool] = Field(
+        default=None, description="Approval status for moderation notifications."
+    )
+    read: Optional[bool] = Field(default=None, description="Whether the notification is read.")
+    created_at: Optional[datetime] = Field(
+        default=None,
+        alias="createdAt",
+        description="Timestamp when the notification was created.",
+    )
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class UnreadNotificationsResponse(BaseModel):
+    """Structured response for unread notification queries."""
+
+    page: int = Field(description="Requested page index for the unread notifications.")
+    size: int = Field(description="Requested page size for the unread notifications.")
+    total: int = Field(description="Number of unread notifications returned in this page.")
+    notifications: list[NotificationData] = Field(
+        default_factory=list,
+        description="Unread notifications returned by the backend.",
+    )

mcp/src/openisle_mcp/search_client.py

@@ -1,41 +1,257 @@
-"""HTTP client helpers for talking to the OpenIsle backend search endpoints."""
+"""HTTP client helpers for talking to the OpenIsle backend endpoints."""
 
 from __future__ import annotations
 
 import json
+import logging
 from typing import Any
 
 import httpx
 
 
-class SearchClient:
-    """Client for calling the OpenIsle search API."""
+logger = logging.getLogger(__name__)
 
-    def __init__(self, base_url: str, *, timeout: float = 10.0) -> None:
+
+class SearchClient:
+    """Client for calling the OpenIsle HTTP APIs used by the MCP server."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout: float = 10.0,
+        access_token: str | None = None,
+    ) -> None:
         self._base_url = base_url.rstrip("/")
         self._timeout = timeout
         self._client: httpx.AsyncClient | None = None
+        self._access_token = self._sanitize_token(access_token)
 
     def _get_client(self) -> httpx.AsyncClient:
         if self._client is None:
-            self._client = httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout)
+            logger.debug(
+                "Creating httpx.AsyncClient for base URL %s with timeout %.2fs",
+                self._base_url,
+                self._timeout,
+            )
+            self._client = httpx.AsyncClient(
+                base_url=self._base_url,
+                timeout=self._timeout,
+            )
         return self._client
 
+    @staticmethod
+    def _sanitize_token(token: str | None) -> str | None:
+        if token is None:
+            return None
+        stripped = token.strip()
+        return stripped or None
+
+    def update_access_token(self, token: str | None) -> None:
+        """Update the default access token used for authenticated requests."""
+
+        self._access_token = self._sanitize_token(token)
+        if self._access_token:
+            logger.debug("Configured default access token for SearchClient requests.")
+        else:
+            logger.debug("Cleared default access token for SearchClient requests.")
+
+    def _resolve_token(self, token: str | None) -> str | None:
+        candidate = self._sanitize_token(token)
+        if candidate is not None:
+            return candidate
+        return self._access_token
+
+    def _require_token(self, token: str | None) -> str:
+        resolved = self._resolve_token(token)
+        if resolved is None:
+            raise ValueError(
+                "Authenticated request requires an access token but none was provided."
+            )
+        return resolved
+
+    def _build_headers(
+        self,
+        *,
+        token: str | None = None,
+        accept: str = "application/json",
+        include_json: bool = False,
+    ) -> dict[str, str]:
+        headers: dict[str, str] = {"Accept": accept}
+        resolved = self._resolve_token(token)
+        if resolved:
+            headers["Authorization"] = f"Bearer {resolved}"
+        if include_json:
+            headers["Content-Type"] = "application/json"
+        return headers
+
     async def global_search(self, keyword: str) -> list[dict[str, Any]]:
         """Call the global search endpoint and return the parsed JSON payload."""
 
         client = self._get_client()
+        logger.debug("Calling global search with keyword=%s", keyword)
         response = await client.get(
             "/api/search/global",
             params={"keyword": keyword},
-            headers={"Accept": "application/json"},
+            headers=self._build_headers(),
         )
         response.raise_for_status()
         payload = response.json()
         if not isinstance(payload, list):
             formatted = json.dumps(payload, ensure_ascii=False)[:200]
             raise ValueError(f"Unexpected response format from search endpoint: {formatted}")
-        return [self._validate_entry(entry) for entry in payload]
+        logger.info(
+            "Global search returned %d results for keyword '%s'",
+            len(payload),
+            keyword,
+        )
+        return [self._ensure_dict(entry) for entry in payload]
+
+    async def reply_to_comment(
+        self,
+        comment_id: int,
+        token: str,
+        content: str,
+        captcha: str | None = None,
+    ) -> dict[str, Any]:
+        """Reply to an existing comment and return the created reply."""
+
+        client = self._get_client()
+        resolved_token = self._require_token(token)
+        headers = self._build_headers(token=resolved_token, include_json=True)
+        payload: dict[str, Any] = {"content": content}
+        if captcha is not None:
+            stripped_captcha = captcha.strip()
+            if stripped_captcha:
+                payload["captcha"] = stripped_captcha
+
+        logger.debug(
+            "Posting reply to comment_id=%s (captcha=%s)",
+            comment_id,
+            bool(captcha),
+        )
+        response = await client.post(
+            f"/api/comments/{comment_id}/replies",
+            json=payload,
+            headers=headers,
+        )
+        response.raise_for_status()
+        body = self._ensure_dict(response.json())
+        logger.info("Reply to comment_id=%s succeeded with id=%s", comment_id, body.get("id"))
+        return body
+
+    async def reply_to_post(
+        self,
+        post_id: int,
+        token: str,
+        content: str,
+        captcha: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a comment on a post and return the backend payload."""
+
+        client = self._get_client()
+        resolved_token = self._require_token(token)
+        headers = self._build_headers(token=resolved_token, include_json=True)
+        payload: dict[str, Any] = {"content": content}
+        if captcha is not None:
+            stripped_captcha = captcha.strip()
+            if stripped_captcha:
+                payload["captcha"] = stripped_captcha
+
+        logger.debug(
+            "Posting comment to post_id=%s (captcha=%s)",
+            post_id,
+            bool(captcha),
+        )
+        response = await client.post(
+            f"/api/posts/{post_id}/comments",
+            json=payload,
+            headers=headers,
+        )
+        response.raise_for_status()
+        body = self._ensure_dict(response.json())
+        logger.info("Reply to post_id=%s succeeded with id=%s", post_id, body.get("id"))
+        return body
+
+    async def recent_posts(self, minutes: int) -> list[dict[str, Any]]:
+        """Return posts created within the given timeframe."""
+
+        client = self._get_client()
+        logger.debug(
+            "Fetching recent posts within last %s minutes",
+            minutes,
+        )
+        response = await client.get(
+            "/api/posts/recent",
+            params={"minutes": minutes},
+            headers=self._build_headers(),
+        )
+        response.raise_for_status()
+        payload = response.json()
+        if not isinstance(payload, list):
+            formatted = json.dumps(payload, ensure_ascii=False)[:200]
+            raise ValueError(
+                f"Unexpected response format from recent posts endpoint: {formatted}"
+            )
+        logger.info(
+            "Fetched %d recent posts for window=%s minutes",
+            len(payload),
+            minutes,
+        )
+        return [self._ensure_dict(entry) for entry in payload]
+
+    async def get_post(self, post_id: int, token: str | None = None) -> dict[str, Any]:
+        """Retrieve the detailed payload for a single post."""
+
+        client = self._get_client()
+        headers = self._build_headers(token=token)
+        logger.debug("Fetching post details for post_id=%s", post_id)
+        response = await client.get(f"/api/posts/{post_id}", headers=headers)
+        response.raise_for_status()
+        body = self._ensure_dict(response.json())
+        logger.info(
+            "Retrieved post_id=%s successfully with %d top-level comments",
+            post_id,
+            len(body.get("comments", []) if isinstance(body.get("comments"), list) else []),
+        )
+        return body
+
+    async def list_unread_notifications(
+        self,
+        *,
+        page: int = 0,
+        size: int = 30,
+        token: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Return unread notifications for the authenticated user."""
+
+        client = self._get_client()
+        resolved_token = self._require_token(token)
+        logger.debug(
+            "Fetching unread notifications with page=%s, size=%s",
+            page,
+            size,
+        )
+        response = await client.get(
+            "/api/notifications/unread",
+            params={"page": page, "size": size},
+            headers=self._build_headers(token=resolved_token),
+        )
+        response.raise_for_status()
+        payload = response.json()
+        if not isinstance(payload, list):
+            formatted = json.dumps(payload, ensure_ascii=False)[:200]
+            raise ValueError(
+                "Unexpected response format from unread notifications endpoint: "
+                f"{formatted}"
+            )
+        logger.info(
+            "Fetched %d unread notifications (page=%s, size=%s)",
+            len(payload),
+            page,
+            size,
+        )
+        return [self._ensure_dict(entry) for entry in payload]
 
     async def aclose(self) -> None:
         """Dispose of the underlying HTTP client."""
@@ -43,9 +259,10 @@ class SearchClient:
         if self._client is not None:
             await self._client.aclose()
             self._client = None
+            logger.debug("Closed httpx.AsyncClient for SearchClient.")
 
     @staticmethod
-    def _validate_entry(entry: Any) -> dict[str, Any]:
+    def _ensure_dict(entry: Any) -> dict[str, Any]:
         if not isinstance(entry, dict):
-            raise ValueError(f"Search entry must be an object, got: {type(entry)!r}")
+            raise ValueError(f"Expected JSON object, got: {type(entry)!r}")
         return entry

mcp/src/openisle_mcp/server.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 from contextlib import asynccontextmanager
 from typing import Annotated
 
@@ -11,12 +12,41 @@ from pydantic import ValidationError
 from pydantic import Field as PydanticField
 
 from .config import get_settings
-from .schemas import SearchResponse, SearchResultItem
+from .schemas import (
+    CommentCreateResult,
+    CommentData,
+    CommentReplyResult,
+    NotificationData,
+    UnreadNotificationsResponse,
+    PostDetail,
+    PostSummary,
+    RecentPostsResponse,
+    SearchResponse,
+    SearchResultItem,
+)
 from .search_client import SearchClient
 
 settings = get_settings()
+if not logging.getLogger().handlers:
+    logging.basicConfig(
+        level=getattr(logging, settings.log_level.upper(), logging.INFO),
+        format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+    )
+else:
+    logging.getLogger().setLevel(
+        getattr(logging, settings.log_level.upper(), logging.INFO)
+    )
+
+logger = logging.getLogger(__name__)
+
 search_client = SearchClient(
-    str(settings.backend_base_url), timeout=settings.request_timeout
+    str(settings.backend_base_url),
+    timeout=settings.request_timeout,
+    access_token=(
+        settings.access_token.get_secret_value()
+        if settings.access_token is not None
+        else None
+    ),
 )
 
 
@@ -25,16 +55,19 @@ async def lifespan(_: FastMCP):
     """Lifecycle hook that disposes shared resources when the server stops."""
 
     try:
+        logger.debug("OpenIsle MCP server lifespan started.")
         yield
     finally:
+        logger.debug("Disposing shared SearchClient instance.")
         await search_client.aclose()
 
 
 app = FastMCP(
     name="openisle-mcp",
     instructions=(
-        "Use this server to search OpenIsle posts, users, tags, categories, and comments "
-        "via the global search endpoint."
+        "Use this server to search OpenIsle content, reply to posts and comments with an "
+        "authentication token, retrieve details for a specific post, list posts created "
+        "within a recent time window, and review unread notification messages."
     ),
     host=settings.host,
     port=settings.port,
@@ -58,6 +91,7 @@ async def search(
         raise ValueError("Keyword must not be empty.")
 
     try:
+        logger.info("Received search request for keyword='%s'", sanitized)
         raw_results = await search_client.global_search(sanitized)
     except httpx.HTTPStatusError as exc:  # pragma: no cover - network errors
         message = (
@@ -83,10 +117,441 @@ async def search(
 
     if ctx is not None:
         await ctx.info(f"Search keyword '{sanitized}' returned {len(results)} results.")
+    logger.debug(
+        "Validated %d search results for keyword='%s'",
+        len(results),
+        sanitized,
+    )
 
     return SearchResponse(keyword=sanitized, total=len(results), results=results)
 
 
+@app.tool(
+    name="reply_to_post",
+    description="Create a comment on a post using an authentication token.",
+    structured_output=True,
+)
+async def reply_to_post(
+    post_id: Annotated[
+        int,
+        PydanticField(ge=1, description="Identifier of the post being replied to."),
+    ],
+    content: Annotated[
+        str,
+        PydanticField(description="Markdown content of the reply."),
+    ],
+    captcha: Annotated[
+        str | None,
+        PydanticField(
+            default=None,
+            description="Optional captcha solution if the backend requires it.",
+        ),
+    ] = None,
+    token: Annotated[
+        str | None,
+        PydanticField(
+            default=None,
+            description=(
+                "Optional JWT bearer token. When omitted the configured access token is used."
+            ),
+        ),
+    ] = None,
+    ctx: Context | None = None,
+) -> CommentCreateResult:
+    """Create a comment on a post and return the backend payload."""
+
+    sanitized_content = content.strip()
+    if not sanitized_content:
+        raise ValueError("Reply content must not be empty.")
+
+    sanitized_token = token.strip() if isinstance(token, str) else None
+
+    sanitized_captcha = captcha.strip() if isinstance(captcha, str) else None
+
+    try:
+        logger.info(
+            "Creating reply for post_id=%s (captcha=%s)",
+            post_id,
+            bool(sanitized_captcha),
+        )
+        raw_comment = await search_client.reply_to_post(
+            post_id,
+            sanitized_token,
+            sanitized_content,
+            sanitized_captcha,
+        )
+    except httpx.HTTPStatusError as exc:  # pragma: no cover - network errors
+        status_code = exc.response.status_code
+        if status_code == 401:
+            message = (
+                "Authentication failed while replying to post "
+                f"{post_id}. Please verify the token."
+            )
+        elif status_code == 403:
+            message = (
+                "The provided token is not authorized to reply to post "
+                f"{post_id}."
+            )
+        elif status_code == 404:
+            message = f"Post {post_id} was not found."
+        else:
+            message = (
+                "OpenIsle backend returned HTTP "
+                f"{status_code} while replying to post {post_id}."
+            )
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+    except httpx.RequestError as exc:  # pragma: no cover - network errors
+        message = (
+            "Unable to reach OpenIsle backend comment service: "
+            f"{exc}."
+        )
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+
+    try:
+        comment = CommentData.model_validate(raw_comment)
+    except ValidationError as exc:
+        message = "Received malformed data from the post comment endpoint."
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+
+    if ctx is not None:
+        await ctx.info(
+            "Reply created successfully for post "
+            f"{post_id}."
+        )
+    logger.debug(
+        "Validated reply comment payload for post_id=%s (comment_id=%s)",
+        post_id,
+        comment.id,
+    )
+
+    return CommentCreateResult(comment=comment)
+
+
+@app.tool(
+    name="reply_to_comment",
+    description="Reply to an existing comment using an authentication token.",
+    structured_output=True,
+)
+async def reply_to_comment(
+    comment_id: Annotated[
+        int,
+        PydanticField(ge=1, description="Identifier of the comment being replied to."),
+    ],
+    content: Annotated[
+        str,
+        PydanticField(description="Markdown content of the reply."),
+    ],
+    captcha: Annotated[
+        str | None,
+        PydanticField(
+            default=None,
+            description="Optional captcha solution if the backend requires it.",
+        ),
+    ] = None,
+    token: Annotated[
+        str | None,
+        PydanticField(
+            default=None,
+            description=(
+                "Optional JWT bearer token. When omitted the configured access token is used."
+            ),
+        ),
+    ] = None,
+    ctx: Context | None = None,
+) -> CommentReplyResult:
+    """Create a reply for a comment and return the backend payload."""
+
+    sanitized_content = content.strip()
+    if not sanitized_content:
+        raise ValueError("Reply content must not be empty.")
+
+    sanitized_token = token.strip() if isinstance(token, str) else None
+
+    sanitized_captcha = captcha.strip() if isinstance(captcha, str) else None
+
+    try:
+        logger.info(
+            "Creating reply for comment_id=%s (captcha=%s)",
+            comment_id,
+            bool(sanitized_captcha),
+        )
+        raw_comment = await search_client.reply_to_comment(
+            comment_id,
+            sanitized_token,
+            sanitized_content,
+            sanitized_captcha,
+        )
+    except httpx.HTTPStatusError as exc:  # pragma: no cover - network errors
+        status_code = exc.response.status_code
+        if status_code == 401:
+            message = (
+                "Authentication failed while replying to comment "
+                f"{comment_id}. Please verify the token."
+            )
+        elif status_code == 403:
+            message = (
+                "The provided token is not authorized to reply to comment "
+                f"{comment_id}."
+            )
+        else:
+            message = (
+                "OpenIsle backend returned HTTP "
+                f"{status_code} while replying to comment {comment_id}."
+            )
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+    except httpx.RequestError as exc:  # pragma: no cover - network errors
+        message = (
+            "Unable to reach OpenIsle backend comment service: "
+            f"{exc}."
+        )
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+
+    try:
+        comment = CommentData.model_validate(raw_comment)
+    except ValidationError as exc:
+        message = "Received malformed data from the reply comment endpoint."
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+
+    if ctx is not None:
+        await ctx.info(
+            "Reply created successfully for comment "
+            f"{comment_id}."
+        )
+    logger.debug(
+        "Validated reply payload for comment_id=%s (reply_id=%s)",
+        comment_id,
+        comment.id,
+    )
+
+    return CommentReplyResult(comment=comment)
+
+
+@app.tool(
+    name="recent_posts",
+    description="Retrieve posts created in the last N minutes.",
+    structured_output=True,
+)
+async def recent_posts(
+    minutes: Annotated[
+        int,
+        PydanticField(gt=0, le=1440, description="Time window in minutes to search for new posts."),
+    ],
+    ctx: Context | None = None,
+) -> RecentPostsResponse:
+    """Fetch recent posts from the backend and return structured data."""
+
+    try:
+        logger.info("Fetching recent posts for last %s minutes", minutes)
+        raw_posts = await search_client.recent_posts(minutes)
+    except httpx.HTTPStatusError as exc:  # pragma: no cover - network errors
+        message = (
+            "OpenIsle backend returned HTTP "
+            f"{exc.response.status_code} while fetching recent posts for the last {minutes} minutes."
+        )
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+    except httpx.RequestError as exc:  # pragma: no cover - network errors
+        message = f"Unable to reach OpenIsle backend recent posts service: {exc}."
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+
+    try:
+        posts = [PostSummary.model_validate(entry) for entry in raw_posts]
+    except ValidationError as exc:
+        message = "Received malformed data from the recent posts endpoint."
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+
+    if ctx is not None:
+        await ctx.info(
+            f"Found {len(posts)} posts created within the last {minutes} minutes."
+        )
+    logger.debug(
+        "Validated %d recent posts for window=%s minutes",
+        len(posts),
+        minutes,
+    )
+
+    return RecentPostsResponse(minutes=minutes, total=len(posts), posts=posts)
+
+
+@app.tool(
+    name="get_post",
+    description="Retrieve detailed information for a single post.",
+    structured_output=True,
+)
+async def get_post(
+    post_id: Annotated[
+        int,
+        PydanticField(ge=1, description="Identifier of the post to retrieve."),
+    ],
+    token: Annotated[
+        str | None,
+        PydanticField(
+            default=None,
+            description="Optional JWT bearer token to view the post as an authenticated user.",
+        ),
+    ] = None,
+    ctx: Context | None = None,
+) -> PostDetail:
+    """Fetch post details from the backend and validate the response."""
+
+    sanitized_token = token.strip() if isinstance(token, str) else None
+    if sanitized_token == "":
+        sanitized_token = None
+
+    try:
+        logger.info("Fetching post details for post_id=%s", post_id)
+        raw_post = await search_client.get_post(post_id, sanitized_token)
+    except httpx.HTTPStatusError as exc:  # pragma: no cover - network errors
+        status_code = exc.response.status_code
+        if status_code == 404:
+            message = f"Post {post_id} was not found."
+        elif status_code == 401:
+            message = "Authentication failed while retrieving the post."
+        elif status_code == 403:
+            message = "The provided token is not authorized to view this post."
+        else:
+            message = (
+                "OpenIsle backend returned HTTP "
+                f"{status_code} while retrieving post {post_id}."
+            )
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+    except httpx.RequestError as exc:  # pragma: no cover - network errors
+        message = f"Unable to reach OpenIsle backend post service: {exc}."
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+
+    try:
+        post = PostDetail.model_validate(raw_post)
+    except ValidationError as exc:
+        message = "Received malformed data from the post detail endpoint."
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+
+    if ctx is not None:
+        await ctx.info(f"Retrieved post {post_id} successfully.")
+    logger.debug(
+        "Validated post payload for post_id=%s with %d comments",
+        post_id,
+        len(post.comments),
+    )
+
+    return post
+
+
+@app.tool(
+    name="list_unread_messages",
+    description="List unread notification messages for the authenticated user.",
+    structured_output=True,
+)
+async def list_unread_messages(
+    page: Annotated[
+        int,
+        PydanticField(
+            default=0,
+            ge=0,
+            description="Page number of unread notifications to retrieve.",
+        ),
+    ] = 0,
+    size: Annotated[
+        int,
+        PydanticField(
+            default=30,
+            ge=1,
+            le=100,
+            description="Number of unread notifications to include per page.",
+        ),
+    ] = 30,
+    token: Annotated[
+        str | None,
+        PydanticField(
+            default=None,
+            description=(
+                "Optional JWT bearer token. When omitted the configured access token is used."
+            ),
+        ),
+    ] = None,
+    ctx: Context | None = None,
+) -> UnreadNotificationsResponse:
+    """Retrieve unread notifications and return structured data."""
+
+    sanitized_token = token.strip() if isinstance(token, str) else None
+
+    try:
+        logger.info(
+            "Fetching unread notifications (page=%s, size=%s)",
+            page,
+            size,
+        )
+        raw_notifications = await search_client.list_unread_notifications(
+            page=page,
+            size=size,
+            token=sanitized_token,
+        )
+    except httpx.HTTPStatusError as exc:  # pragma: no cover - network errors
+        message = (
+            "OpenIsle backend returned HTTP "
+            f"{exc.response.status_code} while fetching unread notifications."
+        )
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+    except httpx.RequestError as exc:  # pragma: no cover - network errors
+        message = f"Unable to reach OpenIsle backend notification service: {exc}."
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+
+    try:
+        notifications = [
+            NotificationData.model_validate(entry) for entry in raw_notifications
+        ]
+    except ValidationError as exc:
+        message = "Received malformed data from the unread notifications endpoint."
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+
+    total = len(notifications)
+    if ctx is not None:
+        await ctx.info(
+            f"Retrieved {total} unread notifications (page {page}, size {size})."
+        )
+    logger.debug(
+        "Validated %d unread notifications for page=%s size=%s",
+        total,
+        page,
+        size,
+    )
+
+    return UnreadNotificationsResponse(
+        page=page,
+        size=size,
+        total=total,
+        notifications=notifications,
+    )
+
+
 def main() -> None:
     """Run the MCP server using the configured transport."""