reflex-mcphost 0.1.0__tar.gz

reflex_mcphost-0.1.0/.gitignore

@@ -0,0 +1,227 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# reflex-mcphost
+/spikes/
+.web/
+coverage.json
+.idea/
+.claude/worktrees/

reflex_mcphost-0.1.0/CHANGELOG.md

@@ -0,0 +1,174 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
+project adheres to [Semantic Versioning](https://semver.org/) (Constitution Art. 9).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-01
+
+First release (date set in the release PR, F8-07b); no `0.1.0a1` / `0.1.0b1`
+pre-releases were published (owner decision 2026-11-01). Highlights: an MCP **host** on both
+protocol eras (`2026-07-28`, `2025-11-25`) over stdio and Streamable HTTP, a fail-closed
+consent layer with a local audit log, OAuth 2.1 for remote Servers, an agent bridge
+(`Toolset`, PydanticAI, LangGraph), an embeddable Reflex UI with the `reflex-mcphost`
+reference app and CLI, and MCP Apps (`2026-01-26`) in sandboxed Views.
+
+### Added
+- Project scaffold: `pyproject.toml` (hatchling, src layout, extras `pydantic-ai`,
+  `langgraph`, `all`; dependency groups `dev`, `test`, `docs`), package skeleton.
+- Agent bridge (Phase 5): `Host.toolset(consumer, include=, exclude=)` and
+  `reflex_mcphost.toolset` (`Toolset`, `ToolSpec`, `ToolCallOutcome`) — live listing of
+  model-visible tools of ready Servers, deterministic collision-free aliases
+  (`^[A-Za-z0-9_-]{1,64}$`), FQN / server-id glob filters, calls only through the
+  consent-checked `Invoker`, every outcome (including denial) returned as agent text.
+- `reflex_mcphost.adapters.pydantic_ai.as_pydantic_ai_toolset` (extra `pydantic-ai`): a
+  PydanticAI `AbstractToolset`, re-listed every run step; errors as `ToolFailed`.
+- `reflex_mcphost.adapters.langgraph.as_langchain_tools` (extra `langgraph`): async-only
+  LangChain `BaseTool`s with the Server's JSON schema; errors as
+  `ToolMessage(status="error")`, so a LangGraph `ToolNode` never fails the graph.
+- `AuthorizationFlow` and `SamplingProvider` are exported from `reflex_mcphost`.
+- `docs/library.md`: using the Host from PydanticAI and LangGraph agents.
+- Reflex UI (Phase 6, `reflex_mcphost.ui`): `install(app, host_factory)` (one Host per
+  backend as a lifespan task, `ReflexPrompter` bound, Host/Origin loopback guard from the
+  Reflex `deploy_url`), the components `servers_panel`, `catalog_browser`,
+  `consent_center`, `permissions_table` and `audit_table`, `HostState` and `HostRuntime`;
+  embeddable in any Reflex app.
+- CLI `reflex-mcphost` (API §6): `run` (also the bare command; `--host`, `--port`,
+  `--no-browser`, `--config`, `--unsafe-allow-remote`, `--log-json`; UI and backend on one
+  loopback port, exit codes 0/2/3), `servers [--json] [--strict] [--config]` and
+  `--version`. The packaged reference app (Servers, Catalog, Permissions, Audit) runs from
+  a per-user workspace, never from site-packages.
+- E2E tests (marker `e2e`, CI job `e2e`): headless smoke of the built wheel and Playwright
+  flows; `playwright` joins the `test` dependency group.
+- MCP Apps (Phase 7, MCP Apps `2026-01-26`): an allowed invocation started from the Host
+  UI of a tool with `_meta.ui.resourceUri` renders the Server's App as a View after it
+  ends (`mcp_app_frame()`, shown by `catalog_browser`; one View per tab). Views run in a
+  sandbox proxy on `http://localhost:<proxy_port>` (an origin distinct from the UI's
+  `http://127.0.0.1:<port>`, served by a minimal `h11` listener on `127.0.0.1` and `::1`)
+  inside an opaque-origin `srcdoc` frame (`sandbox="allow-scripts"`, no device
+  permissions) with a CSP built only from the resource's validated `_meta.ui.csp` entries
+  (invalid entries are left out, logged and listed in a notice; no `'unsafe-eval'`).
+- App bridge: `ui/initialize`, `tool-input` / `tool-result` / `tool-cancelled`,
+  `ui/resource-teardown` (`replaced`, `closed`, `server_removed`, `host_closing`; ≤ 2 s),
+  `tools/call` through the `Invoker` as the Consumer `app:<server_id>` (consent card and
+  audit record per call; only the View's own Server and App-visible tools), `resources/read`,
+  `ui/open-link` (`http`/`https` only, after a confirmation showing the full URL),
+  `notifications/message` and `size-changed`; every View RPC is logged as
+  `method → outcome` in the Server's log stream, never with its content. The relay on the
+  UI origin is data-only and accepts messages only from the proxy window it created.
+- The Client declares the `io.modelcontextprotocol/ui` extension (both eras) only while
+  Views can render (`Host.set_mcp_apps`).
+- Resource limits (API §7): no View for a resource without content for its URI, of another
+  MIME type, not valid UTF-8 or larger than 5 MiB — a notice names the reason; a 1 MiB
+  message limit on the relay.
+- `scripts/check_wheel.py` requires the MCP Apps assets
+  (`reflex_mcphost/ui/proxy/proxy.html`, `reflex_mcphost/ui/assets/mcp_app_relay.js`) in
+  the wheel.
+- E2E: MCP Apps on Chromium, Firefox and WebKit (the S-3 isolation and forgery contract);
+  the CI `e2e` job installs the three engines.
+
+- Hardening (Phase 8):
+  - Server-provided regular expressions (`pattern`, `patternProperties`, `format: regex`
+    checks) run only through the `regex` engine with a 50 ms per-match and 250 ms
+    per-validation bound; a catastrophic pattern ends the request instead of blocking the
+    event loop. New runtime dependency `regex>=2026.9`.
+  - The `Invoker` re-resolves a tool after consent (step 4a): a definition that changed
+    while the prompt was open denies the call (`definition_changed`, one audit record, no
+    second prompt).
+  - Every stdio transport close signals the Server's whole process group (POSIX) / Job
+    Object (Windows), so grandchildren of a Server do not outlive it.
+  - `UnknownToolError` (also a `KeyError`) for an alias not in the current `Toolset`
+    listing; `SecretStoreError` when a sign-out cannot delete the stored credentials.
+  - Event `consent.rules_changed` (`ConsentRulesChanged`, exported from `reflex_mcphost`
+    like every other event; rule ids and change kind, never argument values); the
+    Permissions view refreshes in every tab.
+  - Client ID Metadata Document URL (the default `oauth_client_metadata_url`, frozen from
+    this release on): `https://blog.seraph.to/reflex-mcphost/oauth/client.json` (GitHub
+    Pages under the owner's custom domain; the `github.io` address redirects, which a CIMD
+    `client_id` must not).
+  - `AuthorizationError` reason `secret_store_unavailable`: an authorization whose stored
+    credentials cannot be read (e.g. a locked keyring) says so instead of
+    `discovery_failed` (no backend text).
+  - The UI guard adds `Referrer-Policy: no-referrer` to every response; `install()` refuses
+    to start with a state manager other than MEMORY.
+  - The sandbox proxy caps concurrent connections at 32 (`503`, `Retry-After: 1`); a View
+    that navigates its own frame away is closed.
+  - The CLI prunes workspaces of other versions unused for 7 days (and interrupted build
+    leftovers after 1 day); only directories it created and marked.
+- `docs/user-guide.md` (the reference app) and the embedder rules in `docs/library.md`;
+  README and docs examples are executed by the test suite.
+- `release.yml` job `verify`: after `publish`, installs the release from PyPI on Linux,
+  macOS and Windows and runs `--version`, `servers --json` and (Linux) `run --no-browser`
+  until `/ping` answers; it holds no `id-token`.
+
+### Changed
+- Development status classifier: `4 - Beta`.
+- The `mcp` SDK's own tool-result validation is turned off per session; the Invoker's
+  bounded output-schema check is the only one (the SDK's would run Server patterns
+  unbounded). A failing result is `protocol_error` with code `output_schema_mismatch` or
+  `missing_structured_content`, and its content is dropped.
+- The adapters convert only `UnknownToolError` into "Tool is no longer available"; any
+  other exception propagates.
+- CI: the REQ-coverage gate is strict for every requirement family; a `ResourceWarning`
+  fails the test run.
+
+### Fixed
+- Catalog view: the list now re-renders when the catalog changes (explicit dependencies of
+  `HostState.catalog_shown` / `catalog_more`).
+- Consent center: elicitation, sampling-edit and review-edit forms submit again (the card id
+  travels in a hidden field; the browser raised `card_rx_state_ is not defined`).
+- Sandbox proxy: Views render in Firefox (Firefox reports the proxy frame's
+  `location.ancestorOrigins` as `"null"` for the relay's `referrerpolicy="no-referrer"`
+  iframe, which the proxy took for a foreign embedder).
+- Sign-out forgets the in-memory tokens before deleting the stored ones: a secret store
+  that fails during sign-out can no longer leave the Server signed in.
+- A refused authorization URL cancels the OAuth flow at once (the Server is back in
+  `auth_required` and Authorize works again) instead of waiting for the flow's deadline.
+- Links opened from an MCP App View no longer send the Host UI's address as referrer.
+
+### Known limitations
+- JSON Schema `format` is not enforced (annotation only) for tool arguments and results.
+- Token expiry is unknown after a restart: tokens reloaded from the secret store carry no
+  expiry, so the first `401` triggers the one refresh instead of a proactive one.
+- A Server that re-prompts an elicitation (invalid content) gets a new consent card with
+  the same id; the previous form is not kept open.
+- Server media in results: only `data:` images of type PNG, JPEG, GIF or WebP up to
+  8 MiB are shown; SVG and other types are a placeholder naming the type.
+- `ui/notifications/host-context-changed` is never sent to Views (fixed light theme, no
+  container size reports).
+- The E2E suite (headless smoke, Playwright, MCP Apps) runs on Linux only; macOS and Windows
+  run every other test.
+- HTTP+SSE transport fallback (REQ-CON-013) is deferred to v0.2; VS Code `type: "sse"`
+  entries do not connect.
+- MCP App Views render only for invocations started from the Host UI, and only after the
+  invocation has ended (no streaming of partial input, no View for agent or App
+  invocations).
+- A View that navigates its own frame away is detected and closed, but the navigation
+  itself may already have carried what the Host sent the View (tool input and result); CSP
+  has no directive that prevents it. Residual risk, Technical Design §6.1.
+- Real Safari is not verified: the MCP Apps E2E runs on WebKit through Playwright's WPE
+  build (alongside Chromium and Firefox); no manual pass on Apple Safari was made (owner
+  decision; Plan R-8, accepted residual risk).
+- Client ID Metadata Documents are not verified against a real authorization server
+  (spike S-4, closed with plan B): the CIMD URL is offered first, and the DCR and
+  configured-`client_id` fallbacks are tested against the fixture authorization server. If
+  an authorization server rejects the document, set `[servers.<id>.oauth] client_id`.
+- MCP Apps are disabled in remote mode (`--unsafe-allow-remote`) and whenever the sandbox
+  proxy cannot run or `localhost` does not resolve to loopback only.
+- Tool results are checked against `outputSchema` only by the Host's bounded validator; the
+  `mcp` SDK's own result validation is bypassed by design (see Changed).
+- Process-group cleanup (POSIX) signals the group by the leader's id after the leader has
+  exited; in the short window before the signal the id could in theory be reused.
+- If the keyring fails while tokens are saved, the tokens stay in memory for the Host's
+  lifetime only (nothing is persisted; sign in again after a restart). A keyring that fails
+  while tokens are read fails the authorization with reason `secret_store_unavailable`.
+- A Host data directory that already exists keeps its mode (the files inside are `0600`);
+  one the Host creates is `0700`.
+- Workspace pruning removes another version's workspace unused for 7 days even if a
+  long-running session of that version still uses it.
+- `reflex_mcphost.ui.models` reaches `starlette` through the `mcp` SDK, so its import
+  contract forbids only `reflex`.
+- Embedding apps must set `state_manager_mode="memory"` and run one backend worker (the UI
+  refuses to start otherwise; see `docs/library.md`).

reflex_mcphost-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ernesto Crespo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.