mcp-freecad

# FastMCP Server Implementation This document describes the new FastMCP-based MCP server implementation following best practices. ## Overview The MCP-FreeCAD server has been updated to use the latest **FastMCP 2.13.0.2** library, following modern best practices for MCP server development. ## Key Changes ### 1. Updated Dependencies - **fastmcp**: Upgraded to version 2.13.0.2 (from 0.4.0) - **mcp**: Upgraded to version 1.20.0 (from 1.0.0) - Removed legacy dependencies: `modelcontextprotocol`, `trio`, `flask` ### 2. Refactored Server Implementation The new `cursor_mcp_server.py` uses FastMCP's declarative approach: ```python from fastmcp import FastMCP # Create server instance mcp = FastMCP("freecad-mcp-server") # Define tools using decorators @mcp.tool() def create_box(length: float, width: float, height: float) -> str: """Create a box in FreeCAD.""" # Implementation... # Define resources using decorators @mcp.resource("freecad://status") def get_server_status() -> dict: """Get server status.""" return {"status": "running"} ``` ### 3. Best Practices Applied #### Declarative Tool Definition - Tools are defined using `@mcp.tool()` decorator - Resources are defined using `@mcp.resource()` decorator - Type hints are used for automatic schema generation - Docstrings provide tool descriptions #### Clean, Modular Code - Each tool is a simple, focused function - No complex class hierarchies - Easy to understand and maintain #### Error Handling - All tools include proper exception handling - User-friendly error messages with emoji indicators (✅/❌) - Graceful degradation when FreeCAD is not available ## Available Tools ### 1. test_connection Tests the connection to FreeCAD and returns version information. **Returns:** Connection status message ### 2. create_box Creates a box primitive in FreeCAD. **Parameters:** - `length` (float): Length of the box in mm - `width` (float): Width of the box in mm - `height` (float): Height of the box in mm **Returns:** Success message with box ID and dimensions ### 3. create_document Creates a new FreeCAD document. **Parameters:** - `name` (string): Name of the document **Returns:** Success message with document ID ### 4. create_cylinder Creates a cylinder primitive in FreeCAD. **Parameters:** - `radius` (float): Radius of the cylinder in mm - `height` (float): Height of the cylinder in mm **Returns:** Success message with cylinder ID and dimensions ### 5. create_sphere Creates a sphere primitive in FreeCAD. **Parameters:** - `radius` (float): Radius of the sphere in mm **Returns:** Success message with sphere ID ## Available Resources ### freecad://status Returns the server status including: - Server name - Version - FreeCAD availability - Running status ## Running the Server ### Standalone Mode ```bash python cursor_mcp_server.py ``` The server will start in STDIO mode for MCP client communication. ### With Cursor IDE Configure in your Cursor settings to connect to this MCP server for FreeCAD integration. ## Testing Comprehensive tests are available in `tests/test_fastmcp_server.py`: ```bash # Run all tests pytest tests/test_fastmcp_server.py -v # Run with coverage pytest tests/test_fastmcp_server.py --cov=. --cov-report=html ``` ### Test Coverage - Connection testing (success, failure, exceptions) - Tool functionality for all operations - Error handling and edge cases - Multiple operation sequences - Resource access ## Migration Notes ### From Old MCP SDK The old implementation used the MCP SDK directly with manual tool registration: ```python # Old approach from mcp import Server from mcp.server.stdio import stdio_server server = Server("freecad-mcp-server") @server.list_tools() async def handle_list_tools() -> list[Tool]: return [Tool(...)] ``` ### To FastMCP The new implementation is cleaner and more declarative: ```python # New approach from fastmcp import FastMCP mcp = FastMCP("freecad-mcp-server") @mcp.tool() def my_tool(param: str) -> str: return result ``` ## Benefits of FastMCP 1. **Simpler API**: Decorator-based approach is more intuitive 2. **Better Type Safety**: Automatic schema generation from type hints 3. **Built-in Features**: Storage, caching, authentication support 4. **Better Documentation**: Automatic documentation from docstrings 5. **Modern Patterns**: Follows Python best practices 6. **Async Support**: Native async/await support when needed 7. **Easier Testing**: Tools are regular Python functions ## Future Enhancements The FastMCP framework enables easy addition of: 1. **Persistent Storage**: For session management and caching 2. **Authentication**: OAuth, JWT, or custom auth providers 3. **Resource Caching**: Built-in caching with TTL support 4. **Composite Servers**: Combine multiple MCP servers 5. **Enhanced Monitoring**: Built-in performance tracking ## References - [FastMCP Documentation](https://gofastmcp.com) - [FastMCP GitHub](https://github.com/jlowin/fastmcp) - [MCP Protocol Specification](https://modelcontextprotocol.io)