Contributing
mcp.zig is maintained by volunteers. Bug reports, documentation fixes, and pull requests are all useful.
Ways to Contribute
- Report bugs — open an issue on the issue tracker
- Suggest features — open an issue or a discussion
- Improve documentation — the guide lives in
docs/, the API reference in doc comments undersrc/ - Submit pull requests — fixes, tests, and features
For defects in the library itself, mcp.reportError prints the issue URL (mcp.ISSUES_URL, defined in src/report.zig) along with the error message, so a failing program tells you where to report it. Security vulnerabilities are handled separately; see SECURITY.md.
Getting Started
1. Fork and Clone
git clone https://github.com/YOUR_USERNAME/mcp.zig.git
cd mcp.zig2. Build
zig buildZig 0.17.0 or later is required. The version this tree is developed against is pinned in CI (.github/workflows/ci.yml).
3. Verify
Run the same checks CI runs before you open a pull request:
# Unit tests for every module
zig build test
zig build test --summary all
# Compile the library and all fifteen examples without running them
zig build run-all-examples
# Formatting; CI fails when this is not clean
zig fmt --check src examples build.zig
zig fmt src examples build.zig # to apply formatting
# Cross-target validation: compiles the tests and examples for a target that
# cannot run on the host
zig build test-compile -Dtarget=x86_64-linux
zig build test-compile -Dtarget=x86_64-windows
zig build test-compile -Dtarget=x86_64-macosCI runs zig build test, zig build run-all-examples, and zig fmt --check src examples build.zig on Linux, Windows, and macOS. A second job compiles the library and the tests, without executing them, for seven targets (x86-linux, x86_64-linux, aarch64-linux, x86-windows, x86_64-windows, x86_64-macos, aarch64-macos).
4. Make Your Changes
Work on a branch:
git checkout -b feature/my-new-featureProtocol Changes
The library implements exactly one protocol revision: 2026-07-28. Any change to method names, _meta keys, resultType values, HTTP headers, or error codes must be made in src/protocol/ first, because the client and server both read those constants. A change that alters the wire format needs a test in the relevant module and an update to docs/guide/protocol-version.md.
Methods removed in this revision — initialize, notifications/initialized, ping, logging/setLevel, notifications/roots/list_changed, resources/subscribe, resources/unsubscribe, tasks/result, and tasks/list — must not be reintroduced. There is no legacy fallback and no session id.
The tasks extension (io.modelcontextprotocol/tasks) is implemented on both sides: opt-in _meta key, resultType: "task", relatedTask metadata, notifications/tasks, and tasks/get, tasks/update, tasks/cancel. Keep it that way. A task-augmented tools/call is driven by _meta["io.modelcontextprotocol/task"], never by a task request parameter, except for the single retained compatibility branch for 2025-11-25 clients in Server.handleToolsCall.
Code Guidelines
Style
- Follow the Zig language reference
- Run
zig fmt src examples build.zigbefore committing; CI enforces it - Use descriptive names for types, functions, and struct fields
- Document every public declaration with a
///comment, including its parameters, return value, and errors - Keep handler bodies small; move logic into named helpers
Documentation
/// Brief description of the function.
///
/// More detailed description if needed.
///
/// ## Parameters
/// - `param1`: Description of param1
/// - `param2`: Description of param2
///
/// ## Returns
/// Description of the return value.
///
/// ## Errors
/// - `error.SomeError`: When this error occurs
pub fn myFunction(param1: Type1, param2: Type2) !ReturnType {
// ...
}Doc comments are the source of the API reference: zig build docs renders them to zig-out/docs/.
Testing
- Add a test for every new behaviour, in the module that owns it
- Use
std.testing.allocatorso leaks fail the test - Cover error paths, not only the happy path
test "my feature works" {
const allocator = std.testing.allocator;
// Test implementation
try std.testing.expect(result == expected);
}Examples are compiled by zig build run-all-examples, so a broken example fails CI even when the unit tests pass.
Pull Request Process
- Update documentation if the change is observable
- Add tests for new behaviour
- Run the verification commands above
- Create the pull request against
main - Describe what changed and why in the pull request body
PR Title Format
type(scope): description
Examples:
feat(server): add resource templates support
fix(jsonrpc): handle null request IDs
docs(guide): add advanced usage section
test(client): add connection testsTypes
feat- New featurefix- Bug fixdocs- Documentationtest- Testsrefactor- Code refactoringchore- Maintenance
Development Setup
Prerequisites
- Zig 0.17.0+
- Git
- Bun, to build the documentation site
Building Documentation
The site is a VitePress project in docs/, with bun.lock pinning its dependencies:
cd docs
bun install
bun run docs:dev # local dev server
bun run docs:build # static build into docs/.vitepress/dist
bun run docs:preview # serve the built siteProject Structure
mcp.zig/
├── src/
│ ├── mcp.zig # Module entry point and re-exports
│ ├── report.zig # Error reporting and ISSUES_URL
│ ├── protocol/ # Methods, types, JSON-RPC codec, schemas
│ ├── server/ # Server, tools, resources, prompts, HTTP rules
│ ├── client/ # Client, elicitation, roots, sampling
│ ├── transport/ # Transport interface, STDIO and HTTP
│ └── utils/ # Logging, middleware, progress
├── examples/ # Fifteen runnable examples
├── docs/ # VitePress documentation site
└── build.zig # Build steps: test, docs, examples, test-compileCode of Conduct
- Be respectful and inclusive
- Welcome newcomers
- Accept constructive criticism
- Focus on what is best for the community
Questions?
- Open a discussion
- Check existing issues
License
By contributing, you agree that your contributions are licensed under the MIT License.
