sufy-mcp-server 1.0.0__py3-none-any.whl

mcp_server/__init__.py

@@ -0,0 +1,11 @@
+import logging
+
+from .consts import consts
+from .server import main
+
+# Configure logging
+logging.basicConfig(level=logging.ERROR)
+logger = logging.getLogger(consts.LOGGER_NAME)
+logger.info("Initializing MCP server package")
+
+__all__ = ["main"]

mcp_server/application.py

@@ -0,0 +1,53 @@
+import logging
+from contextlib import aclosing
+from typing import Iterable
+
+import mcp.types as types
+from mcp.types import EmptyResult, AnyUrl, Tool
+
+from mcp import LoggingLevel
+from mcp.server.lowlevel import Server, helper_types as low_types
+
+from . import core
+from .consts import consts
+from .resource import resource
+from .tools import tools
+
+
+logger = logging.getLogger(consts.LOGGER_NAME)
+
+core.load()
+server = Server("sufy-mcp-server")
+
+
+@server.set_logging_level()
+async def set_logging_level(level: LoggingLevel) -> EmptyResult:
+    logger.setLevel(level.lower())
+    await server.request_context.session.send_log_message(
+        level="warning", data=f"Log level set to {level}", logger=consts.LOGGER_NAME
+    )
+    return EmptyResult()
+
+
+@server.list_resources()
+async def list_resources(**kwargs) -> list[types.Resource]:
+    resource_list = []
+    async with aclosing(resource.list_resources(**kwargs)) as results:
+        async for result in results:
+            resource_list.append(result)
+    return resource_list
+
+
+@server.read_resource()
+async def read_resource(uri: AnyUrl) -> [str | bytes | Iterable[low_types.ReadResourceContents]]:
+    return await resource.read_resource(uri)
+
+
+@server.list_tools()
+async def handle_list_tools() -> list[Tool]:
+    return tools.all_tools()
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict):
+    return await tools.call_tool(name, arguments)

mcp_server/config/config.py

@@ -0,0 +1,52 @@
+import logging
+import os
+from typing import List
+from attr import dataclass
+from dotenv import load_dotenv
+
+from ..consts import consts
+
+_CONFIG_ENV_KEY_ACCESS_KEY = "SUFY_ACCESS_KEY"
+_CONFIG_ENV_KEY_SECRET_KEY = "SUFY_SECRET_KEY"
+_CONFIG_ENV_KEY_ENDPOINT_URL = "SUFY_ENDPOINT_URL"
+_CONFIG_ENV_KEY_REGION_NAME = "SUFY_REGION_NAME"
+_CONFIG_ENV_KEY_BUCKETS = "SUFY_BUCKETS"
+
+logger = logging.getLogger(consts.LOGGER_NAME)
+
+# Load environment variables at package initialization
+load_dotenv(override=True)
+
+
+@dataclass
+class Config:
+    access_key: str
+    secret_key: str
+    endpoint_url: str
+    region_name: str
+    buckets: List[str]
+
+
+def load_config() -> Config:
+    config = Config(
+        access_key=os.getenv(_CONFIG_ENV_KEY_ACCESS_KEY, "SUFY_ACCESS_KEY"),
+        secret_key=os.getenv(_CONFIG_ENV_KEY_SECRET_KEY, "SUFY_SECRET_KEY"),
+        endpoint_url=os.getenv(_CONFIG_ENV_KEY_ENDPOINT_URL, "SUFY_ENDPOINT_URL"),
+        region_name=os.getenv(_CONFIG_ENV_KEY_REGION_NAME, "SUFY_REGION_NAME"),
+        buckets=_get_configured_buckets_from_env(),
+    )
+
+    logger.info(f"Configured   access_key: {config.access_key}")
+    logger.info(f"Configured endpoint_url: {config.endpoint_url}")
+    logger.info(f"Configured  region_name: {config.region_name}")
+    logger.info(f"Configured      buckets: {config.buckets}")
+    return config
+
+
+def _get_configured_buckets_from_env() -> List[str]:
+    bucket_list = os.getenv(_CONFIG_ENV_KEY_BUCKETS)
+    if bucket_list:
+        buckets = [b.strip() for b in bucket_list.split(",")]
+        return buckets
+    else:
+        return []

mcp_server/consts/consts.py

@@ -0,0 +1 @@
+LOGGER_NAME = "sufy-mcp"

mcp_server/core/__init__.py

@@ -0,0 +1,17 @@
+from ..config import config
+from .storage import load as load_storage
+from .media_processing import load as load_media_processing
+from .version import load as load_version
+
+
+def load():
+    # 加载配置
+    cfg = config.load_config()
+
+    # 版本
+    load_version(cfg)
+    # 存储业务
+    load_storage(cfg)
+    # 智能多媒体
+    load_media_processing(cfg)
+

mcp_server/core/media_processing/__init__.py

@@ -0,0 +1,11 @@
+from .tools import register_tools
+from ...config import config
+
+
+def load(cfg: config.Config):
+    register_tools(cfg)
+
+
+__all__ = [
+    "load",
+]

mcp_server/core/media_processing/tools.py

@@ -0,0 +1,179 @@
+import logging
+from mcp import types
+
+from . import utils
+from ...consts import consts
+from ...tools import tools
+from ...config import config
+
+logger = logging.getLogger(consts.LOGGER_NAME)
+
+_OBJECT_URL_DESC = "The URL of the image. This can be a URL obtained via the GetObjectURL tool or a URL generated by other Fop tools. Length Constraints: Minimum length of 1."
+
+_COMMON_DESC = """
+The information includes the object_url of the scaled image, which users can directly use for HTTP GET requests to retrieve the image content or open in a browser to view the file.
+The image must be stored in a Sufy Bucket.
+Supported original image formats: psd, jpeg, png, gif, webp, tiff, bmp, avif, heic. Image width and height cannot exceed 30,000 pixels, and total pixels cannot exceed 150 million.
+"""
+
+
+class _ToolImpl:
+    def __init__(self, cfg: config):
+        self.config = cfg
+
+    @tools.tool_meta(
+        types.Tool(
+            name="ImageScaleByPercent",
+            description="""Image scaling tool that resizes images based on a percentage and returns information about the scaled image.
+            """ + _COMMON_DESC,
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "object_url": {
+                        "type": "string",
+                        "description": _OBJECT_URL_DESC
+                    },
+                    "percent": {
+                        "type": "integer",
+                        "description": "Scaling percentage, range [1,999]. For example: 90 means the image width and height are reduced to 90% of the original; 200 means the width and height are enlarged to 200% of the original.",
+                        "minimum": 1,
+                        "maximum": 999
+                    },
+                },
+                "required": ["object_url", "percent"],
+            },
+        )
+    )
+    async def image_scale_by_percent(
+            self, **kwargs
+    ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
+        object_url = kwargs.get("object_url", "")
+        percent = kwargs.get("percent", "")
+        func = f"imgmogr/thumbnail/!{percent}p"
+        object_url = await utils.url_add_processing_func(self.config, object_url, func)
+        return [
+            types.TextContent(
+                type="text",
+                text=str(
+                    {
+                        "object_url": object_url,
+                    }
+                ),
+            )
+        ]
+
+    @tools.tool_meta(
+        types.Tool(
+            name="ImageScaleBySize",
+            description="""Image scaling tool that resizes images based on a specified width or height and returns information about the scaled image.
+            """ + _COMMON_DESC,
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "object_url": {
+                        "type": "string",
+                        "description": _OBJECT_URL_DESC
+                    },
+                    "width": {
+                        "type": "integer",
+                        "description": "Specifies the width for image scaling. The image will be scaled to the specified width, and the height will be adjusted proportionally.",
+                        "minimum": 1
+                    },
+                    "height": {
+                        "type": "integer",
+                        "description": "Specifies the height for image scaling. The image will be scaled to the specified height, and the width will be adjusted proportionally.",
+                        "minimum": 1
+                    },
+                },
+                "required": ["object_url"],
+                "anyOf": [
+                    {"required": ["width"]},
+                    {"required": ["height"]}
+                ]
+            },
+        )
+    )
+    async def image_scale_by_size(
+            self, **kwargs
+    ) -> list[types.TextContent]:
+        object_url = kwargs.get("object_url", "")
+        width = kwargs.get("width", "")
+        height = kwargs.get("height", "")
+
+        func = f"{width}x{height}"
+        if len(func) == 1:
+            return [
+                types.TextContent(
+                    type="text", text="At least one width or height must be set"
+                )
+            ]
+
+        fop = f"imgmogr/thumbnail/{func}"
+        object_url = await utils.url_add_processing_func(self.config, object_url, fop)
+        return [
+            types.TextContent(
+                type="text",
+                text=str(
+                    {
+                        "object_url": object_url,
+                    }
+                ),
+            )
+        ]
+
+    @tools.tool_meta(
+        types.Tool(
+            name="ImageBlur",
+            description="""Applies Gaussian blur to images. Important notes:
+            1. Does NOT affect original GIF format images
+            2. Takes effect after WebP-to-GIF conversion
+            """ + _COMMON_DESC,
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "object_url": {
+                        "type": "string",
+                        "description": _OBJECT_URL_DESC,
+                        "format": "uri"
+                    },
+                    "radius": {
+                        "type": "integer",
+                        "description": "Gaussian blur radius determining intensity (1-200)",
+                        "minimum": 1,
+                        "maximum": 200
+                    },
+                    "sigma": {
+                        "type": "integer",
+                        "description": "Standard deviation of normal distribution controlling smoothness (>0) ",
+                        "minimum": 1
+                    },
+                },
+                "required": ["object_url", "radius", "sigma"],
+            }
+        )
+    )
+    async def image_blur(self, **kwargs) -> list[types.TextContent]:
+        object_url = kwargs.get("object_url", "")
+        radius = kwargs.get("radius", "")
+        sigma = kwargs.get("sigma", "")
+        func = f"imgmogr/blur/{radius}x{sigma}"
+        object_url = await utils.url_add_processing_func(self.config, object_url, func)
+        return [
+            types.TextContent(
+                type="text",
+                text=str({
+                    "object_url": object_url,
+                })
+            )
+        ]
+
+
+def register_tools(cfg: config.Config):
+    tool_impl = _ToolImpl(cfg)
+    tools.auto_register_tools(
+        [
+            tool_impl.image_scale_by_percent,
+            tool_impl.image_scale_by_size,
+            tool_impl.image_blur,
+        ]
+    )

mcp_server/core/media_processing/utils.py

@@ -0,0 +1,157 @@
+from urllib import parse
+from botocore import auth as s3_auth
+from botocore import awsrequest
+from botocore import credentials as s3_credentials
+
+from ...config import config
+
+_FUNC_PREFIXES = [
+    "imgmogr/"
+]
+
+async def url_add_processing_func(cfg: config.Config, url: str, func: str) -> str:
+    func_items = func.split("/")
+    func_prefix = func_items[0]
+
+    url_info = parse.urlparse(url)
+    new_query, expire = _remove_query_sign_info(url_info.query)
+    new_query = _query_add_processing_func(new_query, func, func_prefix)
+    new_query = parse.quote(new_query, safe='&=')
+    url_info = url_info._replace(query=new_query)
+    new_url = parse.urlunparse(url_info)
+    new_url = await _presigned_url(cfg, str(new_url), expire)
+    return str(new_url)
+
+
+def _query_add_processing_func(query: str, func: str, func_prefix: str) -> str:
+    queries = query.split("&")
+    if '' in queries:
+        queries.remove('')
+
+    # query 中不包含任何数据
+    if len(queries) == 0:
+        return func
+
+    # funcs 会放在第一个元素中
+    first_query = parse.unquote(queries[0])
+
+    # funcs 不存在
+    if len(first_query) == 0:
+        queries.insert(0, func)
+        return "&".join(queries)
+
+    # first_query 不是 funcs
+    if not _is_func(first_query):
+        queries.insert(0, func)
+        return "&".join(queries)
+
+    # 移除后面的 =
+    first_query = first_query.removesuffix("=")
+    queries.remove(queries[0])
+
+    # 未找到当前类别的 func
+    if first_query.find(func_prefix) < 0:
+        func = first_query + "|" + func
+        queries.insert(0, func)
+        return "&".join(queries)
+
+    query_funcs = first_query.split("|")
+    if '' in query_funcs:
+        query_funcs.remove('')
+
+    # 只有一个 func，且和当前 func 相同，拼接其后
+    if len(query_funcs) == 1:
+        func = first_query + func.removeprefix(func_prefix)
+        queries.insert(0, func)
+        return "&".join(queries)
+
+    # 多个 func，查看最后一个是否和当前 func 匹配
+    last_func = query_funcs[-1]
+
+    # 最后一个不匹配，只用管道符拼接
+    if last_func.find(func_prefix) < 0:
+        func = first_query + "|" + func
+        queries.insert(0, func)
+        return "&".join(queries)
+
+    # 最后一个匹配，则直接拼接在后面
+    func = first_query + func.removeprefix(func_prefix)
+    queries.insert(0, func)
+    return "&".join(queries)
+
+
+async def _presigned_url(cfg: config.Config, original_url: str, expires: int = 3600) -> str:
+    try:
+        # 创建凭证对象
+        creds = s3_credentials.Credentials(
+            access_key=cfg.access_key,
+            secret_key=cfg.secret_key,
+        )
+
+        # 创建 AWS 请求对象
+        request = awsrequest.AWSRequest(
+            method="GET",
+            url=original_url,
+            headers={}
+        )
+
+        # 创建签名器（禁用路径转义）
+        signer = s3_auth.S3SigV4QueryAuth(
+            credentials=creds,
+            region_name=cfg.region_name,
+            expires=expires,
+            service_name="s3",
+        )
+        signer.URI_ESCAPE_PATH = False  # 对应 DisableURIPathEscaping=True
+
+        # 进行签名（直接修改请求对象）
+        signer.add_auth(request)
+
+        # 构造最终 URL
+        signed_url = request.url
+        return signed_url
+
+    except Exception as e:
+        raise Exception(f"Presign url:{original_url} error: {e}")
+
+
+_S3_SIGN_URL_QUERY_KEYS_EXPIRES = "x-amz-expires"
+_S3_SIGN_URL_QUERY_KEYS = [
+    _S3_SIGN_URL_QUERY_KEYS_EXPIRES,
+    "x-amz-algorithm",
+    "x-amz-credential",
+    "x-amz-date",
+    "x-amz-signedheaders",
+    "x-amz-signature",
+]
+
+def _remove_query_sign_info(query: str) -> (str, int):
+    queries = query.split("&")
+    if '' in queries:
+        queries.remove('')
+
+    expire = 3600
+    new_queries = []
+    for item in queries:
+        # 移除签名信息
+        found_sign_info = ""
+        for sign_info in _S3_SIGN_URL_QUERY_KEYS:
+            if item.lower().find(sign_info) >= 0:
+                found_sign_info = sign_info
+                break
+
+        if len(found_sign_info) == 0:
+            # 不是签名信息
+            new_queries.append(item)
+        elif found_sign_info == _S3_SIGN_URL_QUERY_KEYS_EXPIRES:
+            expires = item.split("=")
+            if len(expires) == 2:
+                expire = int(expires[1])
+
+    return "&".join(new_queries), expire
+
+def _is_func(func: str) -> bool:
+    for prefix in _FUNC_PREFIXES:
+        if func.startswith(prefix):
+            return True
+    return False

mcp_server/core/storage/__init__.py

@@ -0,0 +1,13 @@
+from .storage import StorageService
+from .tools import register_tools
+from .resource import register_resource_provider
+from ...config import config
+
+
+def load(cfg: config.Config):
+    storage_service = StorageService(cfg)
+    register_tools(storage_service)
+    register_resource_provider(storage_service)
+
+
+__all__ = ["load", "StorageService"]

mcp_server/core/storage/resource.py

@@ -0,0 +1,158 @@
+import asyncio
+import logging
+import base64
+from typing import Iterable
+
+from mcp import types
+from mcp.server.lowlevel import helper_types as low_types
+from urllib.parse import unquote
+
+from .storage import StorageService
+from ...consts import consts
+from ...resource import resource
+
+logger = logging.getLogger(consts.LOGGER_NAME)
+
+
+class _ResourceProvider(resource.ResourceProvider):
+    def __init__(self, storage: StorageService):
+        super().__init__("s3")
+        self.storage = storage
+
+    async def list_resources(
+            self, prefix: str = "", max_keys: int = 20, **kwargs
+    ) -> list[types.Resource]:
+        """
+        List S3 buckets and their contents as resources with pagination
+        Args:
+            prefix: Prefix listing after this bucket name
+            max_keys: Returns the maximum number of keys (up to 100), default 20
+        """
+        resources = []
+        logger.debug("Starting to list resources")
+        logger.debug(f"Configured buckets: {self.storage.config.buckets}")
+
+        try:
+            # Get limited number of buckets
+            buckets = await self.storage.list_buckets(prefix)
+            if not buckets or len(buckets) == 0:
+                logger.warning("No buckets found")
+                return []
+
+            # limit concurrent operations
+            async def process_bucket(bucket):
+                bucket_name = bucket["Name"]
+                logger.debug(f"Processing bucket: {bucket_name}")
+
+                try:
+                    # List objects in the bucket with a reasonable limit
+                    objects = await self.storage.list_objects(
+                        bucket_name, max_keys=max_keys
+                    )
+
+                    for obj in objects:
+                        if "Key" in obj and not obj["Key"].endswith("/"):
+                            object_key = obj["Key"]
+                            if self.storage.is_markdown_file(object_key):
+                                mime_type = "text/markdown"
+                            elif self.storage.is_image_file(object_key):
+                                mime_type = "image/png"
+                            else:
+                                mime_type = "text/plain"
+
+                            resource_entry = types.Resource(
+                                uri=f"s3://{bucket_name}/{object_key}",
+                                name=object_key,
+                                mimeType=mime_type,
+                                description=str(obj),
+                            )
+                            resources.append(resource_entry)
+                            logger.debug(f"Added resource: {resource_entry.uri}")
+
+                except Exception as e:
+                    logger.error(
+                        f"Error listing objects in bucket {bucket_name}: {str(e)}"
+                    )
+
+            # Use semaphore to limit concurrent bucket processing
+            semaphore = asyncio.Semaphore(3)  # Limit concurrent bucket processing
+
+            async def process_bucket_with_semaphore(bucket):
+                async with semaphore:
+                    await process_bucket(bucket)
+
+            # Process buckets concurrently
+            await asyncio.gather(
+                *[process_bucket_with_semaphore(bucket) for bucket in buckets]
+            )
+
+        except Exception as e:
+            logger.error(f"Error listing buckets: {str(e)}")
+            raise
+
+        logger.info(f"Returning {len(resources)} resources")
+        return resources
+
+    async def read_resource(self, uri: types.AnyUrl, **kwargs) -> [
+        str | bytes | Iterable[low_types.ReadResourceContents]]:
+        """
+        Read content from an S3 resource and return structured response
+
+        Returns:
+            Dict containing 'contents' list with uri, mimeType, and text for each resource
+        """
+        uri_str = str(uri)
+        logger.debug(f"Reading resource: {uri_str}")
+
+        if not uri_str.startswith("s3://"):
+            raise ValueError("Invalid S3 URI")
+
+        # Parse the S3 URI
+        path = uri_str[5:]  # Remove "s3://"
+        path = unquote(path)  # Decode URL-encoded characters
+        parts = path.split("/", 1)
+
+        if len(parts) < 2:
+            raise ValueError("Invalid S3 URI format")
+
+        bucket = parts[0]
+        key = parts[1]
+
+        response = await self.storage.get_object(bucket, key)
+        file_content = response["Body"]
+        content_type = response.get("ContentType", "application/octet-stream")
+        if content_type.startswith("image/"):
+            base64_data = base64.b64encode(file_content).decode("utf-8")
+            return [
+                low_types.ReadResourceContents(
+                    mime_type=content_type,
+                    content=base64_data,
+                )
+            ]
+
+
+        if not isinstance(file_content, bytes):
+            file_content = str(file_content)
+            return [
+                low_types.ReadResourceContents(
+                    mime_type=content_type,
+                    content=file_content,
+                )
+            ]
+
+        if content_type.startswith("text/"):
+            file_content = file_content.decode("utf-8")
+        else:
+            file_content = base64.b64encode(file_content).decode("utf-8")
+
+        return [
+            low_types.ReadResourceContents(
+                mime_type=content_type,
+                content=file_content,
+            )
+        ]
+
+
+def register_resource_provider(storage: StorageService):
+    resource_provider = _ResourceProvider(storage)
+    resource.register_resource_provider(resource_provider)