biszx-odoo-mcp 1.1.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,135 @@
+"""
+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.read_records)
+tool(tools.create_record)
+tool(tools.create_records)
+tool(tools.write_record)
+tool(tools.write_records)
+tool(tools.unlink_record)
+tool(tools.unlink_records)
+tool(tools.search_count)
+tool(tools.search_ids)
+tool(tools.call_method)
+tool(tools.search_and_update)

biszx_odoo_mcp-1.1.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: biszx-odoo-mcp
+Version: 1.1.0
+Summary: MCP Server for Odoo Integration
+Author-email: Biszx <isares.br@gmail.com>
+License: MIT
+Project-URL: Homepage, https://gitlab.com/biszx/biszx-odoo-mcp
+Project-URL: Issues, https://gitlab.com/biszx/biszx-odoo-mcp/issues
+Keywords: odoo,mcp,server
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncio>=3.4.3
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: mcp[cli]>=1.9.4
+Requires-Dist: odoorpc>=0.10.1
+Dynamic: license-file
+
+# Odoo MCP Server
+
+An MCP server implementation for Odoo ERP systems, providing a set of tools for managing Odoo records, models, and custom methods.
+Inspired by [tuanle96/mcp-odoo](https://github.com/tuanle96/mcp-odoo).
+
+## Tools
+
+### Core CRUD Operations
+
+- **create_record**: Create a single new record
+
+  - Inputs: `model_name` (string), `values` (object)
+  - Returns: Dictionary with created record ID
+
+- **create_records**: Create multiple records at once
+
+  - Inputs: `model_name` (string), `values_list` (array of objects)
+  - Returns: Dictionary with created record IDs
+
+- **read_records**: Read specific records by their IDs
+
+  - Inputs: `model_name` (string), `ids` (array), `fields` (optional array)
+  - Returns: Dictionary with record data
+
+- **write_record**: Update a single record
+
+  - Inputs: `model_name` (string), `record_id` (number), `values` (object)
+  - Returns: Dictionary with operation result
+
+- **write_records**: Update multiple records
+
+  - Inputs: `model_name` (string), `record_ids` (array), `values` (object)
+  - Returns: Dictionary with operation result
+
+- **unlink_record**: Delete a single record
+
+  - Inputs: `model_name` (string), `record_id` (number)
+  - Returns: Dictionary with operation result
+
+- **unlink_records**: Delete multiple records
+  - Inputs: `model_name` (string), `record_ids` (array)
+  - Returns: Dictionary with operation result
+
+### Search and Query Operations
+
+- **search_records**: Search for records with advanced filtering
+
+  - Inputs: `model_name` (string), `domain` (array), `fields` (optional array), `limit` (optional number), `offset` (optional number), `order` (optional string)
+  - Returns: Dictionary with matching records
+
+- **search_ids**: Get only IDs of matching records
+
+  - Inputs: `model_name` (string), `domain` (array), `offset` (optional number), `limit` (optional number), `order` (optional string)
+  - Returns: Dictionary with list of IDs
+
+- **search_count**: Count records matching a domain
+  - Inputs: `model_name` (string), `domain` (array)
+  - Returns: Dictionary with count
+
+### Model Operations
+
+- **search_models**: Search for available models in the Odoo system
+
+  - Inputs: `query` (string) - Search term for model names and display names
+  - Returns: Dictionary with matching models
+
+- **get_model_info**: Get information about a specific model
+
+  - Inputs: `model_name` (string)
+  - Returns: Dictionary with model information
+
+- **get_model_fields**: Get field definitions for a model
+  - Inputs: `model_name` (string), `query_field` (string)
+  - Returns: Dictionary with field definitions
+
+### Utility Operations
+
+- **search_and_update**: Search and update records in one operation
+
+  - Inputs: `model_name` (string), `domain` (array), `values` (object)
+  - Returns: Dictionary with affected record count and IDs
+
+- **call_method**: Call custom methods on models
+
+  - Inputs: `model_name` (string), `method_name` (string), `args` (optional array), `kwargs` (optional object)
+  - Returns: Dictionary with method result
+
+## Resources
+
+### Model Information
+
+- **odoo://models/search/{query}**: Search for models by name or description
+- **odoo://models/{model_name}/info**: Information about a specific model
+- **odoo://models/{model_name}/fields**: Field definitions for a specific model
+
+### Documentation
+
+- **odoo://help/domains**: Complete guide to Odoo domain syntax with examples
+- **odoo://help/operations**: Documentation of all available MCP tools and workflows
+
+## Configuration
+
+### Odoo Connection Setup
+
+To connect to your Odoo instance, set the following environment variables:
+
+- `ODOO_URL`: Your Odoo server URL
+- `ODOO_DB`: Database name
+- `ODOO_USERNAME`: Login username
+- `ODOO_PASSWORD`: Password or API key
+- `ODOO_TIMEOUT`: Connection timeout in seconds (default: 30)
+- `ODOO_VERIFY_SSL`: Whether to verify SSL certificates (default: true)
+- `LOG_LEVEL`: Logging level (default: INFO)
+
+### Usage with Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "odoo": {
+      "command": "uvx",
+      "args": ["biszx-odoo-mcp"],
+      "env": {
+        "ODOO_URL": "https://your-odoo-instance.com",
+        "ODOO_DB": "your-database-name",
+        "ODOO_USERNAME": "your-username",
+        "ODOO_PASSWORD": "your-password-or-api-key"
+      }
+    }
+  }
+}
+```
+
+## Installation
+
+### Python Package
+
+```bash
+pip install biszx-odoo-mcp
+```
+
+### Running the Server
+
+```bash
+# Using the installed package
+biszx-odoo-mcp
+
+# Using uv for development
+uv run biszx-odoo-mcp
+
+# Using the MCP development tools
+uv run mcp dev src/biszx_odoo_mcp/main.py
+```
+
+## License
+
+This MCP server is licensed under the MIT License.

biszx_odoo_mcp-1.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+biszx_odoo_mcp/__init__.py,sha256=J-K5_2GapE12EHcbhrotvjxKDYFS2aGa_eIpcsnHjIg,58
+biszx_odoo_mcp/__main__.py,sha256=b7dX--Aowgjuvgr8Sh4aXa63TCwxPa_vLjh7JYReFz0,1256
+biszx_odoo_mcp/exceptions.py,sha256=vVMyZekFmZIg2SsH53zcefWp_swqFkE4lxQin1OVgB0,6611
+biszx_odoo_mcp/main.py,sha256=_HW_Pblf8BFIOhfZ7-uuT4uKNn3uZ269zsK8Lk7Rt5o,3914
+biszx_odoo_mcp-1.1.0.dist-info/licenses/LICENSE,sha256=_FwB4PGxcQWsToTqX33moF0HqnB45Ox6Fr0VPJiLyBI,1071
+biszx_odoo_mcp-1.1.0.dist-info/METADATA,sha256=zok0QuLLRKeeTpC0W9T1-UCqhTSM8HEX4ZkxVp8qC-4,5394
+biszx_odoo_mcp-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+biszx_odoo_mcp-1.1.0.dist-info/entry_points.txt,sha256=vdIkuiVsddBLNV--8Wgaf8xHu6Pdi2DAia-ISGNdxP0,64
+biszx_odoo_mcp-1.1.0.dist-info/top_level.txt,sha256=l6PxKyczED68V9LsRlWYClo1GfjSJaP9V-SDMnAUJbU,15
+biszx_odoo_mcp-1.1.0.dist-info/RECORD,,

biszx_odoo_mcp-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

biszx_odoo_mcp-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+biszx-odoo-mcp = biszx_odoo_mcp.__main__:main

biszx_odoo_mcp-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lê Anh Tuấn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

biszx_odoo_mcp-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+biszx_odoo_mcp