v3.1.0: remote MCP, tool improvements, response store, release pipeline

[willwebster5]

Summary

Four feature batches landing as v3.1.0. Implemented in dependency order: release pipeline → remote MCP foundation → tool improvements → response store. All 95 existing tests pass; lint and format clean.

1. Release Pipeline (43abb46)

Tag-driven release.yml workflow. Push a v* tag to lint, test, validate that SERVER_VERSION matches the tag, build & push a Docker image to GHCR (versioned + latest), and publish a GitHub Release with auto-generated notes.

2. Remote MCP Server (8b5e24d) — SERVER_VERSION → 3.1.0

Per-client HTTP authentication so the server can run remotely and credential-less. stdio mode is unchanged.

• FalconClient.deferred() for credential-less startup; auth_object guarded against deferred misuse
• BaseModule._get_auth() / _service() resolve auth via a _session_client ContextVar (per-request isolation)
• New common/session_auth.py middleware extracts X-Falcon-Client-Id/Secret/Base-Url, OAuths, caches sessions (25 min TTL, LRU max 100), sets the ContextVar
• New common/health.py ASGI wrapper for /health (no auth)
• auth_middleware now also gates WebSocket scopes
• 10 modules refactored from __init__ service creation to per-call self._service(ServiceClass)
• Dockerfile (python:3.12-slim, non-root, port 8000) + .dockerignore

3. MCP Tool Improvements (7f0247f)

Cuts SOC agent friction observed during live triage:

• get_alerts: offset (native API pagination), q (server-side free-text search), pattern_name reimplemented as server-side FQL wildcard, max_results cap raised to 1000, summary_mode for compact rendering, next_offset in response
• alert_analysis: summary_mode with per-event-type field projection (NGSIEM/endpoint/cloud)
• ngsiem_query: fields parameter for server-side | select([...]) projection (skipped if query already has select()/table())
• FQL guides: full operator table (~, !~, *, ~*, ~*!), now timestamp keyword, corrected name field docs

4. Response Store (576f006)

Keeps the SOC triage agent inside the MCP tool loop when responses exceed the 20KB threshold. Structured tool output is stored as Python dicts before text formatting and queried via a new MCP tool — no Bash/grep over temp files.

• Root-level ResponseStore singleton (FIFO ring buffer, 50 entries)
• get_stored_response tool: query by ref_id with record_index, record_key (scans common ID fields), fields (dot-path projection), search, max_results
• list_stored_responses tool: summary of all stored references
• format_text_response() opt-in via new structured_data and metadata kwargs; tools that don't pass them keep the existing temp-file fallback
• alert_analysis, get_alerts, and ngsiem_query always store structured data (works on small responses too, not just truncation)

Test plan

• All 95 existing tests pass after refactor (pytest tests/)
• ruff check . clean
• ruff format --check . clean
• Manual: stdio mode regression — start server, list tools, run get_alerts/alert_analysis/ngsiem_query
• Manual: HTTP mode — start streamable-http, hit /health, verify 401 without X-Falcon-Client-* headers, verify success with valid headers
• Manual: pagination — get_alerts(max_results=50, offset=0) then offset=50, verify next_offset and total_available consistency
• Manual: response store — trigger a truncated alert_analysis, query the returned ref_id via get_stored_response
• Manual: tag-driven release — push a test v3.1.0-rc1 tag in a fork to verify the release workflow end-to-end before cutting v3.1.0

Out of scope

• Rate limiting / concurrency limits across HTTP clients
• Bearer token auth (clients pre-authenticate, pass short-lived token)
• TTL eviction or disk persistence for ResponseStore
• ECR push from the release workflow

🤖 Generated with Claude Code