GitLab + Jira MCP Server

# Repository Guidelines ## Project Structure & Module Organization - `src/cli.ts`: CLI entry that boots the MCP server. - `src/mcp/server.ts`: MCP transport, tool registration, error mapping. - `src/adapters/gitlab.ts`: GitLab REST client + helpers. - `src/adapters/jira.ts`: Jira REST client + helpers. - `src/config/index.ts`: Loads env and `~/.mcp-gitlab-jira.json` (if present). - `tests/**/*.(spec|test).ts`: Unit/integration tests for tools and adapters. - `bin/mcp-gitlab-jira`: Executable wrapper (published with the package). - `dist/`: Compiled output from TypeScript build. ## Build, Test, and Development Commands - `npm ci`: Install exact dependencies. - `npm run dev`: Start MCP server in watch mode (e.g., tsx/ts-node). - `npm run build`: Compile TypeScript to `dist/` with `tsc`. - `npm test`: Run tests (e.g., Vitest/Jest) and print coverage. - `docker build -t mcp-gitlab-jira .`: Build the Docker image. - `docker run -e GITLAB_URL=... -e GITLAB_TOKEN=... -e JIRA_URL=... -e JIRA_TOKEN=... mcp-gitlab-jira`: Run via Docker. ## Coding Style & Naming Conventions - TypeScript, 2‑space indentation, no semicolons or with Prettier default (follow project config). - Filenames: kebab-case (e.g., `gitlab-client.ts`). - Functions/variables: camelCase. Classes/Types: PascalCase. - Tool identifiers match PRD: `gitlab_list_projects`, `gitlab_list_merge_requests`, `gitlab_list_issues`, `jira_search_issues`, `jira_get_issue`. - Use ESLint + Prettier. Run `npm run lint` and `npm run format` before pushing. ## Testing Guidelines - Framework: Vitest or Jest with ts-node/ts-jest. - Test files: `**/*.spec.ts` colocated near source or under `tests/`. - Aim for ≥80% coverage on `src/adapters/*` and tool handlers. - Examples: - Run all tests: `npm test` - Watch mode: `npm run test:watch` ## Commit & Pull Request Guidelines - Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`. - Use present‑tense, concise subject; add context in body. Link issues (e.g., `Closes #42`). - PRs include: - Summary, rationale, and screenshots or trace logs if behavior changes. - How to run: commands, sample env/config used. - Checklist: tests added/updated, lint/format run, no secrets in logs. ## Security & Configuration Tips - Configure via env vars or `~/.mcp-gitlab-jira.json`: - `GITLAB_URL`, `GITLAB_TOKEN`, `JIRA_URL`, `JIRA_TOKEN`. - Never log tokens; redact headers and query strings. Avoid committing sample tokens. - Prefer dependency‑free HTTP where reasonable; if using SDKs, pin versions. - Validate and fail fast on missing/invalid config with clear MCP errors. ## Architecture Overview - CLI launches an MCP server exposing read‑only tools for GitLab and Jira. - Adapters encapsulate REST calls; handlers convert adapter results to MCP responses. - Keep handlers pure and small; mock adapters in tests for speed and determinism.