create-caspian-app 0.2.0-beta.27 → 0.2.0-beta.28

package/dist/.github/copilot-instructions.md

@@ -13,6 +13,7 @@
 - When `prisma/schema.prisma` changes, follow this order: run `npx prisma migrate dev`; if the change affects seed flow or `prisma/seed.ts`, run `npx prisma generate` and then `npx prisma db seed`; then run `npx ppy generate` so the Python ORM stays aligned with the schema.
 - Reuse the existing Python database layer in `src/lib/prisma/**`; do not create a second app-owned database abstraction unless the user explicitly asks for one.
 - Treat `src/lib/prisma/__init__.py`, `src/lib/prisma/db.py`, `src/lib/prisma/models.py`, and `settings/prisma-schema.json` as generated outputs owned by `npx ppy generate`; do not create or hand-edit them manually.
+- When `caspian.config.json` has `mcp: true`, treat `src/lib/mcp/mcp_server.py` as the app-owned FastMCP server and `src/lib/mcp/fastmcp.json` as the default MCP config. Use `npm run mcp` or `fastmcp run src/lib/mcp/fastmcp.json`; do not assume root `fastmcp.json` auto-discovery.
 - Keep auth policy in `src/lib/auth/auth_config.py` and keep auth bootstrap, middleware wiring, and provider registration in `main.py`.
 - Use PulsePoint and `pp.rpc(...)` as the default frontend and client-to-server contract unless the user requests another stack.
 - Treat `pp-component` on routes, layouts, and components, and `type="text/pp"` on owned PulsePoint scripts, as compiler-injected by the Python side; do not add them manually in authored templates unless the task is explicitly about runtime internals.
@@ -34,6 +35,7 @@
 
 - Keep `src/lib/` for app-owned shared code, service wrappers, and reusable helpers.
 - Reuse the generated `src/lib/prisma/` package for Python database access, but do not hand-edit files under `src/lib/prisma/`; regenerate them with `npx ppy generate` after schema changes.
+- Keep app-owned MCP tools in `src/lib/mcp/mcp_server.py` and keep the default FastMCP config in `src/lib/mcp/fastmcp.json`. If those locations change, update `settings/restart-mcp.ts` and the MCP docs together.
 - Keep auth policy in `src/lib/auth/auth_config.py`. Keep auth bootstrap and middleware order changes in `main.py`.
 
 ### `public/js/main.js`
@@ -77,17 +79,20 @@
 
 - These files are the local documentation layer, not the runtime. Verify every behavior claim against the actual code that runs.
 - Use this verification order:
-	1. `caspian.config.json`, then `main.py`, `src/lib/**`, `public/js/**`, `prisma/**`, `src/app/**`
-	2. `.venv/Lib/site-packages/casp/**`
-	3. the markdown file being edited
+  1.  `caspian.config.json`, then `main.py`, `src/lib/**`, `public/js/**`, `prisma/**`, `src/app/**`
+  2.  `.venv/Lib/site-packages/casp/**`
+  3.  the markdown file being edited
 - Keep repo-specific facts accurate when they matter:
-	- `caspian.config.json` is the first config file to read for enabled workspace features and scan directories
-	- this workspace already has `src/lib/prisma/**`
-	- auth policy lives in `src/lib/auth/auth_config.py`
-	- PulsePoint runtime lives in `public/js/pp-reactive-v2.js`
-	- `pp-component` is injected by the Python render pipeline, and `main.py` rewrites authored body scripts to `type="text/pp"`; authored route, layout, and component templates should not add those attributes manually
-	- route, layout, and component templates must keep a single top-level lowercase HTML root for `pp-component` injection, with any owned plain `<script>` kept inside that same root
-	- dynamic route params are passed to `page()` as a single positional `dict`
-	- `layout()` is sync-only in the installed runtime
-	- `StateManager` persistence depends on `request.state.session`, which is not bridged from `request.session` in the current `main.py`
-- Keep `index.md` and cross-links aligned when adding or changing pages.
+  - `caspian.config.json` is the first config file to read for enabled workspace features and scan directories
+  - this workspace already has `src/lib/prisma/**`
+  - this workspace's app-owned FastMCP server lives in `src/lib/mcp/mcp_server.py`
+  - the default FastMCP config lives in `src/lib/mcp/fastmcp.json`
+  - `package.json` starts MCP through `npm run mcp`, which runs `settings/restart-mcp.ts`; manual FastMCP runs should pass the explicit nested config path because root auto-discovery does not find it
+  - auth policy lives in `src/lib/auth/auth_config.py`
+  - PulsePoint runtime lives in `public/js/pp-reactive-v2.js`
+  - `pp-component` is injected by the Python render pipeline, and `main.py` rewrites authored body scripts to `type="text/pp"`; authored route, layout, and component templates should not add those attributes manually
+  - route, layout, and component templates must keep a single top-level lowercase HTML root for `pp-component` injection, with any owned plain `<script>` kept inside that same root
+  - dynamic route params are passed to `page()` as a single positional `dict`
+  - `layout()` is sync-only in the installed runtime
+  - `StateManager` persistence depends on `request.state.session`, which is not bridged from `request.session` in the current `main.py`
+- Keep `index.md` and cross-links aligned when adding or changing pages.

package/dist/AGENTS.md

@@ -39,11 +39,13 @@ Before making feature, tooling, or scaffolding decisions, read `caspian.config.j
 - App-level auth policy lives in `src/lib/auth/auth_config.py`.
 - `main.py` applies auth settings with `configure_auth(build_auth_settings())` and registers `GithubProvider()` plus `GoogleProvider()`.
 - This workspace already has an app-owned Python database layer in `src/lib/prisma/`.
+- This workspace now has an app-owned FastMCP server at `src/lib/mcp/mcp_server.py`, with `src/lib/mcp/fastmcp.json` as the default MCP server spec.
+- `package.json` starts MCP through `npm run mcp`, which runs `settings/restart-mcp.ts` and prefers `src/lib/mcp/fastmcp.json` before legacy root configs. Direct FastMCP runs should pass the explicit nested config path.
 - Reuse `src/lib/prisma/prisma`, `PrismaClient`, generated models, and helper types instead of creating a second Python database abstraction.
 - Prisma schema source of truth is `prisma/schema.prisma`.
 - The schema-change workflow in this workspace is: `npx prisma migrate dev`; if seed flow or `prisma/seed.ts` is involved, run `npx prisma generate` and then `npx prisma db seed`; then run `npx ppy generate`.
 - `npx ppy generate` owns `src/lib/prisma/__init__.py`, `src/lib/prisma/db.py`, `src/lib/prisma/models.py`, and `settings/prisma-schema.json`; do not hand-edit those generated files.
-- `caspian.config.json` is the first config file to check for enabled workspace features. In the current workspace it sets `backendOnly: false`, `tailwindcss: true`, `mcp: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+- `caspian.config.json` is the first config file to check for enabled workspace features. In the current workspace it sets `backendOnly: false`, `tailwindcss: true`, `mcp: true`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
 - PulsePoint runtime code is shipped in `public/js/pp-reactive-v2.js` and loaded from `public/js/main.js`.
 - `pp-component` is injected by the Python render pipeline onto page, layout, and component roots; authored route and component templates should not add it manually.
 - `main.py` runs `transform_scripts(...)`, so authored body `<script>` tags are rewritten to `<script type="text/pp">` in rendered HTML; route, layout, and component templates should write plain `<script>` in source.
@@ -60,17 +62,18 @@ Before making feature, tooling, or scaffolding decisions, read `caspian.config.j
 
 Use this map before making changes.
 
-| Task area | Read first | Verify against |
-| --- | --- | --- |
-| Project layout and file placement | `node_modules/caspian-utils/dist/docs/index.md`, `node_modules/caspian-utils/dist/docs/project-structure.md` | current workspace tree |
-| Feature availability and tooling switches | `caspian.config.json` | current workspace tree, `main.py`, `prisma/**`, `public/js/**` |
-| Routing, layouts, metadata | `node_modules/caspian-utils/dist/docs/routing.md` | `main.py`, `.venv/Lib/site-packages/casp/layout.py` |
-| Auth, sessions, RBAC, providers | `node_modules/caspian-utils/dist/docs/auth.md` | `src/lib/auth/auth_config.py`, `main.py`, `.venv/Lib/site-packages/casp/auth.py` |
-| RPC, data loading, streaming, uploads | `node_modules/caspian-utils/dist/docs/fetch-data.md`, `node_modules/caspian-utils/dist/docs/pulsepoint.md` | `.venv/Lib/site-packages/casp/rpc.py`, `public/js/pp-reactive-v2.js`, `main.py` |
-| Server state | `node_modules/caspian-utils/dist/docs/state.md` | `.venv/Lib/site-packages/casp/state_manager.py`, `main.py` |
-| Page caching | `node_modules/caspian-utils/dist/docs/cache.md` | `.venv/Lib/site-packages/casp/cache_handler.py`, `main.py` |
-| Validation | `node_modules/caspian-utils/dist/docs/validation.md` | `.venv/Lib/site-packages/casp/validate.py` |
-| Database and seed flow | `node_modules/caspian-utils/dist/docs/database.md` | `prisma/schema.prisma`, `prisma/seed.ts`, `src/lib/prisma/**` |
+| Task area                                 | Read first                                                                                                   | Verify against                                                                   |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| Project layout and file placement         | `node_modules/caspian-utils/dist/docs/index.md`, `node_modules/caspian-utils/dist/docs/project-structure.md` | current workspace tree                                                           |
+| Feature availability and tooling switches | `caspian.config.json`                                                                                        | current workspace tree, `main.py`, `prisma/**`, `public/js/**`                   |
+| MCP server layout and launch flow         | `node_modules/caspian-utils/dist/docs/mcp.md`                                                                | `settings/restart-mcp.ts`, `package.json`, `src/lib/mcp/**`                      |
+| Routing, layouts, metadata                | `node_modules/caspian-utils/dist/docs/routing.md`                                                            | `main.py`, `.venv/Lib/site-packages/casp/layout.py`                              |
+| Auth, sessions, RBAC, providers           | `node_modules/caspian-utils/dist/docs/auth.md`                                                               | `src/lib/auth/auth_config.py`, `main.py`, `.venv/Lib/site-packages/casp/auth.py` |
+| RPC, data loading, streaming, uploads     | `node_modules/caspian-utils/dist/docs/fetch-data.md`, `node_modules/caspian-utils/dist/docs/pulsepoint.md`   | `.venv/Lib/site-packages/casp/rpc.py`, `public/js/pp-reactive-v2.js`, `main.py`  |
+| Server state                              | `node_modules/caspian-utils/dist/docs/state.md`                                                              | `.venv/Lib/site-packages/casp/state_manager.py`, `main.py`                       |
+| Page caching                              | `node_modules/caspian-utils/dist/docs/cache.md`                                                              | `.venv/Lib/site-packages/casp/cache_handler.py`, `main.py`                       |
+| Validation                                | `node_modules/caspian-utils/dist/docs/validation.md`                                                         | `.venv/Lib/site-packages/casp/validate.py`                                       |
+| Database and seed flow                    | `node_modules/caspian-utils/dist/docs/database.md`                                                           | `prisma/schema.prisma`, `prisma/seed.ts`, `src/lib/prisma/**`                    |
 
 ## Editing Rules
 
@@ -82,6 +85,7 @@ Use this map before making changes.
 - When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first. If seed flow or `prisma/seed.ts` is involved, run `npx prisma generate` and then `npx prisma db seed`. After that, run `npx ppy generate` so the Python ORM layer and `settings/prisma-schema.json` stay aligned.
 - Keep auth policy in `src/lib/auth/auth_config.py`.
 - Keep auth bootstrap, middleware ordering, provider wiring, and router behavior in `main.py`.
+- When MCP is enabled, keep the app-owned FastMCP server in `src/lib/mcp/mcp_server.py` and the default config in `src/lib/mcp/fastmcp.json`. If those paths move, update `settings/restart-mcp.ts` and the MCP docs together.
 - Use PulsePoint and `pp.rpc(...)` as the default frontend and browser-to-server contract unless the user explicitly wants another stack.
 - Treat `pp-component` as a framework-owned attribute on authored templates. Document it, but do not manually add it in normal route or component HTML.
 - Treat `type="text/pp"` on PulsePoint scripts as a render-time attribute too. In authored route, layout, and component HTML, write plain `<script>` and let Caspian rewrite it.
@@ -96,6 +100,7 @@ Use this map before making changes.
 The packaged docs in this workspace are already mostly aligned with the installed runtime, but keep these repo-specific clarifications in mind:
 
 - `database.md` is the source doc for the Prisma and Python ORM workflow in this repo: schema changes go through `npx prisma migrate dev`, optional `npx prisma generate` plus `npx prisma db seed`, then `npx ppy generate`, and generated ORM files under `src/lib/prisma/` plus `settings/prisma-schema.json` are not hand-edited.
+- `mcp.md` is the source doc for the nested FastMCP config path, the app-owned MCP server location, direct FastMCP command usage, and the workspace runner discovery order.
 - `state.md` is correct to warn that cross-request persistence depends on `request.state.session`, which is not bridged in the current `main.py`.
 - `routing.md`, `components.md`, `auth.md`, `fetch-data.md`, `cache.md`, `pulsepoint.md`, and `validation.md` should continue to be validated against the installed `casp` package before any behavior claims are changed.
 

package/dist/settings/restart-mcp.ts

@@ -0,0 +1,148 @@
+import { existsSync } from "fs";
+import { join } from "path";
+import caspianConfig from "../caspian.config.json";
+import { createRestartableProcess, onExit } from "./utils.js";
+
+const projectRoot = process.cwd();
+const localFastMcp =
+  process.platform === "win32"
+    ? join(projectRoot, ".venv", "Scripts", "fastmcp.exe")
+    : join(projectRoot, ".venv", "bin", "fastmcp");
+
+const fastMcpCommand = existsSync(localFastMcp) ? localFastMcp : "fastmcp";
+
+const suppressedLinePatterns = [
+  /AuthlibDeprecationWarning/,
+  /^It will be compatible before version 2\.0\.0\.$/,
+  /^from authlib\.jose import /,
+  /^INFO:\s+Started server process/,
+  /^INFO:\s+Waiting for application startup\.$/,
+  /^INFO:\s+Application startup complete\.$/,
+];
+
+function getServerSpec(): string | null {
+  const explicitSpec = process.env.MCP_SERVER_SPEC?.trim();
+  if (explicitSpec) {
+    return explicitSpec;
+  }
+
+  const defaultSpecs = ["src/lib/mcp/fastmcp.json", "fastmcp.json", "mcp.json"];
+  for (const relativeSpec of defaultSpecs) {
+    if (existsSync(join(projectRoot, relativeSpec))) {
+      return relativeSpec;
+    }
+  }
+
+  return null;
+}
+
+function buildArgs(serverSpec: string): string[] {
+  const args = ["run", serverSpec, "--no-banner"];
+  const transport = process.env.MCP_TRANSPORT?.trim();
+  const host = process.env.MCP_HOST?.trim();
+  const port = process.env.MCP_PORT?.trim();
+  const path = process.env.MCP_PATH?.trim();
+  const logLevel = process.env.MCP_LOG_LEVEL?.trim();
+
+  if (transport) args.push("--transport", transport);
+  if (host) args.push("--host", host);
+  if (port) args.push("--port", port);
+  if (path) args.push("--path", path);
+  if (logLevel) args.push("--log-level", logLevel);
+
+  return args;
+}
+
+function createLineHandler(handleLine: (line: string) => void) {
+  let buffer = "";
+
+  return (chunk: Buffer) => {
+    buffer += chunk.toString();
+    const lines = buffer.split(/\r?\n/);
+    buffer = lines.pop() ?? "";
+
+    for (const line of lines) {
+      handleLine(line);
+    }
+  };
+}
+
+function createMcpOutputHandler() {
+  let waitingForReadyUrl = false;
+  let readyReported = false;
+
+  return (line: string) => {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      return;
+    }
+
+    if (suppressedLinePatterns.some((pattern) => pattern.test(trimmed))) {
+      return;
+    }
+
+    if (trimmed.includes("Starting MCP server")) {
+      waitingForReadyUrl = true;
+      return;
+    }
+
+    if (trimmed.includes("transport '") && trimmed.endsWith(" on")) {
+      waitingForReadyUrl = true;
+      return;
+    }
+
+    const urlMatch = trimmed.match(/https?:\/\/\S+/);
+    if (
+      urlMatch &&
+      (waitingForReadyUrl || trimmed.includes("Uvicorn running on"))
+    ) {
+      waitingForReadyUrl = false;
+      if (!readyReported) {
+        console.log(`[mcp] Ready at ${urlMatch[0]}`);
+        readyReported = true;
+      }
+      return;
+    }
+
+    if (trimmed.startsWith("INFO:")) {
+      return;
+    }
+
+    waitingForReadyUrl = false;
+
+    if (/traceback|exception|error/i.test(trimmed)) {
+      console.error(`[mcp] ${trimmed}`);
+      return;
+    }
+
+    console.log(`[mcp] ${trimmed}`);
+  };
+}
+
+if (!caspianConfig.mcp) {
+  console.log("[mcp] Disabled in caspian.config.json, skipping MCP startup.");
+  process.exit(0);
+}
+
+const serverSpec = getServerSpec();
+
+if (!serverSpec) {
+  console.log(
+    "[mcp] Enabled, but no FastMCP server spec was found. Create src/lib/mcp/fastmcp.json or set MCP_SERVER_SPEC to a FastMCP config, file, or URL.",
+  );
+  process.exit(0);
+}
+
+const handleMcpOutput = createMcpOutputHandler();
+
+const runner = createRestartableProcess({
+  name: "mcp",
+  cmd: fastMcpCommand,
+  args: buildArgs(serverSpec),
+  startMessage: "[mcp] Starting MCP server...",
+  onStdout: createLineHandler(handleMcpOutput),
+  onStderr: createLineHandler(handleMcpOutput),
+});
+
+runner.start();
+onExit(() => runner.stop());

package/dist/settings/utils.ts

@@ -40,7 +40,7 @@ export function createSrcWatcher(
     logPrefix?: string;
     usePolling?: boolean;
     interval?: number;
-  }
+  },
 ): FSWatcher {
   const {
     exts,
@@ -87,7 +87,7 @@ export class DebouncedWorker {
   constructor(
     private work: () => Promise<void> | void,
     private debounceMs = 350,
-    private name = "worker"
+    private name = "worker",
   ) {}
 
   schedule(reason?: string) {
@@ -124,6 +124,7 @@ export function createRestartableProcess(spec: {
   cmd: string;
   args?: string[];
   stdio?: "inherit" | [any, any, any];
+  startMessage?: string;
   gracefulSignal?: NodeJS.Signals;
   forceKillAfterMs?: number;
   windowsKillTree?: boolean;
@@ -135,6 +136,7 @@ export function createRestartableProcess(spec: {
     cmd,
     args = [],
     stdio = ["ignore", "pipe", "pipe"],
+    startMessage,
     gracefulSignal = "SIGINT",
     forceKillAfterMs = 2000,
     windowsKillTree = true,
@@ -145,7 +147,9 @@ export function createRestartableProcess(spec: {
   let child: ChildProcess | null = null;
 
   function start() {
-    console.log(`[${name}] Starting: ${cmd} ${args.join(" ")}`.trim());
+    console.log(
+      startMessage ?? `[${name}] Starting: ${cmd} ${args.join(" ")}`.trim(),
+    );
     child = spawn(cmd, args, { stdio, windowsHide: true });
 
     child.stdout?.on("data", (buf: Buffer) => {
@@ -172,7 +176,7 @@ export function createRestartableProcess(spec: {
   function killOnWindows(pid: number): Promise<void> {
     return new Promise((resolve) => {
       const cp = execFile("taskkill", ["/F", "/T", "/PID", String(pid)], () =>
-        resolve()
+        resolve(),
       );
       cp.on("error", () => resolve());
     });

package/dist/src/lib/mcp/fastmcp.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "type": "filesystem",
+    "path": "src/lib/mcp/mcp_server.py",
+    "entrypoint": "mcp"
+  },
+  "deployment": {
+    "transport": "streamable-http",
+    "host": "127.0.0.1",
+    "port": 5101,
+    "path": "/mcp",
+    "log_level": "INFO"
+  }
+}

package/dist/src/lib/mcp/mcp_server.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Literal
+
+from fastmcp import FastMCP
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+CASPIAN_CONFIG_PATH = PROJECT_ROOT / "caspian.config.json"
+PACKAGE_JSON_PATH = PROJECT_ROOT / "package.json"
+FILES_LIST_PATH = PROJECT_ROOT / "settings" / "files-list.json"
+COMPONENT_MAP_PATH = PROJECT_ROOT / "settings" / "component-map.json"
+
+
+mcp = FastMCP(
+    name="Mapka MCP",
+    instructions=(
+        "Read-only workspace metadata for the Mapka Caspian application. "
+        "Use these tools for project configuration, generated file inventory, and component discovery."
+    ),
+)
+
+
+def _load_json(path: Path, fallback: Any) -> Any:
+    if not path.exists():
+        return fallback
+
+    with path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def _normalize_paths(paths: list[str]) -> list[str]:
+    return [item.removeprefix("./").replace("\\", "/") for item in paths]
+
+
+@mcp.tool
+def project_info() -> dict[str, Any]:
+    """Return the core Caspian and package metadata for this workspace."""
+
+    config = _load_json(CASPIAN_CONFIG_PATH, {})
+    package = _load_json(PACKAGE_JSON_PATH, {})
+
+    return {
+        "projectName": config.get("projectName") or package.get("name") or PROJECT_ROOT.name,
+        "projectRoot": str(PROJECT_ROOT),
+        "packageVersion": package.get("version"),
+        "caspianVersion": config.get("version"),
+        "browserSyncTarget": config.get("bsTarget"),
+        "featureFlags": {
+            "backendOnly": config.get("backendOnly"),
+            "tailwindcss": config.get("tailwindcss"),
+            "mcp": config.get("mcp"),
+            "prisma": config.get("prisma"),
+            "typescript": config.get("typescript"),
+        },
+        "componentScanDirs": config.get("componentScanDirs", []),
+    }
+
+
+@mcp.tool
+def workspace_files(kind: Literal["all", "app", "public"] = "all") -> dict[str, Any]:
+    """Return the generated workspace file inventory, optionally filtered by area."""
+
+    files = _normalize_paths(_load_json(FILES_LIST_PATH, []))
+
+    if kind == "app":
+        selected = [path for path in files if path.startswith("src/app/")]
+    elif kind == "public":
+        selected = [path for path in files if path.startswith("public/")]
+    else:
+        selected = files
+
+    return {
+        "kind": kind,
+        "count": len(selected),
+        "files": selected,
+    }
+
+
+@mcp.tool
+def component_inventory() -> dict[str, Any]:
+    """Return the latest generated component inventory for the workspace."""
+
+    components = _load_json(COMPONENT_MAP_PATH, [])
+
+    return {
+        "count": len(components),
+        "components": components,
+    }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-caspian-app",
-  "version": "0.2.0-beta.27",
+  "version": "0.2.0-beta.28",
   "description": "Scaffold a new Caspian project (FastAPI-powered reactive Python framework).",
   "main": "dist/index.js",
   "type": "module",