@noodleseed/agent-kit 0.83.0 → 0.84.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.83.0",
+  "version": "0.84.0",
   "private": false,
   "description": "Self-checking, self-updating agent skills for the Noodle Seed CLI. Authored in this repo by @noodle-borg/agent-kit; this is the published, independently-versioned canonical skills artifact the CLI fetches and verifies.",
   "license": "Apache-2.0",

package/skills/claude-code/SKILL.md

@@ -3,7 +3,7 @@ name: noodle-seed
 description: "Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:13ddce01769caae4 -->
+<!-- noodle-skill version:0.84.0 hash:13ddce01769caae4 -->
 
 # Noodle Seed
 

package/skills/claude-code/authoring-mcp-servers/SKILL.md

@@ -3,7 +3,7 @@ name: authoring-mcp-servers
 description: "Use when creating or extending a headless Noodle Seed MCP server, tool, resource, prompt, or typed model-facing capability."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:11523cb33b9473c0 -->
+<!-- noodle-skill version:0.84.0 hash:11523cb33b9473c0 -->
 
 # authoring-mcp-servers
 

package/skills/claude-code/building-mcp-apps/SKILL.md

@@ -3,7 +3,7 @@ name: building-mcp-apps
 description: "Use when a Noodle Seed MCP App, widget, interactive card, visual interaction, or host-visible UI is the primary requested outcome."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:9fd67d4d24328e15 -->
+<!-- noodle-skill version:0.84.0 hash:9fd67d4d24328e15 -->
 
 # building-mcp-apps
 

package/skills/claude-code/connecting-apis-to-mcp/SKILL.md

@@ -3,7 +3,7 @@ name: connecting-apis-to-mcp
 description: "Use when all four API-evidence inputs exist—and only then: API base URL, authentication scheme, representative safe read, and observed response."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:21bbd3ec441ffd30 -->
+<!-- noodle-skill version:0.84.0 hash:21bbd3ec441ffd30 -->
 
 # connecting-apis-to-mcp
 

package/skills/claude-code/creating-product-agent-guides/SKILL.md

@@ -3,7 +3,7 @@ name: creating-product-agent-guides
 description: "Use when a Noodle Seed MCP server needs a new or revised product agent guide, App Package skill, or explicit product-skill regeneration."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:0fa48a82fe836cf0 -->
+<!-- noodle-skill version:0.84.0 hash:0fa48a82fe836cf0 -->
 
 # creating-product-agent-guides
 

package/skills/claude-code/debugging-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: debugging-mcp-delivery
 description: "Use when an existing Noodle Seed MCP project has a concrete validation, runtime, connector, App, host, deployment, or production failure."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.84.0 hash:aa715bae12041d7c -->
 
 # debugging-mcp-delivery
 

package/skills/claude-code/deploying-mcp-services/SKILL.md

@@ -3,7 +3,7 @@ name: deploying-mcp-services
 description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.84.0 hash:93e735b7ffb45df1 -->
 
 # deploying-mcp-services
 

package/skills/claude-code/designing-mcp-products/SKILL.md

@@ -3,7 +3,7 @@ name: designing-mcp-products
 description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:78a6f181b61f92f1 -->
+<!-- noodle-skill version:0.84.0 hash:78a6f181b61f92f1 -->
 
 # designing-mcp-products
 

package/skills/claude-code/embedding-mcp-assistants/SKILL.md

@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
 description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:cc54a67f21c0ecdb -->
+<!-- noodle-skill version:0.84.0 hash:cc54a67f21c0ecdb -->
 
 # embedding-mcp-assistants
 

package/skills/claude-code/examples/food-ordering/README.md

@@ -26,6 +26,7 @@ private customer data.
 | Handoff | `handoff.allowedDomains` allows only `https://orders.example.com` checkout URLs |
 | Progressive enhancement | Non-Apps hosts still receive stores, featured items, and a readable fallback summary |
 | Fail-closed hydration | The React view treats only the unhydrated, pre-result `{}` envelope as pending; a hydrated empty success remains distinct. It surfaces `isError`, validates required records and identifiers, and withholds ordering actions from malformed results |
+| Upstream MCP composition | This synthetic example keeps its data local. For the canonical frozen-tool import, governed upstream invocation, response normalization, and Noodle-owned widget pattern, use the repository's `shopify-storefront` flagship rather than copying another composition surface here |
 
 The example is intentionally richer than the generated starter, but each inline view still follows the
 same default: one immediate purpose, one primary action, at most one subordinate action, and progressive

package/skills/claude-code/examples/food-ordering/src/server.ts

@@ -352,6 +352,18 @@ export default server(
       description:
         'Open a complete food-ordering widget with store discovery, menu browsing, cart review, and checkout handoff.',
       annotations: readOnly,
+      modelVisibility: {
+        latestMessageIncludesAny: [
+          'order',
+          'food',
+          'menu',
+          'restaurant',
+          'cart',
+          'pickup',
+          'delivery',
+          'checkout',
+        ],
+      },
       input: z.object({
         query: z.string().optional(),
         customer: z.string().default('Guest'),

package/skills/claude-code/examples/food-ordering/test/server.test.ts

@@ -80,6 +80,13 @@ describe('food-ordering example', () => {
     expect(JSON.stringify(tools.get('open_ordering'))).toContain('${context.ambient.serviceArea}');
     expect(JSON.stringify(tools.get('open_ordering'))).toContain('${context.location.latitude}');
     expect(JSON.stringify(tools.get('open_ordering'))).toContain('${context.location.longitude}');
+    expect(tools.get('open_ordering')?.annotations).toMatchObject({
+      'x-noodleseed-model-latest-message-includes-any': expect.arrayContaining([
+        'order',
+        'menu',
+        'checkout',
+      ]),
+    });
     expect(JSON.stringify(tools.get('sync_cart'))).toContain('revision');
     expect(tools.get('sync_cart')?.annotations?.confirm).toBe(false);
     expect(tools.get('prepare_checkout')?.annotations?.confirm).toBe(false);

package/skills/claude-code/executing-noodle-plans/SKILL.md

@@ -3,7 +3,7 @@ name: executing-noodle-plans
 description: "Use when the user asks to execute an approved, decision-complete implementation plan for a Noodle Seed project task by task with test-first changes, review, recovery, and final verification."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.84.0 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

package/skills/claude-code/publishing-mcp-integrations/SKILL.md

@@ -3,7 +3,7 @@ name: publishing-mcp-integrations
 description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.84.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

package/skills/claude-code/references/authoring-workflow.md

@@ -23,7 +23,8 @@
 
 1. **Website scrape** — if the user gives a URL, scrape it for surface hints (products, services, hours, contact, pricing). Stop there: the URL does not reveal CRM, booking systems, custom APIs, auth model, eligibility rules, quoting logic, or approval flows. Those live in the business systems and the owner’s head — ask.
 2. **OpenAPI import** — `noodle import openapi <file>` emits a starter `server.ts` from a spec. Use it when the user provides an OpenAPI document.
-3. **User interview** — Noodle does not interview; you do. Cover custom APIs/integrations, eligibility rules, quoting/approval logic, and private schemas (SQL DDL or JSON samples for custom `connector` declarations). Ask for concrete examples and sample payloads; do not guess a schema from a URL or invent endpoints.
+3. **Upstream MCP import** — `noodle import mcp <url> --name <slug> --output <dir>` discovers `tools/list` once, validates and freezes tool schemas into TypeScript, and writes a secret-free drift snapshot. Upstream annotations are untrusted, so generated tools remain destructive confirmed actions until an author verifies and narrows them. Use `--header-env <header>=<ENV_NAME>` for import-only auth and `--check` for classified, non-mutating drift detection. Runtime never performs discovery.
+4. **User interview** — Noodle does not interview; you do. Cover custom APIs/integrations, eligibility rules, quoting/approval logic, and private schemas (SQL DDL or JSON samples for custom `connector` declarations). Ask for concrete examples and sample payloads; do not guess a schema from a URL or invent endpoints.
 
 ## Fit check
 
@@ -42,10 +43,18 @@ Author in `server.ts`, then `noodle validate` → fix cited errors (see `compile
 Declare connectors as data, not imperative code:
 
 - **HTTP**: `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })` with per-operation `request`/`response` mapping using `${args...}` / `${response...}` expressions.
+- **MCP**: `connector("id").version("1.0.0").mcp({ endpoint, allowedOrigins, auth?, operations })` where each operation freezes the separate upstream `tool` wire name plus input/output schema. Import with `noodle import mcp`; do not hand-copy a live surface or call `tools/list` at runtime.
 - **Compute**: `connector("id").version("1.0.0").compute(name, { input, output, calls?, run })` — a self-contained, sandboxed function (no imports/closure capture) that may call allowlisted operations via `callOperation`.
 
 Tools record connector calls into a flow; recording is not execution. Do not branch on runtime outputs with native `if` — use declarative `when(...)` conditions.
 
+MCP connectors are curated backing operations, never transparent proxies. Publish ordinary Noodle tools
+with stable intent-shaped names, descriptions, annotations, authored schemas, confirmation, visibility,
+and optional React `view`. Normalize a text-only upstream result through compute before rendering when the
+view needs a richer stable output. Upstream resources, prompts, `_meta`, annotations, widgets, and CSP are
+not imported or forwarded. The runtime opens one guarded session for one operation, uses only a broker-minted
+credential, and closes it; it does not act as an agent for upstream sampling, roots, or elicitation.
+
 HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, `delegatedSessionCookie`, and `delegatedTokenExchange` (per-user calls to your own API — see "Delegated downstream auth" below). Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
 
 When one connector needs independently selectable accounts, declare catalog `credentialProfiles` plus each operation’s accepted `credentials.profiles`, then bind each `server.use` alias with `bind(connector, { profile, connection: connection("logical_id", managedSecret(secret("NAME"), { scopes, audience })) })`. The alias is the stable account boundary; never put provider account ids, labels, or credential values in it. `gmailConnector()` is the curated Gmail catalog helper; reuse it under independent aliases and accept canonical `accounts` arrays in tools (one account for writes, or an explicitly ordered supported combination for reads). See the bundled `gmail-multi-account` flagship. Bound managed secrets are supported by hosted execution. For deployed-server access to Google APIs, use `googleWorkloadIdentity({ provider: variable("GOOGLE_WIF_PROVIDER"), access: { kind: "direct" } })`, or add `serviceAccountImpersonation` with a managed service-account email. This is keyless Google Workload Identity Federation: exact Google scopes/audience come from the catalog operation, while `noodle auth google prepare|status|doctor|revoke` owns operator lifecycle. See the bundled `google-bigquery` flagship. `externalExchange()` is runnable only when the deployment operator injects an exact HTTPS provider endpoint/origin/audience and durable shared subject-pin store through service ports; Noodle sends a short-lived platform-signed deployment workload assertion and accepts only a bounded bearer response. Provider implementations must consume assertion replay ids through durable shared atomic storage across instances and restarts. There is intentionally no hosted enrollment or provider CRUD surface yet. The provider wire contract is public, but its conformance kit is workspace/source-only and is not an installable npm package. Bound `clientCredentials(...)` remains fail-closed until its provider slice lands.

package/skills/claude-code/references/connect-an-api.md

@@ -11,6 +11,7 @@ Connect a real API to a focused MCP product using managed credentials, mappings
 - Secure the key first
 - Probe the live API
 - Model the connector from the observed shape
+- Import and curate an upstream MCP server
 - Return a list
 - Create, update, delete
 - Design intent tools
@@ -22,7 +23,7 @@ Connect a real API to a focused MCP product using managed credentials, mappings
 
 ## Use when
 
-- The user provides credentials, a reachable API, or an OpenAPI document and wants real MCP behavior backed by it.
+- The user provides credentials, a reachable API, an OpenAPI document, or an upstream MCP endpoint and wants real MCP behavior backed by it.
 - Existing connector behavior compiles but still needs proof against the actual service and data shape.
 
 ## Do not use when
@@ -80,6 +81,35 @@ Encode the API as an HTTP connector, mapping only the fields you actually saw in
 The full connector shape, every `auth.kind`, and compute connectors are in
 `references/authoring-workflow.md`.
 
+### Import and curate an upstream MCP server
+
+Use an explicit import to discover the upstream tool surface once and generate TypeScript:
+
+```sh
+noodle import mcp https://store.example/api/mcp --name store --output store-app
+# When import discovery needs a credential, read it only from the environment:
+noodle import mcp https://store.example/api/mcp --name store \
+  --header-env Authorization=STORE_MCP_TOKEN
+```
+
+The importer freezes upstream tool names and normalized schemas into `.mcp({ operations })`; it never
+persists the import credential. Runtime calls only those declared operations and never runs `tools/list`.
+MCP annotations are untrusted hints, so every generated tool starts as a destructive confirmed action.
+Verify real behavior and deliberately narrow proven reads before accepting the generated source. Use
+`noodle import mcp <url> --output <dir> --check` in CI to detect upstream additions, removals, or schema
+changes without mutating source; its review labels drift additive, breaking, or metadata-only.
+
+Treat the imported connector operation as a backing-system contract, not the public tool design. Publish
+ordinary intent-shaped `tool(...)` capabilities with stable names and narrower schemas, normalize text or
+large upstream output through compute, and attach a normal Noodle React `view` when UI helps. Upstream
+`_meta`, resources, prompts, annotations, widgets, and CSP are never forwarded. A Noodle-owned widget may
+therefore enrich a headless upstream tool without trusting upstream executable UI.
+
+Managed endpoints require an exact managed origin allowlist. Configure each deployment with
+`variable(...)` and `secret(...)`; inbound MCP/OAuth bearer tokens are never reusable upstream credentials.
+The first release supports no auth, bearer, API key, and client credentials through the broker. Do not
+invent a delegated-user OAuth shortcut for an upstream MCP server.
+
 ### Return a list
 
 Most real tools return a variable-length list (search results, a user’s tasks). Bind the **whole array** — a single `${response.path}` returns the referenced value verbatim, arrays included:

package/skills/claude-code/references/sdk-surface.md

@@ -74,7 +74,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 ## Authoring signatures
 
 - `server(name, options, definitions)` — `options` commonly includes `title`, `version`, `instructions`, `agentGuide`, `distribution`, `branding`, `auth`, `use`, `provides`, `state`, and `handoff`; `definitions` is the array of tools/resources/prompts.
-- `tool(name, { description, input, output, annotations?, visibility?, view?, fulfil })` — `input`/`output` are Zod schemas; `fulfil({ input, connectors, user })` returns data matching `output`. Add `view: { component, entry }` for a React widget; use `visibility: ["app"]` for an app-only helper.
+- `tool(name, { description, input, output, annotations?, visibility?, modelVisibility?, view?, fulfil })` — `input`/`output` are Zod schemas; `fulfil({ input, connectors, user })` returns data matching `output`. Add `view: { component, entry }` for a React widget; use `visibility: ["app"]` for an app-only helper. Use `modelVisibility.latestMessageIncludesAny` only for normalized literal explicit-intent discovery; it does not authorize execution.
 - Keep tool input names application-owned and meaningful; `__noodleIntent` is reserved for an optional serve-time operator analytics adapter and never reaches `fulfil`.
 - `resource(name, { uri, description?, mimeType?, fulfil })` and `prompt(name, { description?, arguments?, fulfil })` expose MCP resources/prompts.
 - View metadata (`viewTitle`, `viewDescription`, `csp`, `domain`, `permissions`) belongs on the tool that renders it; `asset("./path")` packages local files.
@@ -146,7 +146,7 @@ prompt('summarize_ticket', {
 
 ### Non-trivial tool: ctx connectors, annotations, visibility, async
 
-`ctx` is `{ input, user, connectors }`. Bind connectors with `use` on the server, then call one inside `fulfil` to record a step. `annotations.readOnly()` declares a closed-world safe read. TypeScript action helpers enforce confirmation only with `{ confirm: true }`; omitted or `false` executes directly, and action/destructive/open-world hints alone never enable the gate. For stateless hosts that cannot present Noodle confirmation, set `interactions: { confirmationFallback: 'host' }` in the `server` options to explicitly trust native host write approval; omission remains fail-closed and the fallback never supplies missing `ctx.elicit` input. `visibility` defaults to `['model', 'app']` — set `['app']` to hide a helper from the model. `fulfil` may be `async` (the compiler awaits it while recording).
+`ctx` is `{ input, user, connectors }`. Bind connectors with `use` on the server, then call one inside `fulfil` to record a step. `annotations.readOnly()` declares a closed-world safe read. TypeScript action helpers enforce confirmation only with `{ confirm: true }`; omitted or `false` executes directly, and action/destructive/open-world hints alone never enable the gate. For stateless hosts that cannot present Noodle confirmation, set `interactions: { confirmationFallback: 'host' }` in the `server` options to explicitly trust native host write approval; omission remains fail-closed and the fallback never supplies missing `ctx.elicit` input. `visibility` defaults to `['model', 'app']` — set `['app']` to hide a helper from the model. For a narrow explicit-intent tool, `modelVisibility: { latestMessageIncludesAny: [...] }` deterministically limits model discovery to a latest user message containing one of the normalized literal phrases; it is not authorization. `fulfil` may be `async` (the compiler awaits it while recording).
 
 ```ts
 import { annotations, connector, server, tool, z } from '@noodleseed/one';
@@ -177,6 +177,7 @@ export default server('support', { title: 'Support', version: '1.0.0', use: { cr
     output: z.object({ subject: z.string(), status: z.string() }),
     annotations: annotations.readOnly(), // read-only hint for hosts
     visibility: ['model', 'app'], // default; use ['app'] to hide the tool from the model
+    modelVisibility: { latestMessageIncludesAny: ['show ticket', 'open ticket'] },
     // ctx is { input, user, connectors }. A connector call records one flow step (a Ref) —
     // recording is not execution, so never branch on the result with native if (use when).
     fulfil: ({ input, connectors }) => {

package/skills/claude-code/references/widgets-and-apps.md

@@ -12,7 +12,7 @@
 
 ## Tools and views
 
-Use `tool(name, { description, input, output, fulfil, view })` for a model-visible tool that renders a widget, and the same `tool(name, { ..., visibility: ["app"] })` for an app-only helper hidden from the model. A `view` is `{ component: "name", entry: "./views/name.tsx" }` — a React component the compiler bundles at validate/deploy time.
+Use `tool(name, { description, input, output, fulfil, view })` for a model-visible tool that renders a widget, and the same `tool(name, { ..., visibility: ["app"] })` for an app-only helper hidden from the model. When a view is valid only for narrow explicit intent, add `modelVisibility: { latestMessageIncludesAny: ["open the form", ...] }`; Noodle normalizes and matches those literal phrases against the latest user message before model discovery and fails closed on malformed data. This is relevance filtering, never authorization. A `view` is `{ component: "name", entry: "./views/name.tsx" }` — a React component the compiler bundles at validate/deploy time.
 
 ## Noodle Design default
 

package/skills/claude-code/reporting-noodle-feedback/SKILL.md

@@ -3,7 +3,7 @@ name: reporting-noodle-feedback
 description: "Use when a Noodle Seed bug, misleading instruction, missing capability, or concrete product improvement should be proposed to the user."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.84.0 hash:0f404109f4845683 -->
 
 # reporting-noodle-feedback
 

package/skills/claude-code/verifying-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: verifying-mcp-delivery
 description: "Use when proving a Noodle Seed MCP project works at a named compile, local, connector, App, host, deployment, or production evidence level."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.84.0 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery
 

package/skills/claude-code/wrapping-existing-applications/SKILL.md

@@ -3,7 +3,7 @@ name: wrapping-existing-applications
 description: "Use when an existing application has no stable usable API and needs a read-only, identity-first Noodle Seed integration plan before implementation."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:eccc3c158dcafba8 -->
+<!-- noodle-skill version:0.84.0 hash:eccc3c158dcafba8 -->
 
 # wrapping-existing-applications
 

package/skills/codex/SKILL.md

@@ -3,7 +3,7 @@ name: noodle-seed
 description: "Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:13ddce01769caae4 -->
+<!-- noodle-skill version:0.84.0 hash:13ddce01769caae4 -->
 
 # Noodle Seed
 

package/skills/codex/authoring-mcp-servers/SKILL.md

@@ -3,7 +3,7 @@ name: authoring-mcp-servers
 description: "Use when creating or extending a headless Noodle Seed MCP server, tool, resource, prompt, or typed model-facing capability."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:11523cb33b9473c0 -->
+<!-- noodle-skill version:0.84.0 hash:11523cb33b9473c0 -->
 
 # authoring-mcp-servers
 

package/skills/codex/building-mcp-apps/SKILL.md

@@ -3,7 +3,7 @@ name: building-mcp-apps
 description: "Use when a Noodle Seed MCP App, widget, interactive card, visual interaction, or host-visible UI is the primary requested outcome."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:9fd67d4d24328e15 -->
+<!-- noodle-skill version:0.84.0 hash:9fd67d4d24328e15 -->
 
 # building-mcp-apps
 

package/skills/codex/connecting-apis-to-mcp/SKILL.md

@@ -3,7 +3,7 @@ name: connecting-apis-to-mcp
 description: "Use when all four API-evidence inputs exist—and only then: API base URL, authentication scheme, representative safe read, and observed response."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:21bbd3ec441ffd30 -->
+<!-- noodle-skill version:0.84.0 hash:21bbd3ec441ffd30 -->
 
 # connecting-apis-to-mcp
 

package/skills/codex/creating-product-agent-guides/SKILL.md

@@ -3,7 +3,7 @@ name: creating-product-agent-guides
 description: "Use when a Noodle Seed MCP server needs a new or revised product agent guide, App Package skill, or explicit product-skill regeneration."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:0fa48a82fe836cf0 -->
+<!-- noodle-skill version:0.84.0 hash:0fa48a82fe836cf0 -->
 
 # creating-product-agent-guides
 

package/skills/codex/debugging-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: debugging-mcp-delivery
 description: "Use when an existing Noodle Seed MCP project has a concrete validation, runtime, connector, App, host, deployment, or production failure."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.84.0 hash:aa715bae12041d7c -->
 
 # debugging-mcp-delivery
 

package/skills/codex/deploying-mcp-services/SKILL.md

@@ -3,7 +3,7 @@ name: deploying-mcp-services
 description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.84.0 hash:93e735b7ffb45df1 -->
 
 # deploying-mcp-services
 

package/skills/codex/designing-mcp-products/SKILL.md

@@ -3,7 +3,7 @@ name: designing-mcp-products
 description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:78a6f181b61f92f1 -->
+<!-- noodle-skill version:0.84.0 hash:78a6f181b61f92f1 -->
 
 # designing-mcp-products
 

package/skills/codex/embedding-mcp-assistants/SKILL.md

@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
 description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:cc54a67f21c0ecdb -->
+<!-- noodle-skill version:0.84.0 hash:cc54a67f21c0ecdb -->
 
 # embedding-mcp-assistants
 

package/skills/codex/examples/food-ordering/README.md

@@ -26,6 +26,7 @@ private customer data.
 | Handoff | `handoff.allowedDomains` allows only `https://orders.example.com` checkout URLs |
 | Progressive enhancement | Non-Apps hosts still receive stores, featured items, and a readable fallback summary |
 | Fail-closed hydration | The React view treats only the unhydrated, pre-result `{}` envelope as pending; a hydrated empty success remains distinct. It surfaces `isError`, validates required records and identifiers, and withholds ordering actions from malformed results |
+| Upstream MCP composition | This synthetic example keeps its data local. For the canonical frozen-tool import, governed upstream invocation, response normalization, and Noodle-owned widget pattern, use the repository's `shopify-storefront` flagship rather than copying another composition surface here |
 
 The example is intentionally richer than the generated starter, but each inline view still follows the
 same default: one immediate purpose, one primary action, at most one subordinate action, and progressive

package/skills/codex/examples/food-ordering/src/server.ts

@@ -352,6 +352,18 @@ export default server(
       description:
         'Open a complete food-ordering widget with store discovery, menu browsing, cart review, and checkout handoff.',
       annotations: readOnly,
+      modelVisibility: {
+        latestMessageIncludesAny: [
+          'order',
+          'food',
+          'menu',
+          'restaurant',
+          'cart',
+          'pickup',
+          'delivery',
+          'checkout',
+        ],
+      },
       input: z.object({
         query: z.string().optional(),
         customer: z.string().default('Guest'),

package/skills/codex/examples/food-ordering/test/server.test.ts

@@ -80,6 +80,13 @@ describe('food-ordering example', () => {
     expect(JSON.stringify(tools.get('open_ordering'))).toContain('${context.ambient.serviceArea}');
     expect(JSON.stringify(tools.get('open_ordering'))).toContain('${context.location.latitude}');
     expect(JSON.stringify(tools.get('open_ordering'))).toContain('${context.location.longitude}');
+    expect(tools.get('open_ordering')?.annotations).toMatchObject({
+      'x-noodleseed-model-latest-message-includes-any': expect.arrayContaining([
+        'order',
+        'menu',
+        'checkout',
+      ]),
+    });
     expect(JSON.stringify(tools.get('sync_cart'))).toContain('revision');
     expect(tools.get('sync_cart')?.annotations?.confirm).toBe(false);
     expect(tools.get('prepare_checkout')?.annotations?.confirm).toBe(false);

package/skills/codex/executing-noodle-plans/SKILL.md

@@ -3,7 +3,7 @@ name: executing-noodle-plans
 description: "Use when the user asks to execute an approved, decision-complete implementation plan for a Noodle Seed project task by task with test-first changes, review, recovery, and final verification."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.84.0 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

package/skills/codex/publishing-mcp-integrations/SKILL.md

@@ -3,7 +3,7 @@ name: publishing-mcp-integrations
 description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
 ---
 
-<!-- noodle-skill version:0.83.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.84.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

package/skills/codex/references/authoring-workflow.md

@@ -23,7 +23,8 @@
 
 1. **Website scrape** — if the user gives a URL, scrape it for surface hints (products, services, hours, contact, pricing). Stop there: the URL does not reveal CRM, booking systems, custom APIs, auth model, eligibility rules, quoting logic, or approval flows. Those live in the business systems and the owner’s head — ask.
 2. **OpenAPI import** — `noodle import openapi <file>` emits a starter `server.ts` from a spec. Use it when the user provides an OpenAPI document.
-3. **User interview** — Noodle does not interview; you do. Cover custom APIs/integrations, eligibility rules, quoting/approval logic, and private schemas (SQL DDL or JSON samples for custom `connector` declarations). Ask for concrete examples and sample payloads; do not guess a schema from a URL or invent endpoints.
+3. **Upstream MCP import** — `noodle import mcp <url> --name <slug> --output <dir>` discovers `tools/list` once, validates and freezes tool schemas into TypeScript, and writes a secret-free drift snapshot. Upstream annotations are untrusted, so generated tools remain destructive confirmed actions until an author verifies and narrows them. Use `--header-env <header>=<ENV_NAME>` for import-only auth and `--check` for classified, non-mutating drift detection. Runtime never performs discovery.
+4. **User interview** — Noodle does not interview; you do. Cover custom APIs/integrations, eligibility rules, quoting/approval logic, and private schemas (SQL DDL or JSON samples for custom `connector` declarations). Ask for concrete examples and sample payloads; do not guess a schema from a URL or invent endpoints.
 
 ## Fit check
 
@@ -42,10 +43,18 @@ Author in `server.ts`, then `noodle validate` → fix cited errors (see `compile
 Declare connectors as data, not imperative code:
 
 - **HTTP**: `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })` with per-operation `request`/`response` mapping using `${args...}` / `${response...}` expressions.
+- **MCP**: `connector("id").version("1.0.0").mcp({ endpoint, allowedOrigins, auth?, operations })` where each operation freezes the separate upstream `tool` wire name plus input/output schema. Import with `noodle import mcp`; do not hand-copy a live surface or call `tools/list` at runtime.
 - **Compute**: `connector("id").version("1.0.0").compute(name, { input, output, calls?, run })` — a self-contained, sandboxed function (no imports/closure capture) that may call allowlisted operations via `callOperation`.
 
 Tools record connector calls into a flow; recording is not execution. Do not branch on runtime outputs with native `if` — use declarative `when(...)` conditions.
 
+MCP connectors are curated backing operations, never transparent proxies. Publish ordinary Noodle tools
+with stable intent-shaped names, descriptions, annotations, authored schemas, confirmation, visibility,
+and optional React `view`. Normalize a text-only upstream result through compute before rendering when the
+view needs a richer stable output. Upstream resources, prompts, `_meta`, annotations, widgets, and CSP are
+not imported or forwarded. The runtime opens one guarded session for one operation, uses only a broker-minted
+credential, and closes it; it does not act as an agent for upstream sampling, roots, or elicitation.
+
 HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, `delegatedSessionCookie`, and `delegatedTokenExchange` (per-user calls to your own API — see "Delegated downstream auth" below). Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
 
 When one connector needs independently selectable accounts, declare catalog `credentialProfiles` plus each operation’s accepted `credentials.profiles`, then bind each `server.use` alias with `bind(connector, { profile, connection: connection("logical_id", managedSecret(secret("NAME"), { scopes, audience })) })`. The alias is the stable account boundary; never put provider account ids, labels, or credential values in it. `gmailConnector()` is the curated Gmail catalog helper; reuse it under independent aliases and accept canonical `accounts` arrays in tools (one account for writes, or an explicitly ordered supported combination for reads). See the bundled `gmail-multi-account` flagship. Bound managed secrets are supported by hosted execution. For deployed-server access to Google APIs, use `googleWorkloadIdentity({ provider: variable("GOOGLE_WIF_PROVIDER"), access: { kind: "direct" } })`, or add `serviceAccountImpersonation` with a managed service-account email. This is keyless Google Workload Identity Federation: exact Google scopes/audience come from the catalog operation, while `noodle auth google prepare|status|doctor|revoke` owns operator lifecycle. See the bundled `google-bigquery` flagship. `externalExchange()` is runnable only when the deployment operator injects an exact HTTPS provider endpoint/origin/audience and durable shared subject-pin store through service ports; Noodle sends a short-lived platform-signed deployment workload assertion and accepts only a bounded bearer response. Provider implementations must consume assertion replay ids through durable shared atomic storage across instances and restarts. There is intentionally no hosted enrollment or provider CRUD surface yet. The provider wire contract is public, but its conformance kit is workspace/source-only and is not an installable npm package. Bound `clientCredentials(...)` remains fail-closed until its provider slice lands.

package/skills/codex/references/connect-an-api.md

@@ -11,6 +11,7 @@ Connect a real API to a focused MCP product using managed credentials, mappings
 - Secure the key first
 - Probe the live API
 - Model the connector from the observed shape
+- Import and curate an upstream MCP server
 - Return a list
 - Create, update, delete
 - Design intent tools
@@ -22,7 +23,7 @@ Connect a real API to a focused MCP product using managed credentials, mappings
 
 ## Use when
 
-- The user provides credentials, a reachable API, or an OpenAPI document and wants real MCP behavior backed by it.
+- The user provides credentials, a reachable API, an OpenAPI document, or an upstream MCP endpoint and wants real MCP behavior backed by it.
 - Existing connector behavior compiles but still needs proof against the actual service and data shape.
 
 ## Do not use when
@@ -80,6 +81,35 @@ Encode the API as an HTTP connector, mapping only the fields you actually saw in
 The full connector shape, every `auth.kind`, and compute connectors are in
 `references/authoring-workflow.md`.
 
+### Import and curate an upstream MCP server
+
+Use an explicit import to discover the upstream tool surface once and generate TypeScript:
+
+```sh
+noodle import mcp https://store.example/api/mcp --name store --output store-app
+# When import discovery needs a credential, read it only from the environment:
+noodle import mcp https://store.example/api/mcp --name store \
+  --header-env Authorization=STORE_MCP_TOKEN
+```
+
+The importer freezes upstream tool names and normalized schemas into `.mcp({ operations })`; it never
+persists the import credential. Runtime calls only those declared operations and never runs `tools/list`.
+MCP annotations are untrusted hints, so every generated tool starts as a destructive confirmed action.
+Verify real behavior and deliberately narrow proven reads before accepting the generated source. Use
+`noodle import mcp <url> --output <dir> --check` in CI to detect upstream additions, removals, or schema
+changes without mutating source; its review labels drift additive, breaking, or metadata-only.
+
+Treat the imported connector operation as a backing-system contract, not the public tool design. Publish
+ordinary intent-shaped `tool(...)` capabilities with stable names and narrower schemas, normalize text or
+large upstream output through compute, and attach a normal Noodle React `view` when UI helps. Upstream
+`_meta`, resources, prompts, annotations, widgets, and CSP are never forwarded. A Noodle-owned widget may
+therefore enrich a headless upstream tool without trusting upstream executable UI.
+
+Managed endpoints require an exact managed origin allowlist. Configure each deployment with
+`variable(...)` and `secret(...)`; inbound MCP/OAuth bearer tokens are never reusable upstream credentials.
+The first release supports no auth, bearer, API key, and client credentials through the broker. Do not
+invent a delegated-user OAuth shortcut for an upstream MCP server.
+
 ### Return a list
 
 Most real tools return a variable-length list (search results, a user’s tasks). Bind the **whole array** — a single `${response.path}` returns the referenced value verbatim, arrays included:

package/skills/codex/references/sdk-surface.md

@@ -74,7 +74,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 ## Authoring signatures
 
 - `server(name, options, definitions)` — `options` commonly includes `title`, `version`, `instructions`, `agentGuide`, `distribution`, `branding`, `auth`, `use`, `provides`, `state`, and `handoff`; `definitions` is the array of tools/resources/prompts.
-- `tool(name, { description, input, output, annotations?, visibility?, view?, fulfil })` — `input`/`output` are Zod schemas; `fulfil({ input, connectors, user })` returns data matching `output`. Add `view: { component, entry }` for a React widget; use `visibility: ["app"]` for an app-only helper.
+- `tool(name, { description, input, output, annotations?, visibility?, modelVisibility?, view?, fulfil })` — `input`/`output` are Zod schemas; `fulfil({ input, connectors, user })` returns data matching `output`. Add `view: { component, entry }` for a React widget; use `visibility: ["app"]` for an app-only helper. Use `modelVisibility.latestMessageIncludesAny` only for normalized literal explicit-intent discovery; it does not authorize execution.
 - Keep tool input names application-owned and meaningful; `__noodleIntent` is reserved for an optional serve-time operator analytics adapter and never reaches `fulfil`.
 - `resource(name, { uri, description?, mimeType?, fulfil })` and `prompt(name, { description?, arguments?, fulfil })` expose MCP resources/prompts.
 - View metadata (`viewTitle`, `viewDescription`, `csp`, `domain`, `permissions`) belongs on the tool that renders it; `asset("./path")` packages local files.
@@ -146,7 +146,7 @@ prompt('summarize_ticket', {
 
 ### Non-trivial tool: ctx connectors, annotations, visibility, async
 
-`ctx` is `{ input, user, connectors }`. Bind connectors with `use` on the server, then call one inside `fulfil` to record a step. `annotations.readOnly()` declares a closed-world safe read. TypeScript action helpers enforce confirmation only with `{ confirm: true }`; omitted or `false` executes directly, and action/destructive/open-world hints alone never enable the gate. For stateless hosts that cannot present Noodle confirmation, set `interactions: { confirmationFallback: 'host' }` in the `server` options to explicitly trust native host write approval; omission remains fail-closed and the fallback never supplies missing `ctx.elicit` input. `visibility` defaults to `['model', 'app']` — set `['app']` to hide a helper from the model. `fulfil` may be `async` (the compiler awaits it while recording).
+`ctx` is `{ input, user, connectors }`. Bind connectors with `use` on the server, then call one inside `fulfil` to record a step. `annotations.readOnly()` declares a closed-world safe read. TypeScript action helpers enforce confirmation only with `{ confirm: true }`; omitted or `false` executes directly, and action/destructive/open-world hints alone never enable the gate. For stateless hosts that cannot present Noodle confirmation, set `interactions: { confirmationFallback: 'host' }` in the `server` options to explicitly trust native host write approval; omission remains fail-closed and the fallback never supplies missing `ctx.elicit` input. `visibility` defaults to `['model', 'app']` — set `['app']` to hide a helper from the model. For a narrow explicit-intent tool, `modelVisibility: { latestMessageIncludesAny: [...] }` deterministically limits model discovery to a latest user message containing one of the normalized literal phrases; it is not authorization. `fulfil` may be `async` (the compiler awaits it while recording).
 
 ```ts
 import { annotations, connector, server, tool, z } from '@noodleseed/one';
@@ -177,6 +177,7 @@ export default server('support', { title: 'Support', version: '1.0.0', use: { cr
     output: z.object({ subject: z.string(), status: z.string() }),
     annotations: annotations.readOnly(), // read-only hint for hosts
     visibility: ['model', 'app'], // default; use ['app'] to hide the tool from the model
+    modelVisibility: { latestMessageIncludesAny: ['show ticket', 'open ticket'] },
     // ctx is { input, user, connectors }. A connector call records one flow step (a Ref) —
     // recording is not execution, so never branch on the result with native if (use when).
     fulfil: ({ input, connectors }) => {