luma-mcp 1.2.1 → 1.2.2

package/minimax_coding_plan_mcp-0.0.2/minimax_mcp/server.py

@@ -0,0 +1,169 @@
+"""
+MiniMax Coding Plan MCP Server
+
+⚠️ IMPORTANT: This server connects to Minimax API endpoints which may involve costs.
+Any tool that makes an API call is clearly marked with a cost warning. Please follow these guidelines:
+
+1. Only use these tools when users specifically ask for them
+2. For audio generation tools, be mindful that text length affects the cost
+3. Voice cloning features are charged upon first use after cloning
+
+Note: Tools without cost warnings are free to use as they only read existing data.
+"""
+
+import os
+import json
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+from mcp.types import TextContent
+from minimax_mcp.utils import (
+    process_image_url,
+)
+
+from minimax_mcp.const import *
+from minimax_mcp.exceptions import MinimaxAPIError, MinimaxRequestError
+from minimax_mcp.client import MinimaxAPIClient
+
+load_dotenv()
+api_key = os.getenv(ENV_MINIMAX_API_KEY)
+api_host = os.getenv(ENV_MINIMAX_API_HOST)
+fastmcp_log_level = os.getenv(ENV_FASTMCP_LOG_LEVEL) or "WARNING"
+
+if not api_key:
+    raise ValueError("MINIMAX_API_KEY environment variable is required")
+if not api_host:
+    raise ValueError("MINIMAX_API_HOST environment variable is required")
+
+mcp = FastMCP("Minimax",log_level=fastmcp_log_level)
+api_client = MinimaxAPIClient(api_key, api_host)
+
+@mcp.tool(
+    description="""
+    
+    Web Search API, works like Google Search.
+    
+    Args:
+        query (str): The search query string. Use 3-5 keywords. Add the current date for time-sensitive queries, e.g. `latest iPhone 2025`
+        
+    Search Strategy:
+        - If no valid results found, try changing search keywords
+        
+    Returns:
+        Text content with search results in JSON format. The response structure is:
+        {
+            "organic": [
+                {
+                    "title": "string - The title of the search result",
+                    "link": "string - The URL link to the result",
+                    "snippet": "string - A brief description or excerpt",
+                    "date": "string - The date of the result"
+                }
+            ],
+            "related_searches": [
+                {
+                    "query": "string - A related search query suggestion"
+                }
+            ],
+            "base_resp": {
+                "status_code": "int - Response status code",
+                "status_msg": "string - Response status message"
+            }
+        }
+    """
+)
+def web_search(
+    query: str,
+) -> TextContent:
+    try:
+        if not query:
+            raise MinimaxRequestError("Query is required")
+        
+        # Build request payload
+        payload = {
+            "q": query
+        }
+        
+        # Call search API
+        response_data = api_client.post("/v1/coding_plan/search", json=payload)
+        
+        # Return JSON dump of response data
+        return TextContent(
+            type="text",
+            text=json.dumps(response_data, ensure_ascii=False, indent=2)
+        )
+        
+    except MinimaxAPIError as e:
+        return TextContent(
+            type="text",
+            text=f"Failed to perform search: {str(e)}"
+        )
+
+
+@mcp.tool(
+    description="""
+    
+    A powerful LLM that can analyze and understand image content from files or URLs, follow your instruction.
+    Use this tool to understand images by LLM.
+    Only support jpeg, png, webp formats. Other formats like pdf/gif/psd/svg and so on are not supported.
+        
+    Args:
+        prompt (str): The text prompt describing what you want to analyze or extract from the image.
+        image_source (str): The source location of the image to analyze.
+            Accepts:
+            - HTTP/HTTPS URL: "https://example.com/image.jpg"
+            - Local file path: "/path/to/image.png"
+            Supported formats: JPEG, PNG, WebP
+        
+    Returns:
+        Text content with the image analysis result.
+    """
+)
+def understand_image(
+    prompt: str,
+    image_source: str,
+) -> TextContent:
+    try:
+        if not prompt:
+            raise MinimaxRequestError("Prompt is required")
+        if not image_source:
+            raise MinimaxRequestError("Image source is required")
+        
+        # Process image_source: convert HTTP URL or local file to base64, or pass through existing base64
+        processed_image_url = process_image_url(image_source)
+        
+        # Build request payload
+        payload = {
+            "prompt": prompt,
+            "image_url": processed_image_url
+        }
+        
+        # Call VLM API
+        response_data = api_client.post("/v1/coding_plan/vlm", json=payload)
+        
+        # Extract content from response
+        content = response_data.get("content", "")
+        
+        if not content:
+            raise MinimaxRequestError("No content returned from VLM API")
+        
+        # Return the content
+        return TextContent(
+            type="text",
+            text=content
+        )
+        
+    except MinimaxAPIError as e:
+        return TextContent(
+            type="text",
+            text=f"Failed to perform VLM analysis: {str(e)}"
+        )
+
+
+def main():
+    print("Starting Minimax MCP server")
+    """Run the Minimax MCP server"""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

package/minimax_coding_plan_mcp-0.0.2/minimax_mcp/utils.py

@@ -0,0 +1,101 @@
+import os
+import base64
+import requests
+from minimax_mcp.const import *
+from minimax_mcp.exceptions import MinimaxMcpError, MinimaxRequestError
+
+
+def strip_at_prefix(path: str) -> str:
+    """
+    Remove @ prefix from Claude Code file references.
+    
+    Claude Code uses @ as a syntax sugar for workspace files.
+    For example: @test-minimax-image/image.png -> test-minimax-image/image.png
+    
+    Args:
+        path (str): The file path that may have @ prefix
+        
+    Returns:
+        str: Path without @ prefix
+    """
+    if path.startswith('@'):
+        return path[1:]
+    return path
+
+
+def process_image_url(image_url: str) -> str:
+    """
+    Process image URL and convert to base64 data URL format.
+    
+    This function handles three types of image inputs:
+    1. HTTP/HTTPS URLs: Downloads the image and converts to base64
+    2. Base64 data URLs: Passes through as-is
+    3. Local file paths: Reads the file and converts to base64
+    
+    Args:
+        image_url (str): The image URL, data URL, or local file path
+        
+    Returns:
+        str: Base64 data URL in format "data:image/{format};base64,{data}"
+        
+    Raises:
+        MinimaxRequestError: If image cannot be downloaded, read, or processed
+    """
+    # Remove @ prefix if present (Claude Code syntax)
+    image_url = strip_at_prefix(image_url)
+    
+    # If already in base64 data URL format, pass through
+    if image_url.startswith("data:"):
+        return image_url
+    
+    # Handle HTTP/HTTPS URLs
+    if image_url.startswith(("http://", "https://")):
+        try:
+            image_response = requests.get(image_url)
+            image_response.raise_for_status()
+            image_data = image_response.content
+            
+            # Detect image format from content-type header
+            content_type = image_response.headers.get('content-type', '').lower()
+            if 'jpeg' in content_type or 'jpg' in content_type:
+                image_format = 'jpeg'
+            elif 'png' in content_type:
+                image_format = 'png'
+            elif 'webp' in content_type:
+                image_format = 'webp'
+            else:
+                # Default to jpeg if cannot detect
+                image_format = 'jpeg'
+            
+            # Convert to base64 data URL
+            base64_data = base64.b64encode(image_data).decode('utf-8')
+            return f"data:image/{image_format};base64,{base64_data}"
+            
+        except requests.RequestException as e:
+            raise MinimaxRequestError(f"Failed to download image from URL: {str(e)}")
+    
+    # Handle local file paths
+    else:
+        if not os.path.exists(image_url):
+            raise MinimaxRequestError(f"Local image file does not exist: {image_url}")
+        
+        try:
+            with open(image_url, "rb") as f:
+                image_data = f.read()
+                
+                # Detect image format from file extension
+                image_format = 'jpeg'  # Default
+                if image_url.lower().endswith('.png'):
+                    image_format = 'png'
+                elif image_url.lower().endswith('.webp'):
+                    image_format = 'webp'
+                elif image_url.lower().endswith(('.jpg', '.jpeg')):
+                    image_format = 'jpeg'
+                
+                base64_data = base64.b64encode(image_data).decode('utf-8')
+                return f"data:image/{image_format};base64,{base64_data}"
+                
+        except IOError as e:
+            raise MinimaxRequestError(f"Failed to read local image file: {str(e)}")
+
+

package/minimax_coding_plan_mcp-0.0.2/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "minimax-coding-plan-mcp"
+version = "0.0.2"
+description = "Specialized MiniMax Model Context Protocol (MCP) server designed for coding-plan users"
+authors = [
+    { name = "Roy Wu", email = "zhengyu@minimax.chat" },
+]
+readme = "README.md"
+license = { file = "LICENSE" }
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+]
+keywords = [
+    "minimax",
+    "mcp",
+    "web_search",
+    "understand-image",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "mcp[cli]>=1.6.0",
+    "fastapi>=0.109.2",
+    "uvicorn>=0.27.1",
+    "python-dotenv>=1.0.1",
+    "pydantic>=2.6.1",
+    "httpx>=0.28.1",
+    "fuzzywuzzy>=0.18.0",
+    "python-Levenshtein>=0.25.0",
+    "sounddevice>=0.5.1",
+    "soundfile>=0.13.1",
+    "requests>=2.31.0",
+]
+
+[project.scripts]
+minimax-coding-plan-mcp = "minimax_mcp.server:main"
+
+[project.optional-dependencies]
+dev = [
+    "pre-commit>=3.6.2",
+    "ruff>=0.3.0",
+    "fastmcp>=0.4.1",
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "twine>=6.1.0",
+    "build>=1.0.3",
+]
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --cov=minimax_mcp --cov-report=term-missing"

package/minimax_coding_plan_mcp-0.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

package/minimax_coding_plan_mcp-0.0.2/setup.py

@@ -0,0 +1,6 @@
+from setuptools import setup, find_packages
+
+setup(
+    packages=find_packages(),
+    include_package_data=True,
+)

package/minimax_coding_plan_mcp-0.0.2/test_at_prefix.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""
+Test script to verify @ prefix handling
+"""
+
+import sys
+import os
+
+# Add parent directory to path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from minimax_mcp.utils import strip_at_prefix, process_image_url
+from minimax_mcp.exceptions import MinimaxRequestError
+
+
+def test_strip_at_prefix():
+    """Test @ prefix removal"""
+    print("Testing strip_at_prefix()...")
+    
+    # Test cases
+    test_cases = [
+        ("@test-minimax-image/image.png", "test-minimax-image/image.png"),
+        ("@folder/subfolder/image.jpg", "folder/subfolder/image.jpg"),
+        ("./normal/path.png", "./normal/path.png"),
+        ("D:\\images\\test.png", "D:\\images\\test.png"),
+        ("https://example.com/image.jpg", "https://example.com/image.jpg"),
+        ("data:image/png;base64,abc123", "data:image/png;base64,abc123"),
+    ]
+    
+    all_passed = True
+    for input_path, expected in test_cases:
+        result = strip_at_prefix(input_path)
+        passed = result == expected
+        status = "✅ PASS" if passed else "❌ FAIL"
+        print(f"{status}: '{input_path}' -> '{result}' (expected: '{expected}')")
+        if not passed:
+            all_passed = False
+    
+    return all_passed
+
+
+def test_process_image_url_with_at_prefix():
+    """Test process_image_url with @ prefix"""
+    print("\nTesting process_image_url() with @ prefix...")
+    
+    # Create a test image file
+    test_image_path = "test_image_for_at_prefix.png"
+    
+    # Create a simple 1x1 PNG
+    import base64
+    tiny_png_base64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
+    with open(test_image_path, "wb") as f:
+        f.write(base64.b64decode(tiny_png_base64))
+    
+    try:
+        # Test with @ prefix
+        result = process_image_url(f"@{test_image_path}")
+        print(f"✅ PASS: Successfully processed '@{test_image_path}'")
+        print(f"   Result starts with: {result[:50]}...")
+        
+        # Test without @ prefix
+        result2 = process_image_url(test_image_path)
+        print(f"✅ PASS: Successfully processed '{test_image_path}' (without @)")
+        
+        # Results should be identical
+        if result == result2:
+            print(f"✅ PASS: Results are identical (@ prefix correctly removed)")
+            return True
+        else:
+            print(f"❌ FAIL: Results differ")
+            return False
+            
+    except Exception as e:
+        print(f"❌ FAIL: {str(e)}")
+        return False
+    finally:
+        # Cleanup
+        if os.path.exists(test_image_path):
+            os.remove(test_image_path)
+
+
+def test_nonexistent_file_with_at_prefix():
+    """Test error message with @ prefix on nonexistent file"""
+    print("\nTesting error message with @ prefix on nonexistent file...")
+    
+    try:
+        process_image_url("@nonexistent/file.png")
+        print("❌ FAIL: Should have raised MinimaxRequestError")
+        return False
+    except MinimaxRequestError as e:
+        error_msg = str(e)
+        # Error message should NOT contain @ prefix
+        if "@" not in error_msg and "nonexistent/file.png" in error_msg:
+            print(f"✅ PASS: Error message correctly shows path without @")
+            print(f"   Error: {error_msg}")
+            return True
+        else:
+            print(f"❌ FAIL: Error message still contains @ or incorrect path")
+            print(f"   Error: {error_msg}")
+            return False
+    except Exception as e:
+        print(f"❌ FAIL: Wrong exception type: {type(e).__name__}: {str(e)}")
+        return False
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("Testing @ Prefix Handling in minimax_mcp")
+    print("=" * 60)
+    
+    results = []
+    
+    results.append(("strip_at_prefix", test_strip_at_prefix()))
+    results.append(("process_image_url with @", test_process_image_url_with_at_prefix()))
+    results.append(("error message with @", test_nonexistent_file_with_at_prefix()))
+    
+    print("\n" + "=" * 60)
+    print("Test Summary")
+    print("=" * 60)
+    
+    all_passed = True
+    for name, passed in results:
+        status = "✅ PASS" if passed else "❌ FAIL"
+        print(f"{status}: {name}")
+        if not passed:
+            all_passed = False
+    
+    print("=" * 60)
+    if all_passed:
+        print("✅ All tests passed!")
+        sys.exit(0)
+    else:
+        print("❌ Some tests failed")
+        sys.exit(1)

package/minimax_coding_plan_mcp-0.0.2/test_real_image.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""
+Real API test with actual image and API key
+"""
+
+import sys
+import os
+from dotenv import load_dotenv
+
+# Load test environment
+load_dotenv('.env.test')
+
+# Add parent directory to path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from minimax_mcp.utils import process_image_url
+from minimax_mcp.client import MinimaxAPIClient
+from minimax_mcp.exceptions import MinimaxRequestError
+
+
+def test_real_image_with_at_prefix(image_path: str, prompt: str = "请详细描述这张图片的内容，包括画面中的主要元素、文字信息、场景等所有细节"):
+    """
+    Test with real image using actual MiniMax API
+    
+    Args:
+        image_path: Path to the image (can have @ prefix)
+        prompt: Analysis prompt
+    """
+    print("=" * 60)
+    print("Real Image Test with MiniMax API")
+    print("=" * 60)
+    
+    # Get API credentials
+    api_key = os.getenv('MINIMAX_API_KEY')
+    api_host = os.getenv('MINIMAX_API_HOST')
+    
+    if not api_key or api_key == 'your-api-key-here':
+        print("❌ Error: Please set MINIMAX_API_KEY in .env.test file")
+        print("   Edit .env.test and add your actual API key")
+        return False
+    
+    if not api_host:
+        print("❌ Error: MINIMAX_API_HOST not set")
+        return False
+    
+    print(f"API Host: {api_host}")
+    print(f"API Key: {api_key[:10]}...{api_key[-4:]}")
+    print()
+    
+    # Test 1: With @ prefix
+    print("Test 1: With @ prefix")
+    print("-" * 60)
+    print(f"Original path: @{image_path}")
+    
+    try:
+        # Process image
+        print("Processing image...")
+        processed_image_url = process_image_url(f"@{image_path}")
+        print(f"✅ Image processed successfully")
+        print(f"   Data URI length: {len(processed_image_url)} chars")
+        print(f"   First 50 chars: {processed_image_url[:50]}...")
+        
+        # Call API
+        print("\nCalling MiniMax API...")
+        client = MinimaxAPIClient(api_key, api_host)
+        
+        payload = {
+            "prompt": prompt,
+            "image_url": processed_image_url
+        }
+        
+        response = client.post("/v1/coding_plan/vlm", json=payload)
+        
+        content = response.get("content", "")
+        if content:
+            print(f"✅ API call successful!")
+            print("\n" + "=" * 60)
+            print("Response:")
+            print("=" * 60)
+            print(content)
+            print("=" * 60)
+            return True
+        else:
+            print("❌ No content in response")
+            print(f"Response: {response}")
+            return False
+            
+    except Exception as e:
+        print(f"❌ Test failed: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+def test_without_at_prefix(image_path: str, prompt: str = "请详细描述这张图片的内容"):
+    """
+    Test without @ prefix for comparison
+    """
+    print("\n\nTest 2: Without @ prefix (for comparison)")
+    print("-" * 60)
+    print(f"Original path: {image_path}")
+    
+    try:
+        processed_image_url = process_image_url(image_path)
+        print(f"✅ Image processed successfully")
+        print(f"   Data URI length: {len(processed_image_url)} chars")
+        return True
+    except Exception as e:
+        print(f"❌ Test failed: {str(e)}")
+        return False
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python test_real_image.py <image_path> [prompt]")
+        print("\nExample:")
+        print("  python test_real_image.py test-image.png")
+        print("  python test_real_image.py test-image.png \"描述这张图片\"")
+        print("\nNote: Image path should NOT include @ prefix in command line")
+        print("      The script will automatically test both with and without @")
+        sys.exit(1)
+    
+    image_path = sys.argv[1]
+    prompt = sys.argv[2] if len(sys.argv) > 2 else "请详细描述这张图片的内容，包括画面中的主要元素、文字信息、场景等所有细节"
+    
+    # Verify image exists
+    if not os.path.exists(image_path):
+        print(f"❌ Error: Image file not found: {image_path}")
+        sys.exit(1)
+    
+    print(f"Testing with image: {image_path}")
+    print(f"Prompt: {prompt}")
+    print()
+    
+    # Test with @ prefix (calls real API)
+    result1 = test_real_image_with_at_prefix(image_path, prompt)
+    
+    # Test without @ prefix (just image processing)
+    result2 = test_without_at_prefix(image_path, prompt)
+    
+    print("\n" + "=" * 60)
+    print("Test Summary")
+    print("=" * 60)
+    print(f"{'✅' if result1 else '❌'} Test 1: With @ prefix (real API call)")
+    print(f"{'✅' if result2 else '❌'} Test 2: Without @ prefix (image processing)")
+    print("=" * 60)
+    
+    if result1 and result2:
+        print("✅ All tests passed!")
+        sys.exit(0)
+    else:
+        print("❌ Some tests failed")
+        sys.exit(1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luma-mcp",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Multi-model vision understanding MCP server. Supports GLM-4.5V (Zhipu), DeepSeek-OCR (SiliconFlow - Free), and Qwen3-VL-Flash (Aliyun)",
   "type": "module",
   "bin": {