Contributing
Thanks for your interest. mcpwn is a security-testing tool; contributions that sharpen its offensive capabilities, broaden transport/protocol coverage, or improve safety and documentation are all welcome.
Ground rules
Section titled “Ground rules”- Authorized use only. Do not submit examples, payloads, or test fixtures that target real third-party services. Use the bundled vulnerable server or your own infrastructure.
- Responsible disclosure. Findings against real MCP servers go through the process in SECURITY.md, not into issues/PRs.
Development
Section titled “Development”npm installnpm run build # tsc -> dist/npm test # build + node --test (all test/**/*.test.js)npm run lint # eslint (src only)npm run format # prettier --write srcnpm run format:check # prettier --check src (CI gate)npm run coverage # c8 line coverage for src/engine + src/corenpm run docs:api # typedoc -> docs/api/ (git-ignored, build-only)npm run demo # end-to-end inject -> exfil demo (no network, no API key)All dependencies are devDependencies - mcpwn itself has zero runtime
dependencies (Node built-ins only). Please keep it that way: validation is
hand-rolled, and transports use node:http/node:crypto directly.
The codebase is small and layered:
| Path | Responsibility |
|---|---|
src/engine/parser.ts | JSON-RPC framing + tolerant parse/serialize |
src/engine/correlator.ts | id → method mapping so responses are attributable |
src/engine/rules.ts | headless tamper rule engine (applyAction) |
src/engine/validate.ts | hand-rolled, zero-dep rule-file validation |
src/engine/jsonpath.ts | tiny JSON path access for argument tampering |
src/engine/intercept.ts | interactive hold/forward/drop/edit controller |
src/engine/tty.ts | cross-platform controlling-terminal open (/dev/tty, CONIN$/CONOUT$) |
src/core/pipeline.ts | transport-agnostic parse→correlate→rules→intercept→log |
src/core/scope.ts | in-scope membership test |
src/transports/stdio.ts | wrap-and-spawn stdio relay (Transport) |
src/transports/http.ts | Streamable HTTP + SSE reverse proxy (Transport) |
src/detect/* | passive detectors (baseline rug-pull, linters) |
src/findings.ts | findings model + JSON/Markdown/SARIF writers |
src/logger.ts | stderr-only logging (never touches the MCP channel) |
src/cli.ts | arg parsing + wiring |
examples/ | vulnerable demo server(s), attack rules, runnable demo |
Extending mcpwn
Section titled “Extending mcpwn”Adding a new rule kind
Section titled “Adding a new rule kind”A tamper action (RuleAction) is a discriminated union keyed on kind. To add
one - say truncateResult:
- Extend the union. Add the new variant to
RuleActioninsrc/types.ts, e.g.| { kind: "truncateResult"; maxLen: number }. - Handle it in
applyAction. Insrc/engine/rules.ts, add acase "truncateResult":before thedefault:throw. Mutate the clonedjsonin place and returntruewhen you changed it,falsewhen the action did not apply. Thedefault:branch must stay - an unknown kind has to fail loud so the per-rule try/catch logs it and forwards untampered (Invariant: never block the wire). - Add a schema + validate branch. Register the kind in
src/engine/validate.ts: add it toACTION_KINDS, list its allowed fields inACTION_FIELDS, and add acaseinvalidateActionthat checks its required/typed fields (reuse therequireString/requireObject/optionalEnum/… helpers). Mirror the shape inschema/rules.schema.jsonso editors/CI get the sameoneOfdiscrimination. - Add tests. Cover the happy path and no-op path in
test/rules*.test.js, and the validation errors (missing/wrong-typed fields, typo suggestion) intest/validate.test.js.
Adding a transport
Section titled “Adding a transport”Transports own framing + I/O only; all tamper/correlation/logging semantics live
in MessagePipeline, so a new transport inherits them for free:
- Implement the
Transportinterface fromsrc/transports/transport.ts(start(): Promise<number>,stop()). - For every logical JSON-RPC message you frame, call
pipeline.process(raw, direction)and write backresult.forward(with your transport’s framing) unless it isnull(dropped). Do not re-implement rules/correlation/logging. - Honour the invariants: forward the original bytes on any failure, preserve framing/ordering when idle, and keep the human/log output off the data channel.
- Add an “idle = byte-identical” assertion test for the transport (see
test/stdio-idle.test.js/test/http.test.js) plus aprocess()-driven behaviour test.
Invariants (please don’t break these)
Section titled “Invariants (please don’t break these)”- stdout/stdin are sacred. All human output goes to stderr (or
/dev/tty). A byte on stdout that isn’t a forwarded protocol message corrupts the session. - Never block the wire. Every path forwards the original bytes on any failure. Detectors are read-only and must never mutate the flow or throw into the pipeline.
- Transparent when idle. With no rules/detectors/scope, traffic passes through unchanged in content, order, and framing - on both transports.
- Protocol correctness. Preserve
Mcp-Session-Id/Last-Event-IDand SSEevent:/id:framing on HTTP; newline framing on stdio; correlation keys intact in both directions. - No telemetry, no egress beyond the explicit
--upstream. - Zero runtime deps. Node built-ins only; hand-rolled schema validation. New deps are devDependencies only.
- Forget on drop. Any drop path calls
correlator.forgetso a dropped request doesn’t leak a correlation entry. applyActionhas adefault:throw for unknown kinds (surfaced as a logged error, never a crash).
Pull requests
Section titled “Pull requests”- Keep commits atomic and use Conventional Commits
(
feat:,fix:,docs:,refactor:,test:,chore:). - Run
npm run lint,npm run build,npm test, andnpm run demobefore pushing. - One logical change per PR; describe the security rationale where relevant.
Release checklist
Section titled “Release checklist”- All green:
npm run lint && npm run build && npm test && npm run coverage. npm run format:checkis clean.- Bump
versioninpackage.json(SemVer). - Add a dated section to
CHANGELOG.md(Keep a Changelog format) summarising the release. - Verify the publish tarball contents:
npm pack --dry-run- confirmdist/,schema/,payloads/,examples/, andREADME.mdare included and nothing sensitive leaks. (prepublishOnlyrunsnpm run buildautomatically.) - Tag and publish:
git tag vX.Y.Zthennpm publish(scope is published with--access public, already set inpublishConfig).