fa-mcp-sdk 0.4.99 → 0.4.101

package/cli-template/.claude/skills/mcp-app-add-to-server/SKILL.md

@@ -13,13 +13,19 @@ Existing tools get paired with HTML resources that render inline in the host's c
 
 ## Getting Reference Code
 
-Clone the MCP Apps SDK repository (`@modelcontextprotocol/ext-apps`) for working examples and API documentation:
+Clone or update the MCP Apps SDK repository (`@modelcontextprotocol/ext-apps`) using the bundled
+helper. The folder `./mcp-ext-apps/` is already in `.gitignore` and is intentionally persistent —
+it serves as the long-lived reference checkout that this skill (and the `mcp-app-create` skill)
+read from. Do not delete it after use.
 
 ```bash
-git clone --branch "v$(npm view @modelcontextprotocol/ext-apps version)" --depth 1 https://github.com/modelcontextprotocol/ext-apps.git ./mcp-ext-apps
+node scripts/clone-mcp-ext-apps.js --tag latest
 ```
 
-> Add `mcp-ext-apps/` to the project's `.gitignore` — it's a reference clone, not part of the project.
+The script clones into `./mcp-ext-apps/` on first run, pulls the default branch on subsequent
+runs, and (with `--tag latest`) checks out the latest released npm tag so the cloned tree
+matches the published `@modelcontextprotocol/ext-apps` version. Add `--json` to capture machine-
+readable metadata (path, ref, commit) for downstream automation.
 
 ### Protocol Specification
 

package/cli-template/.claude/skills/mcp-app-create/SKILL.md

@@ -42,13 +42,19 @@ Host calls tool → Host renders resource UI → Server returns result → UI re
 
 ## Getting Reference Code
 
-Clone the MCP Apps SDK repository (`@modelcontextprotocol/ext-apps`) for working examples and API documentation:
+Clone or update the MCP Apps SDK repository (`@modelcontextprotocol/ext-apps`) using the bundled
+helper. The folder `./mcp-ext-apps/` is already in `.gitignore` and is intentionally persistent —
+it serves as the long-lived reference checkout that this skill (and the `mcp-app-add-to-server`
+skill) read from. Do not delete it after use.
 
 ```bash
-git clone --branch "v$(npm view @modelcontextprotocol/ext-apps version)" --depth 1 https://github.com/modelcontextprotocol/ext-apps.git ./mcp-ext-apps
+node scripts/clone-mcp-ext-apps.js --tag latest
 ```
 
-> Add `mcp-ext-apps/` to the project's `.gitignore` — it's a reference clone, not part of the project.
+The script clones into `./mcp-ext-apps/` on first run, pulls the default branch on subsequent
+runs, and (with `--tag latest`) checks out the latest released npm tag so the cloned tree
+matches the published `@modelcontextprotocol/ext-apps` version. Add `--json` to capture machine-
+readable metadata (path, ref, commit) for downstream automation.
 
 ### Protocol Specification
 

package/cli-template/CLAUDE.md

@@ -129,6 +129,8 @@ Detailed fa-mcp-sdk docs are in `FA-MCP-SDK-DOC/`:
 | `06-utilities.md` | Error handling, logging, Consul |
 | `07-testing-and-operations.md` | Test clients (STDIO, HTTP, SSE, Streamable HTTP) |
 | `08-agent-tester-and-headless-api.md` | Agent Tester, Headless API, structured logging, automated testing |
+| `09-database.md` | PostgreSQL sugar layer (`queryMAIN`, `execMAIN`, upserts, `mergeByBatch`), `pgvector`, secondary DBs |
+| `10-mcp-apps.md` | Building / extending MCP Apps (UI-augmented tools) — protocol contract, SDK surface, patterns, pitfalls |
 
 ## Development and Testing Through Agent Tester
 
@@ -355,6 +357,23 @@ Any edit or new file under `.claude/**` (SKILL.md, scripts, hooks, agents, `sett
 by `settings.json` — direct `Write`/`Edit` will fail. Invoke the `/edit-claude-files` skill, which
 describes the required `scripts/fcp.js` temp-copy protocol.
 
+## MCP Apps Reference Clone (`scripts/clone-mcp-ext-apps.js`)
+
+Shared helper used by the `/mcp-app-create` and `/mcp-app-add-to-server` skills. Clones or refreshes
+`https://github.com/modelcontextprotocol/ext-apps.git` into `./mcp-ext-apps/` at the project root
+(already in `.gitignore`, intentionally persistent so the same checkout is reused across runs).
+
+```bash
+node scripts/clone-mcp-ext-apps.js                    # clone on first run, pull main otherwise
+node scripts/clone-mcp-ext-apps.js --tag latest       # also checkout the latest npm tag
+node scripts/clone-mcp-ext-apps.js --tag v1.7.2       # checkout a specific tag
+node scripts/clone-mcp-ext-apps.js --json             # JSON output (path, ref, commit, version)
+node scripts/clone-mcp-ext-apps.js --list-examples    # include examples/* metadata in JSON
+```
+
+The script never deletes `mcp-ext-apps/`. The two skills above call it before reading sources from
+the cloned tree, so make sure it has run successfully before troubleshooting their behavior.
+
 
 ## Formatting
 

package/cli-template/FA-MCP-SDK-DOC/00-FA-MCP-SDK-index.md

@@ -22,6 +22,7 @@ npm install fa-mcp-sdk
 | [07-testing-and-operations](07-testing-and-operations.md) | Test clients (STDIO, HTTP, SSE, Streamable HTTP) | Testing, deployment |
 | [08-agent-tester-and-headless-api](08-agent-tester-and-headless-api.md) | Agent Tester, Headless API, structured logging, automated testing, UI `data-testid` reference | Agent-driven tool development, CLI automation, UI E2E tests |
 | [09-database](09-database.md) | PostgreSQL sugar layer (`queryMAIN`, `execMAIN`, `getInsertSqlMAIN`, `getMergeSqlMAIN`, `mergeByBatch`), `pgvector`, secondary DBs | Database access, upserts, batching |
+| [10-mcp-apps](10-mcp-apps.md) | Self-contained digest of the MCP Apps protocol + SDK pinned to `@modelcontextprotocol/ext-apps v1.7.2` (spec 2026-01-26): `ui://` resources, `_meta.ui`, JSON-RPC messages, `App` class, host context, patterns, pitfalls | Building / extending MCP Apps (UI-augmented tools) |
 
 ## Key Exports
 

package/cli-template/FA-MCP-SDK-DOC/01-getting-started.md

@@ -27,7 +27,7 @@ await initMcpServer(serverData);
 ```typescript
 interface McpServerData {
   tools: Tool[] | (() => Promise<Tool[]>);           // Tool definitions
-  toolHandler: <T = TToolHandlerResponse>(params: IToolHandlerParams) => Promise<T>;
+  toolHandler: <T = unknown>(params: IToolHandlerParams) => Promise<TToolHandlerResponse<T>>;
   agentBrief: string;                                 // Brief description
   agentPrompt: string;                                // System prompt
   customPrompts?: IPromptData[];                      // Additional prompts