Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
134 lines (91 loc) · 4.5 KB

CONTRIBUTING.md

File metadata and controls

134 lines (91 loc) · 4.5 KB
Raw

Contributing

Thank you for your interest in contributing! This document covers everything you need to get started.

Table of Contents

Getting Started

Prerequisites

Requirement Version Notes
Python 3.10+ 3.14 recommended (matches the workspace)
pip recent Or uv if you prefer
Git 2.x+ For cloning and version control

Development Setup

  1. Fork the repository on GitHub.

  2. Clone your fork locally:

    git clone https://github.com/<your-username>/toolsmith.git
cd toolsmith

  3. Install in editable mode with dev dependencies:

    pip install -e ".[dev]"

  4. Verify your environment:

    python -m pytest -q

Making Changes

Branching Strategy

All development is based on the master branch.

  • Create a feature branch from master:

    git checkout -b feature/your-feature master

  • Use descriptive branch names: feature/add-xyz, fix/tally-skip-count, refactor/simplify-module-resolution.

Code Style

  • Follow PEP 8.
  • Add type hints to public functions; target the language level in pyproject.toml (requires-python).
  • Use Google-style docstrings (Args: / Returns:) - match the existing modules.
  • Keep each tool's real logic in its library module (toolsmith.gradle, toolsmith.tally, ...); toolsmith.server stays a thin typed veneer that forwards to it.
  • A new MCP tool should also be usable from the command line (a main() / python -m entry), so its logic is testable without the MCP layer.
  • Name a new tool, subcommand, or skill after who can use it rather than after what it parses: gradle_* / toolsmith gradle <cmd> for anything that needs a Gradle build, java_* / toolsmith java <cmd> for anything that acts on Java source. State that requirement in the docstring or the skill description as well - that text is what gets matched when the tool is chosen.

Commit Messages

Write commit messages in imperative mood (e.g., "Add compile-only default to gradle_verify" not "Added ...").

  • Keep the subject line under 72 characters.
  • Use the body to explain why, not just what.
  • Reference issue numbers where applicable (e.g., Fixes #12).

Running Tests

# Run the full suite
python -m pytest -q

# Run one test file
python -m pytest tests/test_imports.py -q

# Run one test
python -m pytest tests/test_imports.py::test_idempotent -q

New behavior needs a test. The reorderer in particular must stay idempotent and byte-faithful to the IntelliJ Default layout - add a fixture rather than loosen an assertion.

Submitting a Pull Request

  1. Push your branch to your fork:

    git push origin feature/your-feature

  2. Open a Pull Request against the master branch of the upstream repository.

  3. In the PR description:

    • Summarize the changes and motivation.
    • Reference any related issues.
    • Note any breaking changes to a tool's return shape.

  4. Respond to feedback - maintainers may request changes before merging.

Reporting Issues

  • Use GitHub Issues to report bugs or request features.
  • For bugs, include: the tool and arguments, expected vs. actual result, and your Python / FastMCP versions.
  • For a new tool request, describe the repeated operation it would replace and the ideal return shape.

Project Architecture

This project is part of the Simplified-Dev ecosystem. Unlike its sibling Java libraries, it is a local, executable MCP server (not a JitPack-published artifact), so it uses a Python src/ layout:

src/toolsmith/    - server + one module per tool
tests/            - pytest suite
pyproject.toml    - packaging + the `toolsmith` entry point

Legal

By contributing, you agree that your contributions will be licensed under the Apache License 2.0, the same license that covers this project.