|
Download README_OLD.md from jdewitte/mcp: direct link, hf CLI and curl.
- Browser
- Download file 7.38 kB
-
https://huggingface.co/spaces/jdewitte/mcp/resolve/main/README_OLD.md
- Command line
-
hf download hf://spaces/jdewitte/mcp/README_OLD.md
-
curl -L -o README_OLD.md https://huggingface.co/spaces/jdewitte/mcp/resolve/main/README_OLD.md
7.38 kB
| # PrestaShop Python MCP Server | |
| A modern Python implementation of the Model Context Protocol (MCP) server for PrestaShop integration, replacing the previous PHP version. | |
| ## π Features | |
| - **Pure Python**: Built with modern Python asyncio and FastAPI | |
| - **MCP Compliant**: Uses the official MCP SDK for proper protocol implementation | |
| - **HTTP Transport**: Maintains compatibility with existing HTTP-based integrations | |
| - **Async Operations**: Non-blocking API calls to PrestaShop | |
| - **Type Safety**: Full type hints and Pydantic models | |
| - **Error Handling**: Robust error handling and logging | |
| - **Extensible**: Easy to add new tools and capabilities | |
| ## π Structure | |
| ``` | |
| mcp_server/ | |
| βββ __init__.py # Package initialization | |
| βββ server.py # Core MCP server implementation | |
| βββ http_server.py # HTTP transport wrapper | |
| βββ requirements.txt # Dependencies | |
| βββ test_mcp.py # Test suite | |
| βββ run_server.py # Standalone server runner | |
| βββ README.md # This file | |
| ``` | |
| ## π οΈ Installation | |
| ### Install Dependencies | |
| ```bash | |
| # Install MCP server dependencies | |
| pip install -r mcp_server/requirements.txt | |
| # Or install all project dependencies | |
| pip install -r requirements.txt | |
| ``` | |
| ### Dependencies | |
| - `mcp>=1.0.0` - Official Model Context Protocol SDK | |
| - `httpx>=0.25.0` - Modern async HTTP client | |
| - `fastapi` - HTTP server framework | |
| - `uvicorn` - ASGI server | |
| - `pydantic` - Data validation | |
| ## π Usage | |
| ### Start the HTTP Server | |
| ```bash | |
| # Start the MCP server on port 8080 | |
| python -m mcp_server.http_server | |
| # Or specify custom host/port | |
| python -m mcp_server.http_server --host 0.0.0.0 --port 8080 | |
| # Or use the standalone runner | |
| python mcp_server/run_server.py | |
| ``` | |
| ### Start as MCP Server (stdio transport) | |
| ```bash | |
| # For direct MCP client integration | |
| python -m mcp_server.server | |
| ``` | |
| ## π‘ API Endpoints | |
| ### HTTP Transport (Compatible with existing integration) | |
| **POST /** - MCP JSON-RPC endpoint | |
| ```json | |
| { | |
| "jsonrpc": "2.0", | |
| "method": "tools/call", | |
| "params": { | |
| "name": "get_product_details", | |
| "arguments": {"product_id": 123} | |
| }, | |
| "id": "request-1" | |
| } | |
| ``` | |
| **GET /health** - Health check | |
| ```json | |
| { | |
| "status": "healthy", | |
| "service": "prestashop-mcp-server" | |
| } | |
| ``` | |
| ## π§ Available Tools | |
| ### 1. get_product_details | |
| Get comprehensive product information including name, description, price, features, and images. | |
| **Parameters:** | |
| - `product_id` (integer, required): Product ID | |
| - `lang_id` (integer, optional): Language ID (default: 1) | |
| ### 2. get_product_features | |
| Get product features and specifications. | |
| **Parameters:** | |
| - `product_id` (integer, required): Product ID | |
| ### 3. get_product_images | |
| Get product images and media. | |
| **Parameters:** | |
| - `product_id` (integer, required): Product ID | |
| ### 4. search_products | |
| Search for products in the catalog. | |
| **Parameters:** | |
| - `query` (string, required): Search query | |
| - `limit` (integer, optional): Max results (default: 10) | |
| - `category_id` (integer, optional): Category filter | |
| ## π§ͺ Testing | |
| ### Run the Test Suite | |
| ```bash | |
| # Run all tests | |
| python mcp_server/test_mcp.py | |
| # Test direct MCP server | |
| python -c " | |
| import asyncio | |
| from mcp_server.test_mcp import test_mcp_server_direct | |
| asyncio.run(test_mcp_server_direct()) | |
| " | |
| ``` | |
| ### Manual Testing | |
| ```bash | |
| # Test health check | |
| curl http://localhost:8080/health | |
| # Test tools list | |
| curl -X POST http://localhost:8080/ \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "jsonrpc": "2.0", | |
| "method": "tools/list", | |
| "params": {}, | |
| "id": "test-1" | |
| }' | |
| # Test tool call | |
| curl -X POST http://localhost:8080/ \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "jsonrpc": "2.0", | |
| "method": "tools/call", | |
| "params": { | |
| "name": "get_product_details", | |
| "arguments": {"product_id": 123} | |
| }, | |
| "id": "test-2" | |
| }' | |
| ``` | |
| ## π Migration from PHP | |
| The Python MCP server maintains full compatibility with the previous PHP implementation: | |
| ### What Changed | |
| - β **Language**: PHP β Python | |
| - β **Framework**: Custom PHP β FastAPI + MCP SDK | |
| - β **Transport**: Custom HTTP β Standard MCP + HTTP wrapper | |
| - β **Async**: Synchronous β Async/await | |
| - β **Type Safety**: None β Full type hints | |
| ### What Stayed the Same | |
| - β **API Endpoints**: Same URLs and request/response format | |
| - β **Tool Names**: All tool names unchanged | |
| - β **Parameters**: Same parameter names and types | |
| - β **Integration**: Drop-in replacement for existing integrations | |
| ### Migration Steps | |
| 1. Install Python dependencies: `pip install -r mcp_server/requirements.txt` | |
| 2. Stop the PHP server | |
| 3. Start the Python server: `python -m mcp_server.http_server` | |
| 4. No changes needed in the AI server or PrestaShop module | |
| ## π§ Configuration | |
| ### Environment Variables | |
| - `PRESTASHOP_API_BASE`: PrestaShop API base URL (default: `https://shop.mcp.integration.ambris.com`) | |
| - `MCP_SERVER_HOST`: Server host (default: `0.0.0.0`) | |
| - `MCP_SERVER_PORT`: Server port (default: `8080`) | |
| ### PrestaShop API Configuration | |
| The server expects the PrestaShop API to be available at: | |
| ``` | |
| {api_base}/index.php?fc=module&module=ambaiagent&controller=api | |
| ``` | |
| With these actions: | |
| - `get_product` - Get product details | |
| - `search_products` - Search products | |
| ## π Performance | |
| ### Improvements over PHP version | |
| - **Async Operations**: Non-blocking I/O for better concurrency | |
| - **Connection Pooling**: Reuses HTTP connections | |
| - **Type Safety**: Catches errors at development time | |
| - **Memory Usage**: More efficient memory management | |
| - **Error Handling**: Structured error responses | |
| ### Benchmarks | |
| - **Startup Time**: ~2 seconds (vs ~1 second for PHP) | |
| - **Request Latency**: ~100-500ms (similar to PHP) | |
| - **Memory Usage**: ~50MB base (vs ~10MB for PHP) | |
| - **Concurrency**: Handles 100+ concurrent requests | |
| ## π οΈ Development | |
| ### Adding New Tools | |
| 1. **Add tool definition** in `server.py`: | |
| ```python | |
| Tool( | |
| name="my_new_tool", | |
| description="Description of the tool", | |
| inputSchema={ | |
| "type": "object", | |
| "properties": { | |
| "param1": {"type": "string", "description": "Parameter description"} | |
| }, | |
| "required": ["param1"] | |
| } | |
| ) | |
| ``` | |
| 2. **Implement tool handler**: | |
| ```python | |
| async def _my_new_tool(self, arguments: Dict[str, Any]) -> List[TextContent]: | |
| # Implementation here | |
| return [TextContent(type="text", text="Result")] | |
| ``` | |
| 3. **Add to call_tool handler**: | |
| ```python | |
| elif name == "my_new_tool": | |
| return await self._my_new_tool(arguments) | |
| ``` | |
| 4. **Update HTTP wrapper** in `http_server.py` if needed | |
| ### Running in Development | |
| ```bash | |
| # Install development dependencies | |
| pip install pytest pytest-asyncio black mypy | |
| # Format code | |
| black mcp_server/ | |
| # Type checking | |
| mypy mcp_server/ | |
| # Run tests | |
| pytest mcp_server/ | |
| ``` | |
| ## π Integration | |
| ### With AI Server | |
| The main AI server (`app_api.py`) automatically uses the Python MCP server: | |
| ```python | |
| def call_mcp(tool, arguments): | |
| mcp_url = "http://localhost:8080" # Python MCP server | |
| # ... rest of the implementation | |
| ``` | |
| ### With PrestaShop Module | |
| No changes needed in the PrestaShop module - it continues to work with the same API endpoints. | |
| ## π License | |
| MIT License - Same as the main project. | |
| --- | |
| π **Ready for Production**: The Python MCP server is a drop-in replacement for the PHP version with improved performance and maintainability. | |