stkit 17.2.1__tar.gz → 17.2.3__tar.gz

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

@@ -1,5 +1,26 @@
 # 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.
+
+- `stk add-role` and `stk cleanup-sessions` crashed with `TypeError: 'NoneType' object is not callable` because they used the database before the app was built. Every command that runs async work now builds the app first. Run `cleanup-sessions` from cron again if you had stopped it.
+- `stk worker` stops on SIGTERM or Ctrl-C at a safe point: it cancels only the running job, hands it back, and exits without a traceback.
+- The home page describes stk as running on Quart, not Flask.
+- Requires quart-security 2.0.5: login takes the same time whether or not an email has an account, and passkey registration refuses a credential ID another user already holds (Authentication).
+
 ## v17.2.1 (2026-10-31)
 
 No migration required.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stkit
-Version: 17.2.1
+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
@@ -28,7 +28,7 @@ Requires-Dist: pillow>=13.0.0
 Requires-Dist: psycopg2-binary>=2.9.10
 Requires-Dist: python-dotenv>=1.2.2
 Requires-Dist: qrcode>=8.2
-Requires-Dist: quart-security<3,>=2.0.4
+Requires-Dist: quart-security<3,>=2.0.5
 Requires-Dist: quart-session>=3.0.0
 Requires-Dist: quart>=0.20.0
 Requires-Dist: rich>=14.0.0

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

@@ -1,6 +1,6 @@
 [project]
 name = "stkit"
-version = "17.2.1"
+version = "17.2.3"
 description = "An async Quart framework optimized for AI-assisted development workflows"
 authors = [
     {name = "Level09", email = "hello@level09.com"}
@@ -30,7 +30,7 @@ dependencies = [
     "python-dotenv>=1.2.2",
     "qrcode>=8.2",
     "quart>=0.20.0",
-    "quart-security>=2.0.4,<3",
+    "quart-security>=2.0.5,<3",
     "quart-session>=3.0.0",
     "rich>=14.0.0",
     "sqlalchemy[asyncio]>=2.0.41",

{stkit-17.2.1 → 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.1"
+__version__ = "17.2.3"
 
 
 def __getattr__(name):

{stkit-17.2.1 → 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.1 → stkit-17.2.3}/stk/cli/base.py

@@ -68,6 +68,9 @@ def cli_app():
 
 def run_async(coro):
     """Run an async function in sync context (for CLI commands)."""
+    # The engine and session factory exist only once the app is built; loading it
+    # here means no command can reach the database without it.
+    cli_app()
 
     async def _wrapper():
         try:

{stkit-17.2.1 → stkit-17.2.3}/stk/cli/develop.py

@@ -1,6 +1,5 @@
 """Starting an app, serving it locally, and running its durable jobs."""
 
-import asyncio
 from pathlib import Path
 
 import click
@@ -82,7 +81,5 @@ def worker(timeout):
             await work(timeout)
 
     console.print("[green]Worker started[/]")
-    try:
-        run_async(run())
-    except (KeyboardInterrupt, asyncio.CancelledError):
-        console.print("Worker stopped")
+    run_async(run())
+    console.print("Worker stopped")

{stkit-17.2.1 → 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.1 → 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.1 → 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.1 → stkit-17.2.3}/stk/tasks/__init__.py

@@ -25,6 +25,7 @@ from stk.tasks.models import Job
 logger = logging.getLogger(__name__)
 
 JOBS = {}
+_running = None  # the job task `stk worker` is awaiting, for a clean shutdown
 TIMEOUT = 3600
 POLL_SECONDS = 2
 RECOVER_SECONDS = 60
@@ -164,8 +165,13 @@ async def run_next(timeout=TIMEOUT):
     job_id, name, payload, attempts, max_attempts = claimed
     async with ext.async_session_factory() as session:
         try:
-            async with asyncio.timeout(timeout):
-                await JOBS[name](session, **payload)
+            global _running
+            _running = asyncio.create_task(JOBS[name](session, **payload))
+            try:
+                # wait_for cancels the job itself on timeout or when this is cancelled.
+                await asyncio.wait_for(_running, timeout)
+            finally:
+                _running = None
             done = await session.execute(
                 _owned(job_id, lease).values(
                     status="done", locked_until=None, last_error=None
@@ -216,11 +222,28 @@ async def recover():
 
 async def work(timeout=TIMEOUT):
     """Run due jobs one at a time until SIGTERM or Ctrl-C."""
-    asyncio.get_running_loop().add_signal_handler(
-        signal.SIGTERM, asyncio.current_task().cancel
-    )
+    stop = asyncio.Event()
+
+    def shutdown():
+        # Cancel only the job, never the worker mid-query: it hands the job back
+        # and the loop ends at its next check.
+        stop.set()
+        if _running is not None:
+            _running.cancel()
+
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        loop.add_signal_handler(sig, shutdown)
+    try:
+        await _drain(timeout, stop)
+    except asyncio.CancelledError:
+        if not stop.is_set():
+            raise
+
+
+async def _drain(timeout, stop):
     recovered = None
-    while True:
+    while not stop.is_set():
         # Also between jobs, so a queue that never empties still recovers.
         if recovered is None or datetime.now() - recovered >= timedelta(
             seconds=RECOVER_SECONDS
@@ -228,4 +251,7 @@ async def work(timeout=TIMEOUT):
             await recover()
             recovered = datetime.now()
         if not await run_next(timeout):
-            await asyncio.sleep(POLL_SECONDS)
+            try:
+                await asyncio.wait_for(stop.wait(), POLL_SECONDS)
+            except TimeoutError:
+                pass

{stkit-17.2.1 → stkit-17.2.3}/stk/templates/index.html

@@ -8,7 +8,7 @@
 
                 <h1 class="text-headline-large font-weight-bold mb-3">Build faster with stk</h1>
                 <p class="text-body-large text-medium-emphasis mb-8">
-                    A modern Flask framework for building web applications.
+                    An async Python framework for building web applications, on Quart.
                 </p>
 
                 {% if current_user.is_authenticated %}

{stkit-17.2.1 → 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.1 → stkit-17.2.3}/tests/test_cli.py

@@ -61,3 +61,20 @@ class DowngradeArgumentTest(unittest.TestCase):
             result = CliRunner().invoke(main, ["db", "downgrade", "-1"])
         self.assertEqual(result.exit_code, 0, result.output)
         self.assertEqual(run.call_args.args[-1], "-1")
+
+
+class DatabaseCommandTest(unittest.TestCase):
+    def test_run_async_builds_the_app_before_touching_the_database(self):
+        """`add-role` and `cleanup-sessions` crashed: nothing had built the engine."""
+        with (
+            patch("stk.cli.base.cli_app") as load,
+            patch("stk.tasks.cleanup_expired_sessions") as cleanup,
+        ):
+            cleanup.side_effect = lambda: _done()
+            result = CliRunner().invoke(main, ["cleanup-sessions"])
+        self.assertEqual(result.exit_code, 0, result.output)
+        load.assert_called()
+
+
+async def _done():
+    return None

{stkit-17.2.1 → stkit-17.2.3}/tests/test_jobs.py

@@ -1,6 +1,8 @@
 """Durable jobs: enqueue, claim, retry, failure, and recovery of a dead worker's job."""
 
 import asyncio
+import os
+import signal
 import unittest
 from datetime import datetime, timedelta
 
@@ -11,7 +13,7 @@ from sqlalchemy import select, update
 import stk.extensions as ext
 from stk.app import Stk
 from stk.settings import TestingConfig
-from stk.tasks import enqueue, job, recover, run_next
+from stk.tasks import enqueue, job, recover, run_next, work
 from stk.tasks.models import Job
 from stk.user.models import Activity, Base, User
 from stk.user.views import api_jobs
@@ -163,6 +165,20 @@ class JobTests(unittest.IsolatedAsyncioTestCase):
         self.assertEqual(row.status, "running")
         self.assertNotIn("lost race", await self.activities())
 
+    async def test_sigterm_hands_back_the_running_job_and_stops_cleanly(self):
+        job_id = await enqueue("jobs_test_slow")
+        worker = asyncio.create_task(work())
+        for _ in range(50):
+            await asyncio.sleep(0.05)
+            if (await self.get(job_id)).status == "running":
+                break
+        os.kill(os.getpid(), signal.SIGTERM)
+        await asyncio.wait_for(worker, 5)  # returns, not CancelledError
+        row = await self.get(job_id)
+        self.assertEqual(
+            (row.status, row.attempts, row.locked_until), ("queued", 0, None)
+        )
+
     async def test_recovers_job_left_running_by_a_dead_worker(self):
         lost = await enqueue("jobs_test_record", user_id=self.user_id, action="lost")
         spent = await enqueue("jobs_test_record", user_id=self.user_id, action="spent")

{stkit-17.2.1 → 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())