Skip to content

Latest commit

 

History

History
132 lines (91 loc) · 4.51 KB

CONTRIBUTING.md

File metadata and controls

132 lines (91 loc) · 4.51 KB

Contributing to SolidWorks MCP Server

Thanks for contributing.

This repository is Python-first and centered on SolidWorks MCP tooling plus optional agent/prompt-testing workflows.

Development Process

  1. Fork the repo and create a branch from main.
  2. Make focused changes with tests/docs updates where relevant.
  3. Run lint/tests/docs build locally.
  4. Run the local CI check (see below) and confirm it passes before opening a PR.
  5. Open a pull request with a concise summary.

Local Setup

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]"

Local CI Check (required before PRs)

Before opening a pull request, run the local CI script to reproduce the same test environment used in GitHub Actions:

.\scripts\run-ci-local.ps1

This 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-test

First run

The 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 -NoBuild

Recommended Commands

Use the helper script:

.\dev-commands.ps1

Typical 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

Testing Expectations

  • 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.

Adding or Changing a Tool

  • 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_data specifically in Args:, and give every input field a Field(description=...).
  • Add its title and behaviour hints to src/solidworks_mcp/tools/tool_hints.py; registration fails without them.
  • tests/integration/test_tool_descriptions.py checks the parts that can be checked.

Documentation Expectations

  • 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:

  • docs/user-guide/ for MCP runtime docs
  • docs/agents/ for agent/skills orchestration and prompt workflows
  • docs/planning/ for future work and roadmap

Pull Request Guidelines

  • Run .\scripts\run-ci-local.ps1 and 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.

Bug Reports

Open issues at:

Helpful bug reports include:

  • environment details (OS, Python, SolidWorks version)
  • reproduction steps
  • expected vs actual behavior
  • logs/error output

License

By contributing, you agree your contributions are licensed under the MIT License.