Contributing

Thanks for helping improve simplelogin-mcp. This project is pre-1.0, but the public MCP tool surface is treated carefully: tool names, bounds, annotations, and safety behavior should not drift without explicit documentation and tests.

Requirements

Git.
Node.js 24.x.
pnpm, preferably through Corepack (corepack enable).
Docker and Docker Compose when changing container behavior.
A SimpleLogin API key only when intentionally running the manual live smoke test.

Do not use live SimpleLogin credentials in unit tests, fixtures, logs, screenshots, or pull request text. .env is for local Compose use and must stay untracked.

Setup

git clone https://github.com/enthouan/simplelogin-mcp.git
cd simplelogin-mcp
corepack enable
pnpm install --frozen-lockfile
pnpm exec playwright install chromium webkit

Local pnpm commands do not automatically load .env. Export environment variables in your shell or source .env before running the server locally.

Development Commands

pnpm typecheck      # TypeScript without emit
pnpm lint           # ESLint
pnpm build          # compile TypeScript to dist/
pnpm test           # Vitest unit tests, no live network required
pnpm website:check  # Astro diagnostics, one build, then static and browser checks
pnpm format         # Prettier write
pnpm format:check   # Prettier check
pnpm smoke:live     # manual live SimpleLogin smoke test; opt-in only

Run the full validation set before opening a pull request:

pnpm typecheck
pnpm lint
pnpm build
pnpm test
pnpm website:check
pnpm format:check

When changing Docker behavior, validate both Compose paths. The default docker-compose.yml is the published-image operator path; use docker-compose.local.yml for source changes and image validation:

SL_API_KEY=compose-validation docker compose --env-file .env.example config --no-env-resolution --quiet
SL_API_KEY=compose-validation docker compose --env-file .env.example -f docker-compose.local.yml config --no-env-resolution --quiet
SL_API_KEY=compose-validation docker compose --env-file .env.example -f docker-compose.local.yml build

Live smoke tests are not part of normal CI. Use them only when a change needs live SimpleLogin verification, and follow docs/live-smoke-test.md.

Dependency Maintenance

Dependabot checks npm/pnpm dependencies, GitHub Actions, and Docker image references weekly. CI remains the gate for every generated dependency pull request, including a non-publishing Docker/release dry run for PRs.

Repository auto-merge must be enabled for low-risk Dependabot updates, but only the Dependabot Auto-Merge workflow can opt a pull request into it. The workflow is limited to same-repository, non-draft pull requests authored and triggered by dependabot[bot] and targeting main; it does not check out or execute pull request code.

Auto-merge is allowed only for Dependabot metadata classified as version-update:semver-patch or version-update:semver-minor in these ecosystems:

github-actions
docker
npm

Branch protection remains the final merge gate. main requires strict required checks and conversation resolution, and Docker Dependabot updates rely on the required docker CI dry-run before they can land automatically.

Keep these dependency updates manual:

major updates, including grouped GitHub Actions PRs where Dependabot reports a major update;
Docker runtime baseline jumps such as node:24-bookworm-slim to node:26-bookworm-slim;
pull requests from forks, draft pull requests, and non-Dependabot dependency updates.

Adding Or Changing API Coverage

Keep endpoint changes small and traceable:

Add or update the API path in src/constants.ts.
Add or update Zod request/response schemas in src/schemas/.
Add a thin method in src/client/simplelogin.ts. The shared request() helper owns authentication, timeouts, error parsing, redaction, and response validation.
Register the MCP tool in src/tools/ with clear input descriptions and annotations from src/tools/catalog.ts.
Add focused unit tests for client behavior, tool registration, local guardrails, and error handling. Tests must use stubs and fixtures, not live credentials.
Update public docs: README.md, TOOL_CATALOG.md, and docs/api-coverage.md when scope changes.

Prefer read-only or locally guarded behavior first. Permanent deletes require explicit confirmation inputs, and mail-routing changes that can stop future delivery must be documented as destructive.

Tool Catalog And Documentation Drift

src/tools/catalog.ts is the source for registered tool order, annotation expectations, bounds, and generated catalog text. TOOL_CATALOG.md is the public rendering of that source, and test/tools.test.ts checks that:

registered tool names exactly match the catalog order;
the protocol-boundary digest freezes titles, descriptions, annotations, and input/output schemas;
tool annotations match the catalog;
permanent-delete tools require literal confirm: true over MCP;
bounded reads document page_id, limits, and defaults;
the concise README points readers to the generated catalog instead of duplicating it;
TOOL_CATALOG.md matches the formatted output of renderToolCatalogMarkdown().

When a tool changes, update the catalog source and the public docs together, regenerate TOOL_CATALOG.md, and confirm pnpm test still passes.

Branch And Pull Request Hygiene

Branch from current origin/main.
Keep each pull request scoped to one issue or one coherent change.
Do not rename existing MCP tools or change runtime behavior in documentation-only issues.
Include validation commands and results in the pull request description.
Do not include secrets, machine-local tokens, or private account details.
Use short, direct commit and pull request titles that match the repository history.
The main branch is protected; release and feature work should go through pull requests.

Security issues should not be filed publicly. Follow SECURITY.md.

Open source and independently maintained

Browse the source, report an issue, or follow the project on GitHub.

Star on GitHubMIT licensedSelf-hostableNode 24