Skip to content

AGENTS.md

Latest commit

 

History

History
41 lines (33 loc) · 3.12 KB

AGENTS.md

File metadata and controls

41 lines (33 loc) · 3.12 KB

Repository Guidelines

Project Structure & Module Organization

  • cmd/mcpproxy hosts the core daemon entrypoint; cmd/mcpproxy-tray builds the CGO-based tray binary.
  • Runtime logic, HTTP handlers, storage, and upstream orchestration live in internal/ (internal/runtime, internal/httpapi, internal/upstream, internal/storage).
  • Vue/Tailwind assets are kept in frontend/; bundled static output is embedded from web/.
  • Integration and regression assets reside under tests/ and scripts/; Go unit tests sit beside source files.

Build, Test, and Development Commands

  • make build — compile the proxy and tray binaries for the host platform.
  • go build ./cmd/mcpproxy — quick core rebuild; GOOS=darwin CGO_ENABLED=1 go build ./cmd/mcpproxy-tray validates the macOS tray target.
  • npm install && npm run build inside frontend/ — install web deps and emit production assets.
  • scripts/run-web-smoke.sh — spin up the proxy and execute the Playwright smoke suite.
  • scripts/verify-api.sh — exercise the /api/v1 REST surface with curated curl calls.

Coding Style & Naming Conventions

  • Run gofmt (tabs, goimports defaults) on all Go sources; prefer descriptive package-level names (runtime, upstream, storage).
  • TypeScript/Vue files follow Prettier defaults (npm run lint); components use PascalCase.vue, composables use useThing.ts.
  • Configuration and DTO structs live in shared packages (internal/contracts, internal/httpapi); avoid anonymous maps between layers.

Testing Guidelines

  • Unit tests: go test ./internal/... (set GOCACHE/GOMODCACHE to workspace paths when sandboxed).
  • Targeted suites: go test ./internal/server -run TestMCP -v for lifecycle checks; npm run test:unit for frontend units.
  • End-to-end: scripts/run-e2e-tests.sh after ensuring @modelcontextprotocol/server-everything is warmed and reachable.
  • Name Go tests TestFeatureScenario; snapshot or fixture data belong under tests/ with explicit prefixes.

Commit & Pull Request Guidelines

  • Use concise, imperative commit messages (e.g., Fix upstream disable locking); avoid AI co-author tags.
  • PR descriptions should summarize impact, list verification commands, and link relevant P# items or issues; attach UI screenshots or log excerpts when behavior changes.
  • Keep change scopes bounded to one surface (runtime vs. tray vs. web); document follow-up ideas in IMPROVEMENTS.md.

Security & Configuration Tips

  • Never hardcode secrets; load them via the tray secure store or environment lookups in internal/secret.
  • When editing configs, prefer runtime.SaveConfiguration() flows so disk state and in-memory state stay aligned; regenerated files land in ~/.mcpproxy/.

Active Technologies

  • Go 1.24 (toolchain go1.24.10) + BBolt (storage), Chi router (HTTP), Zap (logging), regexp (stdlib), existing ActivityService (026-pii-detection)
  • BBolt database (~/.mcpproxy/config.db) - ActivityRecord.Metadata extension (026-pii-detection)

Recent Changes

  • 026-pii-detection: Added Go 1.24 (toolchain go1.24.10) + BBolt (storage), Chi router (HTTP), Zap (logging), regexp (stdlib), existing ActivityService