job-engine-spring AGENTS.md

Repository Guidelines

job-engine-spring is a local-only MCP (Model Context Protocol) server, not a hosted service, REST API, web UI, or job-board scraper. It stores normalized candidate profiles and jobs, produces explainable profile-to-job match reports, and generates resume/cover-letter PDFs. Normal runtime is a persistent Streamable HTTP MCP endpoint published only on host loopback (http://127.0.0.1:8080/mcp); STDIO exists only for CI/package verification and isolated diagnostics. The application is MCP-first: do not add REST controllers unless REST compatibility is explicitly required.

Project Structure & Module Organization

This is a Maven Java 25 Spring Boot 4.1.0 project. The main build descriptor is pom.xml, with the Maven wrapper available as mvnw. Production code lives in src/main/java, tests in src/test/java, and Flyway database migrations in src/main/resources/db/migration.

The package layout follows application boundaries: domain contains core business concepts, application holds use cases and orchestration, and adapter packages contain integrations. Current adapters include adapter/in/mcp, adapter/out/postgres, and adapter/out/http.

Build, Test, and Development Commands

• ./mvnw test runs the unit test suite through Surefire.
• ./mvnw -q -Dtest=ClassName test runs a single test class; comma-separate multiple classes, e.g. ./mvnw -q -Dtest=JobServiceTests,JobMcpAdapterTests,HttpJobLinkContentFetcherTests test.
• ./mvnw verify -Pintegration-tests runs integration tests through Failsafe (Testcontainers/PostgreSQL) plus the JaCoCo coverage gate. Requires Docker.
• ./mvnw spring-boot:run starts the application locally.
• docker compose build mcp builds the local container image for the persistent Streamable HTTP MCP server.
• docker compose up -d --build --wait postgres mcp is the build-from-source dev path: starts PostgreSQL privately and publishes MCP only on host loopback; python3 scripts/smoke-mcp-http.py verifies initialize, discovery, and health.
• ./scripts/rebuild-local-mcp-jar.sh runs ./mvnw test, packages the jar, then runs hermes mcp test job-engine-spring if the Hermes CLI is present (RUN_TESTS=false to skip tests when already green).
• ./scripts/run-release-mcp-http.sh ghcr.io/jonhhh09/job-engine-spring:vX.Y.Z is the guarded release-only deployment path; it refuses local/latest images and recreates the service without building.
• ./scripts/run-local-mcp-container.sh is the explicit STDIO CI/package-verification launcher. It activates the stdio profile and must not be used for normal Hermes tool calls.
• ./scripts/run-mcp-stdio-diag.sh launches a unique-named diagnostic MCP STDIO container so engineering smoke/diagnosis cannot kill an active Hermes session.
• python3 scripts/smoke-mcp-stdio.py -- ./scripts/run-local-mcp-container.sh verifies the containerized MCP initialize + tools/list STDIO contract for the default instance. Prefer ./scripts/run-mcp-stdio-diag.sh when Hermes may already be connected.
• scripts/tests/test-mcp-container-cleanup.sh is a Docker-free regression for cleanup ownership (preserve custom instances; remove default/legacy only for default launches).
• After rebuilding/redeploying: recreate the persistent service, then run /reload-mcp in the connected agent; if tool names/schemas/prompts changed, also run /reset to refresh the agent's cached tool schema.
• Backup/recovery: ./scripts/postgres-backup.sh, ./scripts/postgres-verify-backup.sh, ./scripts/postgres-restore.sh, ./scripts/postgres-backup-prune.sh. Restore/verify always target a disposable Compose project/volume, never the primary one directly.