feat: add MCP search server

.env.example

@@ -2,7 +2,6 @@
 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,13 +1,11 @@
 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.*;
@@ -42,7 +40,6 @@ 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;
@@ -187,37 +184,6 @@ 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,26 +224,6 @@ 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

@@ -1,15 +0,0 @@
-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,7 +3,6 @@ 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;
@@ -11,10 +10,6 @@ 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,10 +19,6 @@ 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,27 +266,6 @@ 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,18 +770,6 @@ 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);
   }

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 mcp
+  frontend_service
 
 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 mcp
+  mysql redis rabbitmq websocket-service springboot frontend_service
 
 echo "👉 Current status:"
 docker compose -f "$compose_file" --env-file "$env_file" ps

deploy/deploy_staging.sh

@@ -39,12 +39,12 @@ echo "👉 Build images (staging)..."
 docker compose -f "$compose_file" --env-file "$env_file" \
   build --pull \
   --build-arg NUXT_ENV=staging \
-  frontend_service mcp
+  frontend_service
 
 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 mcp
+  mysql redis rabbitmq websocket-service springboot frontend_service
 
 echo "👉 Current status:"
 docker compose -f "$compose_file" --env-file "$env_file" ps

docker/docker-compose.yaml

@@ -178,32 +178,6 @@ 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
@@ -239,6 +213,30 @@ services:
       - dev_local_backend
       - prod
 
+  mcp-server:
+    build:
+      context: ..
+      dockerfile: docker/mcp-service.Dockerfile
+    container_name: ${COMPOSE_PROJECT_NAME}-openisle-mcp
+    env_file:
+      - ${ENV_FILE:-../.env}
+    environment:
+      OPENISLE_API_BASE_URL: ${OPENISLE_API_BASE_URL:-http://springboot:8080}
+      OPENISLE_MCP_HOST: ${OPENISLE_MCP_HOST:-0.0.0.0}
+      OPENISLE_MCP_PORT: ${OPENISLE_MCP_PORT:-8000}
+      OPENISLE_MCP_TRANSPORT: ${OPENISLE_MCP_TRANSPORT:-streamable-http}
+    ports:
+      - "${OPENISLE_MCP_PORT:-8000}:8000"
+    depends_on:
+      springboot:
+        condition: service_healthy
+    networks:
+      - openisle-network
+    profiles:
+      - dev
+      - dev_local_backend
+      - prod
+
   frontend_dev:
     image: node:20
     container_name: ${COMPOSE_PROJECT_NAME}-openisle-frontend-dev

docker/mcp-service.Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.11-slim AS base
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+COPY mcp/pyproject.toml mcp/README.md ./
+COPY mcp/src ./src
+RUN pip install --upgrade pip \
+    && pip install .
+
+EXPOSE 8000
+
+ENV OPENISLE_API_BASE_URL=http://springboot:8080 \
+    OPENISLE_MCP_HOST=0.0.0.0 \
+    OPENISLE_MCP_PORT=8000 \
+    OPENISLE_MCP_TRANSPORT=streamable-http
+
+CMD ["openisle-mcp"]

docker/mcp.Dockerfile

@@ -1,21 +0,0 @@
-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"]
-

mcp/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.build/
+.venv/
+.env

mcp/README.md

@@ -1,41 +1,45 @@
 # 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.
+This package exposes a [Model Context Protocol](https://github.com/modelcontextprotocol) (MCP) server for OpenIsle.
+The initial release focuses on surfacing the platform's search capabilities so that AI assistants can discover
+users and posts directly through the existing REST API. Future iterations can expand this service with post
+creation and other productivity tools.
 
-## Configuration
+## Features
 
-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. |
+- 🔍 Keyword search across users and posts using the OpenIsle backend APIs
+- ✅ Structured MCP tool response for downstream reasoning
+- 🩺 Lightweight health check endpoint (`/health`) for container orchestration
+- ⚙️ Configurable via environment variables with sensible defaults for Docker Compose
 
 ## Running locally
 
 ```bash
+cd mcp
 pip install .
-OPENISLE_MCP_BACKEND_BASE_URL="http://localhost:8080" openisle-mcp
+openisle-mcp  # starts the MCP server on http://127.0.0.1:8000 by default
 ```
 
-By default the server listens on port `8085` and serves MCP over Streamable HTTP.
+By default the server targets `http://localhost:8080` for backend requests. Override the target by setting
+`OPENISLE_API_BASE_URL` before starting the service.
 
-## Available tools
+## Environment variables
 
-| 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. |
+| Variable | Default | Description |
+| -------- | ------- | ----------- |
+| `OPENISLE_API_BASE_URL` | `http://localhost:8080` | Base URL of the OpenIsle backend API |
+| `OPENISLE_MCP_HOST` | `127.0.0.1` | Hostname/interface for the MCP HTTP server |
+| `OPENISLE_MCP_PORT` | `8000` | Port for the MCP HTTP server |
+| `OPENISLE_MCP_TRANSPORT` | `streamable-http` | Transport mode (`stdio`, `sse`, or `streamable-http`) |
+| `OPENISLE_MCP_TIMEOUT_SECONDS` | `10` | HTTP timeout when calling 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.
+## Docker
 
+The repository's Docker Compose stack now includes the MCP server. To start it alongside other services:
+
+```bash
+cd docker
+docker compose --profile dev up mcp-server
+```
+
+The service exposes port `8000` by default. Update `OPENISLE_MCP_PORT` to customize the mapped port.

mcp/pyproject.toml

@@ -1,27 +1,28 @@
 [build-system]
-requires = ["hatchling>=1.25"]
-build-backend = "hatchling.build"
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
 
 [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"
+authors = [{ name = "OpenIsle" }]
 dependencies = [
   "mcp>=1.19.0",
-  "httpx>=0.28,<0.29",
-  "pydantic>=2.12,<3",
-  "pydantic-settings>=2.11,<3"
+  "httpx>=0.28.1",
+  "pydantic>=2.7.0"
 ]
 
+[project.urls]
+Homepage = "https://github.com/openisle/openisle"
+
 [project.scripts]
 openisle-mcp = "openisle_mcp.server:main"
 
-[tool.hatch.build]
-packages = ["src/openisle_mcp"]
-
-[tool.ruff]
-line-length = 100
+[tool.setuptools.packages.find]
+where = ["src"]
 
+[tool.setuptools.package-data]
+openisle_mcp = ["py.typed"]

mcp/src/openisle_mcp/__init__.py

@@ -1,6 +1,14 @@
 """OpenIsle MCP server package."""
 
 from .config import Settings, get_settings
+from .models import SearchItem, SearchResponse, SearchScope
 
-__all__ = ["Settings", "get_settings"]
+__all__ = [
+    "Settings",
+    "get_settings",
+    "SearchItem",
+    "SearchResponse",
+    "SearchScope",
+]
 
+__version__ = "0.1.0"

mcp/src/openisle_mcp/client.py

@@ -0,0 +1,33 @@
+"""HTTP client helpers for interacting with the OpenIsle backend APIs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .config import Settings, get_settings
+from .models import SearchScope
+
+
+class OpenIsleAPI:
+    """Thin wrapper around the OpenIsle REST API used by the MCP server."""
+
+    def __init__(self, settings: Settings | None = None) -> None:
+        self._settings = settings or get_settings()
+
+    async def search(self, scope: SearchScope, keyword: str) -> list[Any]:
+        """Execute a search request against the backend API."""
+
+        url_path = self._settings.get_search_path(scope)
+        async with httpx.AsyncClient(
+            base_url=str(self._settings.backend_base_url),
+            timeout=self._settings.request_timeout_seconds,
+        ) as client:
+            response = await client.get(url_path, params={"keyword": keyword})
+            response.raise_for_status()
+            data = response.json()
+
+        if not isinstance(data, list):
+            raise RuntimeError("Unexpected search response payload: expected a list")
+        return data

mcp/src/openisle_mcp/config.py

@@ -1,52 +1,83 @@
-"""Application configuration helpers for the OpenIsle MCP server."""
+"""Configuration helpers for the OpenIsle MCP server."""
 
 from __future__ import annotations
 
+import os
 from functools import lru_cache
-from typing import Literal
+from typing import Dict, Literal
 
-from pydantic import Field
-from pydantic.networks import AnyHttpUrl
-from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import AnyHttpUrl, BaseModel, Field, ValidationError
+
+from .models import SearchScope
+
+TransportType = Literal["stdio", "sse", "streamable-http"]
 
 
-class Settings(BaseSettings):
-    """Configuration for the MCP server."""
+class Settings(BaseModel):
+    """Runtime configuration for the MCP server."""
 
     backend_base_url: AnyHttpUrl = Field(
-        "http://springboot:8080",
-        description="Base URL for the OpenIsle backend service.",
+        default="http://localhost:8080",
+        description="Base URL of the OpenIsle backend API.",
     )
-    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,
+    request_timeout_seconds: float = Field(
+        default=10.0,
         gt=0,
-        description="Timeout (seconds) for backend search requests.",
+        description="HTTP timeout when talking to the backend APIs.",
+    )
+    transport: TransportType = Field(
+        default="streamable-http",
+        description="Transport mode for the MCP server.",
+    )
+    host: str = Field(default="127.0.0.1", description="Hostname/interface used by the MCP HTTP server.")
+    port: int = Field(default=8000, ge=0, description="Port used by the MCP HTTP server.")
+    search_paths: Dict[str, str] = Field(
+        default_factory=lambda: {
+            SearchScope.GLOBAL.value: "/api/search/global",
+            SearchScope.USERS.value: "/api/search/users",
+            SearchScope.POSTS.value: "/api/search/posts",
+            SearchScope.POSTS_TITLE.value: "/api/search/posts/title",
+            SearchScope.POSTS_CONTENT.value: "/api/search/posts/content",
+        },
+        description="Mapping between search scopes and backend API paths.",
     )
 
-    model_config = SettingsConfigDict(
-        env_prefix="OPENISLE_MCP_",
-        env_file=".env",
-        env_file_encoding="utf-8",
-        case_sensitive=False,
-    )
+    def get_search_path(self, scope: SearchScope) -> str:
+        """Return the backend path associated with a given search scope."""
+
+        try:
+            return self.search_paths[scope.value]
+        except KeyError as exc:  # pragma: no cover - defensive guard
+            raise ValueError(f"Unsupported search scope: {scope}") from exc
 
 
 @lru_cache(maxsize=1)
 def get_settings() -> Settings:
-    """Return cached application settings."""
+    """Load settings from environment variables with caching."""
 
-    return Settings()
+    raw_settings: Dict[str, object] = {}
+
+    backend_url = os.getenv("OPENISLE_API_BASE_URL")
+    if backend_url:
+        raw_settings["backend_base_url"] = backend_url
+
+    timeout = os.getenv("OPENISLE_MCP_TIMEOUT_SECONDS")
+    if timeout:
+        raw_settings["request_timeout_seconds"] = float(timeout)
+
+    transport = os.getenv("OPENISLE_MCP_TRANSPORT")
+    if transport:
+        raw_settings["transport"] = transport
+
+    host = os.getenv("OPENISLE_MCP_HOST")
+    if host:
+        raw_settings["host"] = host
+
+    port = os.getenv("OPENISLE_MCP_PORT")
+    if port:
+        raw_settings["port"] = int(port)
+
+    try:
+        return Settings(**raw_settings)
+    except (ValidationError, ValueError) as exc:  # pragma: no cover - configuration errors should surface clearly
+        raise RuntimeError(f"Invalid MCP configuration: {exc}") from exc

mcp/src/openisle_mcp/models.py

@@ -0,0 +1,45 @@
+"""Data models for the OpenIsle MCP server."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+
+class SearchScope(str, Enum):
+    """Supported search scopes exposed via the MCP tool."""
+
+    GLOBAL = "global"
+    USERS = "users"
+    POSTS = "posts"
+    POSTS_TITLE = "posts_title"
+    POSTS_CONTENT = "posts_content"
+
+
+class Highlight(BaseModel):
+    """Highlighted fragments returned by the backend search API."""
+
+    text: Optional[str] = Field(default=None, description="Highlighted main text snippet.")
+    sub_text: Optional[str] = Field(default=None, description="Highlighted secondary text snippet.")
+    extra: Optional[str] = Field(default=None, description="Additional highlighted data.")
+
+
+class SearchItem(BaseModel):
+    """Normalized representation of a single search result."""
+
+    category: str = Field(description="Type/category of the search result, e.g. user or post.")
+    title: Optional[str] = Field(default=None, description="Primary title or label for the result.")
+    description: Optional[str] = Field(default=None, description="Supporting description or summary text.")
+    url: Optional[str] = Field(default=None, description="Canonical URL that references the resource, if available.")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional structured metadata extracted from the API.")
+    highlights: Optional[Highlight] = Field(default=None, description="Highlighted snippets returned by the backend search API.")
+
+
+class SearchResponse(BaseModel):
+    """Structured response returned by the MCP search tool."""
+
+    scope: SearchScope = Field(description="Scope of the search that produced the results.")
+    keyword: str = Field(description="Keyword submitted to the backend search endpoint.")
+    results: list[SearchItem] = Field(default_factory=list, description="Normalized search results from the backend API.")

mcp/src/openisle_mcp/schemas.py

@@ -1,279 +0,0 @@
-"""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")

mcp/src/openisle_mcp/search.py

@@ -0,0 +1,100 @@
+"""Utilities for normalising OpenIsle search results."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Iterable
+
+from .models import Highlight, SearchItem, SearchScope
+
+
+def _truncate(text: str | None, *, limit: int = 240) -> str | None:
+    """Compress whitespace and truncate overly long text fragments."""
+
+    if not text:
+        return None
+    compact = re.sub(r"\s+", " ", text).strip()
+    if len(compact) <= limit:
+        return compact
+    return f"{compact[:limit - 1]}…"
+
+
+def _extract_highlight(data: dict[str, Any]) -> Highlight | None:
+    highlighted = {
+        "text": data.get("highlightedText"),
+        "sub_text": data.get("highlightedSubText"),
+        "extra": data.get("highlightedExtra"),
+    }
+    if any(highlighted.values()):
+        return Highlight(**highlighted)
+    return None
+
+
+def normalise_results(scope: SearchScope, payload: Iterable[dict[str, Any]]) -> list[SearchItem]:
+    """Convert backend payloads into :class:`SearchItem` entries."""
+
+    normalised: list[SearchItem] = []
+
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+
+        if scope is SearchScope.GLOBAL:
+            normalised.append(
+                SearchItem(
+                    category=item.get("type", scope.value),
+                    title=_truncate(item.get("text")),
+                    description=_truncate(item.get("subText")),
+                    metadata={
+                        "id": item.get("id"),
+                        "postId": item.get("postId"),
+                        "extra": item.get("extra"),
+                    },
+                    highlights=_extract_highlight(item),
+                )
+            )
+            continue
+
+        if scope in {SearchScope.POSTS, SearchScope.POSTS_CONTENT, SearchScope.POSTS_TITLE}:
+            author = item.get("author") or {}
+            category = item.get("category") or {}
+            metadata = {
+                "id": item.get("id"),
+                "author": author.get("username"),
+                "category": category.get("name"),
+                "views": item.get("views"),
+                "commentCount": item.get("commentCount"),
+                "tags": [tag.get("name") for tag in item.get("tags", []) if isinstance(tag, dict)],
+            }
+            normalised.append(
+                SearchItem(
+                    category="post",
+                    title=_truncate(item.get("title")),
+                    description=_truncate(item.get("content")),
+                    metadata={k: v for k, v in metadata.items() if v is not None},
+                )
+            )
+            continue
+
+        if scope is SearchScope.USERS:
+            metadata = {
+                "id": item.get("id"),
+                "email": item.get("email"),
+                "followers": item.get("followers"),
+                "following": item.get("following"),
+                "role": item.get("role"),
+            }
+            normalised.append(
+                SearchItem(
+                    category="user",
+                    title=_truncate(item.get("username")),
+                    description=_truncate(item.get("introduction")),
+                    metadata={k: v for k, v in metadata.items() if v is not None},
+                )
+            )
+            continue
+
+        # Fallback: include raw entry to aid debugging of unsupported scopes
+        normalised.append(SearchItem(category=scope.value, metadata=item))
+
+    return normalised

mcp/src/openisle_mcp/search_client.py

@@ -1,139 +0,0 @@
-"""HTTP client helpers for talking to the OpenIsle backend endpoints."""
-
-from __future__ import annotations
-
-import json
-from typing import Any
-
-import httpx
-
-
-class SearchClient:
-    """Client for calling the OpenIsle HTTP APIs used by the MCP server."""
-
-    def __init__(self, base_url: str, *, timeout: float = 10.0) -> None:
-        self._base_url = base_url.rstrip("/")
-        self._timeout = timeout
-        self._client: httpx.AsyncClient | None = None
-
-    def _get_client(self) -> httpx.AsyncClient:
-        if self._client is None:
-            self._client = httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout)
-        return self._client
-
-    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()
-        response = await client.get(
-            "/api/search/global",
-            params={"keyword": keyword},
-            headers={"Accept": "application/json"},
-        )
-        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._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()
-        headers = {
-            "Accept": "application/json",
-            "Content-Type": "application/json",
-            "Authorization": f"Bearer {token}",
-        }
-        payload: dict[str, Any] = {"content": content}
-        if captcha is not None:
-            stripped_captcha = captcha.strip()
-            if stripped_captcha:
-                payload["captcha"] = stripped_captcha
-
-        response = await client.post(
-            f"/api/comments/{comment_id}/replies",
-            json=payload,
-            headers=headers,
-        )
-        response.raise_for_status()
-        return self._ensure_dict(response.json())
-
-    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()
-        headers = {
-            "Accept": "application/json",
-            "Content-Type": "application/json",
-            "Authorization": f"Bearer {token}",
-        }
-        payload: dict[str, Any] = {"content": content}
-        if captcha is not None:
-            stripped_captcha = captcha.strip()
-            if stripped_captcha:
-                payload["captcha"] = stripped_captcha
-
-        response = await client.post(
-            f"/api/posts/{post_id}/comments",
-            json=payload,
-            headers=headers,
-        )
-        response.raise_for_status()
-        return self._ensure_dict(response.json())
-
-    async def recent_posts(self, minutes: int) -> list[dict[str, Any]]:
-        """Return posts created within the given timeframe."""
-
-        client = self._get_client()
-        response = await client.get(
-            "/api/posts/recent",
-            params={"minutes": minutes},
-            headers={"Accept": "application/json"},
-        )
-        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}"
-            )
-        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 = {"Accept": "application/json"}
-        if token:
-            headers["Authorization"] = f"Bearer {token}"
-
-        response = await client.get(f"/api/posts/{post_id}", headers=headers)
-        response.raise_for_status()
-        return self._ensure_dict(response.json())
-
-    async def aclose(self) -> None:
-        """Dispose of the underlying HTTP client."""
-
-        if self._client is not None:
-            await self._client.aclose()
-            self._client = None
-
-    @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

@@ -1,400 +1,121 @@
-"""Entry point for running the OpenIsle MCP server."""
+"""Entry point for the OpenIsle MCP server."""
 
 from __future__ import annotations
 
-from contextlib import asynccontextmanager
+import logging
+import os
 from typing import Annotated
 
-import httpx
 from mcp.server.fastmcp import Context, FastMCP
-from pydantic import ValidationError
-from pydantic import Field as PydanticField
+from mcp.server.fastmcp.logging import configure_logging
+from pydantic import Field
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
 
-from .config import get_settings
-from .schemas import (
-    CommentCreateResult,
-    CommentData,
-    CommentReplyResult,
-    PostDetail,
-    PostSummary,
-    RecentPostsResponse,
-    SearchResponse,
-    SearchResultItem,
-)
-from .search_client import SearchClient
+from .client import OpenIsleAPI
+from .config import Settings, get_settings
+from .models import SearchResponse, SearchScope
+from .search import normalise_results
 
-settings = get_settings()
-search_client = SearchClient(
-    str(settings.backend_base_url), timeout=settings.request_timeout
-)
+_logger = logging.getLogger(__name__)
 
 
-@asynccontextmanager
-async def lifespan(_: FastMCP):
-    """Lifecycle hook that disposes shared resources when the server stops."""
+def _create_server(settings: Settings) -> FastMCP:
+    """Instantiate the FastMCP server with configured metadata."""
 
-    try:
-        yield
-    finally:
-        await search_client.aclose()
+    server = FastMCP(
+        name="OpenIsle MCP",
+        instructions=(
+            "Access OpenIsle search functionality. Provide a keyword and optionally a scope to "
+            "discover users and posts from the community."
+        ),
+        host=settings.host,
+        port=settings.port,
+        transport_security=None,
+    )
+
+    @server.custom_route("/health", methods=["GET"])
+    async def health(_: Request) -> Response:  # pragma: no cover - exercised via runtime checks
+        return JSONResponse({"status": "ok"})
+
+    return server
 
 
-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, and list posts created "
-        "within a recent time window."
-    ),
-    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,
+async def _execute_search(
+    *,
+    api: OpenIsleAPI,
+    scope: SearchScope,
+    keyword: str,
+    context: Context | None,
 ) -> SearchResponse:
-    """Call the OpenIsle global search endpoint and return structured results."""
+    message = f"Searching OpenIsle scope={scope.value} keyword={keyword!r}"
+    if context is not None:
+        context.info(message)
+    else:
+        _logger.info(message)
 
-    sanitized = keyword.strip()
-    if not sanitized:
-        raise ValueError("Keyword must not be empty.")
-
-    try:
-        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.")
-
-    return SearchResponse(keyword=sanitized, total=len(results), results=results)
+    payload = await api.search(scope, keyword)
+    items = normalise_results(scope, payload)
+    return SearchResponse(scope=scope, keyword=keyword, results=items)
 
 
-@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."),
-    ],
-    token: Annotated[
-        str,
-        PydanticField(description="JWT bearer token for the user performing the reply."),
-    ],
-    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,
-    ctx: Context | None = None,
-) -> CommentCreateResult:
-    """Create a comment on a post and return the backend payload."""
+def build_server(settings: Settings | None = None) -> FastMCP:
+    """Configure and return the FastMCP server instance."""
 
-    sanitized_content = content.strip()
-    if not sanitized_content:
-        raise ValueError("Reply content must not be empty.")
+    resolved_settings = settings or get_settings()
+    server = _create_server(resolved_settings)
+    api_client = OpenIsleAPI(resolved_settings)
 
-    sanitized_token = token.strip()
-    if not sanitized_token:
-        raise ValueError("Authentication token must not be empty.")
+    @server.tool(
+        name="openisle_search",
+        description="Search OpenIsle for users and posts.",
+    )
+    async def openisle_search(
+        keyword: Annotated[str, Field(description="Keyword used to query OpenIsle search.")],
+        scope: Annotated[
+            SearchScope,
+            Field(
+                description=(
+                    "Scope of the search. Use 'global' to search across users and posts, or specify "
+                    "'users', 'posts', 'posts_title', or 'posts_content' to narrow the results."
+                )
+            ),
+        ] = SearchScope.GLOBAL,
+        context: Context | None = None,
+    ) -> SearchResponse:
+        try:
+            return await _execute_search(api=api_client, scope=scope, keyword=keyword, context=context)
+        except Exception as exc:  # pragma: no cover - surfaced to the MCP runtime
+            error_message = f"Search failed: {exc}"
+            if context is not None:
+                context.error(error_message)
+            _logger.exception("Search tool failed")
+            raise
 
-    sanitized_captcha = captcha.strip() if isinstance(captcha, str) else None
-
-    try:
-        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}."
-        )
-
-    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."),
-    ],
-    token: Annotated[str, PydanticField(description="JWT bearer token for the user performing the reply.")],
-    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,
-    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 not sanitized_token:
-        raise ValueError("Authentication token must not be empty.")
-
-    sanitized_captcha = captcha.strip() if isinstance(captcha, str) else None
-
-    try:
-        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}."
-        )
-
-    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:
-        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."
-        )
-
-    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:
-        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.")
-
-    return post
+    return server
 
 
 def main() -> None:
-    """Run the MCP server using the configured transport."""
+    """CLI entry point used by the console script."""
 
-    app.run(transport=settings.transport)
+    settings = get_settings()
+    configure_logging("INFO")
+    server = build_server(settings)
+
+    transport = os.getenv("OPENISLE_MCP_TRANSPORT", settings.transport)
+    if transport not in {"stdio", "sse", "streamable-http"}:
+        raise RuntimeError(f"Unsupported transport mode: {transport}")
+
+    _logger.info("Starting OpenIsle MCP server on %s:%s via %s", settings.host, settings.port, transport)
+
+    if transport == "stdio":
+        server.run("stdio")
+    elif transport == "sse":
+        mount_path = os.getenv("OPENISLE_MCP_SSE_PATH")
+        server.run("sse", mount_path=mount_path)
+    else:
+        server.run("streamable-http")
 
 
-if __name__ == "__main__":  # pragma: no cover - manual execution
+if __name__ == "__main__":  # pragma: no cover - manual execution path
     main()
-

nginx/openisle

@@ -100,28 +100,10 @@ server {
         # auth_basic_user_file /etc/nginx/.htpasswd;
     }
 
+
+    # ---------- WEBSOCKET GATEWAY TO :8082 ----------
     location ^~ /websocket/ {
-        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_pass         http://127.0.0.1:8084/; 
         proxy_http_version 1.1;
 
         proxy_set_header   Upgrade              $http_upgrade;

nginx/openisle-staging

@@ -8,8 +8,11 @@ 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;
 
@@ -37,13 +40,59 @@ 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;
@@ -60,6 +109,7 @@ server {
         proxy_cache_bypass 1;
     }
 
+    # ---------- WEBSOCKET GATEWAY TO :8083 ----------
     location ^~ /websocket/ {
         proxy_pass         http://127.0.0.1:8083/;
         proxy_http_version 1.1;
@@ -80,24 +130,4 @@ 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;
-    }
-
-}
+}