ContextDesk: Operational Context MCP for Alexa+

Inspiration

During local software development and deployment, engineers constantly face disruptive context-switching. Pinpointing a sudden failure requires leaving the editor, running shell commands, tailing unstructured build logs, manually tracking down line coordinates, and cross-checking service ports across markdown files.

With the emergence of conversational agents like Alexa+, we saw an opportunity to bring hands-free operational intelligence to the developer’s desk[cite: 1]. Instead of manually grepping through terminal screens, developers should be able to ask: "Alexa, why did my build fail?" or "Alexa, restart the payment service"[cite: 2].

However, connecting an assistant to local developer workspaces introduces severe risks: external cloud LLMs can hallucinate line numbers, introduce network latency, cost money, or inadvertently exfiltrate credentials found in stack traces[cite: 1, 3]. We were inspired to build ContextDesk: a zero-dependency, open-standard Model Context Protocol (MCP) server over Streamable HTTP that provides deterministic diagnostics, strict boundary isolation, and cryptographic safety for developer operations[cite: 1, 3].

What it does

ContextDesk serves as a high-assurance Model Context Protocol (MCP 2025-11-25+) Streamable HTTP server operating on loopback (127.0.0.1:8000)[cite: 1, 3]. It powers an Alexa+ Web Simulator with live Server-Sent Events (SSE) telemetry and Web Speech audio playback[cite: 1, 2]:

• Deterministic Diagnostic Engine (inspect_build_logs): Parses build traces and stack traces in ( <5\text{ ms} ) using pure Python regex parsing[cite: 1, 3]. It pinpoints the exact file and line coordinates (e.g., PaymentController.java:42) with zero external model hallucinations[cite: 1, 2, 3].
• Automated Multi-Pattern Secret Scrubber: Redacts AWS access keys (AKIA...), HTTP Bearer tokens, passwords, GitHub PATs, Slack tokens, and private keys before any diagnostic data reaches the agent or client display[cite: 1, 3].
• Replay-Proof Two-Tier Barrier (execute_service_action): Protects mutating operational commands (restart_service, flush_cache, rollback_deployment)[cite: 1, 3]. Tier 1 issues a 60-second time-boxed challenge signed via HMAC-SHA256[cite: 1, 3]. Tier 2 verifies the cryptographic signature and enforces atomic single-use nonce consumption: $$ \text{nonce} \notin \mathcal{S}_{\text{consumed}} $$ Replay attempts with the same token are immediately rejected[cite: 1, 3].
• Local Codebase Context Search (query_codebase_context): Uses an in-memory SQLite FTS5 full-text search engine to index workspace documentation and retrieve architecture port definitions (e.g., Auth on 8080, Payment on 8081)[cite: 1, 3, 4].
• Real-Time Protocol Inspection: A dual-panel developer console that streams intermediate notifications/progress chunks and final JSON-RPC 2.0 envelopes over text/event-stream alongside voice interactions[cite: 1, 2].

How we built it

We built ContextDesk strictly to the MCP Streamable HTTP transport specification with zero external daemons or cloud dependencies[cite: 1, 3]:

• Transport & RPC Dispatcher: Built using pure Python with FastAPI and Uvicorn over loopback[cite: 1, 3]. We implemented a unified POST /mcp handler processing JSON-RPC 2.0 requests (initialize, tools/list, and tools/call) with chunked SSE streaming (text/event-stream)[cite: 1, 3].
• DNS-Rebinding & Origin Guard: Host and Origin headers are validated via urllib.parse.urlsplit against a loopback allowlist (127.0.0.1, localhost, ::1)[cite: 1, 3]. The server explicitly rejects Origin: null with HTTP 403 Forbidden to prevent sandboxed <iframe> escalation attacks[cite: 1, 3].
• Windows-Safe Path Containment: Filesystem operations are strictly confined to ./workspace using canonical path resolution: $$ \text{commonpath}\left(\left[\text{base_dir}, \text{candidate_abs}\right]\right) == \text{base_dir} $$ Colons (:) and leading slashes are stripped or rejected to block Windows drive-letter escapes and NTFS Alternate Data Streams (ADS)[cite: 1, 3].
• Cryptographic Nonce Store: Confirmation tokens are generated by signing action payloads with HMAC-SHA256: $$ \tau = \text{HMAC-SHA256}_{K}\left(\text{action} \parallel \text{timestamp} \parallel \text{nonce}\right) $$ An in-memory dictionary protected by a threading.Lock validates and burns nonces atomically to enforce single-use authorization[cite: 1, 3].
• Client Interface: Built as a responsive single-file console in index.html using Tailwind CSS, the browser-native Web Speech API, and a custom SSE stream decoder that parses raw incoming wire events[cite: 1, 2].

Challenges we ran into

1. Streamable HTTP SSE Buffering & Progress Semantics: Emitting intermediate notifications/progress chunks unconditionally caused stream desynchronization on standard callers[cite: 1]. We resolved this by adhering strictly to the MCP specification: progress frames are emitted over SSE only when the caller explicitly includes a _meta.progressToken[cite: 1, 3].
2. Loopback CORS & Sandboxed Iframe Pivot (Origin: null): Local developer interfaces often default to accepting Origin: null[cite: 1]. However, malicious web pages can embed <iframe sandbox="allow-scripts">, which transmits an Origin: null header to pivot cross-origin requests onto local loopback endpoints[cite: 1]. We solved this by rejecting Origin: null with an explicit HTTP 403 Forbidden[cite: 1, 3].
3. Windows Path Canonicalization Quirks: On Windows, paths like "/build.log" evaluate to true for os.path.isabs(), triggering false-positive traversal alerts. We addressed this by stripping leading path separators and rejecting colons (:) before resolving candidate paths with os.path.realpath and os.path.commonpath[cite: 1, 3].
4. Token Replay Vulnerability in Mutating Actions: Time-based tokens can be replayed repeatedly within their 60-second validity window[cite: 1, 3]. We introduced an in-memory, thread-safe single-use nonce ledger (_consume_nonce) that burns tokens immediately upon their first successful execution[cite: 1, 3].

Accomplishments that we're proud of

• Zero-Hallucination, 5ms Diagnostics: Built a deterministic log analysis pipeline that identifies root-cause line numbers and exceptions instantly without relying on opaque LLM calls or cloud APIs[cite: 1, 3].
• Comprehensive Test Suite: Achieved an 8-test validation suite covering handshake protocol versioning, tool discovery, path traversal rejection (-32602), NPE extraction, secret redaction, token single-use burning, Origin: null rejection, and 202 Accepted notifications[cite: 1, 5].
• Zero-Cost, Zero-Config Portability: The entire server runs out of the box with standard Python libraries and lightweight web primitives—no Docker containers, background Ollama daemons, or paid API keys required[cite: 1, 3].
• Principal-Grade Threat Model: Successfully implemented a defense-in-depth model that addresses DNS rebinding, secret exposure, token replay, and cross-platform path traversal[cite: 1].

What we learned

• Model Context Protocol (MCP) Streamable HTTP: Gained direct experience implementing the 2025-11-25+ MCP standard over HTTP and chunked SSE streaming, learning the subtle protocol differences between intermediate notifications and final response envelopes[cite: 1, 3].
• Defensive Engineering for Developer Agents: Realized that local developer tools require even stricter origin and path validation than public web apps because they have direct access to local files and shell environments[cite: 1, 3].
• The Power of Deterministic Grounding: Learned that operational tooling is often significantly faster, safer, and more reliable when powered by deterministic parsing and cryptographic checks rather than purely probabilistic language models[cite: 1, 3].

What's next for ContextDesk: Operational Context MCP for Alexa+

• Native IDE Extensions: Package ContextDesk as a lightweight VS Code and JetBrains background plugin so developers can query logs and runbooks directly from their active development environment.
• Out-of-Band Hardware Authorization: Extend Tier 2 confirmation to support physical confirmation buttons on Alexa devices or FIDO2/WebAuthn security keys for critical production rollbacks.
• Automated Log Rotation & Tail Buffering: Introduce memory-bounded circular buffers (collections.deque) to inspect multi-gigabyte production server logs without reading entire files into memory.
• Expanded Multi-Service Registry: Add adapter tools for Docker container metrics, Kubernetes pod status, and local Git branch conflict analysis.

Built With

• alexa
• anyio
• devops
• fastapi
• fts5
• hmac
• httpx
• javascript
• json-rpc
• mcp
• model-context-protocol
• pytest
• python
• rest
• security
• server-sent-events
• sqlite
• sre
• sse
• streamable-http
• tailwindcss
• uvicorn
• web-speech-api
• zero-dependency