biszx-odoo-mcp 1.1.1__tar.gz

biszx_odoo_mcp-1.1.1/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.1/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: biszx-odoo-mcp
+Version: 1.1.1
+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.1/README.md

@@ -0,0 +1,159 @@
+# 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.1/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "biszx-odoo-mcp"
+version = "1.1.1"
+description = "MCP Server for Odoo Integration"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Operating System :: OS Independent",
+]
+keywords = ["odoo", "mcp", "server"]
+authors = [
+    {name = "Biszx", email = "isares.br@gmail.com"}
+]
+dependencies = [
+    "asyncio>=3.4.3",
+    "loguru>=0.7.3",
+    "mcp[cli]>=1.9.4",
+    "odoorpc>=0.10.1",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/biszx/biszx-odoo-mcp"
+Issues = "https://gitlab.com/biszx/biszx-odoo-mcp/issues"
+
+[project.scripts]
+biszx-odoo-mcp = "biszx_odoo_mcp.__main__:main"
+
+[dependency-groups]
+dev = [
+    "flake8>=7.3.0",
+    "mypy>=1.16.1",
+    "pre-commit>=4.2.0",
+    "pylint>=3.3.7",
+    "pytest>=8.4.1",
+    "pytest-cov>=6.2.1",
+    "pytest-asyncio>=1.0.0",
+    "python-dotenv>=1.1.1",
+    "ruff>=0.12.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

biszx_odoo_mcp-1.1.1/setup.cfg

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

biszx_odoo_mcp-1.1.1/src/biszx_odoo_mcp/__init__.py

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

biszx_odoo_mcp-1.1.1/src/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-1.1.1/src/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)