Contributing

# Help improve cxxmcp.

The project follows an SDK-first architecture. Protocol, transport, handler, peer, service, client, and server APIs are the stable public surface.

## Development Flow

Use topic branches from `master`. Keep changes scoped to one behavior, capability family, or documentation concern.

### Before Opening a PR

    # Format check
    pwsh -NoProfile -File scripts\format.ps1 -Check

    # Build and test
    cmake --build build-package-prep --target mcp_protocol_tests mcp_client_server_tests mcp_sdk_tests --parallel
    ctest --test-dir build-package-prep -R "^(protocol|client_server|sdk|package_smoke)$" --output-on-failure --timeout 600

### Transport Changes

Also run the relevant transport tests:

    ctest --test-dir build -R "transport" --output-on-failure

### Package Changes

Run `package_smoke` for both bundled and `CXXMCP_USE_SYSTEM_DEPS=ON` builds.

## Public API Rules

Public headers live under `sdk/**/include/cxxmcp`. New public surface must state one of:

- core — stable SDK contract for normal use
- optional — stable API for a negotiated or opt-in capability
- experimental — available but not yet a stable compatibility promise

### Breaking Changes

Breaking public API changes require a design note or RFC-style issue before implementation. Public renames must:

- Add the new spelling first
- Keep the old spelling as an alias or forwarding wrapper
- Mark the old spelling with `CXXMCP_DEPRECATED("message")`
- Document the migration

## Protocol Compatibility

cxxmcp follows published MCP protocol snapshots and cross-checks behavior against pinned reference SDKs. Do not add custom MCP dialects or alternate wire formats. Unknown or future protocol fields should be preserved through typed models when possible and exposed through raw JSON-RPC escape hatches when they are not modeled yet.

## Tests and Evidence

Every new public behavior should have at least one focused test:

- Protocol tests — model/serialization behavior
- Client/server tests — SDK request handling
- Transport tests — I/O behavior
- Package smoke tests — install/export concerns

Release-candidate evidence is governed by `docs/release_gates.md` and `docs/release_candidate_checklist.md`.

## Code Style

- C++17 public API — no C++20 features in public headers
- Follow the existing naming conventions (`snake_case` for functions, `PascalCase` for types)
- Use `mcp::` namespace; sub-namespaces for protocol, transport, etc.
- Keep headers self-contained — include what you use

## Next Steps

- Issues — find something to work on
- Pull Requests — review open PRs
- Stability — understand the compatibility contract