14. See exactly what a role sees (debugging)

You added @requires tags and want to confirm an operator really can't see stage_id — without wiring up a client and forging auth headers.

Problem. You added @requires tags and want to confirm an operator really can't see stage_id — without wiring up a client and forging auth headers.

Solution. Set cli_context_builder, then use the bundled rake tasks.

# config/initializers/mcp_authorization.rb
config.cli_context_builder = ->(domain:, role:) {
  role_config = ROLES.fetch(role, ROLES["viewer"])
  user = CurrentUser.new(
    id: "cli", name: role_config[:name], role: role.to_sym,
    permissions: role_config[:permissions], defaults: role_config[:defaults] || {}
  )
  ServerContext.new(current_user: user)
}

# What does each role see?
bundle exec rake "mcp:tools[operator,operator]"   # domain=operator, role=operator
bundle exec rake "mcp:tools[operator,manager]"    # same domain, manager role

# Print Claude Code / Desktop config JSON for live testing
bundle exec rake "mcp:claude[operator,manager]"

# Launch the MCP Inspector UI (needs npx)
bundle exec rake "mcp:inspect[operator,manager]"

Result. mcp:tools prints each visible tool with its input field names and output variant shapes — so you can diff operator vs manager at a glance and confirm the gate works. This is the fastest feedback loop while authoring schemas.

Always check the negative case too. A gate that hides a field from everyone looks identical to a working gate in a single-role run. A misspelled predicate (@requires(:backward_routeing)) reads as "the gate works" until someone who should see the field reports that they can't. Run both roles, every time.

When something looks wrong, in rough order of likelihood:

Collected from COOKBOOK.md in the repository. Edit it there, not here.