Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions .github/workflows/deploy-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@ on:
pull_request:
branches:
- main
schedule:
# Weekly: check every link in the docs (the link-check job only).
- cron: '0 6 * * 1'
workflow_dispatch:

permissions:
contents: read
Expand All @@ -23,6 +27,7 @@ concurrency:

jobs:
test:
if: github.event_name != 'schedule'
runs-on: ubuntu-latest
steps:
- name: Checkout
Expand Down Expand Up @@ -108,3 +113,40 @@ jobs:
id: deployment
uses: actions/deploy-pages@v5

# Every link in the README, the docs and llms.txt, after each deploy and
# weekly (spec docs/link-check). A failure flags a link to fix; it does not
# undo the deploy.
link-check:
if: >-
always() && (github.event_name == 'schedule' ||
github.event_name == 'workflow_dispatch' ||
needs.deploy.result == 'success')
runs-on: ubuntu-latest
needs: deploy
permissions:
contents: read
steps:
- name: Checkout
uses: actions/checkout@v7

- name: Setup Python
uses: actions/setup-python@v7
with:
python-version: '3.13'

- name: Install package
run: |
python -m pip install --upgrade pip
pip install -e . "pyyaml>=6.0"

- name: Check every link
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: python -m solidworks_mcp.doc_links check-external

- name: Upload the link report
if: always()
uses: actions/upload-artifact@v7
with:
name: link-report
path: tests/.generated/link-report.md
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- **Our own `llms.txt`**, served at the docs site's root and built from the
docs: each entry's title and summary are copied word for word from its
page, and a test fails when the file and the pages disagree, when it
links outside this project, or when it holds HTML or hidden characters.
Nothing in it is written by hand. Ten pages got a real opening paragraph
to serve as their summary.
- **Every link in the docs is checked.** Links within the project (pages,
files, anchors, repository files) on every test run; every link to
another site after each docs deploy and weekly, failing a dead link or a
redirect to a different site, with a report of every URL
(`python -m solidworks_mcp.doc_links check-external`). The first run
fixed one moved link (the Anthropic console).
- **`create_sketch` takes `face_point`** (#206): a point in mm on a flat
face of the body, in place of `plane`. The sketch opens on that face and
moves with it when the model changes, so a pocket cut from it follows a
Expand Down
10 changes: 10 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,16 @@ When needed (credentials/SolidWorks environment available):
- Update docs for user-visible behavior changes.
- Keep architecture docs implementation-accurate.
- Put roadmap/aspirational content in `docs/planning/`, not runtime architecture pages.
- Every page in the nav opens with a `# ` title and a plain paragraph that
says what the page is. `docs/llms.txt` is built from those: each entry's
title and summary are copied word for word from its page, so never edit
the file by hand. After changing a page's title or opening, or the nav,
run `.\dev-commands.ps1 dev-llms` (or
`python -m solidworks_mcp.doc_links build`) and commit the result; a test
fails until you do. The same test checks every relative link and anchor.
- `.\dev-commands.ps1 dev-links` visits every external link and writes
`tests/.generated/link-report.md`. CI runs it after each docs deploy and
weekly.

Current docs structure:

Expand Down
9 changes: 8 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# SolidWorks MCP Server - Simplified Makefile

.PHONY: help install test test-context-budget test-full test-clean docs build run clean lint format
.PHONY: help install test test-context-budget llms links test-full test-clean docs build run clean lint format

# Default target
.DEFAULT_GOAL := help
Expand Down Expand Up @@ -57,6 +57,13 @@ test: ## Run test suite with coverage
--durations=10 \
-v

llms: ## Rebuild docs/llms.txt, then check it and every project link (offline)
python -m solidworks_mcp.doc_links build
python -m solidworks_mcp.doc_links check

links: ## Visit every external link in the docs (online)
python -m solidworks_mcp.doc_links check-external

test-context-budget: ## Run smoke response-size guard test (CI-friendly)
@echo "$(BLUE)Running smoke response-size guard test...$(NC)"
@if [ -z "$(CONDA_CMD)" ]; then \
Expand Down
15 changes: 14 additions & 1 deletion dev-commands.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,8 @@ function dev-help {
Write-Host " dev-ui Start the FastAPI UI backend"
Write-Host " dev-docs-build Build documentation once (mkdocs build --clean)"
Write-Host " dev-docs-strict Build documentation in strict mode"
Write-Host " dev-llms Rebuild docs/llms.txt from the docs, then check it and every project link"
Write-Host " dev-links Visit every external link in the docs (online; writes tests/.generated/link-report.md)"
Write-Host " dev-docs-audit Run verbose + strict docs audit and write summary"
Write-Host " dev-docs Build and serve documentation (http://localhost:8000)"
Write-Host " dev-docs-discovery Index SolidWorks COM/VBA documentation (Windows + SW running)"
Expand Down Expand Up @@ -385,7 +387,8 @@ function dev-ui {
# FastAPI backend (solidworks_mcp.ui.server:app) - still real,
# independent infrastructure other things build on.
Write-Host "Starting UI backend (FastAPI)..." -ForegroundColor Cyan
& (Join-Path $PSScriptRoot "scriptsun-ui.ps1")
& (Join-Path $PSScriptRoot "scripts
un-ui.ps1")
}

function dev-docs {
Expand All @@ -403,6 +406,16 @@ function dev-docs-build {
else { Write-Host "Docs build failed." -ForegroundColor Red }
}

function dev-llms {
$py = Get-VenvPython
& $py -m solidworks_mcp.doc_links build
if ($LASTEXITCODE -eq 0) { & $py -m solidworks_mcp.doc_links check }
}

function dev-links {
& (Get-VenvPython) -m solidworks_mcp.doc_links check-external
}

function dev-docs-strict {
Write-Host "Building docs in strict mode..." -ForegroundColor Cyan
& (Join-Path $PSScriptRoot "scripts\docs\build-docs.ps1") -Strict
Expand Down
3 changes: 2 additions & 1 deletion docs/agents/agent-skill.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Agent Skill

The server ships a skill, `solidworks-mcp`, for agents that use its tools.
The server ships a skill, `solidworks-mcp`, that teaches agents how to use its tools together: the order to build in, units, choosing geometry, checking results and recovering from errors.

Each tool's own description says what that tool does
([Tool Description Standard](tool-description-standard.md)); the skill
covers what spans tools:
Expand Down
2 changes: 1 addition & 1 deletion docs/agents/agents-and-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -245,7 +245,7 @@ You should see structured JSON output like this:
=== "Anthropic API (BYOK)"

Requires an Anthropic account with active billing credits (separate from Claude Code subscription).
Get your key at: https://console.anthropic.com/settings/keys
Get your key at: https://platform.claude.com/settings/keys

```powershell
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-...", "User")
Expand Down
6 changes: 4 additions & 2 deletions docs/agents/com-api-pitfalls.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
# COM API Pitfalls for LLM Agents

This page documents hard-won lessons from debugging the SolidWorks COM bridge.
This page documents hard-won lessons from debugging the SolidWorks COM bridge,
for anyone changing the server's COM code. Every entry below caused a real
runtime failure that required hours to diagnose.

If you are an AI coding assistant (Claude, GPT-4, Gemini, Copilot, etc.) working on this codebase,
**read this page before touching any COM-related code**.
Every entry below caused a real runtime failure that required hours to diagnose.

!!! tip "For LLM agents"
The patterns here are not obvious from the SolidWorks API docs alone.
Expand Down
4 changes: 3 additions & 1 deletion docs/agents/sample-models-guide.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# Sample Models Guide

This guide describes the SolidWorks 2026 learn samples shipped with SolidWorks and explains which MCP tools and prompting strategies best recreate each part from scratch. Reference files live at:
This guide describes the SolidWorks 2026 learn samples shipped with SolidWorks and explains which MCP tools and prompting strategies best recreate each part from scratch.

Reference files live at:

```
C:\Users\Public\Documents\SOLIDWORKS\SOLIDWORKS 2026\samples\learn\
Expand Down
4 changes: 3 additions & 1 deletion docs/agents/worked-examples.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# Worked Examples: SolidWorks MCP + Agent Workflow

This page shows three practical reconstruction examples using the same inspect -> classify -> delegate loop:
This page shows three practical reconstruction examples, each using the same inspect, classify and delegate loop.

The loop:

1. Read the original model state.
2. Classify the feature family before writing geometry.
Expand Down
4 changes: 3 additions & 1 deletion docs/getting-started/local-llm.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# Local LLM with Ollama (Gemma 4)

The SolidWorks MCP UI can route all LLM calls to a local Ollama instance instead of GitHub Models or OpenAI. This works offline, keeps design data private, and uses Ollama's OpenAI-compatible endpoint at `http://127.0.0.1:11434/v1`.
The SolidWorks MCP UI can route all LLM calls to a local Ollama instance instead of GitHub Models or OpenAI. This works offline and keeps design data private.

It uses Ollama's OpenAI-compatible endpoint at `http://127.0.0.1:11434/v1`.

The official Ollama Gemma 4 library page is here: <https://ollama.com/library/gemma4>

Expand Down
4 changes: 3 additions & 1 deletion docs/getting-started/solidworks-as-code.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# SolidWorks as Code (SoC)

SolidWorks as Code lets you record an interactive MCP session and export it as a clean, runnable Python script. The round-trip is:
SolidWorks as Code lets you record an interactive MCP session and export it as a clean, runnable Python script.

The round-trip is:

```text
MCP tool calls → SQLite log → soc_exporter → script.py
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# U-Joint Rebuild Prompts

**Note:** These prompts are for when you have access to the reference SolidWorks sample models and want to match them exactly. For learning and from-scratch builds, start with the [U-Joint Assembly Tutorial](../tutorials/u-joint-assembly-build.md) instead.
These prompts rebuild the U-Joint from SolidWorks' sample models, for when you have the reference models and want to match them exactly. For learning and from-scratch builds, start with the [U-Joint Assembly Tutorial](../tutorials/u-joint-assembly-build.md) instead.

Reference models location:

Expand Down
2 changes: 2 additions & 0 deletions docs/getting-started/vscode-mcp-setup.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# VS Code MCP Setup

Connect VS Code's MCP client to the SolidWorks MCP server, with the setup command or by editing `mcp.json` by hand.

## Connect with setup

With [uv](https://docs.astral.sh/uv/) installed:
Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
[![Tests](https://github.com/andrewbartels1/SolidworksMCP-python/actions/workflows/ci.yml/badge.svg)](https://github.com/andrewbartels1/SolidworksMCP-python/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/andrewbartels1/SolidworksMCP-python/branch/main/graph/badge.svg)](https://codecov.io/gh/andrewbartels1/SolidworksMCP-python)

**AI-Assisted SolidWorks Automation with MCP**
An MCP server that lets AI agents drive SolidWorks: describe a part, and the agent builds it with the server's 123 tools and checks what SolidWorks reports back.

🚀 **123 Tools** | 🤖 **Agent-Ready Workflows** | ⚡ **Automatic COM/VBA Routing** | 🧪 **Schema-Validated Prompt Runs**

Expand Down
Loading
Loading