@noodleseed/agent-kit 0.64.0 → 0.65.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/manifest.json +265 -265
- package/package.json +1 -1
- package/skills/claude-code/SKILL.md +1 -1
- package/skills/claude-code/authoring-mcp-servers/SKILL.md +1 -1
- package/skills/claude-code/building-mcp-apps/SKILL.md +1 -1
- package/skills/claude-code/connecting-apis-to-mcp/SKILL.md +1 -1
- package/skills/claude-code/debugging-mcp-delivery/SKILL.md +1 -1
- package/skills/claude-code/deploying-mcp-services/SKILL.md +1 -1
- package/skills/claude-code/designing-mcp-products/SKILL.md +1 -1
- package/skills/claude-code/embedding-mcp-assistants/SKILL.md +1 -1
- package/skills/claude-code/examples/acme-discovery/README.md +22 -3
- package/skills/claude-code/examples/acme-discovery/src/server.ts +118 -89
- package/skills/claude-code/examples/acme-tasks/README.md +3 -2
- package/skills/claude-code/examples/customer-auth/src/server.ts +8 -5
- package/skills/claude-code/examples/weather/README.md +2 -1
- package/skills/claude-code/executing-noodle-plans/SKILL.md +1 -1
- package/skills/claude-code/publishing-mcp-integrations/SKILL.md +1 -1
- package/skills/claude-code/references/compile-errors.md +3 -0
- package/skills/claude-code/references/connect-an-api.md +2 -2
- package/skills/claude-code/references/embedded-assistant.md +67 -3
- package/skills/claude-code/references/sdk-surface.md +2 -0
- package/skills/claude-code/reporting-noodle-feedback/SKILL.md +1 -1
- package/skills/claude-code/verifying-mcp-delivery/SKILL.md +1 -1
- package/skills/claude-code/wrapping-existing-applications/SKILL.md +1 -1
- package/skills/codex/SKILL.md +1 -1
- package/skills/codex/authoring-mcp-servers/SKILL.md +1 -1
- package/skills/codex/building-mcp-apps/SKILL.md +1 -1
- package/skills/codex/connecting-apis-to-mcp/SKILL.md +1 -1
- package/skills/codex/debugging-mcp-delivery/SKILL.md +1 -1
- package/skills/codex/deploying-mcp-services/SKILL.md +1 -1
- package/skills/codex/designing-mcp-products/SKILL.md +1 -1
- package/skills/codex/embedding-mcp-assistants/SKILL.md +1 -1
- package/skills/codex/examples/acme-discovery/README.md +22 -3
- package/skills/codex/examples/acme-discovery/src/server.ts +118 -89
- package/skills/codex/examples/acme-tasks/README.md +3 -2
- package/skills/codex/examples/customer-auth/src/server.ts +8 -5
- package/skills/codex/examples/weather/README.md +2 -1
- package/skills/codex/executing-noodle-plans/SKILL.md +1 -1
- package/skills/codex/publishing-mcp-integrations/SKILL.md +1 -1
- package/skills/codex/references/compile-errors.md +3 -0
- package/skills/codex/references/connect-an-api.md +2 -2
- package/skills/codex/references/embedded-assistant.md +67 -3
- package/skills/codex/references/sdk-surface.md +2 -0
- package/skills/codex/reporting-noodle-feedback/SKILL.md +1 -1
- package/skills/codex/verifying-mcp-delivery/SKILL.md +1 -1
- package/skills/codex/wrapping-existing-applications/SKILL.md +1 -1
|
@@ -3,7 +3,7 @@ name: deploying-mcp-services
|
|
|
3
3
|
description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
<!-- noodle-skill version:0.
|
|
6
|
+
<!-- noodle-skill version:0.65.0 hash:93e735b7ffb45df1 -->
|
|
7
7
|
|
|
8
8
|
# deploying-mcp-services
|
|
9
9
|
|
|
@@ -3,7 +3,7 @@ name: designing-mcp-products
|
|
|
3
3
|
description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
<!-- noodle-skill version:0.
|
|
6
|
+
<!-- noodle-skill version:0.65.0 hash:78a6f181b61f92f1 -->
|
|
7
7
|
|
|
8
8
|
# designing-mcp-products
|
|
9
9
|
|
|
@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
|
|
|
3
3
|
description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
<!-- noodle-skill version:0.
|
|
6
|
+
<!-- noodle-skill version:0.65.0 hash:cc54a67f21c0ecdb -->
|
|
7
7
|
|
|
8
8
|
# embedding-mcp-assistants
|
|
9
9
|
|
|
@@ -7,9 +7,28 @@ deep link. It pairs a `tool` discovery carousel with a model-visible `create_han
|
|
|
7
7
|
server-level `handoff.allowedDomains`.
|
|
8
8
|
|
|
9
9
|
Capability slots: top-of-funnel funnel discipline, discovery carousel widget, `create_handoff` deep-link
|
|
10
|
-
handoff with attribution, `handoff.allowedDomains`,
|
|
11
|
-
wireframe below). It shows the "design the experience, then build
|
|
12
|
-
`references/experience-design.md` teaches.
|
|
10
|
+
handoff with attribution, `handoff.allowedDomains`, the **public website assistant surface**, and a worked
|
|
11
|
+
**design-first** artifact (the UX spec + wireframe below). It shows the "design the experience, then build
|
|
12
|
+
it" flow the `noodle-seed` skill's `references/experience-design.md` teaches.
|
|
13
|
+
|
|
14
|
+
## The same tools on Acme's own website
|
|
15
|
+
|
|
16
|
+
The funnel does not only start in ChatGPT. The `assistant` block projects these same three tools onto
|
|
17
|
+
Acme's marketing site for a visitor with **no account and no session backend**:
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
access: publicWebsite({
|
|
21
|
+
origins: ['https://getaways.acme.example'],
|
|
22
|
+
capabilities: [discoverGetaways, createHandoff, shortlistGetaway],
|
|
23
|
+
}),
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
There is no second tool set and no second app — one `server.ts`, projected onto another front door.
|
|
27
|
+
`capabilities` is the entire externally reachable surface, so it stays short enough to review at a glance
|
|
28
|
+
and closed by default: a tool added to this server later is unreachable from the website until someone
|
|
29
|
+
lists it. A tool that needed a signed-in user could not be listed here at all (the compiler rejects it);
|
|
30
|
+
serving those to visitors means `publicWebsite({ ..., signIn: true })`, which lets a visitor sign in
|
|
31
|
+
mid-conversation through Acme's own login.
|
|
13
32
|
|
|
14
33
|
## Design spec (write this before the code)
|
|
15
34
|
|
|
@@ -1,4 +1,14 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import {
|
|
2
|
+
annotations,
|
|
3
|
+
embeddedAssistant,
|
|
4
|
+
openAICompatible,
|
|
5
|
+
publicWebsite,
|
|
6
|
+
secret,
|
|
7
|
+
server,
|
|
8
|
+
tool,
|
|
9
|
+
variable,
|
|
10
|
+
z,
|
|
11
|
+
} from '@noodleseed/one';
|
|
2
12
|
|
|
3
13
|
// Acme Getaways is a fictional travel brand. This app is deliberately top-of-funnel: discovery and
|
|
4
14
|
// configuration happen inside ChatGPT; the booking/transaction happens off-app on Acme's own site,
|
|
@@ -95,6 +105,97 @@ const destinationOutput = z.object({
|
|
|
95
105
|
why: z.string(),
|
|
96
106
|
});
|
|
97
107
|
|
|
108
|
+
const discoverGetaways = tool('discover_getaways', {
|
|
109
|
+
title: 'Discover getaways',
|
|
110
|
+
description:
|
|
111
|
+
'Suggest Acme Getaways destinations for a vibe and month and render a discovery carousel.',
|
|
112
|
+
annotations: readOnly,
|
|
113
|
+
input: discoverInput,
|
|
114
|
+
output: z.object({
|
|
115
|
+
status: z.string(),
|
|
116
|
+
vibe: z.string(),
|
|
117
|
+
month: z.string(),
|
|
118
|
+
travelers: z.number(),
|
|
119
|
+
// Bounded list: the curated catalog is fixed and small, and the declared ceiling tells the
|
|
120
|
+
// model and host the payload cannot grow. `noodle check` reports `tool_design_output_bounds`.
|
|
121
|
+
options: z.array(destinationOutput).max(20),
|
|
122
|
+
}),
|
|
123
|
+
// The carousel presents Acme's curated catalog; the model narrates which fit the stated vibe.
|
|
124
|
+
// (A tool cannot filter on an input value — that is connector/flow work — so all are returned.)
|
|
125
|
+
fulfil: ({ input }) => ({
|
|
126
|
+
status: `Acme Getaways for a ${input.vibe} trip in ${input.month}, ${input.travelers} traveler(s).`,
|
|
127
|
+
vibe: input.vibe,
|
|
128
|
+
month: input.month,
|
|
129
|
+
travelers: input.travelers,
|
|
130
|
+
options: catalog,
|
|
131
|
+
}),
|
|
132
|
+
viewTitle: 'Discover getaways',
|
|
133
|
+
// ChatGPT host status copy (openai/toolInvocation/*) — required for widget-opening tools.
|
|
134
|
+
invoking: 'Finding getaways…',
|
|
135
|
+
invoked: 'Getaways ready',
|
|
136
|
+
domain: 'https://getaways.acme.example',
|
|
137
|
+
view: {
|
|
138
|
+
component: 'discovery-carousel',
|
|
139
|
+
entry: './views/discovery-carousel.tsx',
|
|
140
|
+
},
|
|
141
|
+
viewDescription:
|
|
142
|
+
'A top-of-funnel discovery carousel: pick a destination, then hand off to Acme to book.',
|
|
143
|
+
csp: {
|
|
144
|
+
connectDomains: ['https://acme.example'],
|
|
145
|
+
resourceDomains: ['https://acme.example'],
|
|
146
|
+
frameDomains: ['https://acme.example'],
|
|
147
|
+
},
|
|
148
|
+
});
|
|
149
|
+
|
|
150
|
+
const createHandoff = tool('create_handoff', {
|
|
151
|
+
title: 'Create booking handoff',
|
|
152
|
+
description:
|
|
153
|
+
'Create the Acme booking deep link for a chosen destination, carrying the configured trip. ' +
|
|
154
|
+
'Pass the destination id (url-safe slug, e.g. "coral_bay") and its display name.',
|
|
155
|
+
annotations: openLink,
|
|
156
|
+
input: z.object({
|
|
157
|
+
destination: destinationId,
|
|
158
|
+
destinationName: z.string().min(1),
|
|
159
|
+
month: monthEnum,
|
|
160
|
+
travelers: z.number().int().min(1).default(2),
|
|
161
|
+
}),
|
|
162
|
+
output: z.object({
|
|
163
|
+
status: z.string(),
|
|
164
|
+
destination: z.string(),
|
|
165
|
+
summary: z.string(),
|
|
166
|
+
handoffUrl: z.string(),
|
|
167
|
+
}),
|
|
168
|
+
// Inline the inputs directly so they substitute at runtime; every value is already url-safe
|
|
169
|
+
// (id slug, month enum, integer), and `src=chatgpt` is the attribution the partner measures
|
|
170
|
+
// ChatGPT-sourced conversions on.
|
|
171
|
+
fulfil: ({ input }) => ({
|
|
172
|
+
status: `Ready to continue on Acme for ${input.destinationName}.`,
|
|
173
|
+
destination: input.destination,
|
|
174
|
+
summary: `${input.destinationName} · ${input.month} · ${input.travelers} traveler(s)`,
|
|
175
|
+
handoffUrl: `https://book.acme.example/plan?dest=${input.destination}&month=${input.month}&pax=${input.travelers}&src=chatgpt`,
|
|
176
|
+
}),
|
|
177
|
+
});
|
|
178
|
+
|
|
179
|
+
const shortlistGetaway = tool('shortlist_getaway', {
|
|
180
|
+
visibility: ['app'],
|
|
181
|
+
description: 'Record the traveler’s shortlisted destination from the discovery widget.',
|
|
182
|
+
annotations: localWrite,
|
|
183
|
+
input: z.object({
|
|
184
|
+
destination: z.string(),
|
|
185
|
+
note: z.string().default(''),
|
|
186
|
+
}),
|
|
187
|
+
output: z.object({
|
|
188
|
+
status: z.string(),
|
|
189
|
+
destination: z.string(),
|
|
190
|
+
note: z.string(),
|
|
191
|
+
}),
|
|
192
|
+
fulfil: ({ input }) => ({
|
|
193
|
+
status: `Shortlisted ${input.destination}.`,
|
|
194
|
+
destination: input.destination,
|
|
195
|
+
note: input.note,
|
|
196
|
+
}),
|
|
197
|
+
});
|
|
198
|
+
|
|
98
199
|
export default server(
|
|
99
200
|
'acme_discovery',
|
|
100
201
|
{
|
|
@@ -113,95 +214,23 @@ export default server(
|
|
|
113
214
|
handoff: {
|
|
114
215
|
allowedDomains: ['https://book.acme.example', 'https://acme.example'],
|
|
115
216
|
},
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
status: z.string(),
|
|
126
|
-
vibe: z.string(),
|
|
127
|
-
month: z.string(),
|
|
128
|
-
travelers: z.number(),
|
|
129
|
-
// Bounded list: the curated catalog is fixed and small, and the declared ceiling tells the
|
|
130
|
-
// model and host the payload cannot grow. `noodle check` reports `tool_design_output_bounds`.
|
|
131
|
-
options: z.array(destinationOutput).max(20),
|
|
217
|
+
// The same three tools also serve Acme's own marketing site, with no second tool set and no
|
|
218
|
+
// session backend: a visitor with no account gets the discovery carousel and the booking
|
|
219
|
+
// handoff. `capabilities` is the whole externally reachable surface — short enough to review in
|
|
220
|
+
// one glance, and closed by default when a tool is added to the server later.
|
|
221
|
+
assistant: embeddedAssistant({
|
|
222
|
+
model: openAICompatible({
|
|
223
|
+
baseUrl: variable('ASSISTANT_MODEL_BASE_URL'),
|
|
224
|
+
model: variable('ASSISTANT_MODEL'),
|
|
225
|
+
apiKey: secret('ASSISTANT_MODEL_API_KEY'),
|
|
132
226
|
}),
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
status: `Acme Getaways for a ${input.vibe} trip in ${input.month}, ${input.travelers} traveler(s).`,
|
|
137
|
-
vibe: input.vibe,
|
|
138
|
-
month: input.month,
|
|
139
|
-
travelers: input.travelers,
|
|
140
|
-
options: catalog,
|
|
227
|
+
access: publicWebsite({
|
|
228
|
+
origins: ['https://getaways.acme.example'],
|
|
229
|
+
capabilities: [discoverGetaways, createHandoff, shortlistGetaway],
|
|
141
230
|
}),
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
invoking: 'Finding getaways…',
|
|
145
|
-
invoked: 'Getaways ready',
|
|
146
|
-
domain: 'https://getaways.acme.example',
|
|
147
|
-
view: {
|
|
148
|
-
component: 'discovery-carousel',
|
|
149
|
-
entry: './views/discovery-carousel.tsx',
|
|
150
|
-
},
|
|
151
|
-
viewDescription:
|
|
152
|
-
'A top-of-funnel discovery carousel: pick a destination, then hand off to Acme to book.',
|
|
153
|
-
csp: {
|
|
154
|
-
connectDomains: ['https://acme.example'],
|
|
155
|
-
resourceDomains: ['https://acme.example'],
|
|
156
|
-
frameDomains: ['https://acme.example'],
|
|
157
|
-
},
|
|
231
|
+
layout: { mode: 'floating', position: 'bottom-right' },
|
|
232
|
+
labels: { welcomeHeading: 'Where would you like to go?' },
|
|
158
233
|
}),
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
description:
|
|
162
|
-
'Create the Acme booking deep link for a chosen destination, carrying the configured trip. ' +
|
|
163
|
-
'Pass the destination id (url-safe slug, e.g. "coral_bay") and its display name.',
|
|
164
|
-
annotations: openLink,
|
|
165
|
-
input: z.object({
|
|
166
|
-
destination: destinationId,
|
|
167
|
-
destinationName: z.string().min(1),
|
|
168
|
-
month: monthEnum,
|
|
169
|
-
travelers: z.number().int().min(1).default(2),
|
|
170
|
-
}),
|
|
171
|
-
output: z.object({
|
|
172
|
-
status: z.string(),
|
|
173
|
-
destination: z.string(),
|
|
174
|
-
summary: z.string(),
|
|
175
|
-
handoffUrl: z.string(),
|
|
176
|
-
}),
|
|
177
|
-
// Inline the inputs directly so they substitute at runtime; every value is already url-safe
|
|
178
|
-
// (id slug, month enum, integer), and `src=chatgpt` is the attribution the partner measures
|
|
179
|
-
// ChatGPT-sourced conversions on.
|
|
180
|
-
fulfil: ({ input }) => ({
|
|
181
|
-
status: `Ready to continue on Acme for ${input.destinationName}.`,
|
|
182
|
-
destination: input.destination,
|
|
183
|
-
summary: `${input.destinationName} · ${input.month} · ${input.travelers} traveler(s)`,
|
|
184
|
-
handoffUrl: `https://book.acme.example/plan?dest=${input.destination}&month=${input.month}&pax=${input.travelers}&src=chatgpt`,
|
|
185
|
-
}),
|
|
186
|
-
}),
|
|
187
|
-
tool('shortlist_getaway', {
|
|
188
|
-
visibility: ['app'],
|
|
189
|
-
description: 'Record the traveler’s shortlisted destination from the discovery widget.',
|
|
190
|
-
annotations: localWrite,
|
|
191
|
-
input: z.object({
|
|
192
|
-
destination: z.string(),
|
|
193
|
-
note: z.string().default(''),
|
|
194
|
-
}),
|
|
195
|
-
output: z.object({
|
|
196
|
-
status: z.string(),
|
|
197
|
-
destination: z.string(),
|
|
198
|
-
note: z.string(),
|
|
199
|
-
}),
|
|
200
|
-
fulfil: ({ input }) => ({
|
|
201
|
-
status: `Shortlisted ${input.destination}.`,
|
|
202
|
-
destination: input.destination,
|
|
203
|
-
note: input.note,
|
|
204
|
-
}),
|
|
205
|
-
}),
|
|
206
|
-
],
|
|
234
|
+
},
|
|
235
|
+
[discoverGetaways, createHandoff, shortlistGetaway],
|
|
207
236
|
);
|
|
@@ -82,8 +82,9 @@ noodle open
|
|
|
82
82
|
|
|
83
83
|
## Optional in-product assistant
|
|
84
84
|
|
|
85
|
-
The
|
|
86
|
-
server
|
|
85
|
+
The default SaaS and widget scaffolds are credential-free. When the product deliberately includes an
|
|
86
|
+
assistant, use the existing server tools and add an `assistant` option to the same `server.ts` instead of
|
|
87
|
+
creating a second entrypoint or tool set:
|
|
87
88
|
|
|
88
89
|
```ts
|
|
89
90
|
assistant: embeddedAssistant({
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import {
|
|
2
2
|
annotations,
|
|
3
|
+
authenticatedWebsite,
|
|
3
4
|
connector,
|
|
4
5
|
customerAuth,
|
|
5
6
|
customerEndpoint,
|
|
@@ -113,11 +114,13 @@ export default server(
|
|
|
113
114
|
apiKey: secret('ASSISTANT_MODEL_API_KEY'),
|
|
114
115
|
}),
|
|
115
116
|
// Production origins are exact HTTPS; http://localhost:<port> is allowed for local development.
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
117
|
+
access: authenticatedWebsite({
|
|
118
|
+
origins: [
|
|
119
|
+
'https://app.noodleseed.com',
|
|
120
|
+
'https://dev.noodleseed.com',
|
|
121
|
+
'http://localhost:3000',
|
|
122
|
+
],
|
|
123
|
+
}),
|
|
121
124
|
layout: { mode: 'floating', position: 'bottom-right', panelWidth: 420 },
|
|
122
125
|
labels: {
|
|
123
126
|
welcomeHeading: 'How can I help with Noodle Seed?',
|
|
@@ -32,7 +32,8 @@ It exercises, in one TypeScript-authored app:
|
|
|
32
32
|
to `[]`.
|
|
33
33
|
- **A per-operation transport bound** — `search_list` sets
|
|
34
34
|
`limits: { maxResponseBytes: 256 * 1024 }`, tightening this known-small endpoint below the 1 MiB default.
|
|
35
|
-
|
|
35
|
+
The authoring ceiling is 6 MiB, but grant only the bytes representative evidence proves this operation
|
|
36
|
+
needs.
|
|
36
37
|
- **Sandboxed compute** (no network/fs/env/clock) turning raw numbers into conditions + advice.
|
|
37
38
|
- **Typed input/output schemas** emitted as JSON Schema 2020-12.
|
|
38
39
|
|
|
@@ -3,7 +3,7 @@ name: executing-noodle-plans
|
|
|
3
3
|
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."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
<!-- noodle-skill version:0.
|
|
6
|
+
<!-- noodle-skill version:0.65.0 hash:6a9f132ddb79352e -->
|
|
7
7
|
|
|
8
8
|
# Execute a Noodle Seed implementation plan
|
|
9
9
|
|
|
@@ -3,7 +3,7 @@ name: publishing-mcp-integrations
|
|
|
3
3
|
description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
<!-- noodle-skill version:0.
|
|
6
|
+
<!-- noodle-skill version:0.65.0 hash:efffbf82007f935d -->
|
|
7
7
|
|
|
8
8
|
# publishing-mcp-integrations
|
|
9
9
|
|
|
@@ -67,6 +67,9 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
|
|
|
67
67
|
| `customer_endpoint_mapping_required` | Add the endpoint key at the cited auth routing path; every direct/federated issuer must map every customer endpoint used by the app. |
|
|
68
68
|
| `customer_endpoint_unknown_mapping` | Remove the unknown or unused auth routing key, or use that exact declared `customerEndpoint` key from a reachable connector operation. |
|
|
69
69
|
| `customer_endpoint_bridge_unsupported` | Replace the Firebase/Microsoft bridge with direct or federated OIDC before using auth-derived customer connector endpoints. |
|
|
70
|
+
| `assistant_capability_unknown` | Name a tool, resource, or prompt this server declares in `embeddedAssistant({ capabilities })`, or remove the entry; capabilities reference declared components, not arbitrary names. |
|
|
71
|
+
| `assistant_public_user_reference` | Remove the `${user...}` reference from this tool or drop it from the public assistant `capabilities`; a public website visitor is anonymous, so there is no signed-in user to read. |
|
|
72
|
+
| `assistant_public_effect_unconfirmed` | Add `annotations.readOnly()` if this projected tool only reads, or `{ confirm: true }` if it causes an external effect; a public assistant never reaches an unconfirmed side effect. |
|
|
70
73
|
| `customer_endpoint_action_unsupported` | Set exact `annotations.confirm: true` on the enclosing tool, or keep the customer-routed operation read-only; action hints alone do not enable confirmation. |
|
|
71
74
|
| `customer_endpoint_surface_unsupported` | Move the customer-routed call into a tool fulfilment; routed resources, prompts, and ambient providers are unsupported. |
|
|
72
75
|
| `customer_endpoint_credential_source_unsupported` | Remove the manifest connection binding; a customer-routed connector uses its declared delegated token exchange auth or no auth. |
|
|
@@ -116,12 +116,12 @@ response: { tasks: '${response.items}' },
|
|
|
116
116
|
HTTP operations default to a 1 MiB decoded-response limit. Narrow the upstream query, paginate, or
|
|
117
117
|
reduce the requested dataset before raising it; a `response` mapping runs only after the raw body is
|
|
118
118
|
buffered. When representative evidence proves one operation legitimately needs more, grant only that
|
|
119
|
-
operation the required bytes, up to the
|
|
119
|
+
operation the required bytes, up to the 6 MiB authoring maximum:
|
|
120
120
|
|
|
121
121
|
```ts
|
|
122
122
|
search: {
|
|
123
123
|
type: 'read', method: 'GET', path: '/search',
|
|
124
|
-
limits: { maxResponseBytes:
|
|
124
|
+
limits: { maxResponseBytes: 6 * 1024 * 1024 },
|
|
125
125
|
// input / output / response omitted
|
|
126
126
|
},
|
|
127
127
|
```
|
|
@@ -39,7 +39,9 @@ Before choosing code, ask the user which experience belongs in the existing prod
|
|
|
39
39
|
|
|
40
40
|
## Author and validate
|
|
41
41
|
|
|
42
|
-
|
|
42
|
+
`noodle init` and `noodle init --template widget` deliberately produce credential-free MCP Apps. Add an assistant declaration only when the product explicitly includes a customer-hosted assistant; do not make ordinary external-host widgets depend on model-provider settings.
|
|
43
|
+
|
|
44
|
+
Use the same server tools in the embed; do not create a second tool set. Declare one server-level brand kit and an assistant configuration. `access` decides who may open a session, so choose it before anything else — `authenticatedWebsite(...)` for an in-app embed, `publicWebsite(...)` for a marketing page, or both:
|
|
43
45
|
|
|
44
46
|
```ts
|
|
45
47
|
branding: { name: "Acme", accent: "#3157D5" },
|
|
@@ -50,12 +52,55 @@ assistant: embeddedAssistant({
|
|
|
50
52
|
model: variable("ASSISTANT_MODEL"),
|
|
51
53
|
apiKey: secret("ASSISTANT_MODEL_API_KEY"),
|
|
52
54
|
}),
|
|
53
|
-
|
|
55
|
+
access: authenticatedWebsite({
|
|
56
|
+
origins: ["http://localhost:3000", "https://app.example.com"],
|
|
57
|
+
}),
|
|
54
58
|
layout: { mode: "floating", position: "bottom-right" },
|
|
55
59
|
}),
|
|
56
60
|
```
|
|
57
61
|
|
|
58
|
-
|
|
62
|
+
Origins are exact: scheme, host, and optional port, with no path, trailing slash, or wildcard. Production origins must be HTTPS; plain HTTP is accepted only for loopback development origins (`http://localhost:<port>`, `http://127.0.0.1:<port>`). `noodle dev` serves the MCP project, not the embedding SaaS.
|
|
63
|
+
|
|
64
|
+
### Surfaces: one assistant, every front door
|
|
65
|
+
|
|
66
|
+
A product usually has more than one front door — a marketing site and a signed-in app. One assistant (one brand, one model, one UI) projects onto both; pass `access` an array and each surface owns its own origins and allowlist:
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
access: [
|
|
70
|
+
publicWebsite({
|
|
71
|
+
origins: ["https://www.example.com"],
|
|
72
|
+
capabilities: [answerProductQuestion, requestDemo],
|
|
73
|
+
}),
|
|
74
|
+
authenticatedWebsite({
|
|
75
|
+
origins: ["https://app.example.com"],
|
|
76
|
+
sessionClaims: { plan: { exposeToModel: true } },
|
|
77
|
+
}),
|
|
78
|
+
],
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
At most one public surface (`public` or `mixed`) and at most one authenticated surface, and no origin may appear on two surfaces — otherwise "which projection is this request?" would be ambiguous. Each gets its own embed snippet, budget, and kill switch.
|
|
82
|
+
|
|
83
|
+
`publicWebsite` is for a page with no signed-in user. The visitor is an **anonymous principal**, not an empty user: there is no `${user}`, no roles, no scopes, no customer routing, and no delegated credentials. A tool that needs identity — because it reads `${user}` or declares an `authorization` requirement — cannot be projected to a `public` surface, and the compiler says so.
|
|
84
|
+
|
|
85
|
+
A public surface **must** declare `capabilities`: the exact positive allowlist it may reach. It is required by the type, and it is the whole externally reachable surface — a reviewer should read it in one screenful. Anything absent stays private, and a capability added to the server later is excluded until someone lists it. `authenticatedWebsite` may also take `capabilities` to narrow the in-app surface; omitted, it projects the whole server.
|
|
86
|
+
|
|
87
|
+
### Mixed surfaces: let a visitor sign in mid-conversation
|
|
88
|
+
|
|
89
|
+
Add `signIn: true` to a public surface when some capabilities need a signed-in user. The surface becomes `mixed`: anonymous visitors start immediately, and an identity-dependent capability becomes a **sign-in trigger** rather than a compile error — the same shape ChatGPT and Claude use for connectors that work with or without a linked account.
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
access: publicWebsite({
|
|
93
|
+
origins: ["https://www.example.com"],
|
|
94
|
+
capabilities: [answerProductQuestion, requestDemo, myOrders],
|
|
95
|
+
signIn: true, // `myOrders` reads ${user}; visitors sign in to reach it
|
|
96
|
+
}),
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Elevation runs through the **host application’s own login**, never a Noodle-operated one: the page signs the visitor in and its backend exchanges that verified user for an elevated session on the same conversation. Do not build a second identity provider for this.
|
|
100
|
+
|
|
101
|
+
A connector-backed side effect needs **two** independent declarations to be reachable from a public or mixed surface: inclusion in `capabilities` **and** `{ confirm: true }` on the operation. Signing in proves who the visitor is; it does not pre-authorize an effect, so confirmation still applies on a mixed surface. Confirmation is never authentication or business authorization — the customer backend still owns payload validation, abuse controls, and idempotency. Local or session-only widget state needs no confirmation.
|
|
102
|
+
|
|
103
|
+
Origin is a browser boundary, never bot authentication — scripts can reproduce an allowed `Origin` header. Do not tell a user that origins protect a public embed; the real controls are the capability allowlist, confirmation, admission limits, and the per-surface daily budget.
|
|
59
104
|
|
|
60
105
|
Run:
|
|
61
106
|
|
|
@@ -279,6 +324,25 @@ To make the *downstream API call itself* run as the signed-in user (your API enf
|
|
|
279
324
|
|
|
280
325
|
The exchange returns the versioned Embedded Assistant v1 contract. `token`, `expiresAt`, and `endpoints.turns` / legacy `endpoints.toolConfirmations` (absolute URLs) are always present; current services add `endpoints.interactions` for accept/decline/cancel. `configuration` is optional theming data. Forward the body unchanged; browser clients choose the advertised endpoint. Do not rebuild, filter, or rewrite the response.
|
|
281
326
|
|
|
327
|
+
## Mount a public website surface
|
|
328
|
+
|
|
329
|
+
A `publicWebsite` surface has no backend exchange, because it has no embed secret to protect. `noodle deploy` provisions a non-secret embed id and prints the snippet; the page presents that id directly and receives an anonymous session. Do not build a session route for a public surface — there is nothing for it to hold.
|
|
330
|
+
|
|
331
|
+
```html
|
|
332
|
+
<script src="https://cloud.noodleseed.dev/v1/assistant/embed.js"
|
|
333
|
+
data-embed-id="pub_7f2q4k9x" async></script>
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
The script derives its service origin from its own `src`, so one snippet works unchanged in every environment. In a React application, mount `<NoodleAssistant embedId="pub_7f2q4k9x" />` instead. `embedId` and `sessionEndpoint` are mutually exclusive: an embed id beside a backend endpoint is a mistake, and the client refuses rather than guessing which transport was meant.
|
|
337
|
+
|
|
338
|
+
The embed id is safe in page source and stable across deploys — paste it once; redeploy and rollback swap the projection under a page that never changes. Never treat it as a credential, and never put a client secret on a public page.
|
|
339
|
+
|
|
340
|
+
Tell the operator the two commands that matter: `noodle assistant embeds list` shows each surface with its live origins, capabilities, and today's spend against its cap; `noodle assistant budget set --turns-per-day 0` is the kill switch and stops conversations already under way. Raising the cap serves visitors again. Prefer it to revoking an embed, which destroys the pasted id.
|
|
341
|
+
|
|
342
|
+
A public surface is capped per day, so a visitor can meet an exhausted budget. The widget renders that calmly and offers no retry; do not add one. If the embedding page sets a Content-Security-Policy, it must allow the Noodle service origin in `script-src` (the embed script), `connect-src` (session and turns), and `frame-src` (widget sandbox) — a blocked `script-src` runs no widget code at all, so nothing can report it from the page.
|
|
343
|
+
|
|
344
|
+
Run `noodle check --target embedded-assistant` before deploying a public surface: it lists exactly what a stranger can reach and warns when no `privacyUrl` is declared.
|
|
345
|
+
|
|
282
346
|
## Choose a browser renderer
|
|
283
347
|
|
|
284
348
|
Use the React wrapper in React applications:
|
|
@@ -53,6 +53,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
|
|
|
53
53
|
|
|
54
54
|
### Other
|
|
55
55
|
|
|
56
|
+
- `authenticatedWebsite`
|
|
56
57
|
- `clientCredentials`
|
|
57
58
|
- `customerEndpoint`
|
|
58
59
|
- `embeddedAssistant`
|
|
@@ -60,6 +61,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
|
|
|
60
61
|
- `gmailConnector`
|
|
61
62
|
- `managedSecret`
|
|
62
63
|
- `openAICompatible`
|
|
64
|
+
- `publicWebsite`
|
|
63
65
|
|
|
64
66
|
## Authoring signatures
|
|
65
67
|
|
|
@@ -3,7 +3,7 @@ name: reporting-noodle-feedback
|
|
|
3
3
|
description: "Use when a Noodle Seed bug, misleading instruction, missing capability, or concrete product improvement should be proposed to the user."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
<!-- noodle-skill version:0.
|
|
6
|
+
<!-- noodle-skill version:0.65.0 hash:0f404109f4845683 -->
|
|
7
7
|
|
|
8
8
|
# reporting-noodle-feedback
|
|
9
9
|
|
|
@@ -3,7 +3,7 @@ name: verifying-mcp-delivery
|
|
|
3
3
|
description: "Use when proving a Noodle Seed MCP project works at a named compile, local, connector, App, host, deployment, or production evidence level."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
<!-- noodle-skill version:0.
|
|
6
|
+
<!-- noodle-skill version:0.65.0 hash:6ef6ef551e26b78e -->
|
|
7
7
|
|
|
8
8
|
# verifying-mcp-delivery
|
|
9
9
|
|
|
@@ -3,7 +3,7 @@ name: wrapping-existing-applications
|
|
|
3
3
|
description: "Use when an existing application has no stable usable API and needs a read-only, identity-first Noodle Seed integration plan before implementation."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
<!-- noodle-skill version:0.
|
|
6
|
+
<!-- noodle-skill version:0.65.0 hash:eccc3c158dcafba8 -->
|
|
7
7
|
|
|
8
8
|
# wrapping-existing-applications
|
|
9
9
|
|