Thanks for contributing.
This repository is Python-first and centered on SolidWorks MCP tooling plus optional agent/prompt-testing workflows.
- Fork the repo and create a branch from
main. - Make focused changes with tests/docs updates where relevant.
- Run lint/tests/docs build locally.
- Run the local CI check (see below) and confirm it passes before opening a PR.
- Open a pull request with a concise summary.
git clone https://github.com/<your-username>/SolidworksMCP-python.git
cd SolidworksMCP-python
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip setuptools wheel
.\.venv\Scripts\python.exe -m pip install -e ".[dev,test,docs]"Before opening a pull request, run the local CI script to reproduce the same test environment used in GitHub Actions:
.\scripts\run-ci-local.ps1This builds a Docker image from .ci/Dockerfile and runs make test inside it — the exact command GitHub CI executes. A clean pass here means your PR will not fail CI on test issues.
If Docker is not available, run the full local test suite instead and confirm it passes:
.\dev-commands.ps1 dev-testThe first invocation builds the Docker image (a few minutes). Subsequent runs reuse the cached image unless you pass -NoBuild:
# Force image rebuild
.\scripts\run-ci-local.ps1
# Skip rebuild (faster after first run)
.\scripts\run-ci-local.ps1 -NoBuildUse the helper script:
.\dev-commands.ps1Typical workflow:
.\dev-commands.ps1 dev-test(standard suite).\dev-commands.ps1 dev-lint.\dev-commands.ps1 dev-format.\dev-commands.ps1 dev-make-docs-build
When needed (credentials/SolidWorks environment available):
.\dev-commands.ps1 dev-test-full
- Add or update tests for behavior changes.
- Keep new behavior covered in the appropriate test module under
tests/. - Prefer deterministic tests for CI; keep live/smoke behavior clearly marked.
- Name it with a verb from the verb list (
create_,add_,get_,list_,set_, ...). - Write its docstring to the tool description standard: what it does, when to use it, what it needs, what it changes (or "Read-only."), and what it returns.
- Describe
input_dataspecifically inArgs:, and give every input field aField(description=...). - Add its title and behaviour hints to
src/solidworks_mcp/tools/tool_hints.py; registration fails without them. tests/integration/test_tool_descriptions.pychecks the parts that can be checked.
- 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.txtis 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(orpython -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-linksvisits every external link and writestests/.generated/link-report.md. CI runs it after each docs deploy and weekly.
Current docs structure:
docs/user-guide/for MCP runtime docsdocs/agents/for agent/skills orchestration and prompt workflowsdocs/planning/for future work and roadmap
- Run
.\scripts\run-ci-local.ps1and confirm it passes before opening a PR (see above). - Use concise commit messages that describe intent.
- Keep unrelated generated/local artifacts out of commits.
- Include validation notes (tests/docs build) in the PR description.
- Link related issues when applicable.
Open issues at:
Helpful bug reports include:
- environment details (OS, Python, SolidWorks version)
- reproduction steps
- expected vs actual behavior
- logs/error output
By contributing, you agree your contributions are licensed under the MIT License.