Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
68 lines (53 loc) · 2.67 KB

CONTRIBUTING.md

File metadata and controls

68 lines (53 loc) · 2.67 KB
Raw

Contributing to gitpulse-mcp

Thanks for your interest in improving gitpulse-mcp! Contributions of all kinds are welcome — bug reports, feature ideas, docs, and code.

Getting started

git clone https://github.com/ATOM00blue/gitpulse-mcp.git
cd gitpulse-mcp
npm install
npm run build
npm test

Project layout

src/
  index.ts          # bin entry: argv parsing, stdio transport, signal handling
  server.ts         # createServer(): registers all MCP tools
  config.ts         # CLI args -> ServerConfig
  git/
    exec.ts         # safe git runner (execFile, no shell, timeouts)
    repo.ts         # repo resolution & ref validation
    parse.ts        # parsers for git log / numstat / blame porcelain
  tools/            # one file per MCP tool
  lib/
    format.ts       # output helpers + safeHandler wrapper
    types.ts        # shared types
test/               # vitest unit + integration tests (build a fixture repo)
scripts/smoke.mjs   # end-to-end MCP smoke test over stdio

Development workflow

  • npm run build — compile TypeScript to dist/
  • npm run dev — compile in watch mode
  • npm test — run the test suite (vitest)
  • npm run test:watch — tests in watch mode
  • npm run smoke — build first, then run the end-to-end smoke test
  • npm run lint — eslint
  • npm run format — prettier

Guidelines

  • Read-only. gitpulse-mcp must never modify a repository. Only read commands.
  • No shell. Always invoke git via git() in src/git/exec.ts (uses execFile with an arg array). Never build shell strings.
  • stdout is sacred. It carries JSON-RPC. All logging/diagnostics go to stderr.
  • Structured + human output. Every tool returns both content[0].text (markdown) and structuredContent (typed JSON).
  • Cross-platform. Code must work on Windows, macOS, and Linux. Avoid POSIX-only assumptions; rely on git's porcelain output and normalize paths.
  • Tests. Add/extend tests for any new tool or parser. Tests build a deterministic fixture repo (see test/fixture.ts).

Adding a new tool

  1. Create src/tools/myTool.ts exporting an input schema (ZodRawShape) and an async handler returning a ToolResult.
  2. Register it in src/server.ts with a clear title, description, and annotations: { readOnlyHint: true }.
  3. Add tests in test/tools.test.ts and a check in scripts/smoke.mjs.
  4. Document it in README.md.

Submitting changes

  1. Fork and create a branch.
  2. Make your change with tests; ensure npm run build && npm test && npm run lint && npm run smoke all pass.
  3. Open a PR describing the change and motivation.

Code of conduct

Be kind and constructive. We're all here to build something useful.