mcp-gtw 0.0.1__tar.gz

mcp_gtw-0.0.1/.claude/settings.json

@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(~/Developer/workspaces/**)",
+      "Write(~/Developer/workspaces/**)",
+      "Edit(~/Developer/workspaces/**)",
+      "MultiEdit(~/Developer/workspaces/**)",
+      "Glob(~/Developer/workspaces/**)",
+      "Grep(~/Developer/workspaces/**)",
+      "LS(~/Developer/workspaces/**)",
+
+      "Bash(*)",
+
+      "WebFetch(*)",
+      "WebSearch",
+
+      "mcp__my-gateway"
+    ],
+    "deny": [
+      "Read(~/Developer/workspaces/**/.env)",
+      "Read(~/Developer/workspaces/**/secrets/**)",
+      "Read(~/Developer/workspaces/**/*.pem)",
+      "Read(~/Developer/workspaces/**/*.key)",
+      "Bash(rm -rf *)",
+      "Bash(sudo rm *)"
+    ]
+  }
+}

mcp_gtw-0.0.1/.dockerignore

@@ -0,0 +1,16 @@
+.env
+.env.*
+.venv/
+__pycache__/
+*.pyc
+.git/
+.github/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+coverage.xml
+.coverage
+.DS_Store

mcp_gtw-0.0.1/.editorconfig

@@ -0,0 +1,40 @@
+root = true
+
+[*]
+end_of_line = lf
+charset = utf-8
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.html]
+indent_size = 4
+
+[*.json]
+indent_size = 2
+insert_final_newline = false
+
+[{*[Mm]akefile*,*.mak,*.mk,depend}]
+indent_style = tab
+
+[*.{bat, cmd, cmd.*}]
+end_of_line = crlf
+
+[*.{yml, yaml}]
+indent_size = 2
+
+[*.gemspec]
+indent_size = 2
+
+[*.rb,Fastfile,Gemfile,Brewfile,Podfile]
+indent_size = 2
+
+[*.{kt,kts}]
+ktlint_standard_argument-list-wrapping = disabled
+ktlint_standard_trailing-comma-on-call-site = disabled
+ktlint_standard_trailing-comma-on-declaration-site = disabled
+
+[*.dart]
+indent_size = 2
+indent_brace_style = K&R

mcp_gtw-0.0.1/.env.example

@@ -0,0 +1,36 @@
+# Copy to .env and override any GATEWAY_* setting. See docs/configuration.md.
+# List values are comma separated.
+
+# GATEWAY_APP_NAME=MCP Gateway
+# GATEWAY_APP_VERSION is derived from the installed package version.
+
+# Bind address for the bundled runner (python -m mcp_gateway.main).
+# GATEWAY_HOST=127.0.0.1
+# GATEWAY_PORT=8000
+
+# Origins allowed to open the private provider WebSocket.
+GATEWAY_ALLOWED_PROVIDER_ORIGINS=http://localhost:8000,http://127.0.0.1:8000
+# Origins allowed on /mcp. Empty accepts native clients that send no Origin.
+GATEWAY_ALLOWED_MCP_ORIGINS=
+# Origins allowed by CORS on the HTTP endpoints.
+GATEWAY_CORS_ALLOW_ORIGINS=*
+
+# GATEWAY_TOOL_CALL_TIMEOUT_SECONDS=60
+# GATEWAY_MAXIMUM_TOOLS=128
+# GATEWAY_MAXIMUM_TOOL_DEFINITION_BYTES=65536
+# GATEWAY_MAXIMUM_WEBSOCKET_MESSAGE_BYTES=524288
+# GATEWAY_MAXIMUM_JSON_DEPTH=100
+# GATEWAY_MAXIMUM_PENDING_CALLS_PER_CHANNEL=64
+# GATEWAY_MAXIMUM_MCP_SESSIONS_PER_CHANNEL=16
+# GATEWAY_MAXIMUM_CHANNELS=10000
+# Cap simultaneous connections at the server. Empty means no app-level cap.
+# GATEWAY_MAXIMUM_CONCURRENT_CONNECTIONS=
+# GATEWAY_OFFLINE_TTL_SECONDS=300
+# GATEWAY_REAPER_INTERVAL_SECONDS=30
+
+# GATEWAY_MCP_JSON_RESPONSE=false
+# GATEWAY_MCP_STATELESS=false
+# GATEWAY_MCP_SESSION_IDLE_TIMEOUT_SECONDS=900
+
+# GATEWAY_ADMIN_ENABLED=false
+# GATEWAY_ADMIN_KEY=

mcp_gtw-0.0.1/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: paulocoutinhox
+ko_fi: paulocoutinho

mcp_gtw-0.0.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Execute on terminal '....'
+3. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**System (please complete the following information):**
+ - OS: [e.g. Ubuntu]
+ - Python [e.g. 3.10]
+
+**Additional context**
+Add any other context about the problem here.

mcp_gtw-0.0.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

mcp_gtw-0.0.1/.github/ISSUE_TEMPLATE/other.md

@@ -0,0 +1,10 @@
+---
+name: Other type
+about: Other issue type not related to bug or feature.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+

mcp_gtw-0.0.1/.github/RELEASE-TEMPLATE.md

@@ -0,0 +1,4 @@
+# Announcements
+* First announcement
+
+# Changes

mcp_gtw-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        run: pip install uv
+      - name: Create the environment
+        run: make install
+      - name: Lint
+        run: make lint
+      - name: Coverage gate
+        run: make coverage

mcp_gtw-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        run: pip install uv
+      - name: Verify the tag matches the package version
+        run: |
+          VERSION=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          if [ "${GITHUB_REF_NAME#v}" != "$VERSION" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match pyproject version ${VERSION}"
+            exit 1
+          fi
+      - name: Install
+        run: make install
+      - name: Lint
+        run: make lint
+      - name: Coverage gate
+        run: make coverage
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

mcp_gtw-0.0.1/.gitignore

@@ -0,0 +1,57 @@
+# os
+Thumbs.db
+.DS_Store
+
+# ide
+.idea
+.vscode
+.iml
+
+# auto generated
+**/*.pyc
+*.autosave
+*.user
+*.user.*
+.vs
+__pycache__
+Brewfile.lock.json
+.metals
+.ruff_cache
+
+# node
+node_modules
+package-lock.json
+
+# cmake
+CMakeUserPresets.json
+CMakeSettings.json
+CMakeLists.txt.user
+
+# java/kotlin
+.gradle
+
+# cxx
+.cxx
+
+# flutter
+*.reflectable.dart
+
+# postgres
+postgres-data
+
+# python
+*.egg-info
+.pytest_cache
+poetry.lock
+.venv
+/htmlcov
+
+# app
+*.db
+.coverage
+coverage.xml
+.fastapicloud
+data/
+
+# local secrets (keep .env.example tracked)
+.env

mcp_gtw-0.0.1/.python-version

@@ -0,0 +1 @@
+3.12

mcp_gtw-0.0.1/CLAUDE.md

@@ -0,0 +1,149 @@
+# CLAUDE.md
+
+Guidance for working in this repository.
+
+## How to use this file
+
+**CLAUDE.md is a map, not a copy.** Each subject gets a one-line essence here and a pointer to the
+`docs/*.md` that owns the full detail. Never duplicate doc content into this file — when the code
+changes, update the doc and keep the pointer accurate. The docs are the source of truth for
+behaviour. This file is the source of truth for the conventions and repo mechanics that have no doc
+(module layout, code style, commands, gotchas). If a subject has a doc, read the doc.
+
+## What this is
+
+`mcp-gtw` is a generic, installable [Model Context Protocol](https://modelcontextprotocol.io)
+gateway. It publishes a real MCP endpoint over Streamable HTTP whose capabilities are **registered
+and executed by connected providers** (a browser app or any WebSocket client) over a private
+WebSocket. The gateway never knows them in advance — a provider connects, publishes its own MCP
+tools, resources, resource templates and prompts, and runs their handlers; it can also serve
+completion, logging, progress, and reverse calls (sampling, elicitation). The gateway only registers,
+publishes and routes.
+
+It is a **library**: you build a real app by subclassing `Gateway`, never by editing this package.
+This repo is published to PyPI as `mcp-gtw` (the import package stays `mcp_gtw`).
+
+## Subjects (essence + where the detail lives)
+
+- **How it works / architecture** — public transport `MCP Client ⇄ Streamable HTTP ⇄ /mcp`. Private
+  transport `Gateway ⇄ WebSocket ⇄ provider (/provider)`. A **channel** is one session (one provider,
+  its registries, its pending calls) holding two tokens: `mcp_token` (client) and `provider_token`
+  (provider). One MCP `Server` + one `StreamableHTTPSessionManager` serve every channel, resolved per
+  request by Bearer token on the ASGI scope, with per-channel input validation. Full flows and
+  diagrams: [docs/architecture.md](docs/architecture.md).
+- **Provider protocol** — a JSON-RPC-shaped relay of MCP: gateway→provider `request`/`cancel`/
+  `response`, provider→gateway `register`/`result`/`call`/`notify`, plus `hello.ack`/`ack`/`ping`/
+  `pong`/`protocol.error`, version `mcp-gtw-provider/1`. See
+  [docs/provider-protocol.md](docs/provider-protocol.md).
+- **Provider SDK** — the JavaScript side is the [`mcp-gtw-provider`](https://github.com/mcp-gtw/mcp-gtw-provider)
+  npm package (`registerTool`/`registerResource`/`registerResourceTemplate`/`registerPrompt`,
+  `onComplete`/`onSubscribe`, `notifyResourceUpdated`, `log`, `requestSampling`/`requestElicit`).
+  Usage guide in [docs/provider-sdk.md](docs/provider-sdk.md).
+- **Extending** — subclass `Gateway`, override the hooks, swap `channel_class`/`registry_class`/
+  `settings_class`. Every override point: [docs/gateway-library.md](docs/gateway-library.md).
+- **Configuration** — all `GATEWAY_*` env vars (or `.env`) map to `GatewaySettings`. Lists are comma
+  separated (`NoDecode`, not JSON). Numeric limits/timeouts are validated positive and `port` is
+  bounded, so a bad value fails at startup. Table: [docs/configuration.md](docs/configuration.md).
+- **Runtime, limits & performance** — everything runs on one event loop and is fully async, with no
+  blocking IO on request/websocket paths. Tool validators are compiled once at registration, not per
+  call. A channel holds at most one live provider socket (a new connection atomically replaces the
+  old); channels are capped by `maximum_channels` (checked before allocation); every externally-fed
+  collection (pending calls, remembered sessions, tools) is bounded. The bundled runner
+  (`python -m mcp_gtw.main`) sets the transport frame limit (`ws_max_size`) to
+  `maximum_websocket_message_bytes` and applies `maximum_concurrent_connections` — so run it that way
+  in production, not bare `uvicorn`. Details: [docs/security.md](docs/security.md).
+- **Admin dashboard** — off by default. `GATEWAY_ADMIN_ENABLED=true` registers `/admin` and
+  `/admin/stats`, gated by `GATEWAY_ADMIN_KEY` (required — enabling admin without it raises
+  `GatewayConfigurationError` at construction). Details: [docs/admin.md](docs/admin.md).
+- **Security** — trust boundaries, the two tokens, origin checks, WebSocket robustness, resource
+  limits: [docs/security.md](docs/security.md).
+- **Quickstart / MCP clients / testing / deployment** — [docs/quickstart.md](docs/quickstart.md),
+  [docs/mcp-clients.md](docs/mcp-clients.md), [docs/testing.md](docs/testing.md),
+  [docs/deployment.md](docs/deployment.md).
+
+## Key modules (`src/mcp_gtw/`)
+
+- `gateway.py` — the `Gateway` class: FastAPI app factory, CORS, routes (`/mcp`, `/provider`,
+  `/health`, `/`, `/logo.svg`, optional `/admin`), the `/mcp` ASGI wrapper, the `/provider` websocket
+  pump, the admin dashboard, and the lifespan (session manager + reaper + `serve`).
+- `channel.py` — `Channel`: attach/detach a provider, compile/replace the registries (tools,
+  resources, resource templates, prompts), relay a request to the provider (correlate a `Future` over
+  the WebSocket with timeout), run reverse `call`s against the client, fan out notifications
+  (progress, logging, resource-updated), validate output, notify MCP sessions.
+- `registry.py` — `ChannelRegistry`: create/remove/resolve channels, expiry, `admin_channels`.
+- `protocol.py` — private message builders and `decode_message` (depth-bounded JSON parse).
+- `config.py` — `GatewaySettings` (pydantic-settings, env prefix `GATEWAY_`).
+- `helpers/security.py` — token generation, bearer extraction, origin check, constant-time compare.
+- `listeners.py` — `GatewayListener` hook interface that `Gateway` implements.
+
+## Module organization
+
+- One public class per module, plus its small private support types (`channel.py` keeps
+  `CompiledTool`, `PendingRequest`, `JsonWebSocket`).
+- `errors.py` is the exceptions module (the whole hierarchy lives there).
+- Pure utility functions live under `helpers/`.
+- Every `__init__.py` is empty, so import from the concrete submodule.
+
+## Conventions
+
+- Managed with `uv`. Ruff with `line-length = 100`, formatter is the source of truth.
+- **100% branch coverage is a hard gate** (`fail_under = 100`). Every change keeps it at 100%.
+- `__init__.py` files are **empty** — import from submodules (`from mcp_gtw.gateway import Gateway`).
+- Code and comments are in **English**. Comments are **rare** — only for genuinely non-obvious intent.
+  No narrating comments, no artificial section separators, no semicolons splitting sentences.
+- **Separate blocks with a blank line.** A compound block (`if`/`for`/`while`/`try`/`with`/`def`/
+  `class`) gets a blank line between it and the adjacent statement, so each block reads as its own
+  unit. Never stack blocks directly on top of each other.
+- **No legacy, no back-compat, no fallbacks.** Build the final version and refactor freely. Do not add
+  checks that only exist because something used to be different.
+- Prefer single-line signatures and calls where they fit the line length.
+
+## Supported Python
+
+- `requires-python = ">=3.12"`. Supported versions are **3.12, 3.13, 3.14**.
+- `.python-version` pins **3.12** for local `uv` and the Docker image (`python:3.12-slim`).
+- CI (`.github/workflows/ci.yml`) runs the full `make install` + `make lint` + `make coverage` matrix
+  across all three versions; `UV_PYTHON` selects the interpreter per matrix leg.
+
+## Commands
+
+```bash
+make install       # uv sync --extra dev
+make lint          # ruff check + ruff format --check
+make format        # apply formatting and safe fixes
+make test          # pytest
+make coverage      # pytest behind the 100% gate
+make version v=X.Y.Z  # rewrite the pyproject.toml version (validates semver)
+make build         # uv build (wheel + sdist)
+make run           # serve the bare gateway on 127.0.0.1:8000
+```
+
+## Versioning and releasing
+
+`pyproject.toml` is the single source of the version: `GatewaySettings.app_version` reads it back at
+runtime through `importlib.metadata.version("mcp-gtw")`, so never hardcode a version elsewhere.
+Bump with `make version v=X.Y.Z` (semver `X.Y.Z`, validated), then push a matching `v<version>` tag.
+`.github/workflows/release.yml` verifies the tag equals the `pyproject.toml` version, runs lint + the
+coverage gate, builds, and `uv publish --trusted-publishing always`.
+
+Publishing uses PyPI **Trusted Publishing** (OIDC) — no `PYPI_API_TOKEN` secret. The workflow grants
+`id-token: write`. PyPI supports a **pending publisher**, so configure it before the first release
+(pypi.org → Account → Publishing → Add a pending publisher): PyPI project `mcp-gtw`, owner
+`mcp-gtw`, repository `mcp-gtw`, workflow `release.yml`. Pushing the first `v<version>` tag then
+creates the project token-lessly.
+
+## Documentation policy
+
+Docs must stay consistent with the code. When you change a setting, default, endpoint, module path,
+or behaviour, update the affected `docs/*.md`, `README.md`, and the pointer in this file in the same
+change. Treat a doc that describes something the code no longer does as a bug.
+
+## Gotchas
+
+- `.env` and `.env.example` are under a hard permission deny rule here (Read, Edit, Bash, and Write
+  all fail). The file is effectively immutable in this environment — make `config.py` and
+  `docs/configuration.md` the source of truth and flag any drift to the user.
+- The home page reads `web/index.html` at import and `str.format`s `{name}`/`{initial}` — keep that
+  file free of other `{`/`}`. `web/admin.html` is served raw (its JS braces are fine).
+- Package data (`web/*.html`, `web/logo.svg`, `py.typed`) must ship in the wheel — hatchling includes
+  everything under the package.

mcp_gtw-0.0.1/Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    GATEWAY_HOST=0.0.0.0
+
+WORKDIR /srv
+
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+RUN pip install --no-cache-dir .
+
+EXPOSE 8000
+
+CMD ["python", "-m", "mcp_gtw.main"]

mcp_gtw-0.0.1/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo Coutinho
+
+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.

mcp_gtw-0.0.1/Makefile

@@ -0,0 +1,33 @@
+.DEFAULT_GOAL := help
+.PHONY: help install lint format test coverage version build run
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "} {printf "  \033[36m%-10s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install the environment with dev dependencies
+	uv sync --extra dev
+
+lint: ## Check linting and formatting
+	uv run ruff check .
+	uv run ruff format --check .
+
+format: ## Apply formatting and safe lint fixes
+	uv run ruff format .
+	uv run ruff check --fix .
+
+test: ## Run the test suite
+	uv run pytest -q
+
+coverage: ## Run the test suite with the coverage gate
+	uv run pytest -q --cov --cov-report=term-missing --cov-report=xml
+
+version: ## Set the release version, e.g. make version v=1.2.3
+	@echo "$(v)" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$$' || { echo "usage: make version v=X.Y.Z"; exit 1; }
+	@sed -i.bak -E 's/^version = ".*"/version = "$(v)"/' pyproject.toml && rm -f pyproject.toml.bak
+	@echo "version set to $(v)"
+
+build: ## Build the wheel and sdist for PyPI
+	uv build
+
+run: ## Serve the bare generic gateway on 127.0.0.1:8000
+	uv run python -m mcp_gtw.main