mirror of
https://github.com/samanhappy/mcphub.git
synced 2025-12-24 02:39:19 -05:00
79 lines
4.7 KiB
Markdown
79 lines
4.7 KiB
Markdown
# Repository Guidelines
|
|
|
|
These notes align current contributors around the code layout, daily commands, and collaboration habits that keep `@samanhappy/mcphub` moving quickly.
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
- Backend services live in `src`, grouped by responsibility (`controllers/`, `services/`, `dao/`, `routes/`, `utils/`), with `server.ts` orchestrating HTTP bootstrap.
|
|
- `frontend/src` contains the Vite + React dashboard; `frontend/public` hosts static assets and translations sit in `locales/`.
|
|
- Jest-aware test code is split between colocated specs (`src/**/*.{test,spec}.ts`) and higher-level suites in `tests/`; use `tests/utils/` helpers when exercising the CLI or SSE flows.
|
|
- Build artifacts and bundles are generated into `dist/`, `frontend/dist/`, and `coverage/`; never edit these manually.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
- `pnpm dev` runs backend (`tsx watch src/index.ts`) and frontend (`vite`) together for local iteration.
|
|
- `pnpm backend:dev`, `pnpm frontend:dev`, and `pnpm frontend:preview` target each surface independently; prefer them when debugging one stack.
|
|
- `pnpm build` executes `pnpm backend:build` (TypeScript to `dist/`) and `pnpm frontend:build`; run before release or publishing.
|
|
- `pnpm test`, `pnpm test:watch`, and `pnpm test:coverage` drive Jest; `pnpm lint` and `pnpm format` enforce style via ESLint and Prettier.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
- TypeScript everywhere; default to 2-space indentation and single quotes, letting Prettier settle formatting. ESLint configuration assumes ES modules.
|
|
- Name services and data access layers with suffixes (`UserService`, `AuthDao`), React components and files in `PascalCase`, and utility modules in `camelCase`.
|
|
- Keep DTOs and shared types in `src/types` to avoid duplication; re-export through index files only when it clarifies imports.
|
|
|
|
## Testing Guidelines
|
|
|
|
- Use Jest with the `ts-jest` ESM preset; place shared setup in `tests/setup.ts` and mock helpers under `tests/utils/`.
|
|
- Mirror production directory names when adding new suites and end filenames with `.test.ts` or `.spec.ts` for automatic discovery.
|
|
- Aim to maintain or raise coverage when touching critical flows (auth, OAuth, SSE); add integration tests under `tests/integration/` when touching cross-service logic.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
- Follow the existing Conventional Commit pattern (`feat:`, `fix:`, `chore:`, etc.) with imperative, present-tense summaries and optional multi-line context.
|
|
- Each PR should describe the behavior change, list testing performed, and link issues; include before/after screenshots or GIFs for frontend tweaks.
|
|
- Re-run `pnpm build` and `pnpm test` before requesting review, and ensure generated artifacts stay out of the diff.
|
|
|
|
## DAO Layer & Dual Data Source
|
|
|
|
MCPHub supports **JSON file** (default) and **PostgreSQL** storage. Set `USE_DB=true` + `DB_URL` to switch.
|
|
|
|
### Key Files
|
|
|
|
- `src/types/index.ts` - Core interfaces (`IUser`, `IGroup`, `ServerConfig`, etc.)
|
|
- `src/dao/*Dao.ts` - DAO interface + JSON implementation
|
|
- `src/dao/*DaoDbImpl.ts` - Database implementation
|
|
- `src/db/entities/*.ts` - TypeORM entities
|
|
- `src/db/repositories/*.ts` - TypeORM repository wrappers
|
|
- `src/utils/migration.ts` - JSON-to-database migration
|
|
|
|
### Modifying Data Structures (CRITICAL)
|
|
|
|
When adding/changing fields, update **ALL** these files:
|
|
|
|
| Step | File | Action |
|
|
| ---- | -------------------------- | ---------------------------- |
|
|
| 1 | `src/types/index.ts` | Add field to interface |
|
|
| 2 | `src/dao/*Dao.ts` | Update JSON impl if needed |
|
|
| 3 | `src/db/entities/*.ts` | Add TypeORM `@Column` |
|
|
| 4 | `src/dao/*DaoDbImpl.ts` | Map field in create/update |
|
|
| 5 | `src/db/repositories/*.ts` | Update if needed |
|
|
| 6 | `src/utils/migration.ts` | Include in migration |
|
|
| 7 | `mcp_settings.json` | Update example if applicable |
|
|
|
|
### Data Type Mapping
|
|
|
|
| Model | DAO | DB Entity | JSON Path |
|
|
| -------------- | ----------------- | -------------- | ------------------------ |
|
|
| `IUser` | `UserDao` | `User` | `settings.users[]` |
|
|
| `ServerConfig` | `ServerDao` | `Server` | `settings.mcpServers{}` |
|
|
| `IGroup` | `GroupDao` | `Group` | `settings.groups[]` |
|
|
| `SystemConfig` | `SystemConfigDao` | `SystemConfig` | `settings.systemConfig` |
|
|
| `UserConfig` | `UserConfigDao` | `UserConfig` | `settings.userConfigs{}` |
|
|
|
|
### Common Pitfalls
|
|
|
|
- Forgetting migration script → fields won't migrate to DB
|
|
- Optional fields need `nullable: true` in entity
|
|
- Complex objects need `simple-json` column type
|