Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
106 lines (79 loc) · 4.7 KB

CONTRIBUTING.md

File metadata and controls

106 lines (79 loc) · 4.7 KB

Contributing to FrontMCP

Thanks for helping improve FrontMCP! This repo hosts the core SDK, CLI, adapters, plugins, docs, and the demo app. The project follows the Code of Conduct; by participating you agree to uphold it.

Ways to Contribute

  • Report reproducible bugs, missing docs, or regression risks via GitHub issues.
  • Improve docs (/docs), snippets, or the demo app in apps/demo.
  • Fix bugs or add features inside the packages under libs/*.
  • Build adapters/plugins/examples that showcase how the SDK should be used.

If you are unsure whether a change fits, open an issue first so we can discuss the scope.

Prerequisites and Tooling

  • Node.js >= 22 and npm >= 10 (see README installation section).
  • Yarn (this workspace enables Corepack and sets "packageManager": "yarn" in nx.json). Run corepack enable once if needed.
  • Nx CLI (yarn nx --help) powers builds, lint, tests, and type-checking.
  • Git and a GitHub account for forks/PRs.

First-time setup:

git clone https://github.com/agentfront/frontmcp.git
cd frontmcp
corepack enable
yarn install

Workspace Layout

This is an Nx monorepo. Each folder under libs/* is an independently built package (for example libs/sdk, libs/cli, libs/plugins, libs/adapters). The demo and any showcase apps live under apps/*. Project-specific tasks are declared in each project.json.

Helpful references:

  • README.md for a high-level overview and quickstart.
  • CHANGELOG.md for release notes—update it when user-facing behavior changes.
  • docs/ for the Mintlify-based documentation site (yarn docs:local runs a local preview).

Day-to-Day Commands

yarn dev                       # nx serve demo (demo server hot reload)
yarn nx test sdk               # run Jest tests for libs/sdk
yarn nx lint plugins           # lint a specific project
yarn nx run-many -t lint,test  # run lint+test for everything
yarn nx run-many -t build      # build all publishable packages
yarn docs:local                # preview the docs site locally
yarn nx affected --target test --base main  # limit CI work to changed projects

Before opening a PR, run at least yarn nx run-many -t lint,test and yarn nx run-many -t build. If you changed transport/session/auth flows, also try the Inspector (npx frontmcp inspector) to verify end-to-end behavior.

Coding Standards

  • Use TypeScript, modern ESM syntax, and decorators that align with the SDK’s existing patterns.
  • Keep @frontmcp/* versions aligned inside examples (see README “Version Alignment”).
  • Prefer strongly typed Zod schemas (pass fields directly, matching current code style).
  • Keep changes focused; split unrelated work across multiple PRs.
  • Formatting is enforced by Prettier and lint rules (run yarn nx lint <project> locally). Husky + lint-staged will format staged files on commit.
  • Add concise comments only when necessary to explain non-obvious intent.

Testing Expectations

  • Every bug fix or feature should include/adjust Jest specs alongside the code (*.spec.ts).
  • Use Nx test targets close to the code (yarn nx test sdk, yarn nx test cli, etc.).
  • Integration behavior that spans packages should be validated in the demo app (spin up yarn dev) and, when possible, through Inspector flows.
  • If you touch build tooling, ensure yarn nx run-many -t build succeeds and that emitted artifacts under dist/ look reasonable.

Documentation and Samples

  • Docs live in docs/ (Mintlify). After editing, run yarn docs:local to confirm the nav/build passes.
  • Keep README.md in sync with notable DX changes (new scripts, requirements, etc.).
  • Update code snippets under docs/snippets if your change alters their behavior.
  • Demo updates should remain scoped and easy to understand; prefer creating a new sample app/tool over overloading existing ones.

Pull Request Checklist

  1. Open/mention an issue for significant changes.
  2. Rebase on the latest main; keep history clean (squash in your fork if needed).
  3. Add or update unit tests plus docs/snippets.
  4. Run:
    • yarn nx run-many -t lint,test
    • yarn nx run-many -t build
    • yarn docs:local (if docs changed)
    • npx frontmcp doctor and try Inspector if your change affects runtime behavior.
  5. Update CHANGELOG.md when the change is user-facing.
  6. Include screenshots or logs when the change affects dev tooling or Inspector UX.

Maintainers handle publishing; do not run manual npm publish steps.

Communication

  • For security issues, email david@frontegg.com instead of opening a public issue.
  • For general help, use GitHub Discussions/Issues or reach out during office hours if announced.

We appreciate every contribution—thank you for making FrontMCP better!