stkit 17.2.2__tar.gz → 17.2.3__tar.gz

{stkit-17.2.2 → stkit-17.2.3}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v17.2.3 (2026-10-31)
+
+Run `uv run stk db upgrade`.
+
+- MCP is opt-in, like file uploads: add `stk.mcp` to the app's extensions. Without it stk registers no `mcp` blueprint, no `/mcp`, no `/tokens/` page and no Agent Tokens menu entry, so an app can serve its own MCP endpoint. From 17.2.0 to 17.2.2 stk claimed all of them in every app (JSON APIs).
+- stk's MCP token table is `stk_mcp_token`, like every other core table. 17.2.0 to 17.2.2 created `mcp_token`, which failed to migrate in an app that already had a table by that name. Revision `stk_0006` moves stk's own tokens across; an app's own `mcp_token` is recognised by its columns and left alone.
+- `stk.utils.netguard` adds `stream`, which yields the response with its body unread for large downloads and can cap decoded bytes with `max_bytes` or return a redirect with `follow_redirects=False`, and a public `pin(url)` that vets a URL without fetching it, for a client such as a headless browser. `fetch` is built on `stream`. Cookies are never carried across redirect hops (JSON APIs).
+
+### Upgrade considerations
+
+- An app that uses stk's MCP tools adds `stk.mcp` to its extensions, or `/mcp` and `/tokens/` return 404. Existing tokens keep working after `stk db upgrade`.
+
 ## v17.2.2 (2026-10-31)
 
 No migration required.

{stkit-17.2.2 → stkit-17.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stkit
-Version: 17.2.2
+Version: 17.2.3
 Summary: An async Quart framework optimized for AI-assisted development workflows
 Project-URL: Documentation, https://docs.stkit.dev
 Project-URL: Source, https://github.com/level09/stk

{stkit-17.2.2 → stkit-17.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stkit"
-version = "17.2.2"
+version = "17.2.3"
 description = "An async Quart framework optimized for AI-assisted development workflows"
 authors = [
     {name = "Level09", email = "hello@level09.com"}

{stkit-17.2.2 → stkit-17.2.3}/stk/__init__.py

@@ -3,7 +3,7 @@ stk Framework
 A modern Python web framework optimized for AI-assisted development.
 """
 
-__version__ = "17.2.2"
+__version__ = "17.2.3"
 
 
 def __getattr__(name):

{stkit-17.2.2 → stkit-17.2.3}/stk/app.py

@@ -27,7 +27,6 @@ from werkzeug.security import safe_join
 import stk.extensions as ext
 from stk.agent_login import agent_login_enabled, bp_agent_login
 from stk.extensions import session
-from stk.mcp.views import bp_mcp
 from stk.notification.views import bp_notification
 from stk.portal.views import portal
 from stk.public.views import public
@@ -209,7 +208,6 @@ def register_blueprints(app):
     app.register_blueprint(portal)
     app.register_blueprint(bp_notification)
     app.register_blueprint(ws_bp)
-    app.register_blueprint(bp_mcp)
     if agent_login_enabled(app):
         app.register_blueprint(bp_agent_login)
     return None
@@ -300,7 +298,12 @@ def register_navigation(app):
     app.jinja_env.globals["stk_navigation"] = lambda: [
         *CORE_NAVIGATION_START,
         *app.navigation,
-        *CORE_NAVIGATION_END,
+        *(
+            entry
+            for entry in CORE_NAVIGATION_END
+            # Agent Tokens only for apps that opted in with `stk.mcp`.
+            if entry.get("to") != "/tokens/" or "stk.mcp" in app.extensions
+        ),
     ]
     # The app's entries alone, for a layout that draws its own sidebar.
     app.jinja_env.globals["app_navigation"] = lambda: app.navigation

{stkit-17.2.2 → stkit-17.2.3}/stk/mcp/__init__.py

@@ -1,5 +1,8 @@
 """Expose an app's own functions to AI agents over MCP at `/mcp`.
 
+Opt in with `extensions=[stk.mcp, ...]`; without it there is no `/mcp`, no
+`/tokens/` page, and an app is free to serve its own MCP endpoint.
+
 A tool is an async function taking the validated arguments dict. It runs as the
 token's user: `current_user` and `g.db_session` work as in a request handler.
 """
@@ -51,3 +54,10 @@ def tool(name, description, schema, *, role=None):
         return fn
 
     return decorator
+
+
+def init_app(app):
+    from stk.mcp.views import bp_mcp
+
+    app.extensions["stk.mcp"] = True
+    app.register_blueprint(bp_mcp)

{stkit-17.2.2 → stkit-17.2.3}/stk/mcp/models.py

@@ -13,7 +13,7 @@ LIFETIME = timedelta(days=90)
 
 
 class McpToken(Base):
-    __tablename__ = "mcp_token"
+    __tablename__ = "stk_mcp_token"
 
     id = Column(Integer, primary_key=True)
     user_id = Column(

{stkit-17.2.2 → stkit-17.2.3}/stk/migrations/versions/stk_0005_mcp_tokens.py

@@ -1,4 +1,7 @@
-"""MCP bearer tokens: one row per token, storing only its sha256."""
+"""MCP bearer tokens: one row per token, storing only its sha256.
+
+Until 17.2.3 this created `mcp_token`, a name an app may already use for its own
+table; stk_0006 moves such an stk table to `stk_mcp_token`."""
 
 import sqlalchemy as sa
 from alembic import op
@@ -11,7 +14,7 @@ depends_on = None
 
 def upgrade() -> None:
     op.create_table(
-        "mcp_token",
+        "stk_mcp_token",
         sa.Column("id", sa.Integer(), nullable=False),
         sa.Column("user_id", sa.Integer(), nullable=False),
         sa.Column("name", sa.String(length=80), nullable=False),
@@ -24,19 +27,19 @@ def upgrade() -> None:
         sa.ForeignKeyConstraint(
             ["user_id"],
             ["user.id"],
-            name=op.f("fk_mcp_token_user_id"),
+            name=op.f("fk_stk_mcp_token_user_id"),
             ondelete="CASCADE",
         ),
-        sa.PrimaryKeyConstraint("id", name=op.f("pk_mcp_token")),
-        sa.UniqueConstraint("token_hash", name=op.f("uq_mcp_token_token_hash")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_stk_mcp_token")),
+        sa.UniqueConstraint("token_hash", name=op.f("uq_stk_mcp_token_token_hash")),
     )
-    with op.batch_alter_table("mcp_token", schema=None) as batch_op:
+    with op.batch_alter_table("stk_mcp_token", schema=None) as batch_op:
         batch_op.create_index(
-            batch_op.f("ix_mcp_token_user_id"), ["user_id"], unique=False
+            batch_op.f("ix_stk_mcp_token_user_id"), ["user_id"], unique=False
         )
 
 
 def downgrade() -> None:
-    with op.batch_alter_table("mcp_token", schema=None) as batch_op:
-        batch_op.drop_index(batch_op.f("ix_mcp_token_user_id"))
-    op.drop_table("mcp_token")
+    with op.batch_alter_table("stk_mcp_token", schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f("ix_stk_mcp_token_user_id"))
+    op.drop_table("stk_mcp_token")

stkit-17.2.3/stk/migrations/versions/stk_0006_stk_mcp_token.py

@@ -0,0 +1,69 @@
+"""Move stk's MCP tokens from `mcp_token` to `stk_mcp_token`.
+
+stk 17.2.0 to 17.2.2 created `mcp_token`, a name an app may already use for its
+own table. stk_0005 now creates `stk_mcp_token`; a database that ran the old
+stk_0005 has stk's tokens in `mcp_token` instead. Only that table moves: it is
+recognised by stk's `user_uniquifier` column, so an app's own `mcp_token` stays.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "stk_0006"
+down_revision = "stk_0005"
+branch_labels = None
+depends_on = None
+
+COLUMNS = (
+    "id, user_id, name, token_hash, user_uniquifier, scopes, created_at,"
+    " expires_at, last_used_at"
+)
+
+
+def upgrade() -> None:
+    inspector = sa.inspect(op.get_bind())
+    tables = set(inspector.get_table_names())
+    if "mcp_token" not in tables:
+        return
+    legacy = {c["name"] for c in inspector.get_columns("mcp_token")}
+    if "user_uniquifier" not in legacy or "token_hash" not in legacy:
+        return
+    if "stk_mcp_token" not in tables:
+        # The database ran the old stk_0005, so the new one never created this.
+        _create_stk_mcp_token()
+    op.execute(f"INSERT INTO stk_mcp_token ({COLUMNS}) SELECT {COLUMNS} FROM mcp_token")
+    # destructive: every row was copied to stk_mcp_token on the line above.
+    op.drop_table("mcp_token")
+
+
+def _create_stk_mcp_token():
+    # Same table as stk_0005 creates; revision modules cannot import each other.
+    op.create_table(
+        "stk_mcp_token",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("name", sa.String(length=80), nullable=False),
+        sa.Column("token_hash", sa.String(length=64), nullable=False),
+        sa.Column("user_uniquifier", sa.String(length=255), nullable=False),
+        sa.Column("scopes", sa.JSON(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("expires_at", sa.DateTime(), nullable=False),
+        sa.Column("last_used_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(
+            ["user_id"],
+            ["user.id"],
+            name=op.f("fk_stk_mcp_token_user_id"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_stk_mcp_token")),
+        sa.UniqueConstraint("token_hash", name=op.f("uq_stk_mcp_token_token_hash")),
+    )
+    with op.batch_alter_table("stk_mcp_token", schema=None) as batch_op:
+        batch_op.create_index(
+            batch_op.f("ix_stk_mcp_token_user_id"), ["user_id"], unique=False
+        )
+
+
+def downgrade() -> None:
+    # The old name collided with apps' own tables; there is nothing to restore.
+    pass

{stkit-17.2.2 → stkit-17.2.3}/stk/utils/netguard.py

@@ -6,6 +6,8 @@ address between the check and the connection. Every redirect hop is re-checked."
 import asyncio
 import ipaddress
 import socket
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from urllib.parse import urljoin, urlsplit, urlunsplit
 
 import httpx2
@@ -35,7 +37,7 @@ def _public(addr: str) -> bool:
 
 
 def _origin(url: str) -> tuple:
-    """(scheme, host, port) with the default port filled in; `_pin` rejects bad ones."""
+    """(scheme, host, port) with the default port filled in; `pin` rejects bad ones."""
     parts = urlsplit(url)
     try:
         port = parts.port
@@ -48,8 +50,14 @@ def _origin(url: str) -> tuple:
     )
 
 
-async def _pin(url: str) -> tuple[str, str, str]:
-    """Return (url with the checked IP, Host header, TLS server name)."""
+async def pin(url: str) -> tuple[str, str, str]:
+    """Check a URL and return (url with the checked IP, Host header, TLS server name).
+
+    Raise Blocked unless it is http(s), carries no credentials, and every address
+    its host resolves to is public. Connect to the returned URL, send the Host
+    header, and use the server name for SNI, so the connection goes to the
+    address that was checked. Use it alone to vet a URL another client (a
+    headless browser) will open."""
     parts = urlsplit(url)
     host = parts.hostname
     if parts.scheme not in ("http", "https") or not host:
@@ -84,21 +92,45 @@ async def _pin(url: str) -> tuple[str, str, str]:
     return target, host_header, host
 
 
-async def fetch(
+def _capped(response: httpx2.Response, max_bytes: int) -> None:
+    """Make every read of the body (aread, aiter_bytes/text/lines, .content after
+    aread) raise Blocked past `max_bytes` decoded bytes."""
+    if int(response.headers.get("content-length") or 0) > max_bytes:
+        raise Blocked(f"response is larger than {max_bytes} bytes")
+    read = response.aiter_bytes
+
+    async def aiter_bytes(chunk_size=None):
+        seen = 0
+        async for chunk in read(chunk_size):
+            seen += len(chunk)
+            if seen > max_bytes:
+                raise Blocked(f"response is larger than {max_bytes} bytes")
+            yield chunk
+
+    # aread, aiter_text and aiter_lines all read through self.aiter_bytes.
+    response.aiter_bytes = aiter_bytes
+
+
+@asynccontextmanager
+async def stream(
     url: str,
     *,
     headers: dict | None = None,
     timeout: float = 10,
-    max_bytes: int = 1_048_576,
+    max_bytes: int | None = None,
     max_redirects: int = 5,
+    follow_redirects: bool = True,
     transport: httpx2.AsyncBaseTransport | None = None,
-) -> tuple[httpx2.Response, str]:
-    """GET a user-supplied URL. Return (response with its body read, final url).
-
-    Raise Blocked when the URL, any resolved address, a redirect or the decoded
-    body size is refused, TimeoutError when the whole fetch outlasts `timeout`,
-    and httpx2.HTTPError for transport failures. Environment proxies are ignored:
-    a proxy would resolve the name itself and undo the pin."""
+) -> AsyncIterator[tuple[httpx2.Response, str]]:
+    """GET a user-supplied URL; yield (response with its body unread, final url).
+
+    `timeout` bounds the whole fetch, including reading the body inside the
+    block. With `max_bytes`, reading more decoded bytes than that raises
+    Blocked. With `follow_redirects=False` a redirect is yielded as is. Raise
+    Blocked when the URL, an address or a redirect is refused or there are more
+    than `max_redirects`, TimeoutError past `timeout`, and httpx2.HTTPError for
+    transport failures. Environment proxies are ignored: a proxy would resolve
+    the name itself and undo the pin."""
     headers = dict(headers or {})
     origin = _origin(url)
     async with (
@@ -108,7 +140,7 @@ async def fetch(
         ) as client,
     ):
         for _ in range(max_redirects + 1):
-            target, host_header, server_name = await _pin(url)
+            target, host_header, server_name = await pin(url)
             if _origin(url) != origin:
                 # Never hand the caller's credentials to an origin it did not name,
                 # including the same host over plain HTTP or another port.
@@ -128,19 +160,41 @@ async def fetch(
             # them across hops.
             client.cookies.clear()
             try:
-                if response.has_redirect_location:
+                if follow_redirects and response.has_redirect_location:
                     url = urljoin(url, response.headers["location"])
                     continue
-                if int(response.headers.get("content-length") or 0) > max_bytes:
-                    raise Blocked(f"response is larger than {max_bytes} bytes")
-                body = bytearray()
-                async for chunk in response.aiter_bytes():
-                    body += chunk
-                    if len(body) > max_bytes:
-                        raise Blocked(f"response is larger than {max_bytes} bytes")
-                # What aread() stores; .content, .text and .json() then work.
-                response._content = bytes(body)
-                return response, url
+                if max_bytes is not None:
+                    _capped(response, max_bytes)
+                yield response, url
+                return
             finally:
                 await response.aclose()
         raise Blocked("too many redirects")
+
+
+async def fetch(
+    url: str,
+    *,
+    headers: dict | None = None,
+    timeout: float = 10,
+    max_bytes: int = 1_048_576,
+    max_redirects: int = 5,
+    transport: httpx2.AsyncBaseTransport | None = None,
+) -> tuple[httpx2.Response, str]:
+    """GET a user-supplied URL. Return (response with its body read, final url).
+
+    Same checks and errors as `stream`, with the body read and capped at
+    `max_bytes` decoded bytes (default 1 MiB)."""
+    async with stream(
+        url,
+        headers=headers,
+        timeout=timeout,
+        max_bytes=max_bytes,
+        max_redirects=max_redirects,
+        transport=transport,
+    ) as (response, final_url):
+        # A body the transport already loaded (a test's MockTransport) skips the
+        # streaming guard; check what was read.
+        if len(await response.aread()) > max_bytes:
+            raise Blocked(f"response is larger than {max_bytes} bytes")
+    return response, final_url

{stkit-17.2.2 → stkit-17.2.3}/tests/test_mcp.py

@@ -9,6 +9,7 @@ from quart_security import current_user, hash_password
 from sqlalchemy import func, select
 
 import stk.extensions as ext
+import stk.mcp
 from stk.app import Stk
 from stk.mcp import ToolError, tool
 from stk.mcp.models import McpToken
@@ -53,7 +54,7 @@ def rpc(method, params=None, rid=1):
 
 class McpTests(unittest.IsolatedAsyncioTestCase):
     async def asyncSetUp(self):
-        self.app = Stk(__name__, config=McpConfig)
+        self.app = Stk(__name__, config=McpConfig, extensions=[stk.mcp])
         async with ext.engine.begin() as conn:
             await conn.run_sync(Base.metadata.create_all)
         async with ext.async_session_factory() as db:
@@ -305,5 +306,19 @@ class McpTests(unittest.IsolatedAsyncioTestCase):
             tool("test.array", "Not an object.", {"type": "array"})
 
 
+class McpOptInTests(unittest.IsolatedAsyncioTestCase):
+    async def test_an_app_without_stk_mcp_has_no_mcp_routes_or_menu(self):
+        """An app may serve its own /mcp; stk must not claim it uninvited."""
+        app = Stk(__name__, config=McpConfig)
+        self.assertNotIn("mcp", app.blueprints)
+        self.assertNotIn("/mcp", {r.rule for r in app.url_map.iter_rules()})
+        menu = [e.get("to") for e in app.jinja_env.globals["stk_navigation"]()]
+        self.assertNotIn("/tokens/", menu)
+        with_mcp = Stk(__name__, config=McpConfig, extensions=[stk.mcp])
+        menu = [e.get("to") for e in with_mcp.jinja_env.globals["stk_navigation"]()]
+        self.assertIn("/tokens/", menu)
+        await ext.engine.dispose()
+
+
 if __name__ == "__main__":
     unittest.main()

stkit-17.2.3/tests/test_mcp_migration.py

@@ -0,0 +1,62 @@
+"""stk_0006 moves stk's own `mcp_token` to `stk_mcp_token` and leaves an app's alone."""
+
+import sqlite3
+import tempfile
+import unittest
+from pathlib import Path
+
+from alembic import command
+
+from stk.migrations import build_alembic_config
+
+LEGACY_TOKEN = (
+    "INSERT INTO mcp_token (id, user_id, name, token_hash, user_uniquifier,"
+    " scopes, created_at, expires_at) VALUES (1, 1, 'agent', 'h', 'u', '[]',"
+    " '2026-10-31', '2027-01-29')"
+)
+
+
+class McpTokenTableMigrationTest(unittest.TestCase):
+    def setUp(self):
+        self.dir = tempfile.TemporaryDirectory()
+        self.path = Path(self.dir.name) / "db.sqlite"
+        self.config = build_alembic_config(url=f"sqlite:///{self.path}", quiet=True)
+
+    def tearDown(self):
+        self.dir.cleanup()
+
+    def sql(self, statement):
+        with sqlite3.connect(self.path) as db:
+            return db.execute(statement).fetchall()
+
+    def tables(self):
+        return {
+            r[0] for r in self.sql("select name from sqlite_master where type='table'")
+        }
+
+    def test_fresh_database_gets_only_the_prefixed_table(self):
+        command.upgrade(self.config, "heads")
+        self.assertIn("stk_mcp_token", self.tables())
+        self.assertNotIn("mcp_token", self.tables())
+
+    def test_tokens_from_the_old_table_name_move_over(self):
+        # A database that ran stk_0005 from 17.2.0 to 17.2.2.
+        command.upgrade(self.config, "stk_0004")
+        self.sql(
+            "CREATE TABLE mcp_token (id INTEGER PRIMARY KEY, user_id INTEGER, name TEXT,"
+            " token_hash TEXT, user_uniquifier TEXT, scopes JSON, created_at DATETIME,"
+            " expires_at DATETIME, last_used_at DATETIME)"
+        )
+        self.sql(LEGACY_TOKEN)
+        self.sql("UPDATE alembic_version SET version_num = 'stk_0005'")
+        command.upgrade(self.config, "heads")
+        self.assertNotIn("mcp_token", self.tables())
+        self.assertEqual(self.sql("select name from stk_mcp_token"), [("agent",)])
+
+    def test_an_apps_own_mcp_token_table_is_left_alone(self):
+        command.upgrade(self.config, "stk_0004")
+        self.sql("CREATE TABLE mcp_token (id INTEGER PRIMARY KEY, grant_id TEXT)")
+        self.sql("INSERT INTO mcp_token (id, grant_id) VALUES (7, 'g')")
+        command.upgrade(self.config, "heads")
+        self.assertEqual(self.sql("select id, grant_id from mcp_token"), [(7, "g")])
+        self.assertIn("stk_mcp_token", self.tables())

{stkit-17.2.2 → stkit-17.2.3}/tests/test_netguard.py

@@ -7,7 +7,7 @@ from unittest import mock
 import httpx2
 
 from stk.utils import netguard
-from stk.utils.netguard import Blocked, fetch
+from stk.utils.netguard import Blocked, fetch, pin, stream
 
 PUBLIC = "93.184.215.14"
 
@@ -196,6 +196,64 @@ class NetguardTests(unittest.IsolatedAsyncioTestCase):
             with self.assertRaises(TimeoutError):
                 await fetch("https://slow.example.com/", timeout=0.05)
 
+    async def test_pin_is_public_for_vetting_urls_another_client_opens(self):
+        with resolver({"site.example.com": [PUBLIC], "inside.test": ["10.0.0.2"]}):
+            self.assertEqual(
+                await pin("https://site.example.com/a?b=1"),
+                (f"https://{PUBLIC}/a?b=1", "site.example.com", "site.example.com"),
+            )
+            with self.assertRaises(Blocked):
+                await pin("https://inside.test/")
+
+    async def test_stream_yields_the_body_unread_and_caps_streamed_bytes(self):
+        async def body():
+            for _ in range(10):
+                yield b"x" * 1_000
+
+        def handler(request):
+            return httpx2.Response(200, content=body())
+
+        with resolver({"big.example.com": [PUBLIC]}):
+            async with stream(
+                "https://big.example.com/",
+                max_bytes=5_000,
+                transport=httpx2.MockTransport(handler),
+            ) as (response, final):
+                self.assertEqual(final, "https://big.example.com/")
+                with self.assertRaisesRegex(Blocked, "larger than"):
+                    async for _ in response.aiter_bytes():
+                        pass
+
+    async def test_stream_can_return_a_redirect_instead_of_following_it(self):
+        def handler(request):
+            return httpx2.Response(302, headers={"location": "https://b.example.com/"})
+
+        with resolver({"a.example.com": [PUBLIC]}):
+            async with stream(
+                "https://a.example.com/",
+                follow_redirects=False,
+                transport=httpx2.MockTransport(handler),
+            ) as (response, final):
+                self.assertEqual(response.status_code, 302)
+                self.assertEqual(final, "https://a.example.com/")
+
+    async def test_cookies_are_not_carried_across_redirects(self):
+        seen = []
+
+        def handler(request):
+            seen.append(request)
+            if len(seen) == 1:
+                return httpx2.Response(
+                    302, headers={"location": "/next", "set-cookie": "s=1; Path=/"}
+                )
+            return httpx2.Response(200, text="done")
+
+        with resolver({"a.example.com": [PUBLIC]}):
+            await fetch(
+                "https://a.example.com/", transport=httpx2.MockTransport(handler)
+            )
+        self.assertNotIn("cookie", seen[1].headers)
+
 
 if __name__ == "__main__":
     unittest.main()