@harperfast/template-react-ts-studio 1.12.3 → 1.12.5

package/agent/skills/harper-mcp/AGENTS.md

@@ -155,23 +155,77 @@ To expose read-only _data_, rely on RBAC: a role without write permissions never
 
 ### 2.2 Custom MCP Tools
 
-Expose non-CRUD operations — an LLM-backed `answer`, a domain action, a report generator — as first-class MCP tools.
+Instructions for the agent to follow when exposing custom instance methods as MCP tools via a static `mcpTools` array on a Resource class.
 
 #### When to Use
 
-Use this skill when the auto-generated verb tools aren't enough: the AI should invoke _behavior_, not just CRUD. Also read it before shipping any custom tool on a publicly reachable instance — the security model differs from verb tools.
+Apply this rule when a component needs to expose non-verb instance methods as callable MCP tools. Use it whenever you need custom business logic (e.g., reconciliation, aggregation, batch operations) accessible via the MCP transport beyond the auto-generated verb tools.
 
 #### How It Works
 
-1. **Declare `static mcpTools`** on a Resource class (typically in `resources.js`/`resources.ts`):
+1. **Declare a static `mcpTools` array** on the Resource class. Each entry names the tool, maps it to an instance method, provides a description, and defines an `inputSchema`.
+
+   ```javascript
+   class Orders extends Tables.orders {
+   	static mcpTools = [
+   		{
+   			name: 'reconcile_unsettled',
+   			method: 'reconcileUnsettled',
+   			description: 'Reconcile all orders flagged as unsettled and emit a summary',
+   			inputSchema: {
+   				type: 'object',
+   				properties: { since: { type: 'string', description: 'ISO 8601 timestamp' } },
+   			},
+   		},
+   	];
+
+   	async reconcileUnsettled({ since }) {
+   		/* ... */
+   	}
+   }
+   ```
+
+2. **Understand the security model.** Custom tools are exposed to **every** MCP session — including `anonymous`, unauthenticated ones. The MCP layer does **not**:
+   - Run an `allow*` gate automatically.
+   - Open a Resource transaction automatically.
+   - Filter the tool from `tools/list` based on user role.
+
+   Unlike auto-generated verb tools (which are RBAC-filtered per user at `tools/list` time and enforce table permissions on call), a custom tool is listed to every session and its method executes even when no user is logged in. `context.user` may be empty.
+
+3. **Enforce access control inside the method.** Because the MCP layer performs no authentication or ACL check, the method itself is fully responsible. Check `context.user` at the top of the method and throw when the caller doesn't qualify:
+
+   ```javascript
+   async reconcileUnsettled({ since }) {
+     if (!context.user || !context.user.roles.includes('admin')) {
+       throw new Error('Unauthorized');
+     }
+     /* ... */
+   }
+   ```
+
+4. **Delegate to static Resource operations correctly.** The MCP-created instance context carries the authenticated user and a one-shot `authorize` flag:
+   - For the **first** delegated operation, pass `this.getContext()` directly — the `authorize` flag is consumed by that call:
+     ```javascript
+     const result = await Orders.get(target, this.getContext());
+     ```
+   - For **every subsequent** delegated operation, create a fresh `RequestTarget`, set `target.checkPermission = true` so authorization derives from `context.user`, and pass `this.getContext()`:
+     ```javascript
+     target.checkPermission = true;
+     const next = await Orders.get(target, this.getContext());
+     ```
+   - **Never** accept `checkPermission` from tool arguments or other client input.
+
+#### Examples
+
+Full class with a custom MCP tool that guards access via `context.user`:
 
 ```javascript
-export class Orders extends tables.Orders {
+class Orders extends Tables.orders {
 	static mcpTools = [
 		{
 			name: 'reconcile_unsettled',
-			description: 'Reconcile all unsettled orders and return a summary',
 			method: 'reconcileUnsettled',
+			description: 'Reconcile all orders flagged as unsettled and emit a summary',
 			inputSchema: {
 				type: 'object',
 				properties: { since: { type: 'string', description: 'ISO 8601 timestamp' } },
@@ -179,39 +233,31 @@ export class Orders extends tables.Orders {
 		},
 	];
 
-	async reconcileUnsettled(args, context) {
-		// context: { user, profile, sessionId, signal, progress?, serverRequest? }
-		return { reconciled: 12 };
-	}
-}
-```
+	async reconcileUnsettled({ since }) {
+		// Reject anonymous or unauthorized callers — the MCP layer does not do this.
+		if (!context.user) {
+			throw new Error('Authentication required');
+		}
 
-2. **Dispatch is live-class.** Calls construct an instance of the class currently in the Resource registry, so an exported subclass (and its access-control overrides) always wins after a reload/deploy.
-3. **Per-call context.** The second argument carries `user`, `profile`, `sessionId`, an `AbortSignal` (`signal`) wired to MCP cancellation, and — on streaming calls — `progress()` and `serverRequest()`. Guard optional members (`context.progress?.(…)`).
-4. **Results and errors.** Return values are wrapped into MCP tool results (objects become structured content). Thrown errors surface as `isError: true` tool results with the message only — stack traces stay in the server log.
-5. **Security: custom tools are exposed to ANY session, including anonymous ones.** Unlike verb tools (RBAC-filtered per user), a custom tool is listed to every session and its method executes even with no logged-in user (`context.user` may be empty). The method runs inside the normal `transactional()` envelope, so data access it performs still hits per-record `allow*` predicates — but the _tool itself_ has no gate. To restrict one:
+		// First delegated operation: use the one-shot authorize flag via this.getContext().
+		const target = { since };
+		const unsettled = await Orders.get(target, this.getContext());
 
-```javascript
-async reconcileUnsettled(args, context) {
-	if (!context.user?.username) {
-		throw new Error('authentication required');
+		// Subsequent delegated operations: fresh RequestTarget with checkPermission = true.
+		const updateTarget = { id: unsettled.id };
+		updateTarget.checkPermission = true;
+		await Orders.update(updateTarget, this.getContext());
 	}
-	// ...
 }
 ```
 
-6. **Cost control for public tools.** A cost-bearing anonymous tool needs more than auth checks — see [Rate Limiting](rate-limiting.md) (per-client buckets survive session cycling) and [Durable Quotas](durable-quotas.md) (persisted per-identity limits).
-
-#### Examples
-
-Warn-worthy anti-pattern — a public instance with an expensive tool and no gating:
-
-```javascript
-static mcpTools = [{ name: 'answer', method: 'llmAnswer', ... }];
-async llmAnswer(args) { return await callExpensiveModel(args.q); } // anonymous callers burn your budget
-```
+#### Notes
 
-Fixed: check `context.user` (or accept anonymity deliberately) _and_ configure `rateLimit.perClientPerSecond` + a `quota` hook.
+- `mcpTools` is a **static** array — declare it on the class, not on instances.
+- The `allow*` gates that protect auto-generated verb tools do **not** run for custom tools. All authorization logic must live inside the method.
+- `context.user` is the canonical way to identify the caller; it may be empty for `anonymous` sessions, so always check before trusting it.
+- Never derive `checkPermission` from client-supplied tool arguments — always set it explicitly in your method code.
+- If your custom tool performs expensive or repeated operations, consider applying [rate limiting](rate-limiting.md) or [durable quotas](durable-quotas.md) inside the method to prevent abuse by unauthenticated callers.
 
 ### 2.3 Custom MCP Prompts
 

package/agent/skills/harper-mcp/SKILL.md

@@ -1,7 +1,14 @@
 ---
-description: "Comprehensive guide to Harper's Model Context Protocol (MCP) interface, covering server setup, client connection, automatic and custom tools, prompts, resources, rate limiting, durable quotas, and the security model. Triggers on tasks involving MCP servers on Harper, AI-client integration, and exposing Harper data or behavior to LLM agents."
-license: "Apache-2.0"
-metadata: {"author":"harper","version":"1.0.0"}
+name: harper-mcp
+description: Comprehensive guide to Harper's Model Context Protocol (MCP)
+  interface, covering server setup, client connection, automatic and custom
+  tools, prompts, resources, rate limiting, durable quotas, and the security
+  model. Triggers on tasks involving MCP servers on Harper, AI-client
+  integration, and exposing Harper data or behavior to LLM agents.
+license: Apache-2.0
+metadata:
+  author: harper
+  version: 1.0.0
 ---
 # Harper MCP
 

package/agent/skills/harper-mcp/rules/custom-mcp-tools.md

@@ -7,29 +7,83 @@ metadata:
   mode: generate
   sources:
     - reference/v5/mcp/tools-and-resources.md#Custom `mcpTools` opt-in
-  sourceCommit: d7d2ddb120ce5f2ad39dc425f628f5a4f220c151
-  inputHash: 84a2ffac9bb7b66a
+  sourceCommit: 9e6ecf87dd25bb488ad44dc2876ca6439ccd682e
+  inputHash: 692801362e747c73
 ---
 
 # Custom MCP Tools
 
-Expose non-CRUD operations — an LLM-backed `answer`, a domain action, a report generator — as first-class MCP tools.
+Instructions for the agent to follow when exposing custom instance methods as MCP tools via a static `mcpTools` array on a Resource class.
 
 ## When to Use
 
-Use this skill when the auto-generated verb tools aren't enough: the AI should invoke _behavior_, not just CRUD. Also read it before shipping any custom tool on a publicly reachable instance — the security model differs from verb tools.
+Apply this rule when a component needs to expose non-verb instance methods as callable MCP tools. Use it whenever you need custom business logic (e.g., reconciliation, aggregation, batch operations) accessible via the MCP transport beyond the auto-generated verb tools.
 
 ## How It Works
 
-1. **Declare `static mcpTools`** on a Resource class (typically in `resources.js`/`resources.ts`):
+1. **Declare a static `mcpTools` array** on the Resource class. Each entry names the tool, maps it to an instance method, provides a description, and defines an `inputSchema`.
+
+   ```javascript
+   class Orders extends Tables.orders {
+   	static mcpTools = [
+   		{
+   			name: 'reconcile_unsettled',
+   			method: 'reconcileUnsettled',
+   			description: 'Reconcile all orders flagged as unsettled and emit a summary',
+   			inputSchema: {
+   				type: 'object',
+   				properties: { since: { type: 'string', description: 'ISO 8601 timestamp' } },
+   			},
+   		},
+   	];
+
+   	async reconcileUnsettled({ since }) {
+   		/* ... */
+   	}
+   }
+   ```
+
+2. **Understand the security model.** Custom tools are exposed to **every** MCP session — including `anonymous`, unauthenticated ones. The MCP layer does **not**:
+   - Run an `allow*` gate automatically.
+   - Open a Resource transaction automatically.
+   - Filter the tool from `tools/list` based on user role.
+
+   Unlike auto-generated verb tools (which are RBAC-filtered per user at `tools/list` time and enforce table permissions on call), a custom tool is listed to every session and its method executes even when no user is logged in. `context.user` may be empty.
+
+3. **Enforce access control inside the method.** Because the MCP layer performs no authentication or ACL check, the method itself is fully responsible. Check `context.user` at the top of the method and throw when the caller doesn't qualify:
+
+   ```javascript
+   async reconcileUnsettled({ since }) {
+     if (!context.user || !context.user.roles.includes('admin')) {
+       throw new Error('Unauthorized');
+     }
+     /* ... */
+   }
+   ```
+
+4. **Delegate to static Resource operations correctly.** The MCP-created instance context carries the authenticated user and a one-shot `authorize` flag:
+   - For the **first** delegated operation, pass `this.getContext()` directly — the `authorize` flag is consumed by that call:
+     ```javascript
+     const result = await Orders.get(target, this.getContext());
+     ```
+   - For **every subsequent** delegated operation, create a fresh `RequestTarget`, set `target.checkPermission = true` so authorization derives from `context.user`, and pass `this.getContext()`:
+     ```javascript
+     target.checkPermission = true;
+     const next = await Orders.get(target, this.getContext());
+     ```
+   - **Never** accept `checkPermission` from tool arguments or other client input.
+
+## Examples
+
+Full class with a custom MCP tool that guards access via `context.user`:
 
 ```javascript
-export class Orders extends tables.Orders {
+class Orders extends Tables.orders {
 	static mcpTools = [
 		{
 			name: 'reconcile_unsettled',
-			description: 'Reconcile all unsettled orders and return a summary',
 			method: 'reconcileUnsettled',
+			description: 'Reconcile all orders flagged as unsettled and emit a summary',
 			inputSchema: {
 				type: 'object',
 				properties: { since: { type: 'string', description: 'ISO 8601 timestamp' } },
@@ -37,36 +91,28 @@ export class Orders extends tables.Orders {
 		},
 	];
 
-	async reconcileUnsettled(args, context) {
-		// context: { user, profile, sessionId, signal, progress?, serverRequest? }
-		return { reconciled: 12 };
-	}
-}
-```
+	async reconcileUnsettled({ since }) {
+		// Reject anonymous or unauthorized callers — the MCP layer does not do this.
+		if (!context.user) {
+			throw new Error('Authentication required');
+		}
 
-2. **Dispatch is live-class.** Calls construct an instance of the class currently in the Resource registry, so an exported subclass (and its access-control overrides) always wins after a reload/deploy.
-3. **Per-call context.** The second argument carries `user`, `profile`, `sessionId`, an `AbortSignal` (`signal`) wired to MCP cancellation, and — on streaming calls — `progress()` and `serverRequest()`. Guard optional members (`context.progress?.(…)`).
-4. **Results and errors.** Return values are wrapped into MCP tool results (objects become structured content). Thrown errors surface as `isError: true` tool results with the message only — stack traces stay in the server log.
-5. **Security: custom tools are exposed to ANY session, including anonymous ones.** Unlike verb tools (RBAC-filtered per user), a custom tool is listed to every session and its method executes even with no logged-in user (`context.user` may be empty). The method runs inside the normal `transactional()` envelope, so data access it performs still hits per-record `allow*` predicates — but the _tool itself_ has no gate. To restrict one:
+		// First delegated operation: use the one-shot authorize flag via this.getContext().
+		const target = { since };
+		const unsettled = await Orders.get(target, this.getContext());
 
-```javascript
-async reconcileUnsettled(args, context) {
-	if (!context.user?.username) {
-		throw new Error('authentication required');
+		// Subsequent delegated operations: fresh RequestTarget with checkPermission = true.
+		const updateTarget = { id: unsettled.id };
+		updateTarget.checkPermission = true;
+		await Orders.update(updateTarget, this.getContext());
 	}
-	// ...
 }
 ```
 
-6. **Cost control for public tools.** A cost-bearing anonymous tool needs more than auth checks — see [Rate Limiting](rate-limiting.md) (per-client buckets survive session cycling) and [Durable Quotas](durable-quotas.md) (persisted per-identity limits).
-
-## Examples
-
-Warn-worthy anti-pattern — a public instance with an expensive tool and no gating:
-
-```javascript
-static mcpTools = [{ name: 'answer', method: 'llmAnswer', ... }];
-async llmAnswer(args) { return await callExpensiveModel(args.q); } // anonymous callers burn your budget
-```
+## Notes
 
-Fixed: check `context.user` (or accept anonymity deliberately) _and_ configure `rateLimit.perClientPerSecond` + a `quota` hook.
+- `mcpTools` is a **static** array — declare it on the class, not on instances.
+- The `allow*` gates that protect auto-generated verb tools do **not** run for custom tools. All authorization logic must live inside the method.
+- `context.user` is the canonical way to identify the caller; it may be empty for `anonymous` sessions, so always check before trusting it.
+- Never derive `checkPermission` from client-supplied tool arguments — always set it explicitly in your method code.
+- If your custom tool performs expensive or repeated operations, consider applying [rate limiting](rate-limiting.md) or [durable quotas](durable-quotas.md) inside the method to prevent abuse by unauthenticated callers.

package/agent/skills/harper-mcp/rules.manifest.yaml

@@ -90,7 +90,7 @@ rules:
     must_cover:
       - mcpTools
       - anonymous
-      - live-class
+      - 'allow*'
       - context.user
     cross_links:
       - rate-limiting

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harperfast/template-react-ts-studio",
-	"version": "1.12.3",
+	"version": "1.12.5",
 	"type": "module",
 	"repository": "github:HarperFast/create-harper",
 	"scripts": {},

package/skills-lock.json

@@ -5,13 +5,13 @@
       "source": "harperfast/skills",
       "sourceType": "github",
       "skillPath": "harper-best-practices/SKILL.md",
-      "computedHash": "ab02386c2af20dd8f3b782bb9a884dafd8a0cd9ce313c715bbabbf83453d4e74"
+      "computedHash": "6656243a1b2fc48e9872f62e11fc0aaf6948d7893bdaae6aac437267e6843163"
     },
     "harper-mcp": {
       "source": "harperfast/skills",
       "sourceType": "github",
       "skillPath": "harper-mcp/SKILL.md",
-      "computedHash": "a767336400a2ea7ec3bef3513d842a837ded5ef817165904a3c2ba7e7d14898a"
+      "computedHash": "a0f94e58af6b4128853dc4033e246d7fde2e07416d2aaa705bfd8d984e21ea34"
     }
   }
 }