QA Review: feat/mcp → main

[rsmithlal]

QA Review: feat/mcp → main

Pull Request: #1220
Commits: 16 | Stats: 195 files changed, 14992 insertions(+), 122 deletions(-)
Generated: 2026-02-15 23:59 UTC

---

Change Summary

Category	Count
Models	7
API Controllers	27
Web Controllers	3
Concerns	4
Views	12
Policies	3
API Resources	23
Routes	3
I18n / Locales	4
JavaScript	1
Config / Initializers	11
Migrations	3
MCP Tools	20
Jobs	1
Builders	1
Specs	63
Docs	6
Other	1

---

QA Checklist

Models (7 files)

Changed files

• app/models/better_together/navigation_item.rb
• app/models/better_together/oauth_access_grant.rb
• app/models/better_together/oauth_access_token.rb
• app/models/better_together/oauth_application.rb
• app/models/better_together/person.rb
• app/models/better_together/webhook_delivery.rb
• app/models/better_together/webhook_endpoint.rb

• Verify model validations work correctly (create with invalid data) (confirmed locally 2026-02-16; commit 75bec9f; ran bin/dc-run bundle exec prspec spec/models/better_together/navigation_item_spec.rb spec/models/better_together/oauth_access_grant_spec.rb spec/models/better_together/oauth_access_token_spec.rb spec/models/better_together/oauth_application_spec.rb spec/models/better_together/person_spec.rb spec/models/better_together/webhook_delivery_spec.rb spec/models/better_together/webhook_endpoint_spec.rb)
• Test model associations (belongs_to, has_many, etc.) (confirmed locally 2026-02-16; commit 75bec9f; ran bin/dc-run bundle exec prspec spec/models/better_together/navigation_item_spec.rb spec/models/better_together/oauth_access_grant_spec.rb spec/models/better_together/oauth_access_token_spec.rb spec/models/better_together/oauth_application_spec.rb spec/models/better_together/person_spec.rb spec/models/better_together/webhook_delivery_spec.rb spec/models/better_together/webhook_endpoint_spec.rb)
• Check permitted_attributes are correctly defined (confirmed locally 2026-02-16; commit 75bec9f; ran bin/dc-run bundle exec prspec spec/models/better_together/navigation_item_spec.rb spec/models/better_together/oauth_access_grant_spec.rb spec/models/better_together/oauth_access_token_spec.rb spec/models/better_together/oauth_application_spec.rb spec/models/better_together/person_spec.rb spec/models/better_together/webhook_delivery_spec.rb spec/models/better_together/webhook_endpoint_spec.rb)
• Verify enum values match documentation and are string-based (confirmed locally 2026-02-16; commit 75bec9f; ran bin/dc-run bundle exec prspec spec/models/better_together/navigation_item_spec.rb spec/models/better_together/oauth_access_grant_spec.rb spec/models/better_together/oauth_access_token_spec.rb spec/models/better_together/oauth_application_spec.rb spec/models/better_together/person_spec.rb spec/models/better_together/webhook_delivery_spec.rb spec/models/better_together/webhook_endpoint_spec.rb)
• Test any new scopes or query methods (confirmed locally 2026-02-16; commit 75bec9f; ran bin/dc-run bundle exec prspec spec/models/better_together/navigation_item_spec.rb spec/models/better_together/oauth_access_grant_spec.rb spec/models/better_together/oauth_access_token_spec.rb spec/models/better_together/oauth_application_spec.rb spec/models/better_together/person_spec.rb spec/models/better_together/webhook_delivery_spec.rb spec/models/better_together/webhook_endpoint_spec.rb)

API Controllers (27 files)

Changed files

• app/controllers/better_together/api/application_controller.rb
• app/controllers/better_together/api/doorkeeper/token_info_controller.rb
• app/controllers/better_together/api/doorkeeper/tokens_controller.rb
• app/controllers/better_together/api/oauth/applications_controller.rb
• app/controllers/better_together/api/v1/conversations_controller.rb
• app/controllers/better_together/api/v1/events_controller.rb
• app/controllers/better_together/api/v1/geography_continents_controller.rb
• app/controllers/better_together/api/v1/geography_countries_controller.rb
• app/controllers/better_together/api/v1/geography_regions_controller.rb
• app/controllers/better_together/api/v1/geography_settlements_controller.rb
• app/controllers/better_together/api/v1/geography_states_controller.rb
• app/controllers/better_together/api/v1/invitations_controller.rb
• app/controllers/better_together/api/v1/joatu_agreements_controller.rb
• app/controllers/better_together/api/v1/joatu_offers_controller.rb
• app/controllers/better_together/api/v1/joatu_requests_controller.rb
• app/controllers/better_together/api/v1/messages_controller.rb
• app/controllers/better_together/api/v1/metrics_summary_controller.rb
• app/controllers/better_together/api/v1/navigation_areas_controller.rb
• app/controllers/better_together/api/v1/navigation_items_controller.rb
• app/controllers/better_together/api/v1/notifications_controller.rb
• app/controllers/better_together/api/v1/pages_controller.rb
• app/controllers/better_together/api/v1/person_blocks_controller.rb
• app/controllers/better_together/api/v1/posts_controller.rb
• app/controllers/better_together/api/v1/uploads_controller.rb
• app/controllers/better_together/api/v1/webhook_endpoints_controller.rb
• app/controllers/better_together/api/v1/webhooks_controller.rb
• app/controllers/concerns/better_together/api/oauth_authorization.rb

• Test each API endpoint with valid OAuth token (200/201 responses)
• Test each API endpoint without token (401 Unauthorized)
• Test with insufficient permissions (403 Forbidden)
• Verify JSONAPI response format (type, id, attributes)
• Test pagination parameters (page[number], page[size])
• Test filter parameters where applicable
• Verify error responses include proper JSONAPI error objects
• Check rate limiting (Rack::Attack) applies to API endpoints

Web Controllers (3 files)

Changed files

• app/controllers/better_together/oauth/applications_controller.rb
• app/controllers/better_together/oauth_applications_controller.rb
• app/controllers/better_together/webhook_endpoints_controller.rb

• Test index action — page loads, lists records
• Test show action — displays record details
• Test new/create flow — form renders, submission creates record
• Test edit/update flow — form pre-fills, submission updates record
• Test destroy action — record is deleted/soft-deleted
• Verify Pundit authorization on each action
• Test as unauthenticated user (should redirect to login)
• Test as regular user (appropriate restrictions)
• Test as platform manager (full access)
• Verify flash messages display correctly
• Check Turbo/Hotwire interactions work (no full page reloads) (manual)

Concerns (4 files)

Changed files

• app/models/concerns/better_together/block_filterable.rb
• app/models/concerns/better_together/mcp/pundit_integration.rb
• app/models/concerns/better_together/timezone_scoped.rb
• app/models/concerns/better_together/webhook_publishable.rb

• Verify concern is properly included in target models/controllers
• Test concern behavior through the including class
• Check for proper method delegation and conflict resolution

Views (12 files)

Changed files

• app/views/better_together/oauth_applications/_form.html.erb
• app/views/better_together/oauth_applications/_oauth_application.html.erb
• app/views/better_together/oauth_applications/edit.html.erb
• app/views/better_together/oauth_applications/index.html.erb
• app/views/better_together/oauth_applications/new.html.erb
• app/views/better_together/oauth_applications/show.html.erb
• app/views/better_together/webhook_endpoints/_form.html.erb
• app/views/better_together/webhook_endpoints/_webhook_endpoint.html.erb
• app/views/better_together/webhook_endpoints/edit.html.erb
• app/views/better_together/webhook_endpoints/index.html.erb
• app/views/better_together/webhook_endpoints/new.html.erb
• app/views/better_together/webhook_endpoints/show.html.erb

• Visual inspection of each view in browser
• Verify all user-facing text uses I18n (no hard-coded strings)
• Check Bootstrap 5.3 layout and responsive behavior
• Run accessibility check (axe-core / browser devtools)
• Verify form labels and ARIA attributes (WCAG 2.1 AA)
• Test keyboard navigation on interactive elements
• Check color contrast ratios (4.5:1 normal, 3:1 large text)
• Verify Turbo Frame/Stream boundaries are correct
• Test form validation (client-side and server-side error display)

Policies (3 files)

Changed files

• app/policies/better_together/oauth_application_policy.rb
• app/policies/better_together/post_policy.rb
• app/policies/better_together/webhook_endpoint_policy.rb

• Verify unauthenticated users are denied access (confirmed locally 2026-02-16; commit 75bec9f; ran bin/dc-run bundle exec prspec spec/policies/better_together/oauth_application_policy_spec.rb spec/policies/better_together/post_policy_spec.rb spec/policies/better_together/webhook_endpoint_policy_spec.rb)
• Test regular user permissions match expected behavior (confirmed locally 2026-02-16; commit 75bec9f; ran bin/dc-run bundle exec prspec spec/policies/better_together/oauth_application_policy_spec.rb spec/policies/better_together/post_policy_spec.rb spec/policies/better_together/webhook_endpoint_policy_spec.rb)
• Test platform manager / admin permissions (confirmed locally 2026-02-16; commit 75bec9f; ran bin/dc-run bundle exec prspec spec/policies/better_together/oauth_application_policy_spec.rb spec/policies/better_together/post_policy_spec.rb spec/policies/better_together/webhook_endpoint_policy_spec.rb)
• Verify Scope restricts record visibility appropriately (confirmed locally 2026-02-16; commit 75bec9f; ran bin/dc-run bundle exec prspec spec/policies/better_together/oauth_application_policy_spec.rb spec/policies/better_together/post_policy_spec.rb spec/policies/better_together/webhook_endpoint_policy_spec.rb)
• Check that policy is applied in corresponding controller (confirmed locally 2026-02-16; commit 75bec9f; ran bin/dc-run bundle exec prspec spec/policies/better_together/oauth_application_policy_spec.rb spec/policies/better_together/post_policy_spec.rb spec/policies/better_together/webhook_endpoint_policy_spec.rb)
• Test edge cases (own records vs others' records) (confirmed locally 2026-02-16; commit 75bec9f; ran bin/dc-run bundle exec prspec spec/policies/better_together/oauth_application_policy_spec.rb spec/policies/better_together/post_policy_spec.rb spec/policies/better_together/webhook_endpoint_policy_spec.rb)

API Resources / Serializers (23 files)

Changed files

• app/resources/better_together/api/v1/conversation_resource.rb
• app/resources/better_together/api/v1/event_resource.rb
• app/resources/better_together/api/v1/geography_continent_resource.rb
• app/resources/better_together/api/v1/geography_country_resource.rb
• app/resources/better_together/api/v1/geography_region_resource.rb
• app/resources/better_together/api/v1/geography_settlement_resource.rb
• app/resources/better_together/api/v1/geography_state_resource.rb
• app/resources/better_together/api/v1/invitation_resource.rb
• app/resources/better_together/api/v1/joatu_agreement_resource.rb
• app/resources/better_together/api/v1/joatu_offer_resource.rb
• app/resources/better_together/api/v1/joatu_request_resource.rb
• app/resources/better_together/api/v1/message_resource.rb
• app/resources/better_together/api/v1/navigation_area_resource.rb
• app/resources/better_together/api/v1/navigation_item_resource.rb
• app/resources/better_together/api/v1/notification_resource.rb
• app/resources/better_together/api/v1/page_resource.rb
• app/resources/better_together/api/v1/person_block_resource.rb
• app/resources/better_together/api/v1/person_community_membership_resource.rb
• app/resources/better_together/api/v1/post_resource.rb
• app/resources/better_together/api/v1/upload_resource.rb
• app/resources/better_together/api/v1/webhook_endpoint_resource.rb
• app/resources/better_together/mcp/application_resource.rb
• app/resources/better_together/mcp/public_communities_resource.rb

• Verify exposed attributes match API documentation
• Check that sensitive fields are NOT exposed in API responses
• Verify relationships are serialized correctly
• Test filtering and sorting parameters
• Confirm creatable/updatable fields are properly restricted

Routes (3 files)

Changed files

• config/routes.rb
• config/routes/api.rb
• config/routes/api_v1.rb

• Verify new routes are accessible (rails routes output)
• Check route naming conventions match project standards (manual)
• Test URL helpers work in views and controllers (manual)
• Verify locale constraints are applied to engine routes (manual)
• Check API versioning namespace is correct (manual)

I18n / Locales (4 files)

Changed files

• config/locales/en.yml
• config/locales/es.yml
• config/locales/fr.yml
• config/locales/uk.yml

• Run bin/i18n health — no missing keys (confirmed locally 2026-02-16; commit 75bec9f)
• Verify all new keys have translations in en, es, fr, uk
• Check translation quality (not just English copies)
• Visual inspection with non-English locale (manual)
• Verify interpolation variables are correct
• Check locale files are properly normalized

JavaScript / Stimulus (1 files)

Changed files

• app/javascript/controllers/better_together/secret_toggle_controller.js

• Test Stimulus controller connection (data-controller attribute)
• Verify interactive behavior in browser
• Test keyboard accessibility of interactive elements
• Check for console errors in browser devtools
• Verify importmap registration if new controllers added
• Test graceful degradation without JavaScript

Config / Initializers (11 files)

Changed files

• Gemfile.lock
• better_together.gemspec
• config/initializers/doorkeeper.rb
• config/initializers/fast_mcp.rb
• config/initializers/jsonapi.rb
• config/initializers/rack_attack.rb
• lib/better_together.rb
• lib/better_together/engine.rb
• lib/better_together/mcp.rb
• lib/better_together/mcp/pundit_context.rb
• lib/tasks/oauth.rake

• Verify app starts cleanly with new configuration
• Check no secrets or credentials are hard-coded
• Verify ENV.fetch is used (not ENV[])
• Test configuration in development and test environments
• Review gem version constraints for compatibility

Migrations (3 files)

Changed files

• db/migrate/20260215000001_create_better_together_oauth_tables.rb
• db/migrate/20260215000002_create_better_together_webhook_endpoints.rb
• db/migrate/20260215000003_create_better_together_webhook_deliveries.rb

• Verify migration runs cleanly (rails db:migrate)
• Verify migration is reversible (rails db:rollback)
• Check UUID primary keys (create_bt_table)
• Verify indexes are added for foreign keys and query columns
• Check null constraints and defaults match model validations
• Review for data safety (no destructive changes to existing data)

MCP Tools (20 files)

Changed files

• app/tools/better_together/mcp/application_tool.rb
• app/tools/better_together/mcp/create_event_tool.rb
• app/tools/better_together/mcp/create_post_tool.rb
• app/tools/better_together/mcp/get_event_detail_tool.rb
• app/tools/better_together/mcp/get_metrics_summary_tool.rb
• app/tools/better_together/mcp/get_post_tool.rb
• app/tools/better_together/mcp/list_communities_tool.rb
• app/tools/better_together/mcp/list_conversations_tool.rb
• app/tools/better_together/mcp/list_events_tool.rb
• app/tools/better_together/mcp/list_invitations_tool.rb
• app/tools/better_together/mcp/list_notifications_tool.rb
• app/tools/better_together/mcp/list_offers_tool.rb
• app/tools/better_together/mcp/list_pages_tool.rb
• app/tools/better_together/mcp/list_requests_tool.rb
• app/tools/better_together/mcp/list_uploads_tool.rb
• app/tools/better_together/mcp/manage_navigation_tool.rb
• app/tools/better_together/mcp/search_geography_tool.rb
• app/tools/better_together/mcp/search_people_tool.rb
• app/tools/better_together/mcp/search_posts_tool.rb
• app/tools/better_together/mcp/send_message_tool.rb

• Test each tool via MCP endpoint with valid authentication
• Verify tool respects privacy scoping (no private data leakage)
• Test with blocked users — verify block filtering works
• Verify Pundit authorization is enforced
• Test input validation and error responses
• Check timezone handling in tool responses
• Verify tool descriptions and parameter documentation

Background Jobs (1 files)

Changed files

• app/jobs/better_together/webhook_delivery_job.rb

• Verify job enqueues with correct queue name
• Test job execution with valid inputs
• Test job error handling and retry behavior
• Verify job idempotency (safe to re-run)
• Check Sidekiq dashboard for job visibility

Builders (1 files)

Changed files

• app/builders/better_together/navigation_builder.rb

• Verify navigation items appear in the correct position
• Check navigation item visibility based on authorization
• Test navigation rendering in browser (manual)

Cross-cutting Checks

• Run full test suite: bin/dc-run bin/ci — all passing (confirmed locally 2026-02-16; commit 75bec9f)
• Run security scan: bin/dc-run bundle exec brakeman --quiet --no-pager (confirmed locally 2026-02-16; commit 75bec9f)
• Run style check: bin/dc-run bundle exec rubocop (confirmed locally 2026-02-16; commit 75bec9f)
• Run i18n check: bin/dc-run bin/i18n (confirmed locally 2026-02-16; commit 75bec9f)
• Verify no N+1 queries in new features (check logs)
• Review for proper error handling (no unrescued exceptions)
• Check browser console for JavaScript errors (manual)
• Test in at least one non-English locale (manual)

Documentation (6 files)

Changed files

• .github/copilot-instructions.md
• AGENTS.md
• docs/developers/security/mcp_authentication_security_assessment.md
• docs/development/mcp_integration.md
• docs/implementation/current_plans/mcp_api_integration_plan.md
• docs/implementation/mcp_integration_acceptance_criteria.md

• Review documentation accuracy
• Verify code examples are correct and up to date
• Check for broken links
• Ensure documentation matches implementation

Test Coverage Review (63 spec files)

• Verify new functionality has corresponding specs
• Check that specs test both happy path and error cases
• Review spec descriptions for clarity
• Verify no flaky tests (run specs multiple times)
• Check for proper use of HTML assertion helpers (factory content)

---

Generated by bin/qa-review — see bin/qa-review --help for usage.