Merge pull request #1233 from getlarge/issue-1231-mcp-app-followup

chore(mcp): typed callTool + e2e api-client fix + MCP apps docs/skill (follow-up to #1229)

Author: getlarge

.agents/skills/rendered-pack-bba8dca4/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: rendered-pack-bba8dca4
+description: Use when writing or reviewing MoltNet e2e tests (apps/*/e2e, libs/mcp-test-harness): use @moltnet/api-client (createClient + typed fns like createDiaryEntry) not raw fetch for in-spec endpoints. Raw fetch only for /health, /oauth2/token, /auth/register.
+moltnet:
+  rendered_pack_id: bba8dca4-c029-42ad-a43d-5d28fec0fdc3
+  rendered_pack_cid: bafyreig6xgdiw6hsehuafjv3vr54gprbqvqedmm36ey3rp3pthksduzati
+  source_pack_id: 141fdb3d-eec9-427d-89f8-6171fbd3e0cc
+  bundled_at: 2026-05-24T17:36:03Z
+---
+
+# Context Pack 141fdb3d-eec9-427d-89f8-6171fbd3e0cc
+
+- Created: 2026-05-24T17:31:34.460Z
+- Entries: 4
+
+### Decision: enforce api-client usage in e2e dedup tests
+
+- Entry ID: `7b0a6488-6609-4a1f-8a97-8a117cd7969d`
+- CID: `bafkreihztuh4jkjl2t55bfl5surlotmvrveyw5ujuznqwgxeebkfy4w4ri`
+- Compression: `full`
+- Tokens: 131/131
+
+Decision: Add explicit eval criteria requiring `@moltnet/api-client` helpers (not raw `fetch`) for authenticated duplicate/invalidation e2e coverage.
+Alternatives considered: Keep tests as raw HTTP `fetch` calls for simplicity.
+Reason chosen: API-client usage keeps tests aligned with repo conventions, typed request/response shapes, and auth helper reuse. It also avoids criterion ambiguity around transport details.
+Trade-offs: Slightly more ceremony in concurrent status assertions (`response.status` fields), but higher consistency and maintainability.
+Context: User review explicitly requested criteria entries for avoiding fetch in these e2e tests.
+
+<metadata>
+operator: edouard
+tool: codex
+refs: apps/rest-api/e2e/diary-distill.e2e.test.ts, evals/add-dbos-dedup-queues/criteria.json, libs/api-client/
+timestamp: 2026-03-09T00:00:00Z
+branch: feat/issue-378-eval-runner
+scope: scope:evals, scope:rest-api
+</metadata>
+
+### Incident: raw fetch in e2e tests despite api-client having the endpoints
+
+- Entry ID: `24e3532a-753f-4767-989d-c49bb1c0b16c`
+- CID: `bafkreih3bnpgudnk6l4rjrs3ov6iwhis2v7ts42mm5p34g5sgribyihb64`
+- Compression: `full`
+- Tokens: 80/80
+
+Wrote team-governance.e2e.test.ts using raw fetch() for all governance endpoints instead of @moltnet/api-client. Test was written before OpenAPI regen, not updated after. All endpoints (initiateTransfer, acceptTransfer, rejectTransfer, listPendingTransfers, acceptTeamFounding, createTeam) were in sdk.gen.ts after regeneration. Fix: rewrite to use client functions. Rule: e2e tests must use api-client for any endpoint in the generated spec; raw fetch only for /health, /oauth2/token, /auth/register.
+
+### Recurrence: raw fetch in mcp-host-e2e + mcp-test-harness instead of api-client
+
+- Entry ID: `cbdd365c-b319-4390-8f64-9a59920af2ab`
+- CID: `bafkreicwgdd7scrllup2hqjh3aj43rrmpzsw754kbv6jq4brqqsrfl6bi4`
+- Compression: `full`
+- Tokens: 347/347
+
+What happened: apps/mcp-host-e2e/src/entry-map.spec.ts (added in PR #1229) seeds diary entries with a raw fetch() to POST /diaries/:id/entries instead of the generated @moltnet/api-client (createClient + createDiaryEntry). The shared libs/mcp-test-harness/src/harness.ts does the same for POST /diaries (createDiary). This re-introduces the exact anti-pattern previously documented and ruled against.
+
+Root cause: the new spec followed the harness's existing raw-fetch seeding style rather than the repo convention. The sibling suites apps/rest-api/e2e/_.e2e.test.ts and apps/mcp-server/e2e/_.e2e.test.ts already do this correctly (import createClient + createDiaryEntry from @moltnet/api-client). POST /diaries/:id/entries and POST /diaries ARE in the generated SDK, so per the established rule they must NOT use raw fetch.
+
+The rule (from incident 24e3532a): e2e tests must use api-client for any endpoint in the generated spec; raw fetch is allowed ONLY for /health, /oauth2/token, /auth/register. Decision 7b0a6488 enforces api-client usage in e2e coverage. Both endpoints here are in-spec, so both violate it.
+
+Fix: NOT done in PR #1229 (user explicitly deferred to avoid scope creep). Tracked for the next PR: refactor entry-map.spec.ts seeding to createDiaryEntry, and the mcp-test-harness public-diary creation to createDiary, both via createClient({ baseUrl: restApiUrl }) with the bearer + x-moltnet-team-id headers. Note the harness fix benefits every MCP e2e suite, so it is the higher-leverage one.
+
+Watch for: when writing or copying e2e setup/seeding, use @moltnet/api-client for any in-spec endpoint; only /health, /oauth2/token, /auth/register may use raw fetch. The mcp-test-harness raw-fetch seeding is a tempting template that propagates the anti-pattern — fix it at the source.
+
+<metadata>
+operator: edouard | tool: claude | timestamp: 2026-05-24T17:28:10Z
+branch: issue-1194-diary-map-app | scope: testing,mcp-apps | refs: apps/mcp-host-e2e/src/entry-map.spec.ts, libs/mcp-test-harness/src/harness.ts, @moltnet/api-client, createDiaryEntry
+</metadata>
+
+### Accountable commit: Replace raw fetch() calls in e2e test with @moltnet/api-client functions.
+
+- Entry ID: `73ac8b20-f36b-46ef-803f-8204fba12fc4`
+- CID: `bafkreigebb2uu65tkt43detaiolbjkqj2riivtxxwlncnvlo6wtxgu6jhm`
+- Compression: `full`
+- Tokens: 110/110
+
+<content>
+Replace raw fetch() calls in e2e test with @moltnet/api-client functions. All governance endpoints (createTeam with foundingMembers, acceptTeamFounding, initiateTransfer, listPendingTransfers, acceptTransfer, rejectTransfer) were already in the generated SDK after OpenAPI regen. Two fetch calls remain for GET /diaries/:id to read teamId — the generated getDiary response type does not expose teamId, making raw fetch the correct choice for those assertions.
+</content>
+<metadata>
+signer: 1671-B080-99BF-4270
+operator: edouard
+tool: claude
+risk-level: low
+files-changed: 1
+refs: apps/rest-api/e2e/team-governance.e2e.test.ts
+timestamp: 2026-04-07T17:50:30Z
+branch: feat/team-governance-workflows
+scope: test, governance
+</metadata>

.claude/skills/rendered-pack-bba8dca4/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: rendered-pack-bba8dca4
+description: Use when writing or reviewing MoltNet e2e tests (apps/*/e2e, libs/mcp-test-harness): use @moltnet/api-client (createClient + typed fns like createDiaryEntry) not raw fetch for in-spec endpoints. Raw fetch only for /health, /oauth2/token, /auth/register.
+moltnet:
+  rendered_pack_id: bba8dca4-c029-42ad-a43d-5d28fec0fdc3
+  rendered_pack_cid: bafyreig6xgdiw6hsehuafjv3vr54gprbqvqedmm36ey3rp3pthksduzati
+  source_pack_id: 141fdb3d-eec9-427d-89f8-6171fbd3e0cc
+  bundled_at: 2026-05-24T17:36:03Z
+---
+
+# Context Pack 141fdb3d-eec9-427d-89f8-6171fbd3e0cc
+
+- Created: 2026-05-24T17:31:34.460Z
+- Entries: 4
+
+### Decision: enforce api-client usage in e2e dedup tests
+
+- Entry ID: `7b0a6488-6609-4a1f-8a97-8a117cd7969d`
+- CID: `bafkreihztuh4jkjl2t55bfl5surlotmvrveyw5ujuznqwgxeebkfy4w4ri`
+- Compression: `full`
+- Tokens: 131/131
+
+Decision: Add explicit eval criteria requiring `@moltnet/api-client` helpers (not raw `fetch`) for authenticated duplicate/invalidation e2e coverage.
+Alternatives considered: Keep tests as raw HTTP `fetch` calls for simplicity.
+Reason chosen: API-client usage keeps tests aligned with repo conventions, typed request/response shapes, and auth helper reuse. It also avoids criterion ambiguity around transport details.
+Trade-offs: Slightly more ceremony in concurrent status assertions (`response.status` fields), but higher consistency and maintainability.
+Context: User review explicitly requested criteria entries for avoiding fetch in these e2e tests.
+
+<metadata>
+operator: edouard
+tool: codex
+refs: apps/rest-api/e2e/diary-distill.e2e.test.ts, evals/add-dbos-dedup-queues/criteria.json, libs/api-client/
+timestamp: 2026-03-09T00:00:00Z
+branch: feat/issue-378-eval-runner
+scope: scope:evals, scope:rest-api
+</metadata>
+
+### Incident: raw fetch in e2e tests despite api-client having the endpoints
+
+- Entry ID: `24e3532a-753f-4767-989d-c49bb1c0b16c`
+- CID: `bafkreih3bnpgudnk6l4rjrs3ov6iwhis2v7ts42mm5p34g5sgribyihb64`
+- Compression: `full`
+- Tokens: 80/80
+
+Wrote team-governance.e2e.test.ts using raw fetch() for all governance endpoints instead of @moltnet/api-client. Test was written before OpenAPI regen, not updated after. All endpoints (initiateTransfer, acceptTransfer, rejectTransfer, listPendingTransfers, acceptTeamFounding, createTeam) were in sdk.gen.ts after regeneration. Fix: rewrite to use client functions. Rule: e2e tests must use api-client for any endpoint in the generated spec; raw fetch only for /health, /oauth2/token, /auth/register.
+
+### Recurrence: raw fetch in mcp-host-e2e + mcp-test-harness instead of api-client
+
+- Entry ID: `cbdd365c-b319-4390-8f64-9a59920af2ab`
+- CID: `bafkreicwgdd7scrllup2hqjh3aj43rrmpzsw754kbv6jq4brqqsrfl6bi4`
+- Compression: `full`
+- Tokens: 347/347
+
+What happened: apps/mcp-host-e2e/src/entry-map.spec.ts (added in PR #1229) seeds diary entries with a raw fetch() to POST /diaries/:id/entries instead of the generated @moltnet/api-client (createClient + createDiaryEntry). The shared libs/mcp-test-harness/src/harness.ts does the same for POST /diaries (createDiary). This re-introduces the exact anti-pattern previously documented and ruled against.
+
+Root cause: the new spec followed the harness's existing raw-fetch seeding style rather than the repo convention. The sibling suites apps/rest-api/e2e/_.e2e.test.ts and apps/mcp-server/e2e/_.e2e.test.ts already do this correctly (import createClient + createDiaryEntry from @moltnet/api-client). POST /diaries/:id/entries and POST /diaries ARE in the generated SDK, so per the established rule they must NOT use raw fetch.
+
+The rule (from incident 24e3532a): e2e tests must use api-client for any endpoint in the generated spec; raw fetch is allowed ONLY for /health, /oauth2/token, /auth/register. Decision 7b0a6488 enforces api-client usage in e2e coverage. Both endpoints here are in-spec, so both violate it.
+
+Fix: NOT done in PR #1229 (user explicitly deferred to avoid scope creep). Tracked for the next PR: refactor entry-map.spec.ts seeding to createDiaryEntry, and the mcp-test-harness public-diary creation to createDiary, both via createClient({ baseUrl: restApiUrl }) with the bearer + x-moltnet-team-id headers. Note the harness fix benefits every MCP e2e suite, so it is the higher-leverage one.
+
+Watch for: when writing or copying e2e setup/seeding, use @moltnet/api-client for any in-spec endpoint; only /health, /oauth2/token, /auth/register may use raw fetch. The mcp-test-harness raw-fetch seeding is a tempting template that propagates the anti-pattern — fix it at the source.
+
+<metadata>
+operator: edouard | tool: claude | timestamp: 2026-05-24T17:28:10Z
+branch: issue-1194-diary-map-app | scope: testing,mcp-apps | refs: apps/mcp-host-e2e/src/entry-map.spec.ts, libs/mcp-test-harness/src/harness.ts, @moltnet/api-client, createDiaryEntry
+</metadata>
+
+### Accountable commit: Replace raw fetch() calls in e2e test with @moltnet/api-client functions.
+
+- Entry ID: `73ac8b20-f36b-46ef-803f-8204fba12fc4`
+- CID: `bafkreigebb2uu65tkt43detaiolbjkqj2riivtxxwlncnvlo6wtxgu6jhm`
+- Compression: `full`
+- Tokens: 110/110
+
+<content>
+Replace raw fetch() calls in e2e test with @moltnet/api-client functions. All governance endpoints (createTeam with foundingMembers, acceptTeamFounding, initiateTransfer, listPendingTransfers, acceptTransfer, rejectTransfer) were already in the generated SDK after OpenAPI regen. Two fetch calls remain for GET /diaries/:id to read teamId — the generated getDiary response type does not expose teamId, making raw fetch the correct choice for those assertions.
+</content>
+<metadata>
+signer: 1671-B080-99BF-4270
+operator: edouard
+tool: claude
+risk-level: low
+files-changed: 1
+refs: apps/rest-api/e2e/team-governance.e2e.test.ts
+timestamp: 2026-04-07T17:50:30Z
+branch: feat/team-governance-workflows
+scope: test, governance
+</metadata>

apps/mcp-host-e2e/package.json

@@ -5,6 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
+    "@moltnet/api-client": "workspace:*",
     "@moltnet/mcp-test-harness": "workspace:*"
   },
   "devDependencies": {

apps/mcp-host-e2e/src/entry-map.spec.ts

@@ -1,35 +1,36 @@
+import {
+  type Client,
+  createClient,
+  createDiaryEntry,
+} from '@moltnet/api-client';
 import {
   createMcpTestHarness,
   type McpTestHarness,
 } from '@moltnet/mcp-test-harness';
 import { expect, type Page, test } from '@playwright/test';
 
 let harness: McpTestHarness;
+let client: Client;
 const seededEntryIds: string[] = [];
 
 /** Seed a handful of namespaced-tag entries so a zone resolves a real mosaic. */
 async function seedEntry(content: string, tags: string[]): Promise<string> {
-  const response = await fetch(
-    `${harness.restApiUrl}/diaries/${harness.privateDiaryId}/entries`,
-    {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        authorization: `Bearer ${harness.agent.accessToken}`,
-        'x-moltnet-team-id': harness.personalTeamId,
-      },
-      body: JSON.stringify({ content, tags, entryType: 'semantic' }),
-    },
-  );
-  if (!response.ok) {
-    throw new Error(`seed failed: ${response.status} ${await response.text()}`);
+  const { data, error } = await createDiaryEntry({
+    client,
+    auth: () => harness.agent.accessToken,
+    headers: { 'x-moltnet-team-id': harness.personalTeamId },
+    path: { diaryId: harness.privateDiaryId },
+    body: { content, tags, entryType: 'semantic' },
+  });
+  if (error || !data) {
+    throw new Error(`seed failed: ${JSON.stringify(error)}`);
   }
-  const body = (await response.json()) as { id: string };
-  return body.id;
+  return data.id;
 }
 
 test.beforeAll(async () => {
   harness = await createMcpTestHarness();
+  client = createClient({ baseUrl: harness.restApiUrl });
   seededEntryIds.push(
     await seedEntry('Chose Drizzle migrations over raw SQL.', [
       'scope:infra',

apps/mcp-host-e2e/tsconfig.json

@@ -17,6 +17,9 @@
     "src/**/*.d.ts"
   ],
   "references": [
+    {
+      "path": "../../libs/api-client"
+    },
     {
       "path": "../../libs/mcp-test-harness"
     }

docs/reference/mcp-server.md

@@ -71,10 +71,27 @@ See [DIARY_ENTRY_STATE_MODEL § Signing reference](./diary-entry-state-model#sig
 - `tasks_create` — create and enqueue a task. Validates `input` against the registered task-type schema (TypeBox via `@moltnet/tasks`) before posting. Same operation as `moltnet task create` and `agent.tasks.create(...)`.
 - `tasks_get`, `tasks_list` — fetch by ID or list with filters.
 - `tasks_attempts_list`, `tasks_messages_list` — read attempt envelopes and per-attempt streaming events.
-- `tasks_console_link`, `tasks_app_open` — render a console URL or open the task in the web app.
+- `tasks_console_link` — render a console URL for a task. `tasks_app_open` — open the interactive **Tasks MCP App** (see [MCP Apps](#mcp-apps) below).
 
 See [Tasks](../use/tasks.md) for the three-tab CLI / MCP / SDK examples and [Task Reference § Create envelope](./tasks#create-envelope) for the field-by-field mapping. The MCP tool argument names use snake_case (`task_type`, `team_id`, `correlation_id`, …) and map 1:1 to the CLI's kebab-case flags.
 
+## MCP Apps
+
+Some tools open an **interactive UI** that renders inline in MCP hosts which support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) (Claude Desktop, claude.ai, ChatGPT). Instead of returning text, the tool mounts a small web app in a sandboxed iframe in the chat. You don't call these directly — ask the assistant in plain language ("show me my tasks", "help me make sense of this diary") and it opens the matching app.
+
+| Tool               | App           | What it's for                                                                                                                                                                                                          |
+| ------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tasks_app_open`   | MoltNet Tasks | Inspect a team's task queue, drill into a task's attempts and messages, and jump to the console. Read-only.                                                                                                            |
+| `entries_map_open` | Diary Map     | Human-first sense-making for a large diary: the assistant interprets it into labeled **knowledge zones**; you browse zones, see representative entries, and **save a zone** as a draft context pack to revisit or pin. |
+
+**How they work** (so the behavior isn't surprising):
+
+- **The assistant drives the data.** These tools are deterministic openers — they mount the app and declare which read tools it may call (`entries_list`, `entries_search`, `diary_tags`, `packs_*`). All interpretation (which zones exist, their labels) is done by the assistant in your session, not the server. The server stays retrieval-only; there is no server-side LLM.
+- **Diary Map zones are draft context packs.** "Save this zone" materializes the selection as an _unpinned_ [context pack](../understand/knowledge-factory.md) carrying the search that produced it; validating it pins the pack. Nothing is written to your diary.
+- **Host display limits.** Inline app height is capped by the host (Claude inline ≈ 500px, no nested scroll; ChatGPT grows with content). Where the host allows it, an app can request fullscreen for a roomier view. On hosts without MCP Apps support the opener tool still returns its structured result as text.
+
+To exercise an app locally against the e2e stack, see [`apps/mcp-host/README.md`](https://github.com/getlarge/themoltnet/blob/main/apps/mcp-host/README.md).
+
 ## Prompts
 
 Three MCP prompts shape common agent workflows: