feat: Add optional bearer token authentication (v2.3.1)

[T-rav]

Summary

Adds optional bearer token authentication to WebCat MCP server using the WEBCAT_API_KEY environment variable.

Changes

✅ Authentication Implementation

• Optional bearer token auth using WEBCAT_API_KEY env var
• If WEBCAT_API_KEY is set: requires Authorization: Bearer <token> header
• If not set: no authentication required (backward compatible)
• Properly implemented using FastMCP Context with header extraction

✅ Code Cleanup

• Removed demo UI and custom /sse endpoint
• Removed /demo endpoint
• Focus on core MCP protocol at /mcp/sse
• Cleaned up endpoint responses (removed demo references)
• Removed unused capabilities from server info

✅ Testing

• 11 authentication unit tests (test_auth.py)
• 5 updated search tool tests
• Test client script (test_mcp_client.py) for MCP protocol testing
• curl test script (test_with_curl.sh) for REST endpoints
• All 16 tests passing ✅

✅ Documentation

• Created .env.example with all environment variables
• Updated README with authentication setup instructions
• Added test scripts for easy verification

Version

Bumped to v2.3.1

Breaking Changes

None - Authentication is optional and disabled by default

Test Results

All 16 unit tests passing ✅
- Authentication working with FastMCP Context ✅
- Backward compatible (no auth if WEBCAT_API_KEY not set) ✅

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Optional bearer token authentication via WEBCAT_API_KEY; tools validate requests when set.

• Refactor

  • Replaced SSE demo with FastMCP at /mcp; removed /demo endpoint and related capability mentions.
  • Updated health/root endpoint listings to reflect MCP-focused endpoints.

• Documentation

  • Replaced Docker Quick Start with local development workflow and optional auth setup.
  • Clarified usage notes and removed Docker Hub link.

• Chores

  • Version bumped to 2.3.1.
  • Added .env example with server, auth, and rate-limiting configs.

• Tests

  • Added auth utility tests and expanded search tool tests for auth paths.
  • Added MCP client test and curl-based health/status script.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

The changes replace the Docker-based demo/SSE flow with a FastMCP-mounted FastAPI app at /mcp, introduce optional bearer-token authentication via WEBCAT_API_KEY, update documentation and configs accordingly, remove the demo SSE endpoint, add test clients/scripts, and expand unit tests to cover authentication paths in tools.

Changes

Cohort / File(s)	Summary
Documentation & Config README.md, docker/.env.example	README switches from Docker quick start to local dev steps and documents optional auth via WEBCAT_API_KEY; adds .env example with server and rate-limit settings.
Versioning & Capabilities docker/constants.py	VERSION bumped 2.3.0 → 2.3.1; removed capabilities: "SSE streaming", "Demo UI client".
Server Endpoints & Health docker/endpoints/health_endpoints.py, docker/models/responses/health_responses.py	Removed /demo SSE route and related references; endpoint names updated ("main_mcp" → "mcp"); root/health metadata adjusted.
App Restructure (FastMCP mount) docker/simple_demo.py	Replaced custom SSE demo with FastMCP-integrated FastAPI app mounted at /mcp; removed SSE stream generator and demo client handling.
Auth Utilities docker/utils/auth.py	New optional bearer-token validator based on WEBCAT_API_KEY; extracts headers from MCP context; returns detailed failure reasons.
Tooling Integration (Auth) docker/tools/search_tool.py, docker/tools/api_tools_setup.py	search tool now accepts Context and validates bearer token before executing; returns early on auth failure.
Unit Tests (Tools & Auth) docker/tests/unit/tools/test_search_tool.py, docker/tests/unit/utils/test_auth.py	Tool tests patched to mock validate_bearer_token and include new cases for auth failures/context passing; new auth utility tests for multiple header/token scenarios.
Client & Scripts docker/test_mcp_client.py, docker/test_with_curl.sh	Added async MCP client test over SSE with optional Authorization; added curl script for health/status checks and guidance.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User as Client
  participant API as FastAPI (/mcp)
  participant Auth as validate_bearer_token
  participant Tool as search_tool
  participant Serper as Serper API

  User->>API: POST /mcp/tools.invoke(search, args, headers?)
  API->>Auth: validate_bearer_token(ctx)
  alt Auth required and valid
    Auth-->>API: (True, None)
    API->>Tool: search_tool(query, ctx)
    Tool->>Serper: fetch_with_fallback(query)
    Serper-->>Tool: results / none / error
    Tool-->>API: SearchResponse (dict)
    API-->>User: 200 OK (results or message)
  else Auth required and invalid
    Auth-->>API: (False, "reason")
    API-->>User: 401/403-equivalent payload (success: false, error)
  else Auth not configured
    Auth-->>API: (True, None)
    API->>Tool: search_tool(query, ctx)
    Tool->>Serper: fetch_with_fallback(query)
    Serper-->>Tool: results
    Tool-->>API: SearchResponse
    API-->>User: 200 OK
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Refactor #27 — Touches the same search_tool and its tests; overlaps directly with the new auth gating and unit updates.
• fixes for streamable and updated readme #16 — Adjusts MCP server exposure at /mcp and removes legacy SSE/demo paths, consistent with this PR’s server restructuring.
• updated readme #18 — Updates docs around WEBCAT_API_KEY and auth behavior, aligning with the README and config changes here.

Poem

A whisk of code, a hop to MCP,
Tokens tucked snug in .env’s keep.
No more demo streams that flee—
I nibble tools at path “/mcp”.
If you bear the key, then in you leap;
Otherwise, I still might peep. 🐇✨

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/bearer-auth-v2.3.1

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 91124d7 and b645ee6.

📒 Files selected for processing (13)

• README.md (4 hunks)
• docker/.env.example (1 hunks)
• docker/constants.py (1 hunks)
• docker/endpoints/health_endpoints.py (0 hunks)
• docker/models/responses/health_responses.py (2 hunks)
• docker/simple_demo.py (4 hunks)
• docker/test_mcp_client.py (1 hunks)
• docker/test_with_curl.sh (1 hunks)
• docker/tests/unit/tools/test_search_tool.py (4 hunks)
• docker/tests/unit/utils/test_auth.py (1 hunks)
• docker/tools/api_tools_setup.py (3 hunks)
• docker/tools/search_tool.py (2 hunks)
• docker/utils/auth.py (1 hunks)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}