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