# Contributing to FrontMCP Thanks for helping improve FrontMCP! This repo hosts the core SDK, CLI, adapters, plugins, the skills catalog, and the demo app; the documentation is at [frontmcp.dev](https://frontmcp.dev). The project follows the [Code of Conduct](./CODE_OF_CONDUCT.md); by participating you agree to uphold it. ## Ways to Contribute - Report reproducible bugs, missing docs, or regression risks via GitHub issues. - Improve the skills catalog (`libs/skills/catalog`) 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: ```bash 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. - [frontmcp.dev](https://frontmcp.dev) for the documentation, which lives in a separate repository. ## Day-to-Day Commands ```bash 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 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 ` 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 - FrontMCP's docs live on [frontmcp.dev](https://frontmcp.dev), in a separate repository. Report a docs problem as an issue here. - When your change alters what users see, fill in the PR template's "User-facing change" section, and update the matching entries in `libs/skills/catalog`. - Keep `README.md` in sync with notable DX changes (new scripts, requirements, etc.). - 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, and the skills catalog when behavior changes. 4. Run: - `yarn nx run-many -t lint,test` - `yarn nx run-many -t build` - `npx frontmcp doctor` and try Inspector if your change affects runtime behavior. 5. Update `CHANGELOG.md` and fill in the PR template's "User-facing change" section 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!