Add internal/auth package and update documentation for MCP spec 7.1 authentication

[Copilot]

Centralizes authentication logic into a dedicated internal/auth package and updates documentation to reflect MCP specification 7.1 compliance for Authorization headers.

Changes

New internal/auth package:

• ParseAuthHeader() - Extracts API key and agent ID from Authorization headers per MCP spec 7.1 (plain API key, not Bearer scheme)
• ValidateAPIKey() - Validates provided API keys against expected values
• Maintains backward compatibility with Bearer token format
• Package documentation explains MCP spec 7.1 requirements with usage examples

Documentation updates:

• AGENTS.md - Added auth package to Project Structure and Common Tasks sections
• README.md - Added Authentication section under Security Features documenting:
  • Required header format: Authorization: <api-key> (plain text, NOT Bearer <token>)
  • Configuration via MCP_GATEWAY_API_KEY environment variable
  • Auth package API reference with example curl request
• internal/server/auth.go - Added reference to auth package for header parsing
• internal/guard/context.go - Added note about MCP spec 7.1 compliant parsing

Example Usage

import "github.com/githubnext/gh-aw-mcpg/internal/auth"

// Parse Authorization header per MCP spec 7.1
apiKey, agentID, err := auth.ParseAuthHeader(r.Header.Get("Authorization"))
if err != nil {
    return err
}

// Validate against configured key
if !auth.ValidateAPIKey(apiKey, expectedKey) {
    return http.StatusUnauthorized
}

Request format:

curl -X POST http://localhost:8000/mcp/github \
  -H "Authorization: my-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[task] Update documentation to reflect auth package refactoring</issue_title>
<issue_description>## Objective
Update documentation files to reflect the new internal/auth package structure and authentication implementation after the refactoring is complete.

Context

After creating the internal/auth package, we should update relevant documentation to help developers understand:

• The centralized auth package location
• MCP spec 7.1 compliance for auth headers
• How to add new auth-related functionality

Approach

1. Update AGENTS.md

In the "Project Structure" section, add:

- `internal/auth/` - Authentication header parsing and middleware

In the "Common Tasks" section, add:

**Add Auth Logic**: Implement in `internal/auth/` package  

2. Update README.md (if auth is documented there)

• Add reference to internal/auth package
• Document auth header format per MCP spec 7.1
• Clarify that plain API key format is required (no Bearer prefix)

3. Add package documentation

In internal/auth/header.go, ensure comprehensive package docs:

// Package auth provides authentication header parsing and middleware
// for the MCP Gateway server.
//
// This package implements MCP specification 7.1 for authentication,
// which requires Authorization headers to contain the API key directly
// without any scheme prefix (e.g., NOT "Bearer <key>").
//
// Example usage:
//
//     apiKey, agentID, err := auth.ParseAuthHeader(r.Header.Get("Authorization"))
//     if err != nil {
//         // Handle error
//     }
package auth

4. Update any inline comments

• Review server/auth.go and guard/context.go for stale comments
• Ensure comments reference the auth package where appropriate

Files to Modify

• AGENTS.md (add auth package to structure)
• README.md (if applicable)
• internal/auth/header.go (add package documentation)
• internal/server/auth.go (update comments)
• internal/guard/context.go (update comments)

Acceptance Criteria

• AGENTS.md updated with auth package structure
• Package documentation added to auth/header.go
• MCP spec 7.1 compliance documented clearly
• All auth-related comments are accurate and up-to-date
• Documentation reviewed for consistency
• No broken links or references

Dependencies

• Requires: #aw_auth001 (auth package creation)
• Requires: #aw_auth002 (auth tests)

Priority

Low - Documentation update should follow implementation.

Estimated Effort

30 minutes - 1 hour
Related to #226

AI generated by Plan Command for #226

Comments on the Issue (you are @copilot in this section)

• Fixes [task] Update documentation to reflect auth package refactoring #237

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.