Enhance MCP logging and add unread message tool

Add MCP support for replying to posts

.env.example

@@ -2,6 +2,7 @@
 SERVER_PORT=8080
 FRONTEND_PORT=3000
 WEBSOCKET_PORT=8082
+OPENISLE_MCP_PORT=8085
 MYSQL_PORT=3306
 REDIS_PORT=6379
 RABBITMQ_PORT=5672

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

@@ -66,6 +66,7 @@ public class PostController {
       req.getContent(),
       req.getTagIds(),
       req.getType(),
+      req.getPostVisibleScopeType(),
       req.getPrizeDescription(),
       req.getPrizeIcon(),
       req.getPrizeCount(),
@@ -103,7 +104,8 @@ public class PostController {
       req.getCategoryId(),
       req.getTitle(),
       req.getContent(),
-      req.getTagIds()
+      req.getTagIds(),
+      req.getPostVisibleScopeType()
     );
     return ResponseEntity.ok(postMapper.toDetailDto(post, auth.getName()));
   }
@@ -222,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/dto/PostChangeLogDto.java

@@ -1,6 +1,7 @@
 package com.openisle.dto;
 
 import com.openisle.model.PostChangeType;
+import com.openisle.model.PostVisibleScopeType;
 import java.time.LocalDateTime;
 import java.util.List;
 import lombok.Getter;
@@ -29,5 +30,7 @@ public class PostChangeLogDto {
   private LocalDateTime newPinnedAt;
   private Boolean oldFeatured;
   private Boolean newFeatured;
+  private PostVisibleScopeType oldVisibleScope;
+  private PostVisibleScopeType newVisibleScope;
   private Integer amount;
 }

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

@@ -3,6 +3,8 @@ package com.openisle.dto;
 import com.openisle.model.PostType;
 import java.time.LocalDateTime;
 import java.util.List;
+
+import com.openisle.model.PostVisibleScopeType;
 import lombok.Data;
 
 /**
@@ -19,6 +21,7 @@ public class PostRequest {
 
   // optional for lottery posts
   private PostType type;
+  private PostVisibleScopeType postVisibleScopeType;
   private String prizeDescription;
   private String prizeIcon;
   private Integer prizeCount;

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

@@ -4,6 +4,8 @@ import com.openisle.model.PostStatus;
 import com.openisle.model.PostType;
 import java.time.LocalDateTime;
 import java.util.List;
+
+import com.openisle.model.PostVisibleScopeType;
 import lombok.Data;
 
 /**
@@ -34,4 +36,5 @@ public class PostSummaryDto {
   private PollDto poll;
   private boolean rssExcluded;
   private boolean closed;
+  private PostVisibleScopeType visibleScope;
 }

backend/src/main/java/com/openisle/mapper/PostChangeLogMapper.java

@@ -52,6 +52,9 @@ public class PostChangeLogMapper {
     } else if (log instanceof PostFeaturedChangeLog f) {
       dto.setOldFeatured(f.isOldFeatured());
       dto.setNewFeatured(f.isNewFeatured());
+    } else if (log instanceof PostVisibleScopeChangeLog v) {
+      dto.setOldVisibleScope(v.getOldVisibleScope());
+      dto.setNewVisibleScope(v.getNewVisibleScope());
     } else if (log instanceof PostDonateChangeLog d) {
       dto.setAmount(d.getAmount());
     }

backend/src/main/java/com/openisle/mapper/PostMapper.java

@@ -75,6 +75,7 @@ public class PostMapper {
     dto.setPinnedAt(post.getPinnedAt());
     dto.setRssExcluded(post.getRssExcluded() == null || post.getRssExcluded());
     dto.setClosed(post.isClosed());
+    dto.setVisibleScope(post.getVisibleScope());
 
     List<ReactionDto> reactions = reactionService
       .getReactionsForPost(post.getId())

backend/src/main/java/com/openisle/model/Post.java

@@ -66,6 +66,10 @@ public class Post {
   @Column(nullable = false)
   private PostType type = PostType.NORMAL;
 
+  @Enumerated(EnumType.STRING)
+  @Column(nullable = false)
+  private PostVisibleScopeType visibleScope = PostVisibleScopeType.ALL;
+
   @Column(nullable = false)
   private boolean closed = false;
 

backend/src/main/java/com/openisle/model/PostChangeType.java

@@ -8,6 +8,7 @@ public enum PostChangeType {
   CLOSED,
   PINNED,
   FEATURED,
+  VISIBLE_SCOPE,
   VOTE_RESULT,
   LOTTERY_RESULT,
   DONATE,

backend/src/main/java/com/openisle/model/PostVisibleScopeChangeLog.java

@@ -0,0 +1,23 @@
+package com.openisle.model;
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@Entity
+@Table(name = "post_visible_scope_change_logs")
+public class PostVisibleScopeChangeLog extends PostChangeLog {
+
+  @Enumerated(EnumType.STRING)
+  private PostVisibleScopeType oldVisibleScope;
+
+  @Enumerated(EnumType.STRING)
+  private PostVisibleScopeType newVisibleScope;
+}

backend/src/main/java/com/openisle/model/PostVisibleScopeType.java

@@ -0,0 +1,32 @@
+package com.openisle.model;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonValue;
+
+public enum PostVisibleScopeType {
+    ALL,
+    ONLY_ME,
+    ONLY_REGISTER;
+
+    /**
+     * 防止画面传递错误的值
+     * @param value
+     * @return
+     */
+    @JsonCreator
+    public static PostVisibleScopeType fromString(String value) {
+        if (value == null) return ALL;
+        for (PostVisibleScopeType type : PostVisibleScopeType.values()) {
+            if (type.name().equalsIgnoreCase(value)) {
+                return type;
+            }
+        }
+        // 不匹配时给默认值，而不是抛异常
+        return ALL;
+    }
+
+    @JsonValue
+    public String toValue() {
+        return this.name();
+    }
+}

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/PostChangeLogService.java

@@ -99,6 +99,21 @@ public class PostChangeLogService {
     logRepository.save(log);
   }
 
+  public void recordVisibleScopeChange(
+    Post post,
+    User user,
+    PostVisibleScopeType oldVisibleScope,
+    PostVisibleScopeType newVisibleScope
+  ) {
+    PostVisibleScopeChangeLog log = new PostVisibleScopeChangeLog();
+    log.setPost(post);
+    log.setUser(user);
+    log.setType(PostChangeType.VISIBLE_SCOPE);
+    log.setOldVisibleScope(oldVisibleScope);
+    log.setNewVisibleScope(newVisibleScope);
+    logRepository.save(log);
+  }
+
   public void recordVoteResult(Post post) {
     PostVoteResultChangeLog log = new PostVoteResultChangeLog();
     log.setPost(post);

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

@@ -1,6 +1,7 @@
 package com.openisle.service;
 
 import com.openisle.config.CachingConfig;
+import com.openisle.exception.NotFoundException;
 import com.openisle.exception.RateLimitException;
 import com.openisle.model.*;
 import com.openisle.repository.CategoryProposalPostRepository;
@@ -252,6 +253,7 @@ public class PostService {
     String content,
     List<Long> tagIds,
     PostType type,
+    PostVisibleScopeType postVisibleScopeType,
     String prizeDescription,
     String prizeIcon,
     Integer prizeCount,
@@ -336,6 +338,14 @@ public class PostService {
     post.setCategory(category);
     post.setTags(new HashSet<>(tags));
     post.setStatus(publishMode == PublishMode.REVIEW ? PostStatus.PENDING : PostStatus.PUBLISHED);
+
+    // 什么都没设置的情况下，默认为ALL
+    if (Objects.isNull(postVisibleScopeType)) {
+      post.setVisibleScope(PostVisibleScopeType.ALL);
+    } else {
+      post.setVisibleScope(postVisibleScopeType);
+    }
+
     if (post instanceof LotteryPost) {
       post = lotteryPostRepository.save((LotteryPost) post);
     } else if (post instanceof CategoryProposalPost categoryProposalPost) {
@@ -716,7 +726,7 @@ public class PostService {
       .orElseThrow(() -> new com.openisle.exception.NotFoundException("Post not found"));
     if (post.getStatus() != PostStatus.PUBLISHED) {
       if (viewer == null) {
-        throw new com.openisle.exception.NotFoundException("Post not found");
+        throw new com.openisle.exception.NotFoundException("User not found");
       }
       User viewerUser = userRepository
         .findByUsername(viewer)
@@ -760,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);
   }
@@ -1147,7 +1169,8 @@ public class PostService {
     Long categoryId,
     String title,
     String content,
-    java.util.List<Long> tagIds
+    List<Long> tagIds,
+    PostVisibleScopeType postVisibleScopeType
   ) {
     if (tagIds == null || tagIds.isEmpty()) {
       throw new IllegalArgumentException("At least one tag required");
@@ -1179,6 +1202,8 @@ public class PostService {
     post.setContent(content);
     post.setCategory(category);
     post.setTags(new java.util.HashSet<>(tags));
+    PostVisibleScopeType oldVisibleScope = post.getVisibleScope();
+    post.setVisibleScope(postVisibleScopeType);
     Post updated = postRepository.save(post);
     imageUploader.adjustReferences(oldContent, content);
     notificationService.notifyMentions(content, user, updated, null);
@@ -1200,6 +1225,14 @@ public class PostService {
     if (!oldTags.equals(newTags)) {
       postChangeLogService.recordTagChange(updated, user, oldTags, newTags);
     }
+    if (!java.util.Objects.equals(oldVisibleScope, postVisibleScopeType)) {
+      postChangeLogService.recordVisibleScopeChange(
+        updated,
+        user,
+        oldVisibleScope,
+        postVisibleScopeType
+      );
+    }
     if (updated.getStatus() == PostStatus.PUBLISHED) {
       searchIndexEventPublisher.publishPostSaved(updated);
     }

backend/src/main/resources/db/migration/V6__add_visible_scope_to_posts.sql

@@ -0,0 +1 @@
+ALTER TABLE posts ADD COLUMN visible_scope ENUM('ALL', 'ONLY_ME', 'ONLY_REGISTER') NOT NULL DEFAULT 'ALL'

deploy/deploy.sh

@@ -40,12 +40,12 @@ echo "👉 Build images ..."
 docker compose -f "$compose_file" --env-file "$env_file" \
   build --pull \
   --build-arg NUXT_ENV=production \
-  frontend_service
+  frontend_service mcp
 
 echo "👉 Recreate & start all target services (no dev profile)..."
 docker compose -f "$compose_file" --env-file "$env_file" \
   up -d --force-recreate --remove-orphans --no-deps \
-  mysql redis rabbitmq websocket-service springboot frontend_service
+  mysql redis rabbitmq websocket-service springboot frontend_service mcp
 
 echo "👉 Current status:"
 docker compose -f "$compose_file" --env-file "$env_file" ps

deploy/deploy_staging.sh

@@ -36,16 +36,15 @@ echo "👉 Pull base images (for image-based services)..."
 docker compose -f "$compose_file" --env-file "$env_file" pull --ignore-pull-failures
 
 echo "👉 Build images (staging)..."
-# 前端 + OpenSearch 都是自建镜像；--pull 更新其基础镜像
 docker compose -f "$compose_file" --env-file "$env_file" \
   build --pull \
   --build-arg NUXT_ENV=staging \
-  frontend_service
+  frontend_service mcp
 
 echo "👉 Recreate & start all target services (no dev profile)..."
 docker compose -f "$compose_file" --env-file "$env_file" \
   up -d --force-recreate --remove-orphans --no-deps \
-  mysql redis rabbitmq websocket-service springboot frontend_service
+  mysql redis rabbitmq websocket-service springboot frontend_service mcp
 
 echo "👉 Current status:"
 docker compose -f "$compose_file" --env-file "$env_file" ps

docker/docker-compose.yaml

@@ -161,8 +161,8 @@ services:
         condition: service_started
       websocket-service:
         condition: service_healthy
-      opensearch:
-        condition: service_healthy
+      # opensearch:
+      #   condition: service_healthy
     command: >
       sh -c "apt-get update && apt-get install -y --no-install-recommends curl &&
              mvn clean spring-boot:run -Dmaven.test.skip=true"
@@ -178,6 +178,32 @@ services:
       - dev
       - prod
 
+  mcp:
+    build:
+      context: ..
+      dockerfile: docker/mcp.Dockerfile
+    container_name: ${COMPOSE_PROJECT_NAME}-openisle-mcp
+    env_file:
+      - ${ENV_FILE:-../.env}
+    environment:
+      OPENISLE_MCP_BACKEND_BASE_URL: http://springboot:${SERVER_PORT:-8080}
+      OPENISLE_MCP_HOST: 0.0.0.0
+      OPENISLE_MCP_PORT: ${OPENISLE_MCP_PORT:-8085}
+      OPENISLE_MCP_TRANSPORT: ${OPENISLE_MCP_TRANSPORT:-streamable-http}
+      OPENISLE_MCP_REQUEST_TIMEOUT: ${OPENISLE_MCP_REQUEST_TIMEOUT:-10.0}
+    ports:
+      - "${OPENISLE_MCP_PORT:-8085}:${OPENISLE_MCP_PORT:-8085}"
+    depends_on:
+      springboot:
+        condition: service_started
+    networks:
+      - openisle-network
+    profiles:
+      - dev
+      - dev_local_backend
+      - prod
+
+
   websocket-service:
     image: maven:3.9-eclipse-temurin-17
     container_name: ${COMPOSE_PROJECT_NAME}-openisle-websocket

docker/mcp.Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.11-slim AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY mcp/pyproject.toml mcp/README.md ./
+COPY mcp/src ./src
+
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir .
+
+ENV OPENISLE_MCP_HOST=0.0.0.0 \
+    OPENISLE_MCP_PORT=8085 \
+    OPENISLE_MCP_TRANSPORT=streamable-http
+
+EXPOSE 8085
+
+CMD ["openisle-mcp"]
+

frontend_nuxt/components/HeaderComponent.vue

@@ -543,6 +543,7 @@ onMounted(async () => {
 .header-label {
   font-size: 12px;
   line-height: 1;
+  white-space: nowrap;
 }
 
 /* 在线人数的数字文字样式（无背景） */

frontend_nuxt/components/LoginOverlay.vue

@@ -3,15 +3,30 @@
     <div class="login-overlay-blur"></div>
     <div class="login-overlay-content">
       <user-icon class="login-overlay-icon" />
-      <div class="login-overlay-text">请先登录，点击跳转到登录页面</div>
-      <div class="login-overlay-button" @click="goLogin">登录</div>
+      <div class="login-overlay-text">{{ props.text }}</div>
+      <div class="login-overlay-button" @click="goLogin">{{ props.buttonText }}</div>
     </div>
   </div>
 </template>
 
 <script setup>
+const props = defineProps({
+  text: {
+    type: String,
+    default: '请先登录，点击跳转到登录页面',
+  },
+  buttonText: {
+    type: String,
+    default: '登录',
+  },
+  buttonLink: {
+    type: String,
+    default: '/login',
+  },
+})
+
 const goLogin = () => {
-  navigateTo('/login', { replace: true })
+  navigateTo(props.buttonLink, { replace: true })
 }
 </script>
 

frontend_nuxt/components/PostChangeLogItem.vue

@@ -36,6 +36,10 @@
         <template v-if="log.newFeatured">将文章设为精选</template>
         <template v-else>取消精选文章</template>
       </span>
+      <span v-else-if="log.type === 'VISIBLE_SCOPE'" class="change-log-content">
+        变更了文章可见范围, 从 {{ formatVisibleScope(log.oldVisibleScope) }} 修改为
+        {{ formatVisibleScope(log.newVisibleScope) }}
+      </span>
       <span v-else-if="log.type === 'VOTE_RESULT'" class="change-log-content"
         >系统已计算投票结果</span
       >
@@ -69,6 +73,17 @@ const props = defineProps({
   title: String,
 })
 
+const VISIBLE_SCOPE_LABELS = {
+  ALL: '全部可见',
+  ONLY_ME: '仅自己可见',
+  ONLY_REGISTER: '仅注册用户可见',
+}
+
+const formatVisibleScope = (scope) => {
+  if (!scope) return VISIBLE_SCOPE_LABELS.ALL
+  return VISIBLE_SCOPE_LABELS[scope] ?? scope
+}
+
 const diffHtml = computed(() => {
   // Track theme changes
   const isDark = import.meta.client && document.documentElement.dataset.theme === 'dark'

frontend_nuxt/components/PostVisibleScopeSelect.vue

@@ -0,0 +1,41 @@
+<template>
+  <Dropdown
+    v-model="selected"
+    :fetch-options="fetchTypes"
+    placeholder="选择帖子可见范围"
+  />
+</template>
+
+<script>
+import { computed, ref, watch } from 'vue'
+import Dropdown from '~/components/Dropdown.vue'
+
+export default {
+  name: 'PostVisibleScopeSelect',
+  components: { Dropdown },
+  props: {
+    modelValue: { type: String, default: 'ALL' },
+    // options: { type: Array, default: () => [] },
+  },
+  emits: ['update:modelValue'],
+  setup(props, { emit }) {
+
+    const fetchTypes = async () => {
+      return [
+        { id: 'ALL', name: '全部可见', icon: 'communication' },
+        { id: 'ONLY_ME', name: '仅自己可见', icon: 'user-icon' },
+        { id: 'ONLY_REGISTER', name: '仅注册用户可见', icon: 'peoples-two' },
+      ]
+    }
+
+    const selected = computed({
+      get: () => props.modelValue,
+      set: (v) => emit('update:modelValue', v),
+    })
+
+    return { fetchTypes, selected }
+  },
+}
+</script>
+
+<style scoped></style>

frontend_nuxt/pages/index.vue

@@ -70,6 +70,7 @@
               <hands v-else-if="article.type === 'PROPOSAL'" class="proposal-icon" />
               <star v-if="!article.rssExcluded" class="featured-icon" />
               {{ article.title }}
+              <lock class="preview-close-icon" v-if="article.isRestricted" />
             </NuxtLink>
             <NuxtLink class="article-item-description main-item" :to="`/posts/${article.id}`">
               <div v-html="stripMarkdownWithTiebaMoji(article.description, 500)"></div>
@@ -295,6 +296,7 @@ const {
       comments: p.commentCount,
       views: p.views,
       rssExcluded: p.rssExcluded || false,
+      isRestricted: p.visibleScope === 'ONLY_ME' || p.visibleScope === 'ONLY_REGISTER',
       time: TimeManager.format(
         selectedTopic.value === '最新回复' ? p.lastReplyAt || p.createdAt : p.createdAt,
       ),
@@ -336,6 +338,7 @@ const fetchNextPage = async () => {
     members: (p.participants || []).map((m) => ({ id: m.id, avatar: m.avatar })),
     comments: p.commentCount,
     views: p.views,
+    isRestricted: p.visibleScope === 'ONLY_ME' || p.visibleScope === 'ONLY_REGISTER',
     rssExcluded: p.rssExcluded || false,
     time: TimeManager.format(
       selectedTopic.value === '最新回复' ? p.lastReplyAt || p.createdAt : p.createdAt,

frontend_nuxt/pages/new-post.vue

@@ -11,6 +11,7 @@
           <CategorySelect v-model="selectedCategory" />
           <TagSelect v-model="selectedTags" creatable />
           <PostTypeSelect v-model="postType" />
+          <PostVisibleScopeSelect v-model="postVisibleScope"/>
         </div>
         <div class="post-options-right">
           <div class="post-clear" @click="clearPost"><clear-icon /> 清空</div>
@@ -54,6 +55,7 @@ import PollForm from '~/components/PollForm.vue'
 import ProposalForm from '~/components/ProposalForm.vue'
 import { toast } from '~/main'
 import { authState, getToken } from '~/utils/auth'
+import PostVisibleScopeSelect from '~/components/PostVisibleScopeSelect.vue'
 const config = useRuntimeConfig()
 const API_BASE_URL = config.public.apiBaseUrl
 
@@ -62,6 +64,7 @@ const content = ref('')
 const selectedCategory = ref('')
 const selectedTags = ref([])
 const postType = ref('NORMAL')
+const postVisibleScope = ref('ALL')
 const lottery = reactive({
   prizeIcon: '',
   prizeIconFile: null,
@@ -100,6 +103,7 @@ const loadDraft = async () => {
       content.value = data.content || ''
       selectedCategory.value = data.categoryId || ''
       selectedTags.value = data.tagIds || []
+      postVisibleScope.value = data.visiblescope
 
       toast.success('草稿已加载')
     }
@@ -115,6 +119,7 @@ const clearPost = async () => {
   content.value = ''
   selectedCategory.value = ''
   selectedTags.value = []
+  postVisibleScope.value = 'ALL'
   postType.value = 'NORMAL'
   lottery.prizeIcon = ''
   lottery.prizeIconFile = null
@@ -168,6 +173,7 @@ const saveDraft = async () => {
         content: content.value,
         categoryId: selectedCategory.value || null,
         tagIds,
+        postVisibleScopeType:postVisibleScope.value
       }),
     })
     if (res.ok) {
@@ -328,6 +334,7 @@ const submitPost = async () => {
       categoryId: selectedCategory.value,
       tagIds: selectedTags.value,
       type: postType.value,
+      postVisibleScopeType: postVisibleScope.value,
     }
 
     if (postType.value === 'LOTTERY') {
@@ -355,6 +362,7 @@ const submitPost = async () => {
       },
       body: JSON.stringify(payload),
     })
+    
     const data = await res.json()
     if (res.ok) {
       if (data.reward && data.reward > 0) {

frontend_nuxt/pages/posts/[id]/edit.vue

@@ -10,6 +10,7 @@
         <div class="post-options-left">
           <CategorySelect v-model="selectedCategory" />
           <TagSelect v-model="selectedTags" creatable />
+          <PostVisibleScopeSelect v-model="selectedVisibleScope"/>
         </div>
         <div class="post-options-right">
           <div class="post-clear" @click="clearPost"><clear-icon /> 清空</div>
@@ -44,6 +45,7 @@ import TagSelect from '~/components/TagSelect.vue'
 import { toast } from '~/main'
 import { getToken, authState } from '~/utils/auth'
 import LoginOverlay from '~/components/LoginOverlay.vue'
+import PostVisibleScopeSelect from '~/components/PostVisibleScopeSelect.vue'
 const config = useRuntimeConfig()
 const API_BASE_URL = config.public.apiBaseUrl
 
@@ -51,6 +53,7 @@ const title = ref('')
 const content = ref('')
 const selectedCategory = ref('')
 const selectedTags = ref([])
+const selectedVisibleScope = ref('ALL')
 const isWaitingPosting = ref(false)
 const isAiLoading = ref(false)
 const isLogin = computed(() => authState.loggedIn)
@@ -70,6 +73,7 @@ const loadPost = async () => {
       content.value = data.content || ''
       selectedCategory.value = data.category.id || ''
       selectedTags.value = (data.tags || []).map((t) => t.id)
+      selectedVisibleScope.value = data.visibleScope
     }
   } catch (e) {
     toast.error('加载失败')
@@ -180,6 +184,7 @@ const submitPost = async () => {
         content: content.value,
         categoryId: selectedCategory.value,
         tagIds: selectedTags.value,
+        postVisibleScopeType:selectedVisibleScope.value
       }),
     })
     const data = await res.json()

frontend_nuxt/pages/posts/[id]/index.vue

@@ -1,5 +1,22 @@
 <template>
-  <div class="post-page-container">
+  <div v-if="isRestricted" class="restricted-content">
+    <template v-if="visibleScope === 'ONLY_ME'">
+      <LoginOverlay
+        text="这是一篇私密文章，仅作者本人及管理员可见"
+        button-text="返回首页"
+        button-link="/"
+      />
+    </template>
+
+    <template v-else-if="visibleScope === 'ONLY_REGISTER'">
+      <LoginOverlay
+        text="这是一篇仅登录用户可见的文章，请先登录"
+        button-text="登录"
+        button-link="/login"
+      />
+    </template>
+  </div>
+  <div v-else class="post-page-container">
     <div v-if="isWaitingFetchingPost" class="loading-container">
       <l-hatch size="28" stroke="4" speed="3.5" color="var(--primary-color)"></l-hatch>
     </div>
@@ -16,7 +33,9 @@
           <div v-if="status === 'PENDING'" class="article-pending-button">审核中</div>
           <div v-if="status === 'REJECTED'" class="article-block-button">已拒绝</div>
           <div v-if="!rssExcluded" class="article-featured-button">精品</div>
-          <div v-if="closed" class="article-closed-button">已关闭</div>
+          <div v-if="closed" class="article-gray-button">已关闭</div>
+          <div v-if="visibleScope === 'ONLY_ME'" class="article-gray-button">仅自己可见</div>
+          <div v-if="visibleScope === 'ONLY_REGISTER'" class="article-gray-button">仅登录可见</div>
           <div
             v-if="!closed && loggedIn && !isAuthor && !subscribed"
             class="article-subscribe-button"
@@ -165,25 +184,6 @@
       </div>
     </div>
 
-    <div class="post-page-scroller-container">
-      <div class="scroller">
-        <div v-if="isWaitingFetchingPost" class="scroller-time">loading...</div>
-        <div v-else class="scroller-time">{{ scrollerTopTime }}</div>
-        <div class="scroller-middle">
-          <input
-            type="range"
-            class="scroller-range"
-            :max="totalPosts"
-            :min="1"
-            v-model.number="currentIndex"
-            @input="onSliderInput"
-          />
-          <div class="scroller-index">{{ currentIndex }}/{{ totalPosts }}</div>
-        </div>
-        <div v-if="isWaitingFetchingPost" class="scroller-time">loading...</div>
-        <div v-else class="scroller-time">{{ lastReplyTime }}</div>
-      </div>
-    </div>
     <vue-easy-lightbox
       :visible="lightboxVisible"
       :index="lightboxIndex"
@@ -228,6 +228,7 @@ import { useIsMobile } from '~/utils/screen'
 import Dropdown from '~/components/Dropdown.vue'
 import { ClientOnly } from '#components'
 import { useConfirm } from '~/composables/useConfirm'
+import { Lock } from '@icon-park/vue-next'
 const { confirm } = useConfirm()
 
 const config = useRuntimeConfig()
@@ -241,6 +242,13 @@ const author = ref('')
 const postContent = ref('')
 const category = ref('')
 const tags = ref([])
+const visibleScope = ref('ALL') // 可见范围
+const isRestricted = computed(() => {
+  return (
+    (visibleScope.value === 'ONLY_ME' && !isAuthor.value && !isAdmin.value) ||
+    (visibleScope.value === 'ONLY_REGISTER' && !loggedIn.value)
+  )
+})
 const postReactions = ref([])
 const postReactionsGroupRef = ref(null)
 const postLikeCount = computed(
@@ -408,6 +416,14 @@ const changeLogIcon = (l) => {
     } else {
       return 'dislike'
     }
+  } else if (l.type === 'VISIBLE_SCOPE') {
+    if (l.newVisibleScope === 'ONLY_ME') {
+      return 'lock-one'
+    } else if (l.newVisibleScope === 'ONLY_REGISTER') {
+      return 'peoples-two'
+    } else {
+      return 'communication'
+    }
   } else if (l.type === 'VOTE_RESULT') {
     return 'check-one'
   } else if (l.type === 'LOTTERY_RESULT') {
@@ -438,6 +454,8 @@ const mapChangeLog = (l) => ({
   newCategory: l.newCategory,
   oldTags: l.oldTags,
   newTags: l.newTags,
+  oldVisibleScope: l.oldVisibleScope,
+  newVisibleScope: l.newVisibleScope,
   amount: l.amount,
   icon: changeLogIcon(l),
 })
@@ -497,15 +515,27 @@ const onCommentDeleted = (id) => {
   fetchTimeline()
 }
 
+const tokenHeader = computed(() => {
+  const token = getToken()
+  return token ? { Authorization: `Bearer ${token}` } : {}
+})
 const {
   data: postData,
   pending: pendingPost,
   error: postError,
   refresh: refreshPost,
-} = await useAsyncData(`post-${postId}`, () => $fetch(`${API_BASE_URL}/api/posts/${postId}`), {
-  server: true,
-  lazy: false,
-})
+} = await useAsyncData(
+  `post-${postId}`,
+  async () => {
+    try {
+      return await $fetch(`${API_BASE_URL}/api/posts/${postId}`, { headers: tokenHeader.value })
+    } catch (err) {}
+  },
+  {
+    server: false,
+    lazy: false,
+  },
+)
 
 // 用 pendingPost 驱动现有 UI（替代 isWaitingFetchingPost 手控）
 const isWaitingFetchingPost = computed(() => pendingPost.value)
@@ -519,6 +549,7 @@ watchEffect(() => {
   title.value = data.title
   category.value = data.category
   tags.value = data.tags || []
+  visibleScope.value = data.visibleScope || 'ALL'
   postReactions.value = data.reactions || []
   subscribed.value = !!data.subscribed
   status.value = data.status
@@ -935,7 +966,7 @@ onMounted(async () => {
 <style>
 .post-page-container {
   background-color: var(--background-color);
-  display: flex;
+  display: block;
   flex-direction: row;
 }
 
@@ -948,9 +979,10 @@ onMounted(async () => {
 }
 
 .post-page-main-container {
+  position: relative;
   scrollbar-width: none;
   padding: 20px;
-  width: calc(85% - 40px);
+  width: calc(100% - 40px);
 }
 
 .info-content-text p code {
@@ -1002,6 +1034,35 @@ onMounted(async () => {
   opacity: 0.5;
 }
 
+.skeleton {
+  background-color: #eee;
+  border-radius: 8px;
+  overflow: hidden;
+  position: relative;
+  height: 20px;
+  margin-top: 5px;
+}
+
+.skeleton::before {
+  content: '';
+  display: block;
+  position: absolute;
+  top: 0;
+  left: 0;
+  bottom: 0;
+  right: 0;
+  background: linear-gradient(90deg, #eee 0%, #f5f5f7 40%, #e0e0e0 100%);
+  transform: translateX(-100%);
+  animation: skeleton-shimmer 1.5s infinite linear;
+  z-index: 1;
+  border-radius: 8px;
+}
+@keyframes skeleton-shimmer {
+  100% {
+    transform: translateX(100%);
+  }
+}
+
 .user-avatar-container {
   display: flex;
   flex-direction: row;
@@ -1106,7 +1167,7 @@ onMounted(async () => {
   white-space: nowrap;
 }
 
-.article-closed-button,
+.article-gray-button,
 .article-subscribe-button-text,
 .article-featured-button,
 .article-unsubscribe-button-text {
@@ -1159,7 +1220,7 @@ onMounted(async () => {
   font-size: 14px;
 }
 
-.article-closed-button {
+.article-gray-button {
   background-color: var(--background-color);
   color: gray;
   border: 1px solid gray;
@@ -1341,6 +1402,76 @@ onMounted(async () => {
   position: relative;
 }
 
+/* ======== 权限锁定状态 ======== */
+.is-blurred {
+  filter: blur(10px);
+  pointer-events: none;
+  user-select: none;
+  transition: filter 0.3s ease;
+}
+
+/* 遮罩层 */
+.restricted-overlay {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 999;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  backdrop-filter: blur(12px);
+  background: rgba(0, 0, 0, 0.45);
+  animation: fadeIn 0.3s ease forwards;
+}
+
+/* 中央提示框 */
+.restricted-content {
+  background: #ffff;
+  color: var(--primary-color);
+  text-align: center;
+}
+
+.restricted-icon {
+  font-size: 60px;
+  opacity: 0.8;
+  margin-bottom: 15px;
+}
+
+.restricted-button {
+  display: inline-block;
+  margin-top: 20px;
+  padding: 10px 18px;
+  background: var(--primary-color);
+  color: white;
+  border-radius: 8px;
+  text-decoration: none;
+  transition: background 0.2s ease;
+}
+
+.restricted-button:hover {
+  background: var(--primary-color-hover);
+}
+
+.restricted-actions {
+  margin-top: 20px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 12px;
+}
+
+/* 淡入动画 */
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
 @media (max-width: 768px) {
   .post-page-main-container {
     width: calc(100% - 20px);

frontend_nuxt/plugins/iconpark.client.ts

@@ -82,6 +82,7 @@ import {
   Share,
   Financing,
   Hands,
+  PreviewCloseOne,
 } from '@icon-park/vue-next'
 
 export default defineNuxtPlugin((nuxtApp) => {
@@ -167,4 +168,5 @@ export default defineNuxtPlugin((nuxtApp) => {
   nuxtApp.vueApp.component('Share', Share)
   nuxtApp.vueApp.component('Financing', Financing)
   nuxtApp.vueApp.component('Hands', Hands)
+  nuxtApp.vueApp.component('PreviewCloseOne', PreviewCloseOne)
 })

frontend_nuxt/utils/markdown.js

@@ -268,23 +268,21 @@ export function stripMarkdownLength(text, length) {
 
 // 朴素文本带贴吧表情
 export function stripMarkdownWithTiebaMoji(text, length){
-  console.error(text)
     if (!text) return ''
 
-  // Markdown 转成纯文本
-  const plain = stripMarkdown(text)
- console.error(plain)
-  // 替换 :tieba123: 为 <img>
-  const withEmoji = plain.replace(/:tieba(\d+):/g, (match, num) => {
-    const key = `tieba${num}`
-    const file = tiebaEmoji[key]
-    return file
-      ? `<img loading="lazy" class="emoji" src="${file}" alt="${key}">`
-      : match // 没有匹配到图片则保留原样
-  })
+    // Markdown 转成纯文本
+    const plain = stripMarkdown(text)
+    // 替换 :tieba123: 为 <img>
+    const withEmoji = plain.replace(/:tieba(\d+):/g, (match, num) => {
+      const key = `tieba${num}`
+      const file = tiebaEmoji[key]
+      return file
+        ? `<img loading="lazy" class="emoji" src="${file}" alt="${key}">`
+        : match // 没有匹配到图片则保留原样
+    })
 
-  // 截断纯文本长度（防止撑太长）
-  const truncated = withEmoji.length > length ? withEmoji.slice(0, length) + '...' : withEmoji
-  return truncated
+    // 截断纯文本长度（防止撑太长）
+    const truncated = withEmoji.length > length ? withEmoji.slice(0, length) + '...' : withEmoji
+    return truncated
 
 }

mcp/README.md

@@ -0,0 +1,41 @@
+# OpenIsle MCP Server
+
+This package provides a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server
+that exposes OpenIsle's search capabilities as MCP tools. The initial release focuses on the
+global search endpoint so the agent ecosystem can retrieve relevant posts, users, tags, and
+other resources.
+
+## Configuration
+
+The server is configured through environment variables (all prefixed with `OPENISLE_MCP_`):
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `BACKEND_BASE_URL` | `http://springboot:8080` | Base URL of the OpenIsle backend. |
+| `PORT` | `8085` | TCP port when running with the `streamable-http` transport. |
+| `HOST` | `0.0.0.0` | Interface to bind when serving HTTP. |
+| `TRANSPORT` | `streamable-http` | Transport to use (`stdio`, `sse`, or `streamable-http`). |
+| `REQUEST_TIMEOUT` | `10.0` | Timeout (seconds) for backend HTTP requests. |
+
+## Running locally
+
+```bash
+pip install .
+OPENISLE_MCP_BACKEND_BASE_URL="http://localhost:8080" openisle-mcp
+```
+
+By default the server listens on port `8085` and serves MCP over Streamable HTTP.
+
+## Available tools
+
+| 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 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/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openisle-mcp"
+version = "0.1.0"
+description = "Model Context Protocol server exposing OpenIsle search capabilities."
+readme = "README.md"
+authors = [{ name = "OpenIsle", email = "engineering@openisle.example" }]
+requires-python = ">=3.11"
+dependencies = [
+  "mcp>=1.19.0",
+  "httpx>=0.28,<0.29",
+  "pydantic>=2.12,<3",
+  "pydantic-settings>=2.11,<3"
+]
+
+[project.scripts]
+openisle-mcp = "openisle_mcp.server:main"
+
+[tool.hatch.build]
+packages = ["src/openisle_mcp"]
+
+[tool.ruff]
+line-length = 100
+

mcp/src/openisle_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""OpenIsle MCP server package."""
+
+from .config import Settings, get_settings
+
+__all__ = ["Settings", "get_settings"]
+

mcp/src/openisle_mcp/config.py

@@ -0,0 +1,66 @@
+"""Application configuration helpers for the OpenIsle MCP server."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Literal
+
+from pydantic import Field, SecretStr
+from pydantic.networks import AnyHttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Configuration for the MCP server."""
+
+    backend_base_url: AnyHttpUrl = Field(
+        "http://springboot:8080",
+        description="Base URL for the OpenIsle backend service.",
+    )
+    host: str = Field(
+        "0.0.0.0",
+        description="Host interface to bind when running with HTTP transports.",
+    )
+    port: int = Field(
+        8085,
+        ge=1,
+        le=65535,
+        description="TCP port for HTTP transports.",
+    )
+    transport: Literal["stdio", "sse", "streamable-http"] = Field(
+        "streamable-http",
+        description="MCP transport to use when running the server.",
+    )
+    request_timeout: float = Field(
+        10.0,
+        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_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+    )
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Return cached application settings."""
+
+    return Settings()

mcp/src/openisle_mcp/schemas.py

@@ -0,0 +1,333 @@
+"""Pydantic models describing tool inputs and outputs."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class SearchResultItem(BaseModel):
+    """A single search result entry."""
+
+    type: str = Field(description="Entity type for the result (post, user, tag, etc.).")
+    id: Optional[int] = Field(default=None, description="Identifier of the matched entity.")
+    text: Optional[str] = Field(default=None, description="Primary text associated with the result.")
+    sub_text: Optional[str] = Field(
+        default=None,
+        alias="subText",
+        description="Secondary text, e.g. a username or excerpt.",
+    )
+    extra: Optional[str] = Field(default=None, description="Additional contextual information.")
+    post_id: Optional[int] = Field(
+        default=None,
+        alias="postId",
+        description="Associated post identifier when relevant.",
+    )
+    highlighted_text: Optional[str] = Field(
+        default=None,
+        alias="highlightedText",
+        description="Highlighted snippet of the primary text if available.",
+    )
+    highlighted_sub_text: Optional[str] = Field(
+        default=None,
+        alias="highlightedSubText",
+        description="Highlighted snippet of the secondary text if available.",
+    )
+    highlighted_extra: Optional[str] = Field(
+        default=None,
+        alias="highlightedExtra",
+        description="Highlighted snippet of extra information if available.",
+    )
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class SearchResponse(BaseModel):
+    """Structured response returned by the search tool."""
+
+    keyword: str = Field(description="The keyword that was searched.")
+    total: int = Field(description="Total number of matches returned by the backend.")
+    results: list[SearchResultItem] = Field(
+        default_factory=list,
+        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

@@ -0,0 +1,268 @@
+"""HTTP client helpers for talking to the OpenIsle backend endpoints."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import httpx
+
+
+logger = logging.getLogger(__name__)
+
+
+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:
+            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=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}")
+        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."""
+
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+            logger.debug("Closed httpx.AsyncClient for SearchClient.")
+
+    @staticmethod
+    def _ensure_dict(entry: Any) -> dict[str, Any]:
+        if not isinstance(entry, dict):
+            raise ValueError(f"Expected JSON object, got: {type(entry)!r}")
+        return entry

mcp/src/openisle_mcp/server.py

@@ -0,0 +1,563 @@
+"""Entry point for running the OpenIsle MCP server."""
+
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from typing import Annotated
+
+import httpx
+from mcp.server.fastmcp import Context, FastMCP
+from pydantic import ValidationError
+from pydantic import Field as PydanticField
+
+from .config import get_settings
+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,
+    access_token=(
+        settings.access_token.get_secret_value()
+        if settings.access_token is not None
+        else None
+    ),
+)
+
+
+@asynccontextmanager
+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 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,
+    lifespan=lifespan,
+)
+
+
+@app.tool(
+    name="search",
+    description="Perform a global search across OpenIsle resources.",
+    structured_output=True,
+)
+async def search(
+    keyword: Annotated[str, PydanticField(description="Keyword to search for.")],
+    ctx: Context | None = None,
+) -> SearchResponse:
+    """Call the OpenIsle global search endpoint and return structured results."""
+
+    sanitized = keyword.strip()
+    if not sanitized:
+        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 = (
+            "OpenIsle backend returned HTTP "
+            f"{exc.response.status_code} while searching for '{sanitized}'."
+        )
+        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 search service: {exc}."
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+
+    try:
+        results = [SearchResultItem.model_validate(entry) for entry in raw_results]
+    except ValidationError as exc:
+        message = "Received malformed data from the OpenIsle backend search endpoint."
+        if ctx is not None:
+            await ctx.error(message)
+        raise ValueError(message) from exc
+
+    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."""
+
+    app.run(transport=settings.transport)
+
+
+if __name__ == "__main__":  # pragma: no cover - manual execution
+    main()
+

nginx/openisle

@@ -100,10 +100,28 @@ server {
         # auth_basic_user_file /etc/nginx/.htpasswd;
     }
 
-
-    # ---------- WEBSOCKET GATEWAY TO :8082 ----------
     location ^~ /websocket/ {
-        proxy_pass         http://127.0.0.1:8084/; 
+        proxy_pass         http://127.0.0.1:8084/;
+        proxy_http_version 1.1;
+
+        proxy_set_header   Upgrade              $http_upgrade;
+        proxy_set_header   Connection           $connection_upgrade;
+
+        proxy_set_header   Host                 $host;
+        proxy_set_header   X-Real-IP            $remote_addr;
+        proxy_set_header   X-Forwarded-For      $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto    $scheme;
+        proxy_set_header   X-Forwarded-Host     $host;
+
+        proxy_read_timeout 300s;
+        proxy_send_timeout 300s;
+        proxy_buffering    off;
+        proxy_cache        off;
+        add_header         Cache-Control "no-store" always;
+    }
+
+    location /mcp {
+        proxy_pass         http://127.0.0.1:8085;
         proxy_http_version 1.1;
 
         proxy_set_header   Upgrade              $http_upgrade;

nginx/openisle-staging

@@ -8,11 +8,8 @@ server {
     listen 443 ssl;
     server_name staging.open-isle.com www.staging.open-isle.com;
 
-
     ssl_certificate     /etc/letsencrypt/live/staging.open-isle.com/fullchain.pem;
     ssl_certificate_key /etc/letsencrypt/live/staging.open-isle.com/privkey.pem;
-    # ssl_certificate     /etc/letsencrypt/live/open-isle.com/fullchain.pem;
-    # ssl_certificate_key /etc/letsencrypt/live/open-isle.com/privkey.pem;
     include /etc/letsencrypt/options-ssl-nginx.conf;
     ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
 
@@ -40,59 +37,13 @@ server {
         add_header X-Upstream $upstream_addr always;
     }
 
-    # 1) 原生 WebSocket
-    location ^~ /api/ws {
-        proxy_pass         http://127.0.0.1:8081;  # 不要尾随 /，保留原样 URI
-        proxy_http_version 1.1;
-
-        # 升级所需
-        proxy_set_header   Upgrade              $http_upgrade;
-        proxy_set_header   Connection           $connection_upgrade;
-
-        # 统一透传这些头（你在 /api/ 有，/api/ws 也要有）
-        proxy_set_header   Host                 $host;
-        proxy_set_header   X-Real-IP            $remote_addr;
-        proxy_set_header   X-Forwarded-For      $proxy_add_x_forwarded_for;
-        proxy_set_header   X-Forwarded-Proto    $scheme;
-        proxy_set_header   X-Forwarded-Host     $host;
-
-        proxy_read_timeout 300s;
-        proxy_send_timeout 300s;
-        proxy_buffering    off;
-        proxy_cache        off;
-    }
-
-    # 2) SockJS（包含 /info、/iframe.html、/.../websocket 等）
-    location ^~ /api/sockjs {
-        proxy_pass         http://127.0.0.1:8081;
-        proxy_http_version 1.1;
-
-        proxy_set_header   Upgrade              $http_upgrade;
-        proxy_set_header   Connection           $connection_upgrade;
-
-        proxy_set_header   Host                 $host;
-        proxy_set_header   X-Real-IP            $remote_addr;
-        proxy_set_header   X-Forwarded-For      $proxy_add_x_forwarded_for;
-        proxy_set_header   X-Forwarded-Proto    $scheme;
-        proxy_set_header   X-Forwarded-Host     $host;
-
-        proxy_read_timeout 300s;
-        proxy_send_timeout 300s;
-        proxy_buffering    off;
-        proxy_cache        off;
-
-        # 如要同源 iframe 回退，下面两行二选一（或者交给 Spring Security 的 sameOrigin）
-        # proxy_hide_header  X-Frame-Options;
-        # add_header         X-Frame-Options "SAMEORIGIN" always;
-    }    
-
     # ---------- API ----------
     location /api/ {
         proxy_pass http://127.0.0.1:8081/api/;
         proxy_http_version 1.1;
 
-    	proxy_set_header Upgrade $http_upgrade;
-    	proxy_set_header Connection $connection_upgrade;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
 
 
         proxy_set_header Host              $host;
@@ -109,7 +60,6 @@ server {
         proxy_cache_bypass 1;
     }
 
-    # ---------- WEBSOCKET GATEWAY TO :8083 ----------
     location ^~ /websocket/ {
         proxy_pass         http://127.0.0.1:8083/;
         proxy_http_version 1.1;
@@ -130,4 +80,24 @@ server {
         add_header         Cache-Control "no-store" always;
     }
 
-}
+    location /mcp {
+        proxy_pass         http://127.0.0.1:8086;
+        proxy_http_version 1.1;
+
+        proxy_set_header   Upgrade              $http_upgrade;
+        proxy_set_header   Connection           $connection_upgrade;
+
+        proxy_set_header   Host                 $host;
+        proxy_set_header   X-Real-IP            $remote_addr;
+        proxy_set_header   X-Forwarded-For      $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto    $scheme;
+        proxy_set_header   X-Forwarded-Host     $host;
+
+        proxy_read_timeout 300s;
+        proxy_send_timeout 300s;
+        proxy_buffering    off;
+        proxy_cache        off;
+        add_header         Cache-Control "no-store" always;
+    }
+
+}