diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 3907b09..80fa311 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,15 +1,13 @@ -## Summary +## What does this PR do? - + -## Changes +## How to test -- + -## Test Plan +## Checklist -- [ ] `pytest packages/mcp-forge-core/tests/` passes -- [ ] `pytest packages/mcp-forge-aws/tests/` passes -- [ ] `pytest packages/mcp-forge-cli/tests/` passes +- [ ] Tests added or updated - [ ] `ruff check packages/` passes -- [ ] No business-specific references in source code +- [ ] `pytest` passes for affected package(s) diff --git a/.github/workflows/release-aws.yml b/.github/workflows/release-aws.yml new file mode 100644 index 0000000..9138205 --- /dev/null +++ b/.github/workflows/release-aws.yml @@ -0,0 +1,21 @@ +name: Release AWS + +on: + push: + tags: ["v*"] + +jobs: + publish: + runs-on: ubuntu-latest + permissions: + id-token: write + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - run: pip install build + - run: python -m build packages/mcp-forge-aws + - uses: pypa/gh-action-pypi-publish@release/v1 + with: + packages-dir: packages/mcp-forge-aws/dist/ diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml new file mode 100644 index 0000000..e11b0f5 --- /dev/null +++ b/.github/workflows/release-cli.yml @@ -0,0 +1,21 @@ +name: Release CLI + +on: + push: + tags: ["v*"] + +jobs: + publish: + runs-on: ubuntu-latest + permissions: + id-token: write + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - run: pip install build + - run: python -m build packages/mcp-forge-cli + - uses: pypa/gh-action-pypi-publish@release/v1 + with: + packages-dir: packages/mcp-forge-cli/dist/ diff --git a/.github/workflows/release-core.yml b/.github/workflows/release-core.yml new file mode 100644 index 0000000..868c0a6 --- /dev/null +++ b/.github/workflows/release-core.yml @@ -0,0 +1,21 @@ +name: Release Core + +on: + push: + tags: ["v*"] + +jobs: + publish: + runs-on: ubuntu-latest + permissions: + id-token: write + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - run: pip install build + - run: python -m build packages/mcp-forge-core + - uses: pypa/gh-action-pypi-publish@release/v1 + with: + packages-dir: packages/mcp-forge-core/dist/ diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml deleted file mode 100644 index 3a605fc..0000000 --- a/.github/workflows/release.yml +++ /dev/null @@ -1,30 +0,0 @@ -name: Release - -on: - push: - tags: ["v*"] - -jobs: - publish: - runs-on: ubuntu-latest - strategy: - matrix: - package: [mcp-forge-core, mcp-forge-aws, mcp-forge-cli] - permissions: - id-token: write # Trusted publishing - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - - name: Install build tools - run: pip install build - - - name: Build package - run: python -m build packages/${{ matrix.package }} - - - name: Publish to PyPI - uses: pypa/gh-action-pypi-publish@release/v1 - with: - packages-dir: packages/${{ matrix.package }}/dist/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8877529..f19fa43 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,32 +1,89 @@ # Contributing to mcp-forge -## Quick Start +We'd love your help making mcp-forge better. Whether it's a bug fix, new provider, or documentation improvement — all contributions are welcome. + +## Getting Started ```bash -git clone https://github.com/CoreNovus/mcp-forge.git +# 1. Fork this repo on GitHub, then: +git clone git@github.com:/mcp-forge.git cd mcp-forge + +# 2. Install everything pip install -e packages/mcp-forge-core[dev] pip install -e packages/mcp-forge-aws[dev] pip install -e packages/mcp-forge-cli[dev] + +# 3. Make sure it works +ruff check packages/ +pytest packages/mcp-forge-core/tests/ +pytest packages/mcp-forge-aws/tests/ +pytest packages/mcp-forge-cli/tests/ +``` + +That's it. You're ready to contribute. + +## How to Contribute + +### 1. Pick something to work on + +- Browse [open issues](https://github.com/CoreNovus/mcp-forge/issues) +- Look for `good first issue` labels if this is your first contribution +- Or just fix something that bothers you + +### 2. Create a branch and make your changes + +```bash +git checkout -b feat/your-idea # feature +git checkout -b fix/what-you-fixed # bug fix +git checkout -b docs/what-you-added # docs +``` + +### 3. Write tests + +Every change needs tests. We aim for real boundary testing — not just happy paths: + +```python +# Good: tests the edge case +async def test_cache_empty_string_key(self, cache): + await cache.put("", {"v": 1}) + assert await cache.get("") == {"v": 1} + +# Good: tests error behavior +async def test_unknown_type_raises(self): + with pytest.raises(ValueError, match="Unknown"): + await provider.extract(b"img", "nonexistent") +``` + +### 4. Run checks, then open a PR + +```bash +ruff check packages/ # lint +pytest packages/mcp-forge-core/tests/ # core tests +pytest packages/mcp-forge-aws/tests/ # aws tests +pytest packages/mcp-forge-cli/tests/ # cli tests ``` -## Workflow +Push your branch, open a PR, and fill in the template. CI runs automatically — once it's green and reviewed, we'll merge it. + +## What Goes Where + +| Package | What belongs here | +|---------|------------------| +| **mcp-forge-core** | Provider ABCs, config, server factory, ToolContext, decorators, resilience patterns. Pure Python, zero cloud dependencies. | +| **mcp-forge-aws** | AWS-specific implementations. Depends on boto3. | +| **mcp-forge-cli** | Scaffold CLI and Jinja2 templates. | + +## Things to Keep in Mind + +**Framework, not application.** mcp-forge is used by many different MCP servers. Don't add code that assumes a specific use case (document processing, image analysis, etc.). -1. Fork the repo -2. Create a branch from `main` -3. Make changes, add tests -4. Run `ruff check packages/` and `pytest` -5. Open a PR — CI must pass and 1 review is required +**Provider ABCs are domain-agnostic.** Infrastructure providers (Cache, Session, Telemetry) are top-level exports. Capability providers (Vision, Transcribe) exist for swappability but are direct-import only — the framework doesn't assume everyone needs them. -## Rules +**Tests matter.** We test boundaries: empty input, unicode, TTL expiry, error propagation, concurrent access. If you find an untested edge case, that's a great first PR. -- Every PR needs tests -- `ruff check` must pass -- No business-specific code — this is a generic framework -- Keep provider ABCs domain-agnostic +**Keep it simple.** If your change adds complexity, make sure it solves a real problem. Three lines of clear code beats a clever abstraction. -## Package Structure +## Questions? -- `mcp-forge-core` — infrastructure providers, patterns, server factory -- `mcp-forge-aws` — AWS implementations (Bedrock, DynamoDB, CloudWatch) -- `mcp-forge-cli` — scaffold CLI tool +Open an [issue](https://github.com/CoreNovus/mcp-forge/issues). There are no dumb questions.