chrore: major overhaul of docs, commands, and workflows (#23)
* ci: add status badges to README * chore: major overhaul - docs, commands & workflows * fix: general fixes and improvements * chore: various updates and fixes * chore: minor fixes
This commit is contained in:
Sean P. Kane
+4
-4
@@ -33,7 +33,7 @@ You have two options depending on your workflow:
|
||||
Best for automated workflows, batch processing, or when you don't need visual feedback.
|
||||
|
||||
```bash
|
||||
just run-headless
|
||||
just freecad::run-headless
|
||||
```
|
||||
|
||||
**Capabilities:** All modeling operations, export, scripting.
|
||||
@@ -44,7 +44,7 @@ just run-headless
|
||||
Best for interactive design work where you want to see results visually.
|
||||
|
||||
```bash
|
||||
just run-gui
|
||||
just freecad::run-gui
|
||||
```
|
||||
|
||||
**Capabilities:** Everything headless mode can do, plus screenshots, colors, view control.
|
||||
@@ -441,7 +441,7 @@ Instead of creating many individual features:
|
||||
|
||||
You're running in headless mode and trying to use a GUI-only feature. Either:
|
||||
|
||||
- Switch to GUI mode: `just run-gui`
|
||||
- Switch to GUI mode: `just freecad::run-gui`
|
||||
- Use an alternative approach (e.g., skip visual operations)
|
||||
|
||||
### Objects Not Appearing
|
||||
@@ -474,7 +474,7 @@ If the MCP bridge isn't responding:
|
||||
|
||||
1. Check FreeCAD is running with the bridge started
|
||||
1. Verify ports 9875 (XML-RPC) and 9876 (socket) are available
|
||||
1. Restart FreeCAD with `just run-gui` or `just run-headless`
|
||||
1. Restart FreeCAD with `just freecad::run-gui` or `just freecad::run-headless`
|
||||
|
||||
---
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -2,7 +2,7 @@
|
||||
|
||||
This document provides a technical overview of the FreeCAD MCP Server architecture.
|
||||
|
||||
For the full architecture document with design decisions and rationale, see [ARCHITECTURE-MCP.md](https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/ARCHITECTURE-MCP.md).
|
||||
For the full architecture document with design decisions and rationale, see [Detailed Architecture](architecture-detailed.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -39,17 +39,18 @@ The FreeCAD MCP Server follows a **Bridge with Adapter** pattern:
|
||||
|
||||
```text
|
||||
src/freecad_mcp/
|
||||
├── __init__.py
|
||||
├── __init__.py # Package entry point
|
||||
├── _version.py # Version info (auto-generated)
|
||||
├── server.py # Main MCP server entry point
|
||||
├── config.py # Configuration management
|
||||
├── py.typed # PEP 561 marker for type hints
|
||||
│
|
||||
├── bridge/ # FreeCAD communication layer
|
||||
│ ├── __init__.py # Bridge factory
|
||||
│ ├── base.py # Abstract bridge interface
|
||||
│ ├── embedded.py # In-process FreeCAD (Linux only)
|
||||
│ ├── socket.py # JSON-RPC socket bridge
|
||||
│ ├── xmlrpc.py # XML-RPC bridge (recommended)
|
||||
│ └── protocol.py # Wire protocol definitions
|
||||
│ └── xmlrpc.py # XML-RPC bridge (recommended)
|
||||
│
|
||||
├── tools/ # MCP tool implementations
|
||||
│ ├── __init__.py
|
||||
@@ -69,7 +70,8 @@ src/freecad_mcp/
|
||||
│ ├── __init__.py
|
||||
│ └── freecad.py # Modeling and debugging prompts
|
||||
│
|
||||
└── freecad_workbench_addon/ # Workbench addon (deprecated location)
|
||||
└── utils/ # Utility modules
|
||||
└── __init__.py
|
||||
```
|
||||
|
||||
---
|
||||
@@ -124,7 +126,6 @@ The workbench addon runs inside FreeCAD:
|
||||
|
||||
```text
|
||||
addon/FreecadRobustMCP/
|
||||
├── package.xml # FreeCAD addon metadata
|
||||
├── Init.py # Module initialization
|
||||
├── InitGui.py # GUI initialization (workbench)
|
||||
├── FreecadRobustMCP.svg # Workbench icon
|
||||
@@ -132,8 +133,12 @@ addon/FreecadRobustMCP/
|
||||
├── __init__.py
|
||||
├── server.py # XML-RPC/JSON-RPC server
|
||||
└── headless_server.py # Headless mode launcher
|
||||
|
||||
package.xml # FreeCAD addon metadata (in project root)
|
||||
```
|
||||
|
||||
Note: The `package.xml` file is in the project root, not inside the addon directory. This is because it defines metadata for multiple components (workbench and macros) in a single manifest.
|
||||
|
||||
### Thread Safety
|
||||
|
||||
The workbench uses a queue-based system for thread-safe GUI operations:
|
||||
@@ -256,4 +261,4 @@ Embedded mode receives **minimal testing**:
|
||||
## Next Steps
|
||||
|
||||
- [Contributing](contributing.md) - How to contribute
|
||||
- [Full Architecture Document](https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/ARCHITECTURE-MCP.md) - Complete design details
|
||||
- [Detailed Architecture](architecture-detailed.md) - Complete design details
|
||||
|
||||
@@ -46,15 +46,15 @@ uv run safety auth --login
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
just test
|
||||
|
||||
# Run unit tests only
|
||||
# Run unit tests
|
||||
just testing::unit
|
||||
|
||||
# Run with coverage
|
||||
just testing::cov
|
||||
|
||||
# Run all tests including integration
|
||||
just testing::all
|
||||
|
||||
# Run type checking
|
||||
uv run mypy src/
|
||||
```
|
||||
@@ -63,16 +63,16 @@ uv run mypy src/
|
||||
|
||||
```bash
|
||||
# Run all pre-commit checks
|
||||
just check
|
||||
just quality::check
|
||||
|
||||
# Run linting
|
||||
just lint
|
||||
just quality::lint
|
||||
|
||||
# Format code
|
||||
just format
|
||||
just quality::format
|
||||
|
||||
# Run security checks
|
||||
just quality::secrets
|
||||
just quality::security
|
||||
```
|
||||
|
||||
---
|
||||
@@ -106,20 +106,20 @@ freecad-robust-mcp-and-more/
|
||||
- Follow PEP 8 with 88-character line length (ruff/black)
|
||||
- Use type hints for all function signatures
|
||||
- Write Google-style docstrings
|
||||
- Run `just format` before committing
|
||||
- Run `just quality::format` before committing
|
||||
|
||||
### Testing
|
||||
|
||||
- Write tests for all new functionality
|
||||
- Maintain test coverage
|
||||
- Run `just test` before submitting PRs
|
||||
- Run `just all` before submitting PRs (runs quality checks + unit tests)
|
||||
- Integration tests require FreeCAD (run via CI)
|
||||
|
||||
### Documentation
|
||||
|
||||
- Update docstrings for API changes
|
||||
- Update user docs for feature changes
|
||||
- Run `just docs` to build and verify
|
||||
- Run `just documentation::build` to build and verify
|
||||
|
||||
### Commits
|
||||
|
||||
@@ -214,7 +214,6 @@ Currently, embedded mode has only mocked unit tests. Adding live integration tes
|
||||
## Getting Help
|
||||
|
||||
- **Issues:** [GitHub Issues](https://github.com/spkane/freecad-robust-mcp-and-more/issues)
|
||||
- **Discussions:** [GitHub Discussions](https://github.com/spkane/freecad-robust-mcp-and-more/discussions)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,570 @@
|
||||
# MkDocs Documentation Guide
|
||||
|
||||
This project uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) for documentation. This guide covers our specific configuration, extensions, and how to use them.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Serve docs locally with live reload
|
||||
just documentation::serve
|
||||
|
||||
# Build static site
|
||||
just documentation::build
|
||||
|
||||
# Open docs in browser
|
||||
just documentation::open
|
||||
```
|
||||
|
||||
## Theme Configuration
|
||||
|
||||
We use **Material for MkDocs** with dark mode as the default. Users can toggle between dark and light modes using the sun/moon icon in the header.
|
||||
|
||||
**Color scheme:** Deep purple primary with purple accent.
|
||||
|
||||
## Markdown Extensions
|
||||
|
||||
### Code Blocks
|
||||
|
||||
#### Syntax Highlighting
|
||||
|
||||
Standard fenced code blocks with language hints:
|
||||
|
||||
````markdown
|
||||
```python
|
||||
def hello():
|
||||
print("Hello, world!")
|
||||
```
|
||||
````
|
||||
|
||||
#### Line Numbers and Highlighting
|
||||
|
||||
````markdown
|
||||
```python linenums="1" hl_lines="2 3"
|
||||
def hello():
|
||||
# These lines are highlighted
|
||||
print("Hello!")
|
||||
```
|
||||
````
|
||||
|
||||
#### Code Annotations
|
||||
|
||||
Add numbered annotations that expand on hover:
|
||||
|
||||
````markdown
|
||||
```python
|
||||
def process(data): # (1)!
|
||||
return data.strip() # (2)!
|
||||
```
|
||||
|
||||
1. This function processes input data
|
||||
2. Removes leading/trailing whitespace
|
||||
|
||||
````
|
||||
|
||||
#### Inline Code Highlighting
|
||||
|
||||
Use `#!python print("inline")` for inline syntax highlighting:
|
||||
|
||||
```markdown
|
||||
Use `#!python print("inline")` for inline code with highlighting.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Tabbed Content
|
||||
|
||||
Create tabs for platform-specific or alternative content:
|
||||
|
||||
```markdown
|
||||
=== "macOS"
|
||||
|
||||
```bash
|
||||
~/Library/Application Support/FreeCAD/Macro/
|
||||
```
|
||||
|
||||
=== "Linux"
|
||||
|
||||
```bash
|
||||
~/.local/share/FreeCAD/Macro/
|
||||
```
|
||||
|
||||
=== "Windows"
|
||||
|
||||
```bash
|
||||
%APPDATA%/FreeCAD/Macro/
|
||||
```
|
||||
```
|
||||
|
||||
**Renders as:**
|
||||
|
||||
<!-- markdownlint-disable MD046 -->
|
||||
=== "macOS"
|
||||
|
||||
```bash
|
||||
~/Library/Application Support/FreeCAD/Macro/
|
||||
```
|
||||
|
||||
=== "Linux"
|
||||
|
||||
```bash
|
||||
~/.local/share/FreeCAD/Macro/
|
||||
```
|
||||
|
||||
=== "Windows"
|
||||
|
||||
```bash
|
||||
%APPDATA%/FreeCAD/Macro/
|
||||
```
|
||||
<!-- markdownlint-enable MD046 -->
|
||||
|
||||
---
|
||||
|
||||
### Admonitions (Call-outs)
|
||||
|
||||
Create styled call-out boxes:
|
||||
|
||||
```markdown
|
||||
!!! note "Optional Title"
|
||||
This is a note admonition.
|
||||
|
||||
!!! warning
|
||||
This is a warning without a custom title.
|
||||
|
||||
!!! danger "Critical"
|
||||
This is a danger/error admonition.
|
||||
|
||||
!!! tip
|
||||
This is a tip admonition.
|
||||
|
||||
!!! info
|
||||
This is an info admonition.
|
||||
|
||||
!!! example
|
||||
This is an example admonition.
|
||||
```
|
||||
|
||||
**Collapsible admonitions:**
|
||||
|
||||
```markdown
|
||||
??? note "Click to expand"
|
||||
This content is hidden by default.
|
||||
|
||||
???+ note "Expanded by default"
|
||||
This content is visible but can be collapsed.
|
||||
```
|
||||
|
||||
**Available types:** `note`, `abstract`, `info`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, `quote`
|
||||
|
||||
---
|
||||
|
||||
### Task Lists
|
||||
|
||||
Create checkbox lists:
|
||||
|
||||
```markdown
|
||||
- [x] Completed task
|
||||
- [ ] Incomplete task
|
||||
- [ ] Another task
|
||||
```
|
||||
|
||||
**Renders as:**
|
||||
|
||||
- [x] Completed task
|
||||
- [ ] Incomplete task
|
||||
- [ ] Another task
|
||||
|
||||
---
|
||||
|
||||
### Keyboard Keys
|
||||
|
||||
Style keyboard shortcuts:
|
||||
|
||||
```markdown
|
||||
Press ++ctrl+c++ to copy.
|
||||
Press ++cmd+shift+p++ on macOS.
|
||||
Press ++enter++ to confirm.
|
||||
```
|
||||
|
||||
**Renders as:** Press ++ctrl+c++ to copy.
|
||||
|
||||
**Common keys:** `ctrl`, `alt`, `shift`, `cmd`, `enter`, `tab`, `esc`, `backspace`, `delete`, `up`, `down`, `left`, `right`, `f1`-`f12`
|
||||
|
||||
---
|
||||
|
||||
### Text Formatting
|
||||
|
||||
#### Highlighting
|
||||
|
||||
```markdown
|
||||
==This text is highlighted==
|
||||
```
|
||||
|
||||
**Renders as:** ==This text is highlighted==
|
||||
|
||||
#### Subscript and Superscript
|
||||
|
||||
```markdown
|
||||
H~2~O (subscript)
|
||||
x^2^ (superscript)
|
||||
```
|
||||
|
||||
**Renders as:** H~2~O and x^2^
|
||||
|
||||
#### Strikethrough
|
||||
|
||||
```markdown
|
||||
~~deleted text~~
|
||||
```
|
||||
|
||||
**Renders as:** ~~deleted text~~
|
||||
|
||||
#### Critic Markup (for diffs/reviews)
|
||||
|
||||
```markdown
|
||||
{--deleted--}
|
||||
{++added++}
|
||||
{~~old~>new~~}
|
||||
{==highlighted==}
|
||||
{>>comment<<}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Definition Lists
|
||||
|
||||
```markdown
|
||||
Term 1
|
||||
: Definition for term 1
|
||||
|
||||
Term 2
|
||||
: Definition for term 2
|
||||
: Can have multiple definitions
|
||||
```
|
||||
|
||||
**Renders as:**
|
||||
|
||||
Term 1
|
||||
: Definition for term 1
|
||||
|
||||
Term 2
|
||||
: Definition for term 2
|
||||
: Can have multiple definitions
|
||||
|
||||
---
|
||||
|
||||
### Footnotes
|
||||
|
||||
```markdown
|
||||
This needs a citation[^1].
|
||||
|
||||
[^1]: This is the footnote content.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Mermaid Diagrams
|
||||
|
||||
Create diagrams using Mermaid syntax:
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
graph LR
|
||||
A[MCP Client] --> B[MCP Server]
|
||||
B --> C[FreeCAD Bridge]
|
||||
C --> D[FreeCAD]
|
||||
```
|
||||
````
|
||||
|
||||
**Renders as:**
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[MCP Client] --> B[MCP Server]
|
||||
B --> C[FreeCAD Bridge]
|
||||
C --> D[FreeCAD]
|
||||
```
|
||||
|
||||
**Supported diagram types:** flowchart, sequence, class, state, ER, gantt, pie, journey
|
||||
|
||||
---
|
||||
|
||||
## Plugins
|
||||
|
||||
### Git Revision Date
|
||||
|
||||
Pages automatically show "Last updated X ago" at the bottom. No action needed.
|
||||
|
||||
### Image Lightbox (GLightbox)
|
||||
|
||||
All images are automatically zoomable. Click any image to open in a lightbox overlay.
|
||||
|
||||
To exclude an image from lightbox:
|
||||
|
||||
```markdown
|
||||
{ .off-glb }
|
||||
```
|
||||
|
||||
### Minification
|
||||
|
||||
HTML is automatically minified in production builds. No action needed.
|
||||
|
||||
### Search
|
||||
|
||||
Full-text search is enabled. Features:
|
||||
|
||||
- Search suggestions as you type
|
||||
- Search result highlighting
|
||||
- Shareable search URLs
|
||||
|
||||
---
|
||||
|
||||
## Macros Plugin
|
||||
|
||||
### Custom Delimiters
|
||||
|
||||
<!-- markdownlint-disable MD046 -->
|
||||
!!! warning "Important"
|
||||
We use **custom delimiters** to avoid conflicts with Python dict literals in code blocks.
|
||||
|
||||
- Variables: `{` `{@` and `@}` `}`
|
||||
- Blocks: `{%` `@` and `@` `%}`
|
||||
|
||||
Standard Jinja2 `{` `{` `}` `}` syntax will NOT work.
|
||||
<!-- markdownlint-enable MD046 -->
|
||||
|
||||
### Using Variables
|
||||
|
||||
Variables are defined in `docs/variables.yaml`:
|
||||
|
||||
```yaml
|
||||
# docs/variables.yaml
|
||||
project_name: FreeCAD MCP Server
|
||||
package_name: freecad-robust-mcp
|
||||
xmlrpc_port: 9875
|
||||
socket_port: 9876
|
||||
```
|
||||
|
||||
Use in Markdown:
|
||||
|
||||
```markdown
|
||||
The default XML-RPC port is {{@ xmlrpc_port @}}.
|
||||
Install with: `pip install {{@ package_name @}}`
|
||||
```
|
||||
|
||||
### Available Variables
|
||||
|
||||
| Variable | Value | Description |
|
||||
|----------|-------|-------------|
|
||||
| `project_name` | FreeCAD MCP Server | Display name |
|
||||
| `package_name` | freecad-robust-mcp | PyPI package name |
|
||||
| `docker_image` | spkane/freecad-robust-mcp | Docker image |
|
||||
| `xmlrpc_port` | 9875 | XML-RPC server port |
|
||||
| `socket_port` | 9876 | Socket server port |
|
||||
| `paths.macos.macro` | ~/Library/... | macOS macro path |
|
||||
| `paths.linux.macro` | ~/.local/share/... | Linux macro path |
|
||||
| `paths.windows.macro` | %APPDATA%/... | Windows macro path |
|
||||
|
||||
### Built-in Macros
|
||||
|
||||
```markdown
|
||||
Current time: {{@ now() @}}
|
||||
Page URL: {{@ page.url @}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Documentation (mkdocstrings)
|
||||
|
||||
Auto-generate API docs from Python docstrings:
|
||||
|
||||
```markdown
|
||||
::: freecad_mcp.server
|
||||
options:
|
||||
show_source: true
|
||||
heading_level: 3
|
||||
```
|
||||
|
||||
This renders the module's docstrings, classes, and functions automatically.
|
||||
|
||||
**Options:**
|
||||
|
||||
- `show_source: true` - Show source code
|
||||
- `heading_level: 3` - Start headings at h3
|
||||
- `members: [func1, func2]` - Only show specific members
|
||||
- `filters: ["!^_"]` - Exclude private members
|
||||
|
||||
---
|
||||
|
||||
## Navigation
|
||||
|
||||
### Features Enabled
|
||||
|
||||
- **Instant navigation** - Pages load without full refresh
|
||||
- **Navigation tabs** - Top-level sections as tabs
|
||||
- **Section index pages** - Click section to see overview
|
||||
- **Back to top** - Button appears when scrolling
|
||||
- **Table of contents** - Follows scroll position
|
||||
|
||||
---
|
||||
|
||||
## Images
|
||||
|
||||
### Basic Image
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
### Image with Caption
|
||||
|
||||
```markdown
|
||||
<figure markdown>
|
||||
|
||||
<figcaption>This is the caption</figcaption>
|
||||
</figure>
|
||||
```
|
||||
|
||||
### Image Alignment
|
||||
|
||||
```markdown
|
||||
{ align=left }
|
||||
{ align=right }
|
||||
```
|
||||
|
||||
### Image Size
|
||||
|
||||
```markdown
|
||||
{ width="300" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Links
|
||||
|
||||
### Internal Links
|
||||
|
||||
```markdown
|
||||
[Installation Guide](../getting-started/installation.md)
|
||||
[Config section](configuration.md#environment-variables)
|
||||
```
|
||||
|
||||
### External Links
|
||||
|
||||
External links automatically open in new tab (Material theme default).
|
||||
|
||||
```markdown
|
||||
[FreeCAD](https://www.freecad.org/)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tables
|
||||
|
||||
Standard Markdown tables with sorting enabled:
|
||||
|
||||
```markdown
|
||||
| Column 1 | Column 2 | Column 3 |
|
||||
|----------|----------|----------|
|
||||
| Data 1 | Data 2 | Data 3 |
|
||||
| Data 4 | Data 5 | Data 6 |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```text
|
||||
docs/
|
||||
├── index.md # Home page
|
||||
├── variables.yaml # Macros variables
|
||||
├── overrides/ # Theme customizations
|
||||
│ └── .gitkeep
|
||||
├── assets/ # Images, favicon, etc.
|
||||
├── getting-started/
|
||||
│ ├── installation.md
|
||||
│ ├── configuration.md
|
||||
│ └── quickstart.md
|
||||
├── guide/
|
||||
│ └── ...
|
||||
├── api/
|
||||
│ └── ...
|
||||
└── development/
|
||||
├── contributing.md
|
||||
├── architecture.md
|
||||
├── releasing.md
|
||||
└── mkdocs-guide.md # This file
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Adding a New Page
|
||||
|
||||
1. Create the markdown file in the appropriate directory
|
||||
2. Add to `nav:` section in `mkdocs.yaml`
|
||||
|
||||
### Adding Redirects
|
||||
|
||||
If you move/rename a page, add a redirect in `mkdocs.yaml`:
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
- redirects:
|
||||
redirect_maps:
|
||||
'old-page.md': 'new-location/new-page.md'
|
||||
```
|
||||
|
||||
### Custom CSS
|
||||
|
||||
Add custom styles in `docs/overrides/stylesheets/extra.css` and reference in `mkdocs.yaml`:
|
||||
|
||||
```yaml
|
||||
extra_css:
|
||||
- overrides/stylesheets/extra.css
|
||||
```
|
||||
|
||||
### Custom JavaScript
|
||||
|
||||
Add scripts in `docs/overrides/javascripts/extra.js` and reference in `mkdocs.yaml`:
|
||||
|
||||
```yaml
|
||||
extra_javascript:
|
||||
- overrides/javascripts/extra.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Macros Not Rendering
|
||||
|
||||
Remember to use custom delimiters: `{{@ variable @}}` not `{{ variable }}`.
|
||||
|
||||
### Git Revision Date Warnings
|
||||
|
||||
New files not yet committed will show warnings. Commit the file to fix.
|
||||
|
||||
### Build Errors
|
||||
|
||||
```bash
|
||||
# Check for syntax errors
|
||||
uv run mkdocs build --strict
|
||||
|
||||
# Verbose output
|
||||
uv run mkdocs build -v
|
||||
```
|
||||
|
||||
### Serve Not Auto-Reloading
|
||||
|
||||
Some changes (like `mkdocs.yaml`) require restarting the server.
|
||||
|
||||
---
|
||||
|
||||
## Reference Links
|
||||
|
||||
- [MkDocs Documentation](https://www.mkdocs.org/)
|
||||
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
|
||||
- [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/)
|
||||
- [mkdocstrings](https://mkdocstrings.github.io/)
|
||||
- [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/)
|
||||
@@ -0,0 +1,416 @@
|
||||
# Release Process
|
||||
|
||||
This project uses **component-specific versioning**. Each component (MCP Server, Workbench, Macros) has its own version and release cycle, allowing independent updates without affecting other components.
|
||||
|
||||
## Components and Their Release Targets
|
||||
|
||||
| Component | Tag Format | Releases To |
|
||||
| --------- | ---------- | ----------- |
|
||||
| MCP Server | `robust-mcp-server-vX.Y.Z` | PyPI, Docker Hub, GitHub Release |
|
||||
| MCP Bridge Workbench | `robust-mcp-workbench-vX.Y.Z` | GitHub Release (archive) |
|
||||
| Cut Object for Magnets Macro | `macro-cut-object-for-magnets-vX.Y.Z` | GitHub Release (archive) |
|
||||
| Multi Export Macro | `macro-multi-export-vX.Y.Z` | GitHub Release (archive) |
|
||||
|
||||
## Version Format
|
||||
|
||||
All versions follow [Semantic Versioning 2.0](https://semver.org/):
|
||||
|
||||
- `X.Y.Z` - Stable release (published to PyPI for MCP Server)
|
||||
- `X.Y.Z-alpha` or `X.Y.Z-alpha.N` - Alpha pre-release (TestPyPI only)
|
||||
- `X.Y.Z-beta` or `X.Y.Z-beta.N` - Beta pre-release (PyPI)
|
||||
- `X.Y.Z-rc.N` - Release candidate (PyPI)
|
||||
|
||||
## Release Workflow Overview
|
||||
|
||||
Releases follow a **two-step process**:
|
||||
|
||||
1. **Bump**: Update version in all source files locally, then commit
|
||||
2. **Tag**: Create and push the git tag (triggers CI/CD)
|
||||
|
||||
This ensures the version in source files matches the git tag on the same commit.
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 1. just release::bump-<component> X.Y.Z │
|
||||
│ └── Updates version in all relevant files │
|
||||
│ │
|
||||
│ 2. git add -A && git commit -m "chore: bump ... to X.Y.Z" │
|
||||
│ └── Commit the version changes │
|
||||
│ │
|
||||
│ 3. just release::tag-<component> X.Y.Z │
|
||||
│ └── Verifies versions match, then creates & pushes tag │
|
||||
│ │
|
||||
│ 4. GitHub Actions workflow runs automatically │
|
||||
│ └── Verifies versions, builds, and publishes release │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Pre-Release Checklist
|
||||
|
||||
Before creating any release, complete these steps:
|
||||
|
||||
### 1. Check Release Status
|
||||
|
||||
See which components have unreleased changes:
|
||||
|
||||
```bash
|
||||
just release::status
|
||||
```
|
||||
|
||||
This shows the number of commits since the last release for each component.
|
||||
|
||||
### 2. Review Changes
|
||||
|
||||
View the specific changes for the component you're releasing:
|
||||
|
||||
```bash
|
||||
# For MCP Server
|
||||
just release::changes-since mcp-server
|
||||
|
||||
# For Workbench
|
||||
just release::changes-since workbench
|
||||
|
||||
# For Macros
|
||||
just release::changes-since macro-magnets
|
||||
just release::changes-since macro-export
|
||||
```
|
||||
|
||||
### 3. Run All Quality Checks
|
||||
|
||||
Ensure all tests and checks pass:
|
||||
|
||||
```bash
|
||||
just all
|
||||
```
|
||||
|
||||
For a more thorough check including integration tests:
|
||||
|
||||
```bash
|
||||
just all-with-integration
|
||||
```
|
||||
|
||||
### 4. Update CHANGELOG.md
|
||||
|
||||
The changelog uses a multi-component structure. Each release date section contains entries for each component that was released.
|
||||
|
||||
#### Draft Release Notes
|
||||
|
||||
Use the `draft-notes` command to generate a starting point from conventional commits:
|
||||
|
||||
```bash
|
||||
# Generate draft notes for a component
|
||||
just release::draft-notes mcp-server
|
||||
just release::draft-notes workbench
|
||||
just release::draft-notes macro-magnets
|
||||
just release::draft-notes macro-export
|
||||
```
|
||||
|
||||
This categorizes commits by type (feat, fix, refactor, etc.) to help you write the changelog entry.
|
||||
|
||||
#### Changelog Structure
|
||||
|
||||
Add entries under the appropriate component section in `CHANGELOG.md`:
|
||||
|
||||
```markdown
|
||||
## YYYY-MM-DD - Release Title (optional)
|
||||
|
||||
### MCP Server vX.Y.Z
|
||||
|
||||
Brief description of the release.
|
||||
|
||||
#### Added
|
||||
- New feature description
|
||||
|
||||
#### Changed
|
||||
- Changed behavior description
|
||||
|
||||
#### Fixed
|
||||
- Bug fix description
|
||||
|
||||
---
|
||||
|
||||
### MCP Bridge Workbench vX.Y.Z
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
**Important:** The changelog section header format must match exactly for the GitHub Release workflow to extract it:
|
||||
|
||||
- MCP Server: `### MCP Server vX.Y.Z`
|
||||
- Workbench: `### MCP Bridge Workbench vX.Y.Z`
|
||||
- Magnets Macro: `### Cut Object for Magnets Macro vX.Y.Z`
|
||||
- Export Macro: `### Multi Export Macro vX.Y.Z`
|
||||
|
||||
The release workflows automatically extract the changelog section and include it in the GitHub Release body.
|
||||
|
||||
## Releasing Each Component
|
||||
|
||||
### MCP Server Release
|
||||
|
||||
The MCP Server is the main Python package. It uses `setuptools-scm` to derive version from git tags at build time, so there's no version bump step needed.
|
||||
|
||||
```bash
|
||||
# 1. Ensure all changes are committed
|
||||
git status # Should show clean working tree
|
||||
|
||||
# 2. Update CHANGELOG.md and commit
|
||||
git add CHANGELOG.md
|
||||
git commit -m "docs: update changelog for MCP Server v1.0.0"
|
||||
|
||||
# 3. Create and push the release tag
|
||||
just release::tag-mcp-server 1.0.0
|
||||
```
|
||||
|
||||
**What happens automatically:**
|
||||
|
||||
1. GitHub Actions validates the tag format
|
||||
2. Builds Python wheel and source distribution (version from tag)
|
||||
3. Tests installation on Ubuntu and macOS
|
||||
4. Publishes to PyPI (or TestPyPI for alpha versions)
|
||||
5. Builds multi-architecture Docker image (amd64 + arm64)
|
||||
6. Pushes to Docker Hub as `spkane/freecad-robust-mcp:1.0.0`
|
||||
7. Creates GitHub Release with wheel and tar.gz artifacts
|
||||
|
||||
**Pre-release versions:**
|
||||
|
||||
```bash
|
||||
# Alpha (goes to TestPyPI only)
|
||||
just release::tag-mcp-server 1.0.0-alpha.1
|
||||
|
||||
# Beta (goes to PyPI)
|
||||
just release::tag-mcp-server 1.0.0-beta.1
|
||||
|
||||
# Release candidate (goes to PyPI)
|
||||
just release::tag-mcp-server 1.0.0-rc.1
|
||||
```
|
||||
|
||||
### MCP Bridge Workbench Release
|
||||
|
||||
The workbench is a FreeCAD addon that provides the MCP bridge GUI.
|
||||
|
||||
```bash
|
||||
# 1. Bump version in source files
|
||||
just release::bump-workbench 1.0.0
|
||||
|
||||
# 2. Review and commit the changes
|
||||
git diff # Review changes
|
||||
git add -A
|
||||
git commit -m "chore: bump workbench to 1.0.0"
|
||||
|
||||
# 3. Create and push the release tag
|
||||
just release::tag-workbench 1.0.0
|
||||
```
|
||||
|
||||
**Files updated by `bump-workbench`:**
|
||||
|
||||
- `addon/FreecadRobustMCP/freecad_mcp_bridge/__init__.py` (`__version__`)
|
||||
- `package.xml` (workbench section: `<version>` and `<date>`)
|
||||
|
||||
**What happens automatically:**
|
||||
|
||||
1. GitHub Actions validates the tag format
|
||||
2. Verifies version in source files matches tag
|
||||
3. Creates archive (tar.gz and zip)
|
||||
4. Creates GitHub Release with the archives
|
||||
|
||||
### Macro Releases
|
||||
|
||||
Each macro can be released independently.
|
||||
|
||||
**Cut Object for Magnets Macro:**
|
||||
|
||||
```bash
|
||||
# 1. Bump version in source files
|
||||
just release::bump-macro-magnets 1.0.0
|
||||
|
||||
# 2. Review and commit the changes
|
||||
git diff # Review changes
|
||||
git add -A
|
||||
git commit -m "chore: bump Cut Object for Magnets macro to 1.0.0"
|
||||
|
||||
# 3. Create and push the release tag
|
||||
just release::tag-macro-magnets 1.0.0
|
||||
```
|
||||
|
||||
**Multi Export Macro:**
|
||||
|
||||
```bash
|
||||
# 1. Bump version in source files
|
||||
just release::bump-macro-export 1.0.0
|
||||
|
||||
# 2. Review and commit the changes
|
||||
git diff # Review changes
|
||||
git add -A
|
||||
git commit -m "chore: bump Multi Export macro to 1.0.0"
|
||||
|
||||
# 3. Create and push the release tag
|
||||
just release::tag-macro-export 1.0.0
|
||||
```
|
||||
|
||||
**Files updated by macro bump commands:**
|
||||
|
||||
- `macros/<MacroDir>/<Macro>.FCMacro` (`__Version__` and `__Date__`)
|
||||
- `macros/<MacroDir>/README-<Macro>.md` (`**Version:**`)
|
||||
- `macros/<MacroDir>/wiki-source.txt` (`|Version=` and `|Date=`)
|
||||
- `package.xml` (macro section: `<version>` and `<date>`)
|
||||
|
||||
**What happens automatically:**
|
||||
|
||||
1. GitHub Actions validates the tag format
|
||||
2. Verifies version in source files matches tag
|
||||
3. Creates archive (tar.gz and zip)
|
||||
4. Creates GitHub Release with the archives
|
||||
|
||||
## Verifying a Release
|
||||
|
||||
### Check GitHub Actions
|
||||
|
||||
After pushing a tag, monitor the release workflow:
|
||||
|
||||
1. Go to [GitHub Actions](https://github.com/spkane/freecad-robust-mcp-and-more/actions)
|
||||
2. Find the workflow run triggered by your tag
|
||||
3. Verify all steps complete successfully
|
||||
|
||||
### Verify Published Artifacts
|
||||
|
||||
**For MCP Server:**
|
||||
|
||||
```bash
|
||||
# Check PyPI
|
||||
pip index versions freecad-robust-mcp
|
||||
|
||||
# Check Docker Hub
|
||||
docker pull spkane/freecad-robust-mcp:1.0.0
|
||||
```
|
||||
|
||||
**For Workbench/Macros:**
|
||||
|
||||
- Check the GitHub Releases page for the archive downloads
|
||||
- Verify the `package.xml` version was updated
|
||||
|
||||
## Managing Release Tags
|
||||
|
||||
### List All Tags
|
||||
|
||||
```bash
|
||||
# All tags grouped by component
|
||||
just release::list-tags
|
||||
|
||||
# Latest version of each component
|
||||
just release::latest-versions
|
||||
```
|
||||
|
||||
### Delete a Tag (If Needed)
|
||||
|
||||
If a release has issues and needs to be removed:
|
||||
|
||||
```bash
|
||||
just release::delete-tag robust-mcp-server-v1.0.0
|
||||
```
|
||||
|
||||
!!! warning "Deleting Published Releases"
|
||||
Deleting a tag does not unpublish from PyPI or Docker Hub. Contact the respective registries to remove published artifacts if necessary.
|
||||
|
||||
### Preview a Release (Dry Run)
|
||||
|
||||
To see what a release tag would look like without creating it:
|
||||
|
||||
```bash
|
||||
just release::dry-run-tag mcp-server 1.0.0
|
||||
just release::dry-run-tag workbench 1.0.0
|
||||
just release::dry-run-tag macro-magnets 1.0.0
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Release Workflow Failed
|
||||
|
||||
1. Check the GitHub Actions logs for the specific error
|
||||
2. Common issues:
|
||||
- Invalid version format (must be semver)
|
||||
- Version mismatch between source files and tag
|
||||
- Missing secrets (PyPI token, Docker credentials)
|
||||
- Tests failing during the release build
|
||||
|
||||
### Version Mismatch Error
|
||||
|
||||
If the workflow fails with "Version mismatch":
|
||||
|
||||
```bash
|
||||
# You forgot to bump the version before tagging
|
||||
# Delete the tag
|
||||
just release::delete-tag <full-tag-name>
|
||||
|
||||
# Bump the version
|
||||
just release::bump-<component> X.Y.Z
|
||||
|
||||
# Commit the changes
|
||||
git add -A && git commit -m "chore: bump <component> to X.Y.Z"
|
||||
|
||||
# Create the tag again
|
||||
just release::tag-<component> X.Y.Z
|
||||
```
|
||||
|
||||
### Tag Already Exists
|
||||
|
||||
If you try to create a tag that already exists:
|
||||
|
||||
```bash
|
||||
# Delete the existing tag first
|
||||
just release::delete-tag robust-mcp-server-v1.0.0
|
||||
|
||||
# Then create the new tag
|
||||
just release::tag-mcp-server 1.0.0
|
||||
```
|
||||
|
||||
### Wrong Version Released
|
||||
|
||||
1. Delete the tag: `just release::delete-tag <tag>`
|
||||
2. Create a new release with the correct version
|
||||
3. For PyPI: you cannot re-upload the same version; increment the patch version instead
|
||||
|
||||
## Release Cadence Recommendations
|
||||
|
||||
- **MCP Server**: Release when there are significant new features or important bug fixes
|
||||
- **Workbench**: Release in sync with server changes that affect the bridge protocol
|
||||
- **Macros**: Release independently when macro functionality changes
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```bash
|
||||
# Check what needs releasing
|
||||
just release::status
|
||||
|
||||
# View changes for a component
|
||||
just release::changes-since mcp-server
|
||||
|
||||
# Draft changelog entries from commits
|
||||
just release::draft-notes mcp-server
|
||||
just release::draft-notes workbench
|
||||
just release::draft-notes macro-magnets
|
||||
just release::draft-notes macro-export
|
||||
|
||||
# Bump versions (for workbench and macros)
|
||||
just release::bump-workbench 1.0.0
|
||||
just release::bump-macro-magnets 1.0.0
|
||||
just release::bump-macro-export 1.0.0
|
||||
|
||||
# Commit version changes
|
||||
git add -A && git commit -m "chore: bump <component> to X.Y.Z"
|
||||
|
||||
# Create releases (verifies versions, creates and pushes tag)
|
||||
just release::tag-mcp-server 1.0.0
|
||||
just release::tag-workbench 1.0.0
|
||||
just release::tag-macro-magnets 1.0.0
|
||||
just release::tag-macro-export 1.0.0
|
||||
|
||||
# List existing releases
|
||||
just release::list-tags
|
||||
just release::latest-versions
|
||||
|
||||
# Extract changelog for a version (used by CI)
|
||||
just release::extract-changelog mcp-server 1.0.0
|
||||
|
||||
# Delete a tag if needed
|
||||
just release::delete-tag <full-tag-name>
|
||||
```
|
||||
@@ -0,0 +1,28 @@
|
||||
# Variables for mkdocs-macros-plugin
|
||||
# Use in docs with {{ variable_name }}
|
||||
|
||||
# Project info
|
||||
project_name: FreeCAD MCP Server
|
||||
package_name: freecad-robust-mcp
|
||||
docker_image: spkane/freecad-robust-mcp
|
||||
|
||||
# URLs
|
||||
repo_url: https://github.com/spkane/freecad-robust-mcp-and-more
|
||||
pypi_url: https://pypi.org/project/freecad-robust-mcp/
|
||||
docker_url: https://hub.docker.com/r/spkane/freecad-robust-mcp
|
||||
|
||||
# Ports
|
||||
xmlrpc_port: 9875
|
||||
socket_port: 9876
|
||||
|
||||
# Paths (platform-specific)
|
||||
paths:
|
||||
macos:
|
||||
macro: ~/Library/Application Support/FreeCAD/Macro/
|
||||
mod: ~/Library/Application Support/FreeCAD/Mod/
|
||||
linux:
|
||||
macro: ~/.local/share/FreeCAD/Macro/
|
||||
mod: ~/.local/share/FreeCAD/Mod/
|
||||
windows:
|
||||
macro: "%APPDATA%/FreeCAD/Macro/"
|
||||
mod: "%APPDATA%/FreeCAD/Mod/"
|
||||
Reference in New Issue
Block a user