Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
73 lines (56 loc) · 2.83 KB

CONTRIBUTING.md

File metadata and controls

73 lines (56 loc) · 2.83 KB
Raw

Contributing

Thanks for helping out. This server is a thin adapter over the DeckProbe engine, and most of its value comes from staying that way.

Getting set up

npm install
npm test

npm test runs the typecheck, the linter, the build, and the full suite. The tests spawn the real engine, so no mocking layer has to be kept in sync with it.

Useful during development:

npm run test:watch
npm run lint:fix
npm run build && node dist/main.js --help

Where a change belongs

Change Where
A new target, format, or report field Upstream. It reaches this server for free.
A new tool, or a new option on one Here — see the design constraints below.
Report wording, confidence semantics, exit codes Upstream. This server passes them through verbatim.

Design constraints

These are what keep the server small, and a pull request that crosses one needs to say why in the description.

  • The report is passed through unmodified. Reshaping engine output would make this server a second, drifting contract. The two deliberate exceptions are the batch wrapper, which adds the requested path to each entry because the engine's error envelope has no way to say which file failed, and the compact list_targets view, which is opt-out via detail: "full".
  • Every tool field costs tokens in every session. tools/list is re-sent to the model on every conversation, so a new option has to earn its schema and description. That is why -o, -O, --plan, --strict, and --telemetry are not exposed.
  • partial is a success. It means a target was unresolved, not that the document is broken. Do not map it to isError.
  • stdout belongs to the MCP transport. Everything else goes to stderr.
  • The engine is spawned, not linked. Untrusted parsing stays in its own process, with a deadline that can kill it.

Adding a tool

  1. Put the zod schema in src/schemas.ts if any part of it is shared.
  2. Register the tool in src/tools/, wrapping the body in guard() so failures come back in the one error grammar.
  3. Mark it readOnlyHint: true and openWorldHint: false — this server only reads local files.
  4. Cover it in tests/tools.test.ts, including at least one failure path.

Commits and pull requests

Keep commits focused and their subject in the imperative mood. In the pull request, say what an agent can do afterwards that it could not before, and note any change to the engine dependency range.

Reporting bugs

Include the server version, the engine version (both are on the startup line this server writes to stderr), the client you are using, the tool arguments, and the result you got back. A vulnerability goes privately to the address in SECURITY.md instead.