caspian-utils 0.0.10 → 0.0.12

package/dist/docs/auth.md

@@ -3,7 +3,7 @@ title: Authentication
 description: Manage session-backed authentication in Caspian with `casp.auth`, `AuthSettings`, the global `auth` object, centralized `auth_config.py`, page decorators, RPC protection, role-based routes, and optional Google or GitHub OAuth providers.
 related:
   title: Related docs
-    description: Use the fetch-data guide when sign-in happens through RPC, then use the state guide for transient auth-adjacent request state, validation to guard credentials, and routing or project structure to place auth files correctly.
+  description: Use the fetch-data guide when sign-in or signout happens through RPC, then use the state guide for transient auth-adjacent request state, validation to guard credentials, and routing or project structure to place auth files correctly.
   links:
     - /docs/fetch-data
     - /docs/state
@@ -50,6 +50,7 @@ from casp.auth import (
 
 - Define app-wide auth behavior in `build_auth_settings()` and apply it once at startup with `configure_auth(...)`.
 - Use `auth.sign_in(...)` and `auth.sign_out(...)` instead of setting or clearing session keys directly.
+- Prefer `pp.rpc(...)` plus `@rpc(require_auth=True)` for signout buttons or menus rendered in pages or components. Use a dedicated signout route only when you need a plain HTML form POST or a no-JavaScript fallback.
 - Use `@require_auth`, `@require_role`, and `@guest_only` for page access rules.
 - Use `@rpc(require_auth=True, allowed_roles=[...])` for browser-triggered actions that need protection.
 - Use `StateManager` only for transient auth-adjacent request state; keep the authenticated session itself owned by `casp.auth`.
@@ -112,12 +113,52 @@ Important behavior from the current implementation:
 - `default_token_validity` is parsed by the installed auth runtime with the format `^\d+(s|m|h|d)$`. Use values such as `30m`, `1h`, or `7d`.
 - `token_auto_refresh` only changes behavior when the request lifecycle calls `auth.refresh_session()`. In the installed `auth.py`, the flag alone does not refresh expiry by itself.
 - The framework `AuthSettings` dataclass defaults `is_all_routes_private=True`, but the project example above explicitly changes that to `False`.
+- In generated app-owned config like this workspace, `src/lib/auth/auth_config.py` starts with `is_all_routes_private=False`, so routes are public by default until the app chooses stricter route protection.
 - `public_routes`, `auth_routes`, `private_routes`, and `role_based_routes` are exact path matches in the installed `Auth` methods.
 - `private_routes` matters only when `is_all_routes_private=False`.
 - `role_based_routes` currently expects `PATH -> [ROLES]`, not role names keyed to paths the other way around.
 - `role_identifier` defaults to `role`, and the current `auth.sign_in(...)` flow also normalizes `userRole` into `role` when possible.
 - `api_auth_prefix` defaults to `/api/auth` and should stay centralized here rather than being hard-coded across routes.
 
+## Choosing Public vs Private Route Mode
+
+Make this decision at app setup time in `src/lib/auth/auth_config.py`.
+
+- In the default app-owned starter pattern used in this workspace, routes start public because `is_all_routes_private=False` in `src/lib/auth/auth_config.py`.
+- If the application has only a few public pages and most routes require auth, set `is_all_routes_private=True` and list the exceptions in `public_routes`.
+- If the application has many public pages and only a few protected areas, keep `is_all_routes_private=False` and list only the protected routes in `private_routes`.
+- In the current runtime, `auth_routes=["/signin", "/signup"]` stays public by default, and most apps do not need to change it unless the user explicitly asks for different auth routes.
+- In all-private mode, the default `public_routes=["/"]` keeps the home page public unless you change that list.
+- `token_auto_refresh=True` does not make routes private. It only enables sliding-session refresh when the request lifecycle calls `auth.refresh_session()`.
+- You do not need to modify Caspian core files for this decision. Keep the policy in `src/lib/auth/auth_config.py`.
+- If you customize `src/lib/auth/auth_config.py`, add it to `excludeFiles` in `caspian.config.json` so update commands do not overwrite your local auth policy.
+
+Example all-private setup with a few public exceptions:
+
+```python
+return AuthSettings(
+    default_token_validity="1h",
+    token_auto_refresh=False,
+    is_all_routes_private=True,
+    public_routes=["/", "/pricing", "/about"],
+    auth_routes=["/signin", "/signup"],
+    private_routes=[],
+)
+```
+
+Example mixed app with many public routes and only a few protected areas:
+
+```python
+return AuthSettings(
+    default_token_validity="1h",
+    token_auto_refresh=False,
+    is_all_routes_private=False,
+    public_routes=["/"],
+    auth_routes=["/signin", "/signup"],
+    private_routes=["/dashboard", "/settings", "/billing"],
+)
+```
+
 ## Environment Variables
 
 The installed auth code reads several values from `.env` when explicit values are not passed.
@@ -414,16 +455,58 @@ src/
             signup/
                 index.py
                 index.html
-        signout/
-            index.py
+            signout/
+                index.py
         dashboard/
             index.py
             index.html
 ```
 
-Use `guest_only()` on signin and signup routes, use `auth.sign_in(...)` inside the owning RPC action after validation and credential checks, and protect private destinations with `require_auth()` or central route policy.
+Use `guest_only()` on signin and signup routes, use `auth.sign_in(...)` inside the owning RPC action after validation and credential checks, prefer RPC for signout UI actions, and protect private destinations with `require_auth()` or central route policy.
+
+Preferred signout pattern: auth-protected RPC from a page or component.
+
+Use this when the logout trigger lives in a page, layout, header, dropdown, or reusable component. The HTML can live at page level or component level.
+
+```html
+<div>
+    <button onclick="signout()">
+        Sign out
+    </button>
+
+    <script>
+        async function signout() {
+            await pp.rpc("signout");
+        }
+    </script>
+</div>
+```
+
+```python
+from casp.auth import auth
+from casp.rpc import rpc
+
+
+@rpc(require_auth=True)
+def signout():
+    return auth.sign_out()
+```
+
+Fallback signout pattern: dedicated route.
+
+Use this when you need a plain HTML form POST, a no-JavaScript fallback, or a full-route signout endpoint.
+
+HTML:
+
+```html
+<form action="/signout" method="post">
+    <button type="submit">
+        <span>Log Out</span>
+    </button>
+</form>
+```
 
-Simple signout route example:
+Route: `src/app/(auth)/signout/index.py`
 
 ```python
 from casp.auth import auth, require_auth
@@ -659,11 +742,17 @@ Validate and authenticate close to the input boundary.
 Common placement patterns are:
 
 - put centralized policy in `src/lib/auth/auth_config.py`
+- decide public-vs-private route mode at app start in `src/lib/auth/auth_config.py` instead of scattering route privacy logic across route files
+- use `is_all_routes_private=True` only when most routes should require auth; otherwise keep `is_all_routes_private=False` and maintain `private_routes`
+- keep public exceptions in `public_routes`, and leave `auth_routes=["/signin", "/signup"]` alone unless the app explicitly needs different auth endpoints
 - call `configure_auth(build_auth_settings())` during startup
-- keep sign-in, signup, signout, and reset-password handlers in the owning route backend under `src/app/**/index.py`
+- keep sign-in, signup, and reset-password handlers in the owning route backend under `src/app/**/index.py`
+- prefer signout through `pp.rpc("signout")` with `@rpc(require_auth=True)` when the trigger lives in page or component UI
+- use a dedicated signout route only for no-JavaScript, form-post, or full-navigation edge cases
 - use `@rpc()` for browser-triggered auth actions and page decorators for full-route protection
 - use `Validate` and `Rule` from `casp.validate` before password checks, user lookup, persistence, or external provider flows
 - keep reusable auth helpers in `src/lib/auth/`
+- protect customized auth policy files from updater overwrite with `excludeFiles` in `caspian.config.json`
 
 For browser-triggered auth forms, pair this page with `fetch-data.md`. For credential and form validation, pair it with `validation.md`.
 
@@ -673,15 +762,22 @@ If an AI agent is deciding how to handle auth in Caspian, apply these rules firs
 
 - Treat `casp.auth` as the default authentication layer.
 - Centralize route visibility, redirects, and RBAC policy in `src/lib/auth/auth_config.py`.
+- Decide route mode early in `src/lib/auth/auth_config.py`: use `is_all_routes_private=True` when most routes should require auth, otherwise keep `is_all_routes_private=False` and list protected routes in `private_routes`.
+- In app-owned starter config like this workspace, treat `is_all_routes_private=False` as the default starting point, which means routes begin public until the app opts into stricter protection.
+- Treat `public_routes` as the public exception list for all-private apps. In the current defaults, `/` stays public and `auth_routes=["/signin", "/signup"]` stays public too.
 - Apply settings at startup in `main.py` with `configure_auth(build_auth_settings())`.
 - Register provider instances in `main.py` with `Auth.set_providers(...)` when Google or GitHub OAuth is enabled.
 - Use `auth.sign_in(...)` and `auth.sign_out(...)` for session lifecycle changes.
+- Prefer `pp.rpc("signout")` plus `@rpc(require_auth=True)` for logout buttons or menus in pages and components.
+- Use a dedicated `/signout` route only for plain HTML form POST, no-JavaScript fallback, or other full-navigation edge cases.
+- Do not treat `token_auto_refresh` as a route-privacy switch. In the current app it only affects sliding-session refresh if `auth.refresh_session()` is called.
 - Use `@require_auth`, `@require_role`, and `@guest_only` for page-level access rules.
 - Use `@rpc(require_auth=True, allowed_roles=[...])` for protected browser-triggered actions.
 - Keep `SessionMiddleware` outermost so auth, CSRF, and RPC handlers can read `request.session`.
 - Use [state.md](./state.md) only for transient auth-adjacent request state, not as the auth session store.
 - Align `SESSION_LIFETIME_HOURS` with `default_token_validity` unless you intentionally want different cookie and auth-payload expiry windows.
 - Prefer exact route strings in `public_routes`, `auth_routes`, `private_routes`, and `role_based_routes`.
+- Protect customized `src/lib/auth/auth_config.py` from updater overwrite by adding it to `excludeFiles` in `caspian.config.json`.
 - Keep auth secrets and OAuth provider credentials in `.env`.
 - Set `AUTH_COOKIE_NAME` explicitly so the session middleware cookie name and auth settings stay aligned.
 - Use `.venv/Lib/site-packages/casp/auth.py` only when the task is about framework auth internals or debugging installed behavior.

package/dist/docs/commands.md

@@ -3,10 +3,11 @@ title: Commands
 description: Use the current Caspian CLI reference to choose the right scaffold, starter-kit, update, and Prisma regeneration workflow for the current workspace.
 related:
   title: Related docs
-  description: Start with installation for new apps, then use database and structure docs when commands affect schema, generated ORM files, or project layout.
+  description: Start with installation for new apps, then use database, MCP, and structure docs when commands affect schema, server tooling, generated ORM files, or project layout.
   links:
     - /docs/installation
     - /docs/database
+    - /docs/mcp
     - /docs/routing
     - /docs/project-structure
     - /docs/index
@@ -18,6 +19,8 @@ This page documents the current Caspian command families used with this workspac
 
 The current workspace includes a local `prisma` binary, but it does not include local `create-caspian-app`, `casp`, or `ppy` binaries under `node_modules/.bin`. Treat project creation, project update, and Python ORM generation as external `npx` workflows rather than project-local executables.
 
+The current workspace also includes a local MCP run path through `npm run mcp`, which starts the app-owned FastMCP server via `settings/restart-mcp.ts`.
+
 Examples below use `npx create-caspian-app` for readability. If you want to force the latest published scaffold package explicitly, you can use `npx create-caspian-app@latest` instead.
 
 This updated reference includes the newer updater behavior and the current scaffold behavior:
@@ -29,7 +32,7 @@ This updated reference includes the newer updater behavior and the current scaff
 - Windows-safe execution that resolves `npx.cmd` on Win32
 - scaffold behavior that reuses an existing `.venv` instead of recreating it every time
 
-Before running update commands, read `caspian.config.json` because it controls feature flags and `excludeFiles` overwrite protection. In the current workspace that config shows `backendOnly: false`, `tailwindcss: true`, `mcp: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+Before running update commands, read `caspian.config.json` because it controls feature flags and `excludeFiles` overwrite protection. In the current workspace that config shows `backendOnly: false`, `tailwindcss: true`, `mcp: true`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
 
 ## 1. Main Command Families
 
@@ -66,6 +69,38 @@ npx casp update project
 
 Use when you are inside an existing Caspian project and want to refresh framework-managed files using the project's `caspian.config.json`.
 
+### Run the local MCP server
+
+```bash
+npm run mcp
+```
+
+Use when you want the workspace's app-owned FastMCP server only.
+
+### Run the full local stack including MCP
+
+```bash
+npm run dev
+```
+
+Use when you want BrowserSync, Tailwind, the Python app server, and MCP together.
+
+### Inspect the local MCP config directly
+
+```powershell
+.venv\Scripts\fastmcp.exe inspect src/lib/mcp/fastmcp.json
+```
+
+Use when you are debugging the nested FastMCP config or checking which tools the current MCP server exposes.
+
+### Run FastMCP directly with the nested config
+
+```powershell
+.venv\Scripts\fastmcp.exe run src/lib/mcp/fastmcp.json --no-banner
+```
+
+Use when you want the raw FastMCP path without the npm wrapper.
+
 ### Regenerate ORM after schema changes
 
 ```bash
@@ -80,6 +115,8 @@ npx ppy generate
 
 Use when `prisma/schema.prisma` changes and you need migrations, seed flow, and the generated Python ORM layer to stay aligned.
 
+Because this workspace keeps `fastmcp.json` under `src/lib/mcp/`, plain `fastmcp run` from the project root does not auto-detect the config. Use `npm run mcp` or pass the explicit config path.
+
 ## 2. Supported Flags And Options
 
 ### For `create-caspian-app`
@@ -606,6 +643,10 @@ This is useful for protecting:
 - entry-point files
 - other locally modified framework-managed files
 
+Auth example:
+
+- add `./src/lib/auth/auth_config.py` to `excludeFiles` when you customize route privacy policy, public-route exceptions, redirects, or other app-specific auth settings there
+
 If you exclude a file, the updater preserves it, but you are responsible for merging future framework changes into that file manually.
 
 ## 10. Operational Notes

package/dist/docs/fetch-data.md

@@ -3,9 +3,10 @@ title: Fetch Data
 description: Fetch first-render and interactive data in Caspian with async route functions, `@rpc()` actions, `pp.rpc()`, streaming, and uploads, with RPC as the default browser-to-server data path.
 related:
   title: Related docs
-  description: Use the routing guide to place route logic correctly, then use the auth guide for protected actions, the state guide for transient request-scoped mutation state, the cache guide for reusable first-render HTML, and the PulsePoint runtime guide for client-side `pp.rpc()` details.
+  description: Use the routing guide to place route logic correctly, then use the auth guide for protected actions, the MCP guide for AI-facing tools, the state guide for transient request-scoped mutation state, the cache guide for reusable first-render HTML, and the PulsePoint runtime guide for client-side `pp.rpc()` details.
   links:
     - /docs/auth
+    - /docs/mcp
     - /docs/state
     - /docs/database
     - /docs/cache
@@ -19,6 +20,8 @@ This page explains how data fetching works in Caspian. Use route functions for i
 
 Treat RPC as the default way for browser code to talk to Python in Caspian. Do not reach for ad hoc fetch calls to custom JSON endpoints, alternate transport layers, or older helper names unless the task explicitly requires that shape.
 
+MCP is a separate integration surface. Do not place app-owned FastMCP tools in route `index.py` files or treat `@rpc()` actions as a replacement for MCP tools. In this workspace, MCP tool definitions live under `src/lib/mcp/` and are documented in `mcp.md`.
+
 ## Overview
 
 Caspian has two main data-loading paths:

package/dist/docs/index.md

@@ -7,6 +7,7 @@ related:
   links:
     - /docs/installation
     - /docs/commands
+    - /docs/mcp
     - /docs/project-structure
     - /docs/components
 ---
@@ -37,8 +38,9 @@ The packaged Caspian docs distributed by the current toolchain also live here:
 
 - `installation.md` - First-time setup flow for creating a new Caspian application
 - `commands.md` - Main Caspian CLI workflows for project creation, generation, updates, and config-aware maintenance
+- `mcp.md` - Workspace FastMCP server layout, nested config path, local launch flow, and MCP-specific AI routing rules
 - `database.md` - Prisma schema, migration, seed, and client-generation workflow for the current workspace, plus Python-side helper caveats
-- `auth.md` - Session-backed authentication with `casp.auth`, centralized `auth_config.py`, decorators, RBAC, and OAuth provider helpers
+- `auth.md` - Session-backed authentication with `casp.auth`, centralized `auth_config.py`, public-vs-private route mode guidance, RPC-first signout guidance, RBAC, and OAuth provider helpers
 - `components.md` - Create reusable Python components, template-backed UI, JSX-style imports, and the single-parent root rule for component HTML files
 - `pulsepoint.md` - Default reactive frontend runtime contract for component scripts, state, effects, directives, and client-side behaviors
 - `fetch-data.md` - Initial server-side data loading and browser-triggered RPC flows with `pp.rpc()`, streaming, uploads, and auth-aware actions
@@ -57,7 +59,7 @@ Preferred lookup order:
 
 1. Read `node_modules/caspian-utils/dist/docs/index.md` to discover available local docs.
 2. Read `./caspian.config.json` before making any feature assumption. Use it to confirm which project capabilities are enabled and which directories or tooling rules apply.
-3. Read `database.md` for Prisma setup and ORM usage, `auth.md` for session auth and route protection, `components.md` for reusable UI authoring, `pulsepoint.md` for browser-side reactive runtime behavior, `fetch-data.md` for data flows, `state.md` for transient request-scoped state, `cache.md` for page caching, and `validation.md` for input boundaries.
+3. Read `database.md` for Prisma setup and ORM usage, `mcp.md` for the current FastMCP server layout and local run flow, `auth.md` for session auth and route protection, `components.md` for reusable UI authoring, `pulsepoint.md` for browser-side reactive runtime behavior, `fetch-data.md` for data flows, `state.md` for transient request-scoped state, `cache.md` for page caching, and `validation.md` for input boundaries.
 4. For authored component, route, and layout HTML files, generate exactly one top-level lowercase HTML element. Think React-style single parent wrapper: keep any owned PulsePoint logic in a plain `<script>` inside that root, do not handwrite `pp-component="..."` or `type="text/pp"` because Caspian injects those runtime attributes automatically, and treat `<!-- @import ... -->` comments as file-level directives that belong above the authored root element instead of inside `<div>`, `<section>`, or `<html>`. When several component tags come from one Python file, import them from that exact file path, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`.
 5. Prefer local docs before generating code, commands, or migration guidance.
 6. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.

package/dist/docs/installation.md

@@ -3,8 +3,10 @@ title: Installation
 description: Learn how to create a new Caspian application so AI agents use the first-time setup flow instead of assuming an existing project is already in place.
 related:
   title: Related docs
-  description: Continue with the routing and structure guides after scaffold so the new app follows Caspian conventions.
+  description: Continue with the routing, structure, and MCP guides after scaffold so the new app follows Caspian conventions and keeps optional FastMCP files in the right place.
   links:
+    - /docs/commands
+    - /docs/mcp
     - /docs/routing
     - /docs/project-structure
     - /docs/index
@@ -54,6 +56,8 @@ The interactive wizard walks through the main project options, including:
 - Feature toggles such as backend-only mode, Tailwind CSS, Prisma, MCP, and TypeScript
 - Other scaffold options exposed by the current CLI version
 
+If the project enables MCP, use `mcp.md` after scaffold to place the app-owned FastMCP server and config files correctly for the current workspace conventions.
+
 ## Recommended VS Code Setup
 
 For the best development experience, use these VS Code extensions:
@@ -83,7 +87,8 @@ In this workspace, `npm run dev` is backed by BrowserSync plus PostCSS watchers,
 Once the project is scaffolded:
 
 - Read `database.md` when the app includes Prisma ORM support or needs database changes.
-- Read `auth.md` before wiring session config, sign-in or signout routes, route guards, or OAuth providers.
+- Read `mcp.md` when the app includes MCP support or needs FastMCP server, config, or launch-flow changes.
+- Read `auth.md` before choosing public-vs-private route mode, wiring session config, sign-in or signout flows, route guards, or OAuth providers.
 - Read `pulsepoint.md` before generating interactive frontend behavior.
 - Read `fetch-data.md` before adding browser-triggered reads, writes, uploads, or streams.
 - Read `validation.md` before handling forms, auth input, or RPC payloads.
@@ -97,5 +102,6 @@ If an AI agent is reading this page, treat it as the source for new-project inst
 - Use this workflow when the user is creating a Caspian app from scratch.
 - Do not use existing-project migration or update commands unless the project already exists.
 - After scaffold, default to PulsePoint for interactive UI, RPC for browser-to-server data flow, and `casp.validate` for validation.
+- If MCP is enabled, read [mcp.md](./mcp.md) before editing FastMCP files or assuming where the server config should live.
 - Once the app exists, check [routing.md](./routing.md) before creating or changing routes under `src/app/`.
 - Check [index.md](./index.md) first when deciding which local doc to follow.

package/dist/docs/mcp.md

@@ -0,0 +1,102 @@
+---
+title: MCP
+description: Use the workspace FastMCP setup through src/lib/mcp/mcp_server.py, src/lib/mcp/fastmcp.json, and settings/restart-mcp.ts, with npm-driven startup and explicit manual paths when running FastMCP directly.
+related:
+  title: Related docs
+  description: Start with project structure for file placement, then use commands for local run flows and index for documentation routing.
+  links:
+    - /docs/project-structure
+    - /docs/commands
+    - /docs/fetch-data
+    - /docs/index
+---
+
+This page documents the Model Context Protocol workflow present in this workspace.
+
+The current repo enables MCP in `caspian.config.json`, keeps the app-owned FastMCP server at `src/lib/mcp/mcp_server.py`, keeps the FastMCP config at `src/lib/mcp/fastmcp.json`, and starts it through `npm run mcp`, which runs `settings/restart-mcp.ts`.
+
+## Overview
+
+Use these rules as the default MCP workflow in this workspace:
+
+1. Read `caspian.config.json` and confirm `mcp: true` before assuming MCP files should exist or be started.
+2. Edit `src/lib/mcp/mcp_server.py` when changing FastMCP tools, server instructions, or server-owned helper logic.
+3. Edit `src/lib/mcp/fastmcp.json` when changing the transport, host, port, path, or server entrypoint.
+4. Edit `settings/restart-mcp.ts` when changing discovery order, environment overrides, or MCP log filtering.
+5. Use `npm run mcp` as the normal local launch flow.
+
+## Current Workspace Layout
+
+- `src/lib/mcp/mcp_server.py` defines `mcp = FastMCP(...)` and the current workspace tools.
+- `src/lib/mcp/fastmcp.json` points to `src/lib/mcp/mcp_server.py` and configures `streamable-http` on `127.0.0.1:5101/mcp`.
+- `settings/restart-mcp.ts` is the npm-facing launcher. It resolves MCP config paths, starts FastMCP, and trims noisy banner or warning output down to essential lines.
+- `package.json` defines `npm run mcp` as `tsx settings/restart-mcp.ts` and includes `mcp` in `npm run dev`.
+- `caspian.config.json` is the feature gate. If `mcp` is false, the MCP runner exits cleanly without starting a server.
+
+## Current Tools
+
+The app-owned MCP server currently exposes these read-only tools:
+
+- `project_info` returns the project name, root path, version metadata, browser sync target, feature flags, and component scan directories.
+- `workspace_files` returns the generated workspace file list, optionally filtered to `all`, `app`, or `public`.
+- `component_inventory` returns the latest generated component map from `settings/component-map.json`.
+
+Add or change tools in `src/lib/mcp/mcp_server.py`.
+
+## Running The Server
+
+### Preferred local commands
+
+```bash
+npm run mcp
+npm run dev
+```
+
+Use `npm run mcp` when you want the MCP server only. Use `npm run dev` when you want BrowserSync, Tailwind, the Python app server, and MCP together.
+
+### Direct FastMCP commands
+
+On this Windows workspace, the direct FastMCP commands are:
+
+```powershell
+.venv\Scripts\fastmcp.exe inspect src/lib/mcp/fastmcp.json
+.venv\Scripts\fastmcp.exe run src/lib/mcp/fastmcp.json --no-banner
+```
+
+Because the config file lives under `src/lib/mcp/`, plain `fastmcp run` from the project root does not auto-detect it. Use `npm run mcp` or pass the explicit config path.
+
+## Config And Discovery Rules
+
+`settings/restart-mcp.ts` currently resolves MCP server specs in this order:
+
+1. `MCP_SERVER_SPEC`
+2. `src/lib/mcp/fastmcp.json`
+3. `fastmcp.json`
+4. `mcp.json`
+
+The runner also forwards these optional overrides to FastMCP:
+
+- `MCP_TRANSPORT`
+- `MCP_HOST`
+- `MCP_PORT`
+- `MCP_PATH`
+- `MCP_LOG_LEVEL`
+
+Keep the `source.path` value in `src/lib/mcp/fastmcp.json` root-relative as `src/lib/mcp/mcp_server.py`. Do not shorten it to `mcp_server.py` unless the launch working directory changes too, because FastMCP resolves that path from the current working directory.
+
+## AI Routing Notes
+
+If an AI tool is working on MCP in this workspace, use this order:
+
+1. Read `caspian.config.json` to confirm `mcp: true`.
+2. Read `node_modules/caspian-utils/dist/docs/mcp.md` for the current workspace MCP rules.
+3. Read `src/lib/mcp/mcp_server.py` for tool definitions and server instructions.
+4. Read `src/lib/mcp/fastmcp.json` for transport and entrypoint configuration.
+5. Read `settings/restart-mcp.ts` and `package.json` for local start behavior.
+
+Default placement rules:
+
+- Put app-owned FastMCP tools in `src/lib/mcp/mcp_server.py`.
+- Keep the default FastMCP config in `src/lib/mcp/fastmcp.json`.
+- Keep npm-facing launch behavior in `settings/restart-mcp.ts`.
+- If the MCP file layout changes, update this page, `AGENTS.md`, `.github/copilot-instructions.md`, and any workspace runner logic together.

package/dist/docs/project-structure.md

@@ -1,13 +1,14 @@
 ---
 title: Project Structure
-description: Understand the default Caspian project layout so AI agents place routes, reusable components, PulsePoint templates, RPC actions, validation helpers, auth code, configuration, and database changes in the correct directories.
+description: Understand the default Caspian project layout so AI agents place routes, reusable components, PulsePoint templates, RPC actions, validation helpers, auth code, MCP files, configuration, and database changes in the correct directories.
 related:
   title: Related docs
-  description: Start with installation for new apps, then use the component guide for reusable UI, the auth guide for bootstrap and session wiring, the routing guide to map URLs correctly, and the cache guide when route HTML should be reused safely.
+  description: Start with installation for new apps, then use the component guide for reusable UI, the auth guide for bootstrap and session wiring, the MCP guide for server layout, the routing guide to map URLs correctly, and the cache guide when route HTML should be reused safely.
   links:
     - /docs/installation
     - /docs/components
     - /docs/auth
+    - /docs/mcp
     - /docs/routing
     - /docs/cache
     - /docs/database
@@ -31,6 +32,7 @@ Before an AI agent decides which Caspian features are available in a workspace,
 - `src/` contains routes, page templates, styles, and shared libraries.
 - `src/components/` contains reusable Python components and optional same-name HTML templates.
 - `src/lib/auth/auth_config.py` contains auth-specific configuration for the app.
+- `src/lib/mcp/` contains the app-owned FastMCP server and nested FastMCP config when MCP is enabled.
 - `prisma/` contains the Prisma schema and seed scripts.
 - `public/` contains static assets served directly.
 - `main.py` is the application entry point.
@@ -62,6 +64,9 @@ my-app/
     lib/
       auth/
         auth_config.py
+      mcp/
+        fastmcp.json
+        mcp_server.py
       prisma/
         __init__.py
         db.py
@@ -112,6 +117,8 @@ Use this folder for shared helpers, reusable validators, RPC-facing service wrap
 
 This workspace already includes an app-owned Python database layer under `src/lib/prisma/`. Reuse that package for Python-side data access and keep any additional shared database helpers in `src/lib/`.
 
+When MCP is enabled in the current workspace, this folder also contains the app-owned FastMCP server under `src/lib/mcp/`.
+
 ### Shared Database Helpers
 
 If your Python routes or RPC actions need reusable database access code, keep that helper layer under `src/lib/` and extend the existing `src/lib/prisma/` package.
@@ -122,6 +129,17 @@ In this workspace, Prisma schema and seed files live under `prisma/`, while the
 
 Use this folder for authentication-specific project code. The main auth configuration file lives at `src/lib/auth/auth_config.py`.
 
+### `src/lib/mcp/`
+
+Use this folder for app-owned Model Context Protocol server files.
+
+In the current workspace:
+
+- `src/lib/mcp/mcp_server.py` defines `mcp = FastMCP(...)` and the current tool set.
+- `src/lib/mcp/fastmcp.json` is the default FastMCP config used by `npm run mcp`.
+
+Keep MCP tool definitions here instead of placing them in route files, `main.py`, or framework internals.
+
 ### `prisma/`
 
 This folder contains your database model definitions in `schema.prisma` and any seed logic such as `seed.ts`.
@@ -153,12 +171,22 @@ The core feature configuration file for the application.
 
 AI agents should read this file before making almost any feature-level decision. Use it to confirm which capabilities are enabled, which code generation paths make sense, and which directories should be scanned for components or other project assets.
 
-In the current workspace, `caspian.config.json` shows `backendOnly: false`, `tailwindcss: true`, `mcp: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+In the current workspace, `caspian.config.json` shows `backendOnly: false`, `tailwindcss: true`, `mcp: true`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
 
 ### `src/lib/auth/auth_config.py`
 
 The project auth configuration file. Use this path when changing authentication behavior.
 
+### `src/lib/mcp/mcp_server.py`
+
+The app-owned FastMCP server module for this workspace. It exports the `mcp` server instance and should be the default place for workspace MCP tools.
+
+### `src/lib/mcp/fastmcp.json`
+
+The default FastMCP config file for this workspace.
+
+Because this file is nested under `src/lib/mcp/`, direct FastMCP commands should pass the explicit path, for example `fastmcp run src/lib/mcp/fastmcp.json`, unless the launch working directory changes.
+
 ### `src/app/layout.html`
 
 The root layout shared across pages.
@@ -204,9 +232,11 @@ If an AI agent is deciding where to make changes, use these rules first.
 - Put route templates and route-specific backend logic in `src/app/`.
 - Check [routing.md](./routing.md) when you need URL segment rules, layout nesting behavior, or dynamic route conventions.
 - Put reusable component files in `src/components/` and check [components.md](./components.md) for `@component`, `render_html(__file__)`, import comments, and single-root template rules.
+- Use [mcp.md](./mcp.md) when the task involves FastMCP tool definitions, nested config discovery, or local MCP commands.
 - Keep `<!-- @import ... -->` comments above the single authored root element in route, layout, and component HTML files.
 - For route and component HTML files, always emit one top-level lowercase HTML element. Good: one wrapper containing the content and a plain `<script>` when needed. Bad: a wrapper element followed by a sibling top-level `<script>`, or handwritten `pp-component="..."` and `type="text/pp"` attributes in source.
 - Put shared helpers and reusable libraries in `src/lib/`.
+- Put app-owned FastMCP code in `src/lib/mcp/`.
 - Use PulsePoint conventions in route templates for reactive frontend behavior.
 - Use `@rpc()` in route/backend code and `pp.rpc()` in client code for browser-triggered data flows.
 - Use `casp.cache_handler` when a route's first-render HTML should be reused safely across requests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caspian-utils",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {