freecad-robust-mcp-fc111/docs/guide/resources.md

MCP Resources

The FreeCAD Robust MCP Server exposes several resources that allow AI assistants to query FreeCAD's state without executing code.

---

Overview

MCP Resources are read-only endpoints that provide context about FreeCAD's current state. They're useful for:

• Understanding what documents and objects exist
• Getting system information
• Discovering available capabilities

---

Available Resources

The Robust MCP Server provides 12 resources for querying FreeCAD state:

freecad://capabilities

Returns a comprehensive JSON catalog of all available tools, resources, and prompts.

Use case: Understanding what the Robust MCP Server can do.

Example response:

{
  "tools": {
    "execution": ["execute_python", "get_freecad_version", ...],
    "documents": ["create_document", "open_document", ...],
    ...
  },
  "resources": ["freecad://capabilities", "freecad://documents", ...],
  "prompts": ["freecad-help", "create-parametric-part", ...]
}

freecad://version

Gets FreeCAD version and build information.

Use case: Checking FreeCAD compatibility and environment.

Example response:

{
  "version": "1.0.0",
  "build_date": "2024-01-15",
  "python_version": "3.11.6",
  "gui_available": true
}

freecad://status

Gets current FreeCAD connection and runtime status.

Use case: Verifying connection health and mode.

Example response:

{
  "connected": true,
  "mode": "xmlrpc",
  "freecad_version": "1.0.0",
  "gui_available": true,
  "last_ping_ms": 12.5,
  "error": null
}

freecad://documents

Lists all open FreeCAD documents with basic information.

Use case: Seeing what documents are currently open.

Example response:

[
  {
    "name": "MyPart",
    "label": "My Part Design",
    "path": "/home/user/projects/mypart.FCStd",
    "is_modified": true,
    "object_count": 15,
    "active_object": "Pad"
  }
]

freecad://documents/{name}

Gets detailed information about a specific document.

Use case: Examining a document's contents.

Example response:

{
  "name": "MyPart",
  "label": "My Part Design",
  "path": "/home/user/projects/mypart.FCStd",
  "objects": ["Body", "Sketch", "Pad", "Fillet"],
  "is_modified": true,
  "active_object": "Fillet"
}

freecad://documents/{name}/objects

Gets list of objects in a specific document.

Use case: Listing all objects in a document with their types.

Example response:

[
  {
    "name": "Body",
    "label": "Body",
    "type_id": "PartDesign::Body",
    "visibility": true
  },
  {
    "name": "Sketch",
    "label": "Sketch",
    "type_id": "Sketcher::SketchObject",
    "visibility": false
  }
]

freecad://objects/{doc_name}/{obj_name}

Gets detailed information about a specific object including properties and shape data.

Use case: Inspecting object properties and geometry.

Example response:

{
  "name": "Pad",
  "label": "Pad",
  "type_id": "PartDesign::Pad",
  "properties": {
    "Length": 10.0,
    "Type": "Length",
    "Symmetric": false
  },
  "shape_info": {
    "shape_type": "Solid",
    "volume": 1000.0,
    "area": 600.0,
    "is_valid": true
  },
  "children": [],
  "parents": ["Sketch"],
  "visibility": true
}

freecad://active-document

Gets the currently active document.

Use case: Quick access to the document the user is working on.

Example response:

{
  "name": "MyPart",
  "label": "My Part Design",
  "path": "/home/user/projects/mypart.FCStd",
  "objects": ["Body", "Sketch", "Pad"],
  "is_modified": false,
  "active_object": "Pad"
}

freecad://workbenches

Gets list of available FreeCAD workbenches.

Use case: Understanding what workbenches are available.

Example response:

[
  {
    "name": "PartDesignWorkbench",
    "label": "Part Design",
    "is_active": true
  },
  {
    "name": "SketcherWorkbench",
    "label": "Sketcher",
    "is_active": false
  }
]

freecad://workbenches/active

Gets the currently active workbench.

Use case: Knowing which workbench context is active.

Example response:

{
  "name": "PartDesignWorkbench",
  "label": "Part Design"
}

freecad://macros

Gets list of available FreeCAD macros.

Use case: Discovering available automation macros.

Example response:

[
  {
    "name": "MultiExport",
    "path": "/home/user/.local/share/FreeCAD/Macro/MultiExport.FCMacro",
    "description": "Export objects to multiple formats",
    "is_system": false
  }
]

freecad://console

Gets recent FreeCAD console output.

Use case: Debugging and seeing FreeCAD messages.

Example response:

{
  "lines": [
    "MCP Bridge started!",
    "  - XML-RPC: localhost:9875",
    "  - Socket: localhost:9876",
    "Document created: MyPart"
  ],
  "count": 4
}

---

Using Resources in Prompts

When talking to an AI assistant connected via MCP, resources are automatically available. The AI can read them to understand context.

Example conversation:

User: "What documents do I have open?"

AI: [Reads freecad://documents resource]
    "You have two documents open:
     1. 'Bracket' - modified, 12 objects
     2. 'Housing' - saved, 8 objects"

---

Resources vs Tools

Aspect	Resources	Tools
Purpose	Query state (read-only)	Perform actions
Side effects	None	May modify documents
Response	Data/text	Operation result
Example	freecad://documents	create_document()

---

Resource URI Summary

URI	Description
freecad://capabilities	All available tools, resources, prompts
freecad://version	FreeCAD version and build info
freecad://status	Connection status and mode
freecad://documents	List of open documents
freecad://documents/{name}	Single document details
freecad://documents/{name}/objects	Objects in a document
freecad://objects/{doc_name}/{obj_name}	Detailed object information
freecad://active-document	Currently active document
freecad://workbenches	Available workbenches
freecad://workbenches/active	Currently active workbench
freecad://macros	Available macros
freecad://console	Recent console output

---

Implementing Custom Resources

If you're extending the Robust MCP Server, you can add custom resources:

@mcp.resource("freecad://custom/{param}")
async def my_custom_resource(param: str) -> str:
    """Return custom data based on param."""
    # Query FreeCAD and return data
    result = await bridge.execute_python(f"...")
    return json.dumps(result)

---

Next Steps

• Tools Reference - Complete API for MCP tools
• Connection Modes - How to connect to FreeCAD