π European Parliament MCP Server β Future State Diagrams
Planned State Management: Streaming, OAuth Sessions, Enhanced Cache, Real-Time Subscriptions
Future state machine documentation for EP MCP Server evolution
**π Document Owner:** Hack23 | **π Version:** 2.0 | **π
Last Updated:** 2026-03-19 (UTC)
**π Review Cycle:** Quarterly | **β° Next Review:** 2026-06-19
**π·οΈ Classification:** Public (Open Source MCP Server)
**β
ISMS Compliance:** ISO 27001 (A.5.1, A.8.1, A.14.2), NIST CSF 2.0 (ID.AM, PR.DS), CIS Controls v8.1 (2.1, 16.1)
---
## π Table of Contents
1. [Security Documentation Map](#security-documentation-map)
2. [Streaming Response States (v1.2)](#streaming-response-states-v12)
3. [Real-Time Subscription States (v1.2)](#real-time-subscription-states-v12)
4. [Enhanced Cache State Machine (v1.1)](#enhanced-cache-state-machine-v11)
5. [OAuth Session States (v2.0)](#oauth-session-states-v20)
6. [Circuit Breaker States (v1.1)](#circuit-breaker-states-v11)
7. [Webhook Delivery States (v2.0)](#webhook-delivery-states-v20)
---
## πΊοΈ Security Documentation Map
| Document | Current | Future | Description |
|----------|---------|--------|-------------|
| **Architecture** | [ARCHITECTURE.md](./ARCHITECTURE.md) | [FUTURE_ARCHITECTURE.md](./FUTURE_ARCHITECTURE.md) | C4 model, containers, components, ADRs |
| **Security Architecture** | [SECURITY_ARCHITECTURE.md](./SECURITY_ARCHITECTURE.md) | [FUTURE_SECURITY_ARCHITECTURE.md](./FUTURE_SECURITY_ARCHITECTURE.md) | Security controls, threat model |
| **Data Model** | [DATA_MODEL.md](./DATA_MODEL.md) | [FUTURE_DATA_MODEL.md](./FUTURE_DATA_MODEL.md) | Entity relationships, branded types |
| **Flowchart** | [FLOWCHART.md](./FLOWCHART.md) | [FUTURE_FLOWCHART.md](./FUTURE_FLOWCHART.md) | Business process flows |
| **State Diagram** | [STATEDIAGRAM.md](./STATEDIAGRAM.md) | [FUTURE_STATEDIAGRAM.md](./FUTURE_STATEDIAGRAM.md) | System state transitions |
| **Mind Map** | [MINDMAP.md](./MINDMAP.md) | [FUTURE_MINDMAP.md](./FUTURE_MINDMAP.md) | System concepts and relationships |
| **SWOT Analysis** | [SWOT.md](./SWOT.md) | [FUTURE_SWOT.md](./FUTURE_SWOT.md) | Strategic positioning |
---
## π Streaming Response States (v1.2)
MCP streaming support for long-running tool operations:
```mermaid
stateDiagram-v2
[*] --> StreamRequested : tool_call with streaming=true
StreamRequested --> StreamValidating : Input validation starts
StreamValidating --> StreamRejected : Validation fails
StreamValidating --> StreamInitializing : Validation passes
StreamRejected --> [*] : Error response sent
StreamInitializing --> StreamHeaderSent : stream_start event emitted
StreamHeaderSent --> ChunkPhase1 : Phase 1 processing starts
ChunkPhase1 --> Chunk1Emitted : Phase 1 data ready
Chunk1Emitted --> ChunkPhase2 : Phase 2 processing starts
ChunkPhase2 --> Chunk2Emitted : Phase 2 data ready
Chunk2Emitted --> ChunkPhase3 : Phase 3 processing starts
ChunkPhase3 --> Chunk3Emitted : Phase 3 data ready
Chunk3Emitted --> ChunkPhase4 : Phase 4 processing starts
ChunkPhase4 --> Chunk4Emitted : Final chunk ready
Chunk4Emitted --> StreamCompleted : stream_end event emitted
ChunkPhase1 --> StreamError : Phase error
ChunkPhase2 --> StreamError : Phase error
ChunkPhase3 --> StreamError : Phase error
ChunkPhase4 --> StreamError : Phase error
StreamError --> StreamCompleted : stream_error + stream_end emitted
StreamCompleted --> [*]
note right of StreamHeaderSent
Emits immediately to client.
Informs client to expect
multiple chunks.
Contains: tool, estimated_chunks
end note
note right of StreamError
Partial results may be
delivered before error.
Client receives what was
computed successfully.
end note
```
---
## π‘ Real-Time Subscription States (v1.2)
Client subscription lifecycle for EP data change notifications:
```mermaid
stateDiagram-v2
[*] --> SubscriptionRequested : subscribe() called with event types
SubscriptionRequested --> Authenticating : Auth check (v2.0+)
Authenticating --> AuthFailed : Invalid credentials
AuthFailed --> [*] : Subscription rejected
Authenticating --> ValidatingEvents : Auth passed
SubscriptionRequested --> ValidatingEvents : (no auth in v1.2 local mode)
ValidatingEvents --> InvalidEvents : Unknown event types requested
InvalidEvents --> [*] : Subscription rejected (list valid types)
ValidatingEvents --> Active : Subscription created (ID assigned)
Active --> Receiving : EP data change event arrives
Receiving --> Active : Event delivered to client
Active --> Paused : Client sends pause signal
Paused --> Active : Client sends resume signal
Active --> Closing : Client calls unsubscribe()
Paused --> Closing : Client calls unsubscribe()
Active --> Closing : Server shutdown detected
Active --> Closing : Auth token expired (v2.0)
Closing --> Closed : Cleanup complete (remove from registry)
Closed --> [*]
note right of Active
Subscription ID returned.
Client receives events via:
- SSE (v1.2)
- WebSocket (v1.2)
- GraphQL subscription (v2.0)
end note
note right of Paused
Events buffered (max 1000).
Delivered on resume.
Buffer overflow: oldest dropped.
end note
```
---
## πΎ Enhanced Cache State Machine (v1.1)
Two-tier cache (LRU + Redis) state management:
```mermaid
stateDiagram-v2
[*] --> L1Empty : Server starts (L1 empty)
[*] --> L2Check : Redis configured
L2Check --> L2Warmup : Redis available
L2Check --> L1Empty : Redis unavailable (fallback to L1 only)
L2Warmup --> L1Warmed : Frequently accessed keys pre-loaded to L1
L1Empty --> L1Miss : Cache lookup (no entry)
L1Warmed --> L1Hit : Cache lookup (entry found, fresh)
L1Warmed --> L1Stale : Cache lookup (entry found, TTL expired)
L1Warmed --> L1Miss : Cache lookup (entry not in L1)
L1Miss --> L2Hit : L2 Redis lookup success
L1Miss --> BothMiss : L2 Redis miss
L2Hit --> L1Populated : Write to L1 (promote from L2)
L1Populated --> L1Hit : Next lookup served from L1
BothMiss --> Fetching : Fetch from EP API
Fetching --> L1Written : Write to L1 (15-min TTL)
L1Written --> L2Written : Write to L2 (60-min TTL)
L2Written --> L1Hit : Data available
L1Stale --> BackgroundRefresh : Stale-while-revalidate (v1.1)
BackgroundRefresh --> L1Hit : Background fetch updates L1
L1Stale --> L1Stale : Stale value returned while refreshing
L1Hit --> [*] : Data returned (~1ms)
L2Hit --> [*] : Data returned (~5ms)
note right of L2Warmup
On startup, Redis keys
with remaining TTL are
pre-loaded to L1 cache.
Reduces EP API calls
after restart.
end note
```
---
## π OAuth Session States (v2.0)
User session lifecycle for HTTP transport with OAuth 2.0:
```mermaid
stateDiagram-v2
[*] --> Anonymous : HTTP request without token
Anonymous --> Authenticating : Bearer token presented
Authenticating --> TokenInvalid : JWT signature invalid
Authenticating --> TokenExpired : JWT expiry check fails
Authenticating --> TokenValid : JWT valid, claims extracted
TokenInvalid --> [*] : 401 response
TokenExpired --> RefreshFlow : Refresh token available
TokenExpired --> [*] : 401 response (no refresh token)
RefreshFlow --> Refreshing : POST to token endpoint
Refreshing --> TokenValid : New access token received
Refreshing --> RefreshFailed : Refresh token expired/invalid
RefreshFailed --> [*] : 401 - re-authentication required
TokenValid --> RBACCheck : Check tool permissions
RBACCheck --> Authorized : Role has tool permission
RBACCheck --> Forbidden : Role lacks permission
Forbidden --> [*] : 403 response
Authorized --> Active : Session established
Active --> Active : Subsequent requests (token cached 5 min)
Active --> TokenExpired : Token TTL reached
Active --> SessionRevoked : Admin revokes session
Active --> SessionEnded : User logs out / timeout
SessionRevoked --> [*] : 401 response
SessionEnded --> [*]
note right of Active
Token validation results
cached for 5 minutes.
Avoids JWKS call on
every request.
end note
note right of Anonymous
In v2.0, anonymous access
allowed only for localhost
or with specific config.
Production requires auth.
end note
```
---
## β‘ Circuit Breaker States (v1.1)
EP API circuit breaker state machine:
```mermaid
stateDiagram-v2
[*] --> Closed : Initialized (normal operation)
Closed --> Closed : Request succeeds
Closed --> RecordingFailure : Request fails
RecordingFailure --> Closed : Failure count below threshold (5)
RecordingFailure --> Open : Failure threshold reached
Open --> Open : Requests fast-fail (no API call)
Open --> HalfOpen : Timeout elapsed (30 seconds)
HalfOpen --> Closed : Probe request succeeds (circuit reset)
HalfOpen --> Open : Probe request fails (extend open period)
note right of Closed
Normal operating state.
All API calls pass through.
Failure counter tracked.
Reset on success.
end note
note right of Open
EP API assumed unreachable.
All requests fast-fail.
Cached data returned if available.
Otherwise: circuit open error.
end note
note right of HalfOpen
Single probe allowed.
Tests if EP API recovered.
Success: fully close circuit.
Failure: reopen for 30s.
end note
```
---
## π Webhook Delivery States (v2.0)
Individual webhook delivery attempt state machine:
```mermaid
stateDiagram-v2
[*] --> Pending : Event detected, webhook matched
Pending --> Signing : Create HMAC signature
Signing --> Sending : HTTP POST initiated
Sending --> Delivered : HTTP 200 received
Sending --> TemporaryFailure : HTTP 4xx/5xx received
Sending --> NetworkFailure : Connection timeout/error
Delivered --> [*] : Success logged in audit trail
TemporaryFailure --> WaitingRetry1 : Schedule retry 1 (after 1 min)
NetworkFailure --> WaitingRetry1 : Schedule retry 1 (after 1 min)
WaitingRetry1 --> Retry1 : Retry 1 attempt
Retry1 --> Delivered : HTTP 200 received
Retry1 --> WaitingRetry2 : Still failing (after 5 min)
WaitingRetry2 --> Retry2 : Retry 2 attempt
Retry2 --> Delivered : HTTP 200 received
Retry2 --> WaitingRetry3 : Still failing (after 15 min)
WaitingRetry3 --> Retry3 : Final retry attempt
Retry3 --> Delivered : HTTP 200 received
Retry3 --> PermanentFailure : All retries exhausted
PermanentFailure --> [*] : Alert webhook owner, disable webhook
note right of PermanentFailure
After 3 retries (total 4 attempts),
webhook marked as failed.
Owner notified via email/notification.
Webhook auto-disabled after
5 consecutive permanent failures.
end note
```
---
*See [STATEDIAGRAM.md](./STATEDIAGRAM.md) for the current implemented state machines.*