IMPLEMENTATION

Rosetta Implementation Summary

This file is a durable summary of the current implementation state. It is intentionally concise and should not be used as a chronological work log.

For detailed change history, use git history and PRs instead of expanding this file.

Current State

• Rosetta is an OSS instruction platform with:
• a Python MCP server in `src/rosetta-mcp-server/`
• a Python CLI in `src/rosetta-cli/`
• public documentation in `docs/` and `docs/web/`
• deployment examples under `deployment/`
• The MCP server supports both `stdio` and HTTP transports.
• HTTP mode supports OAuth-based authentication, session storage, and policy-based authorization.
• The CLI supports publish, verify, list, parse, cleanup, and related packaging flows.
• The repository contains both user-facing OSS docs and contributor-oriented implementation notes.

Major Implemented Workstreams

MCP Server

• Refactored into a modular package structure with dedicated `config`, `context`, `services`, `tools`, `auth`, and `analytics` modules.
• PostHog analytics parity restored in `rosetta_mcp/analytics/tracker.py`: added `$referring_domain`, `$screen_name`, `$title`, `error_type`/`error_message` on soft errors, `$pageview` and `$web_vitals` events, `error_status_code` on HTTP exceptions, `$browser`/`$browser_version` in exception context, `on_error` logging on Posthog constructor, inner try/except isolating analytics failures from tool results; all exception sites use `logger.warning`. Fixed `feedback.py` `distinct_id` to `call_ctx.username` (was composite `username@repository`). 18 new test cases added covering all acceptance criteria including boundary conditions.
• Core MCP tools are implemented, including:
• `get_context_instructions`
• `query_instructions`
• `list_instructions`
• `submit_feedback`
• `query_project_context`
• `store_project_context`
• `discover_projects`
• `plan_manager`
• Added HTTP transport support on top of the existing `stdio` mode.
• Added Redis-backed session and plan storage with in-memory fallbacks for local development.
• Added OAuth/OIDC integration for HTTP deployments, including introspection-based validation and offline-refresh handling.
• Added a FastMCP loopback redirect compatibility patch so CIMD-based OAuth clients using ephemeral localhost callback ports can complete HTTP authentication.
• Added origin validation and cross-tool hardening around invalid inputs, malformed requests, and wrapper failures.
• Added response-shape and schema cleanup so tool contracts are more predictable for coding agents.
• MCP dataset lookup caches dataset objects as well as name/id mappings, avoiding repeated dataset-open calls during instruction/resource/project tool execution.
• Analytics repository detection caches MCP roots per HTTP session and uses a fixed singleton cache key for STDIO/local transports.

MCP Server — HTTP Observability + RC1 Hang Fix (rosetta-mcp-http-observability)

• **RC1 fix (A3/A4):** All sync RAGFlow calls that previously blocked the asyncio event loop are now offloaded via `asyncio.to_thread` + `asyncio.wait_for` using the new `offload()` helper in `tracing.py`. Leaf sites: `list_docs_with_keyword_fallback`, `ragflow.retrieve` in `tools/instructions.py`; `doc_cache.get_all_docs_async` in `clients/doc_cache.py` (used by `list_instructions` and `read_instruction_resource`). Cache reads/writes remain on the event-loop thread (SPECS A-1).
• **RAGFlow timeout injection (A2/DD-3):** `_traced_http_method` in `tracing.py` now calls `kwargs.setdefault("timeout", _get_ragflow_http_timeout())` before every RAGFlow HTTP call, defaulting to 60s.
• **Redis socket timeouts (A5/DD-4):** `_build_redis_store` in `server.py` appends `socket_timeout`, `socket_connect_timeout`, and `health_check_interval` query params to the Redis URL when not already present.
• **OAuth/OIDC timeouts (A6):** `IntrospectionTokenVerifier` and `OIDCProxy` in `auth/oauth.py` now receive `timeout_seconds=config.oauth_http_timeout` (default 10s).
• **Exception cause chain (A7):** `_retry_once` raises `RuntimeError(...) from last_exc` so `__cause__` is preserved.
• **In-flight watchdog (A8/REQ-OBS-6):** OS-thread daemon (`threading.Thread`) started in `main()` before `asyncio.run`; reads `_INFLIGHT_REGISTRY` under a `threading.Lock`; WARN-logs slow requests and calls `faulthandler.dump_traceback()` on stuck entries.
• **9 env knobs (A1):** Added `ENV_*` + `DEFAULT_*` constants to `constants.py` and dataclass fields + `os.getenv` parsing to `config.py` for all 9 observability/timeout knobs.
• **RequestLoggingMiddleware repositioned (B1/DD-5):** Now wraps the return value of `mcp.http_app(...)` as the outermost ASGI layer, so auth-rejected requests are also logged.
• **Response-started flag ordering fixed (B2):** Flag set AFTER `await send(message)` succeeds, not before.
• **Response completion + disconnect logging (B3):** `http.response.body` with `more_body=False` logs completion; `_wrapped_receive` detects `http.disconnect`/`websocket.disconnect` and logs disconnect.
• **SSE chunk tracing (B4/REQ-OBS-5):** `_send` wrapper logs one compact INFO per SSE chunk (seq+bytes); payload only under DEBUG.
• **Error logging (C1):** Added `logger.error`/`logger.exception` at all `return "Error: ..."` sites in `tools/instructions.py` and `tools/resources.py`.
• **exc_info in tracing (C3):** `traced_execution` and `_traced_http_method` failures now log with `exc_info=True`.
• **Transport loggers wired (C4):** `mcp.server.streamable_http` and `mcp.server.streamable_http_manager` loggers attached to the rosetta-mcp handler at startup.
• **Origin-block log (C5/REQ-OBS-7):** `OriginValidationMiddleware` now WARN-logs rejected origins with origin/path/client.
• **`/healthz` endpoint (D1-D3):** Registered via `@mcp.custom_route("/healthz", methods=["GET"])`; genuinely unauthenticated (no `RequireAuthMiddleware`); probes RAGFlow off-loop via `asyncio.to_thread` + `asyncio.wait_for(timeout