biszx-odoo-mcp 1.2.0__py3-none-any.whl

biszx_odoo_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""
+Odoo MCP Server - MCP Server for Odoo Integration
+"""

biszx_odoo_mcp/__main__.py

@@ -0,0 +1,49 @@
+"""
+Command line entry point for the Odoo MCP Server
+"""
+
+import sys
+
+from loguru import logger
+
+from biszx_odoo_mcp.exceptions import OdooMCPError
+from biszx_odoo_mcp.main import mcp
+
+
+def main() -> int:
+    """
+    Run the MCP server
+    """
+    try:
+        logger.info("🚀 Odoo MCP Server starting")
+
+        # Simplified capability check
+        logger.debug(f"Python version: {sys.version.split()[0]}")
+        logger.debug("MCP server initialized with tools and resources")
+
+        logger.info("▶️ Starting MCP server...")
+
+        mcp.run()
+
+        logger.info("✅ MCP server stopped")
+        return 0
+    except KeyboardInterrupt:
+        logger.info("⏹️ Server stopped by user")
+        return 0
+    except OdooMCPError as e:
+        logger.error(f"Odoo MCP Error: {e}")
+        logger.debug(
+            f"Error details - Type: {e.__class__.__name__}, Code: {e.error_code}"
+        )
+        if e.details:
+            logger.debug(f"Additional details: {e.details}")
+        return 1
+    except Exception as e:
+        logger.error(f"Critical server error: {e}")
+        logger.debug(f"Exception type: {type(e)}")
+        logger.debug("Traceback:", exc_info=True)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

biszx_odoo_mcp/exceptions.py

@@ -0,0 +1,226 @@
+"""
+Custom exception classes for Odoo MCP Server.
+
+This module defines a comprehensive hierarchy of custom exceptions for better
+error handling and debugging in the Odoo MCP Server application.
+
+Exception Hierarchy:
+===================
+
+OdooMCPError (Base)
+├── OdooConnectionError
+│   ├── ConnectionTimeoutError
+│   ├── AuthenticationError
+│   └── SSLVerificationError
+├── ModelError
+│   └── ModelNotFoundError
+├── ServerError
+│   ├── OdooRPCError
+│   └── InternalServerError
+└── MCPError
+    ├── ResourceError
+    └── ToolError
+"""
+
+from typing import Any, Optional
+
+from odoorpc.error import RPCError
+
+
+class OdooMCPError(Exception):
+    """
+    Base exception class for all Odoo MCP Server errors.
+
+    This serves as the base class for all custom exceptions in the application,
+    providing a consistent interface for error handling and logging.
+
+    Attributes:
+        message: Human-readable error message
+        error_code: Machine-readable error code for programmatic handling
+        details: Additional context information about the error
+    """
+
+    def __init__(
+        self,
+        message: str,
+        error_code: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+        original_error: Optional[Exception] = None,
+    ) -> None:
+        """
+        Initialize the exception.
+
+        Args:
+            message: Human-readable error message
+            error_code: Machine-readable error code
+            details: Additional context information
+            original_error: The original exception that caused this error
+        """
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code or self.__class__.__name__.upper()
+        self.details = details or {}
+        self.original_error = original_error
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert the exception to a dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation of the exception
+        """
+        result = {
+            "error_type": self.__class__.__name__,
+            "error_code": self.error_code,
+            "message": self.message,
+            "details": self.details,
+        }
+
+        if self.original_error:
+            result["original_error"] = {
+                "type": self.original_error.__class__.__name__,
+                "message": str(self.original_error),
+            }
+
+        return result
+
+    def __str__(self) -> str:
+        """String representation of the exception."""
+        return f"{self.error_code}: {self.message}"
+
+
+# =============================================================================
+# CONNECTION RELATED ERRORS
+# =============================================================================
+
+
+class OdooConnectionError(OdooMCPError):
+    """Base class for Odoo connection-related errors."""
+
+
+class ConnectionTimeoutError(OdooConnectionError):
+    """Raised when a connection to Odoo times out."""
+
+    def __init__(
+        self,
+        message: str = "Connection to Odoo server timed out",
+        timeout: Optional[float] = None,
+        **kwargs: Any,
+    ) -> None:
+        details = kwargs.get("details", {})
+        if timeout is not None:
+            details["timeout_seconds"] = timeout
+        kwargs["details"] = details
+        super().__init__(message, **kwargs)
+
+
+class AuthenticationError(OdooConnectionError):
+    """Raised when authentication with Odoo fails."""
+
+    def __init__(
+        self,
+        message: str = "Authentication with Odoo failed",
+        username: Optional[str] = None,
+        database: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        details = kwargs.get("details", {})
+        if username:
+            details["username"] = username
+        if database:
+            details["database"] = database
+        kwargs["details"] = details
+        super().__init__(message, **kwargs)
+
+
+# =============================================================================
+# MODEL RELATED ERRORS
+# =============================================================================
+
+
+class ModelError(OdooMCPError):
+    """Base class for model-related errors."""
+
+
+class ModelNotFoundError(ModelError):
+    """Raised when a requested model doesn't exist."""
+
+    def __init__(
+        self, model_name: str, message: Optional[str] = None, **kwargs: Any
+    ) -> None:
+        message = message or f"Model '{model_name}' not found"
+        details = kwargs.get("details", {})
+        details["model_name"] = model_name
+        kwargs["details"] = details
+        super().__init__(message, **kwargs)
+
+
+# =============================================================================
+# SERVER RELATED ERRORS
+# =============================================================================
+
+
+class ServerError(OdooMCPError):
+    """Base class for server-related errors."""
+
+
+class OdooRPCError(ServerError):
+    """Raised when an RPC call to Odoo fails."""
+
+    def __init__(
+        self,
+        error: RPCError,
+        method: str,
+        message: str = "RPC call failed",
+        **kwargs: Any,
+    ) -> None:
+        kwargs["details"] = {
+            "method": method,
+            "odoo_error": error.info,
+        }
+        super().__init__(message, **kwargs)
+
+
+class InternalServerError(ServerError):
+    """Raised when an internal server error occurs."""
+
+
+# =============================================================================
+# MCP RELATED ERRORS
+# =============================================================================
+
+
+class MCPError(OdooMCPError):
+    """Base class for MCP protocol-related errors."""
+
+
+class ResourceError(MCPError):
+    """Raised when an MCP resource operation fails."""
+
+    def __init__(
+        self,
+        message: str = "Resource operation failed",
+        resource_name: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        details = kwargs.get("details", {})
+        if resource_name:
+            details["resource_name"] = resource_name
+        kwargs["details"] = details
+        super().__init__(message, **kwargs)
+
+
+class ToolError(MCPError):
+    """Raised when an MCP tool operation fails."""
+
+    def __init__(
+        self,
+        message: str = "Tool operation failed",
+        tool_name: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        details = kwargs.get("details", {})
+        if tool_name:
+            details["tool_name"] = tool_name
+        kwargs["details"] = details
+        super().__init__(message, **kwargs)

biszx_odoo_mcp/main.py

@@ -0,0 +1,134 @@
+"""
+MCP server for Odoo integration
+
+Provides MCP tools and resources for interacting with Odoo ERP systems
+"""
+
+import inspect
+import os
+import sys
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager
+from typing import Any
+
+from loguru import logger
+from mcp.server.fastmcp import FastMCP
+
+from biszx_odoo_mcp.server import resources, tools
+from biszx_odoo_mcp.server.context import AppContext
+from biszx_odoo_mcp.tools.odoo_client import get_odoo_client
+
+
+def init() -> None:
+    """
+    Initialize the Odoo MCP Server environment
+    """
+    try:
+        from dotenv import load_dotenv  # pylint: disable=import-outside-toplevel
+
+        load_dotenv()
+    except ImportError:
+        pass
+
+    # Configure loguru with appropriate log level
+    logger.remove()
+    log_level = os.environ.get("LOG_LEVEL", "INFO").upper()
+    logger.add(
+        sys.stderr,
+        format=(
+            "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
+            "<level>{level: <8}</level> | "
+            "<level>{message}</level>"
+        ),
+        level=log_level,
+        colorize=True,
+    )
+
+
+@asynccontextmanager
+async def app_lifespan(_: FastMCP) -> AsyncIterator[AppContext]:
+    """Application lifespan for initialization and cleanup"""
+    odoo_client = get_odoo_client()
+    try:
+        yield AppContext(odoo=odoo_client)
+    finally:
+        pass
+
+
+# Create MCP server
+mcp = FastMCP(
+    name="Odoo MCP Server",
+    instructions="MCP Server for interacting with Odoo ERP systems",
+    dependencies=["requests"],
+    lifespan=app_lifespan,
+)
+
+
+# Tool registration helper
+def tool(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Decorator to register a tool that calls the underlying function with mcp"""
+
+    # Get the original function signature
+    sig = inspect.signature(func)
+
+    # Create a new signature excluding the 'mcp' parameter
+    new_params = [p for name, p in sig.parameters.items() if name != "mcp"]
+    new_sig = sig.replace(parameters=new_params)
+
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        return await func(mcp, *args, **kwargs)
+
+    # Set wrapper properties manually to match the new signature
+    wrapper.__name__ = func.__name__
+    wrapper.__doc__ = func.__doc__
+    wrapper.__annotations__ = {
+        k: v for k, v in func.__annotations__.items() if k != "mcp"
+    }
+
+    # Set the corrected signature
+    object.__setattr__(wrapper, "__signature__", new_sig)
+
+    return mcp.tool()(wrapper)
+
+
+# Resource wrapper functions
+async def search_models_resource(query: str):
+    """Search for models by name or description"""
+    return await resources.search_models_resource(mcp, query)
+
+
+async def model_info_resource(model_name: str):
+    """Get information about a specific model"""
+    return await resources.get_model_info_resource(mcp, model_name)
+
+
+async def model_fields_resource(model_name: str, query_field: str) -> str:
+    """Get field definitions for a specific model"""
+    return await resources.get_model_fields_resource(mcp, model_name, query_field)
+
+
+init()
+
+# Register all resources directly
+mcp.resource("odoo://models/search/{query}")(search_models_resource)
+mcp.resource("odoo://models/{model_name}/info")(model_info_resource)
+mcp.resource("odoo://models/{model_name}/fields/{query_field}")(model_fields_resource)
+mcp.resource("odoo://help/domains")(resources.get_domain_help_resource)
+mcp.resource("odoo://help/operations")(resources.get_operations_help_resource)
+
+
+# Register all tools using the helper
+tool(tools.search_models)
+tool(tools.get_model_info)
+tool(tools.get_model_fields)
+tool(tools.search_records)
+tool(tools.search_ids)
+tool(tools.search_count)
+tool(tools.read_records)
+tool(tools.read_group)
+tool(tools.create_records)
+tool(tools.write_records)
+tool(tools.search_and_write)
+tool(tools.unlink_records)
+tool(tools.search_and_unlink)
+tool(tools.call_method)

biszx_odoo_mcp/server/context.py

@@ -0,0 +1,19 @@
+"""
+MCP Server Application Context
+
+This module defines the application context for the MCP server, which includes
+the Odoo client used to interact with the Odoo server.
+"""
+
+from dataclasses import dataclass
+
+from biszx_odoo_mcp.tools.odoo_client import OdooClient
+
+
+@dataclass
+class AppContext:
+    """
+    Application context for the MCP server
+    """
+
+    odoo: OdooClient

biszx_odoo_mcp/server/resources.py

@@ -0,0 +1,230 @@
+"""
+MCP Resources for Odoo integration
+
+This module contains all the MCP resource functions for Odoo data access.
+"""
+
+from typing import Any, cast
+
+from biszx_odoo_mcp.exceptions import OdooMCPError, ResourceError
+from biszx_odoo_mcp.server.context import AppContext
+from biszx_odoo_mcp.server.response import Response
+
+
+async def search_models_resource(mcp: Any, query: str) -> str:
+    """
+    Resource for searching models from the Odoo application.
+
+    This searches through model names and display names to find models that
+    match the given query term.
+
+    Args:
+        query: Search term to find models (searches in model name and display name)
+
+    Returns:
+        JSON string with matching models
+    """
+    # Access lifespan context to get the Odoo client
+    ctx = mcp.get_context()
+    app_context = cast(AppContext, ctx.request_context.lifespan_context)
+
+    try:
+        data = app_context.odoo.search_models(query)
+        return Response(data=data).to_json_string()
+    except OdooMCPError as e:
+        return Response(error=e.to_dict()).to_json_string()
+    except Exception as e:
+        resource_error = ResourceError(
+            f"Unexpected error searching models: {str(e)}",
+            resource_name="search_models_resource",
+            details={"query": query},
+            original_error=e,
+        )
+        return Response(error=resource_error.to_dict()).to_json_string()
+
+
+async def get_model_fields_resource(mcp: Any, model_name: str, query_field: str) -> str:
+    """
+    Resource containing field definitions for a specific model.
+
+    Args:
+        model_name: Name of the model (e.g., 'res.partner')
+        query_field: Search term to find fields (searches in field name and string)
+
+    Returns:
+        JSON string with field definitions
+    """
+    # Access lifespan context to get the Odoo client
+    ctx = mcp.get_context()
+    app_context = cast(AppContext, ctx.request_context.lifespan_context)
+
+    try:
+        data = app_context.odoo.get_model_fields(model_name, query_field)
+        return Response(data=data).to_json_string()
+    except OdooMCPError as e:
+        return Response(error=e.to_dict()).to_json_string()
+    except Exception as e:
+        resource_error = ResourceError(
+            f"Unexpected error getting model fields: {str(e)}",
+            resource_name="get_model_fields_resource",
+            details={"model_name": model_name},
+            original_error=e,
+        )
+        return Response(error=resource_error.to_dict()).to_json_string()
+
+
+async def get_model_info_resource(mcp: Any, model_name: str) -> str:
+    """
+    Resource containing information about a specific model.
+
+    Args:
+        model_name: Name of the model (e.g., 'res.partner')
+
+    Returns:
+        JSON string with model information
+    """
+    # Access lifespan context to get the Odoo client
+    ctx = mcp.get_context()
+    app_context = cast(AppContext, ctx.request_context.lifespan_context)
+
+    try:
+        data = app_context.odoo.get_model_info(model_name)
+        return Response(data=data).to_json_string()
+    except OdooMCPError as e:
+        return Response(error=e.to_dict()).to_json_string()
+    except Exception as e:
+        resource_error = ResourceError(
+            f"Unexpected error getting model info: {str(e)}",
+            resource_name="get_model_info_resource",
+            details={"model_name": model_name},
+            original_error=e,
+        )
+        return Response(error=resource_error.to_dict()).to_json_string()
+
+
+async def get_domain_help_resource() -> str:
+    """
+    Resource containing help information about Odoo domain syntax.
+
+    Returns:
+        JSON string with domain syntax examples and explanations
+    """
+    domain_help = {
+        "odoo_domain_syntax": {
+            "description": "Odoo domains are used for filtering records",
+            "syntax": "List of tuples: [('field', 'operator', 'value')]",
+            "operators": {
+                "=": "equals",
+                "!=": "not equals",
+                "<": "less than",
+                "<=": "less than or equal",
+                ">": "greater than",
+                ">=": "greater than or equal",
+                "in": "in list",
+                "not in": "not in list",
+                "like": "contains (case insensitive)",
+                "ilike": "contains (case insensitive)",
+                "=like": "matches pattern",
+                "=ilike": "matches pattern (case insensitive)",
+            },
+            "logical_operators": {
+                "&": "AND (default between conditions)",
+                "|": "OR",
+                "!": "NOT",
+            },
+            "examples": [
+                {
+                    "description": "Find companies only",
+                    "domain": "[('is_company', '=', True)]",
+                },
+                {
+                    "description": "Find partners with email containing 'gmail'",
+                    "domain": "[('email', 'ilike', 'gmail')]",
+                },
+                {
+                    "description": "Find products with price between 10 and 100",
+                    "domain": "[('list_price', '>=', 10), ('list_price', '<=', 100)]",
+                },
+                {
+                    "description": "Find active products or services",
+                    "domain": (
+                        "['|', ('type', '=', 'product'), "
+                        "('type', '=', 'service'), ('active', '=', True)]"
+                    ),
+                },
+                {
+                    "description": "Find draft or confirmed sales orders",
+                    "domain": "['|', ('state', '=', 'draft'), ('state', '=', 'sent')]",
+                },
+            ],
+        }
+    }
+
+    response = Response(data=domain_help)
+    return response.to_json_string()
+
+
+async def get_operations_help_resource() -> str:
+    """
+    Resource containing help information about available MCP tools and operations.
+
+    Returns:
+        JSON string with operations documentation
+    """
+    operations_help = {
+        "mcp_tools": {
+            "data_retrieval": {
+                "get_odoo_models": "Get list of all available models",
+                "get_model_info": "Get information about a specific model",
+                "get_model_fields": "Get field definitions for a model",
+                "search_records": "Search for records with domain filters",
+                "read_records": "Read specific records by IDs",
+                "search_ids": "Get only IDs of matching records",
+                "search_count": "Count records matching a domain",
+            },
+            "data_modification": {
+                "create_record": "Create a single new record",
+                "create_records": "Create multiple records at once",
+                "write_record": "Update a single record",
+                "write_records": "Update multiple records",
+                "unlink_record": "Delete a single record",
+                "unlink_records": "Delete multiple records",
+            },
+            "advanced": {
+                "call_method": "Call custom methods on models",
+                "search_and_update": "Search and update records in one operation",
+            },
+        },
+        "common_workflows": [
+            {
+                "name": "Create a new customer",
+                "steps": [
+                    "1. Use create_record with model 'res.partner'",
+                    (
+                        "2. Provide values like {'name': 'Customer Name', "
+                        "'email': 'email@domain.com', 'is_company': True}"
+                    ),
+                ],
+            },
+            {
+                "name": "Search for products",
+                "steps": [
+                    "1. Use search_records with model 'product.template'",
+                    (
+                        "2. Use domain like [('name', 'ilike', 'search_term')] "
+                        "to find products by name"
+                    ),
+                ],
+            },
+            {
+                "name": "Update product price",
+                "steps": [
+                    "1. Use search_ids to find the product",
+                    "2. Use write_records to update the list_price field",
+                ],
+            },
+        ],
+    }
+
+    response = Response(data=operations_help)
+    return response.to_json_string()