@noodleseed/agent-kit 0.11.0 → 0.13.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 +9 -9
- package/package.json +1 -1
- package/skills/claude-code/SKILL.md +7 -6
- package/skills/claude-code/references/authoring-workflow.md +96 -51
- package/skills/claude-code/references/sdk-surface.md +67 -9
- package/skills/claude-code/references/troubleshooting.md +2 -1
- package/skills/codex/SKILL.md +7 -6
- package/skills/codex/references/authoring-workflow.md +96 -51
- package/skills/codex/references/sdk-surface.md +67 -9
- package/skills/codex/references/troubleshooting.md +2 -1
package/manifest.json
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
{
|
|
2
|
-
"packageVersion": "0.
|
|
2
|
+
"packageVersion": "0.13.0",
|
|
3
3
|
"files": [
|
|
4
4
|
{
|
|
5
5
|
"path": "skills/codex/SKILL.md",
|
|
6
|
-
"sha256": "
|
|
6
|
+
"sha256": "4dfd82f9f2acf59f7df30617b8f319b8cc0a743c721aeb027e454cb1af0f1c0a",
|
|
7
7
|
"agentTarget": "codex"
|
|
8
8
|
},
|
|
9
9
|
{
|
|
10
10
|
"path": "skills/codex/references/sdk-surface.md",
|
|
11
|
-
"sha256": "
|
|
11
|
+
"sha256": "410fe309a6091b469892edc55c8083b0643cae7706b3769e9b836546a6ad1235",
|
|
12
12
|
"agentTarget": "codex"
|
|
13
13
|
},
|
|
14
14
|
{
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
},
|
|
29
29
|
{
|
|
30
30
|
"path": "skills/codex/references/authoring-workflow.md",
|
|
31
|
-
"sha256": "
|
|
31
|
+
"sha256": "eca8d1f2b98ee64f6beda4d983f0f0df9023ceed8bd00ffb9dd6b5025dcaa4e4",
|
|
32
32
|
"agentTarget": "codex"
|
|
33
33
|
},
|
|
34
34
|
{
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
},
|
|
44
44
|
{
|
|
45
45
|
"path": "skills/codex/references/troubleshooting.md",
|
|
46
|
-
"sha256": "
|
|
46
|
+
"sha256": "834d2c6626dc90c009aebac3ee7ff8977a1f97dfb66cf5b955fd6414e6e2a897",
|
|
47
47
|
"agentTarget": "codex"
|
|
48
48
|
},
|
|
49
49
|
{
|
|
@@ -63,12 +63,12 @@
|
|
|
63
63
|
},
|
|
64
64
|
{
|
|
65
65
|
"path": "skills/claude-code/SKILL.md",
|
|
66
|
-
"sha256": "
|
|
66
|
+
"sha256": "6027e2822f6045e36955996c3757370cc287966493ef3bb0dd56420eeeb47f1e",
|
|
67
67
|
"agentTarget": "claude-code"
|
|
68
68
|
},
|
|
69
69
|
{
|
|
70
70
|
"path": "skills/claude-code/references/sdk-surface.md",
|
|
71
|
-
"sha256": "
|
|
71
|
+
"sha256": "410fe309a6091b469892edc55c8083b0643cae7706b3769e9b836546a6ad1235",
|
|
72
72
|
"agentTarget": "claude-code"
|
|
73
73
|
},
|
|
74
74
|
{
|
|
@@ -88,7 +88,7 @@
|
|
|
88
88
|
},
|
|
89
89
|
{
|
|
90
90
|
"path": "skills/claude-code/references/authoring-workflow.md",
|
|
91
|
-
"sha256": "
|
|
91
|
+
"sha256": "eca8d1f2b98ee64f6beda4d983f0f0df9023ceed8bd00ffb9dd6b5025dcaa4e4",
|
|
92
92
|
"agentTarget": "claude-code"
|
|
93
93
|
},
|
|
94
94
|
{
|
|
@@ -103,7 +103,7 @@
|
|
|
103
103
|
},
|
|
104
104
|
{
|
|
105
105
|
"path": "skills/claude-code/references/troubleshooting.md",
|
|
106
|
-
"sha256": "
|
|
106
|
+
"sha256": "834d2c6626dc90c009aebac3ee7ff8977a1f97dfb66cf5b955fd6414e6e2a897",
|
|
107
107
|
"agentTarget": "claude-code"
|
|
108
108
|
},
|
|
109
109
|
{
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@noodleseed/agent-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"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.",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: noodle-seed
|
|
3
3
|
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.
|
|
4
|
-
version: 0.
|
|
5
|
-
hash:
|
|
4
|
+
version: 0.13.0
|
|
5
|
+
hash: dd621716fbd94dab
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Noodle Seed
|
|
@@ -20,10 +20,11 @@ This CLI is agent-native: the cold-agent-path commands speak the `--json` envelo
|
|
|
20
20
|
3. **Validate** — `noodle validate --json`; on failure `{ok:false,error:{code,message,fix,next,errors:[{code,path,message}]}}` — the per-field detail is in `error.errors[]`.
|
|
21
21
|
4. **Repair** — fix each `error.errors[]` entry at its `path`, then re-run `noodle validate --json`; `noodle validate --fix-prompt` emits ready-to-apply repair prose. Never freeform re-edit (see `references/compile-errors.md`).
|
|
22
22
|
5. **Smoke** — `noodle test --json`: local compile plus a loopback MCP smoke.
|
|
23
|
-
6. **
|
|
24
|
-
7. **
|
|
25
|
-
8. **
|
|
26
|
-
9. **
|
|
23
|
+
6. **Prove real output** — `validate`/`test` prove a connector tool *compiles and registers*, not that its response mapping returns data. Set the secret locally (`noodle secrets set <NAME> --from-env <ENV>`), then run a live read — `noodle tools call <read_tool> --args '{...}'` executes the connector against the real API in-process — and confirm the mapped fields are populated, not `undefined`, before trusting it. Only run a live write if it is safe/approved.
|
|
24
|
+
7. **Apps/widgets** — `noodle check --json` (add `--target chatgpt|claude`), then `noodle devtools` (see `references/widgets-and-apps.md`).
|
|
25
|
+
8. **Deploy** — `noodle deploy`; auth fails clean with `error.next` = `noodle login` (see `references/deploy-and-ops.md`).
|
|
26
|
+
9. **Wire into a host** — `noodle connect <codex|claude-code|chatgpt>` (prove it in a real host per `references/test-in-hosts.md`; debug symptoms with `references/troubleshooting.md`).
|
|
27
|
+
10. **Health** — `noodle metrics --agent-output`: a health verdict plus the exact next command per attention item.
|
|
27
28
|
|
|
28
29
|
## References
|
|
29
30
|
|
|
@@ -6,8 +6,8 @@
|
|
|
6
6
|
- Fit check
|
|
7
7
|
- Repair loop
|
|
8
8
|
- Connectors
|
|
9
|
-
- HTTP connector example
|
|
10
|
-
-
|
|
9
|
+
- HTTP connector example (full server)
|
|
10
|
+
- Design tools for the model
|
|
11
11
|
- Compute connector example
|
|
12
12
|
- Tests
|
|
13
13
|
- Secrets and variables
|
|
@@ -36,83 +36,128 @@ Declare connectors as data, not imperative code:
|
|
|
36
36
|
|
|
37
37
|
Tools record connector calls into a flow; recording is not execution. Do not branch on runtime outputs with native `if` — use declarative `when(...)` conditions.
|
|
38
38
|
|
|
39
|
-
HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `
|
|
39
|
+
HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, and `delegatedSessionCookie`. Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
|
|
40
40
|
|
|
41
|
-
## HTTP connector example
|
|
41
|
+
## HTTP connector example (full server)
|
|
42
42
|
|
|
43
|
-
The operation mapping in detail: `request`
|
|
43
|
+
Declare the API as data, bind it with `use`, then record calls in tools. The operation mapping in detail: `request` builds the JSON request body, `query: [...]` names the input args sent as URL query parameters, and `response` maps the parsed HTTP body (bound to `${response}`) into your typed `output`. `auth` reads a managed `secret(...)` — never inline a key. This whole example is compile-verified on every `pnpm test`.
|
|
44
44
|
|
|
45
45
|
```ts
|
|
46
|
-
import { connector, secret, variable } from '@noodleseed/one';
|
|
46
|
+
import { connector, secret, variable, server, tool, z } from '@noodleseed/one';
|
|
47
47
|
|
|
48
48
|
const crm = connector('crm').version('1.0.0').http({
|
|
49
49
|
baseUrl: variable('CRM_BASE_URL'),
|
|
50
|
-
allowedOrigins: [
|
|
50
|
+
allowedOrigins: ['https://api.crm.example'],
|
|
51
51
|
auth: { kind: 'bearer', secret: secret('CRM_TOKEN') },
|
|
52
52
|
operations: {
|
|
53
|
-
|
|
53
|
+
find_customer: {
|
|
54
54
|
type: 'read',
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
response: { id:
|
|
55
|
+
method: 'GET',
|
|
56
|
+
path: '/customers',
|
|
57
|
+
query: ['email'],
|
|
58
|
+
input: { email: { type: 'string', required: true } },
|
|
59
|
+
output: { id: { type: 'string', required: true }, name: { type: 'string' } },
|
|
60
|
+
response: { id: '${response.data[0].id}', name: '${response.data[0].name}' },
|
|
61
61
|
},
|
|
62
|
-
|
|
62
|
+
create_ticket: {
|
|
63
63
|
type: 'action',
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
request: {
|
|
69
|
-
response: {
|
|
64
|
+
method: 'POST',
|
|
65
|
+
path: '/tickets',
|
|
66
|
+
input: { customer_id: { type: 'string', required: true }, body: { type: 'string', required: true } },
|
|
67
|
+
output: { ticket_id: { type: 'string', required: true } },
|
|
68
|
+
request: { customer_id: '${args.customer_id}', body: '${args.body}' },
|
|
69
|
+
response: { ticket_id: '${response.id}' },
|
|
70
70
|
},
|
|
71
71
|
},
|
|
72
72
|
});
|
|
73
|
+
|
|
74
|
+
export default server('support', { title: 'Support', version: '1.0.0', use: { crm } }, [
|
|
75
|
+
tool('find_customer', {
|
|
76
|
+
description: 'Find a customer by email address.',
|
|
77
|
+
input: z.object({ email: z.string() }),
|
|
78
|
+
output: z.object({ id: z.string(), name: z.string().optional() }),
|
|
79
|
+
fulfil: ({ input, connectors }) => {
|
|
80
|
+
const customer = connectors.crm.find_customer({ email: input.email });
|
|
81
|
+
return { id: customer.id, name: customer.name };
|
|
82
|
+
},
|
|
83
|
+
}),
|
|
84
|
+
tool('open_ticket', {
|
|
85
|
+
description: 'Open a support ticket for a customer.',
|
|
86
|
+
input: z.object({ customer_id: z.string(), body: z.string() }),
|
|
87
|
+
output: z.object({ ticket_id: z.string() }),
|
|
88
|
+
fulfil: ({ input, connectors }) => {
|
|
89
|
+
const ticket = connectors.crm.create_ticket({ customer_id: input.customer_id, body: input.body });
|
|
90
|
+
return { ticket_id: ticket.ticket_id };
|
|
91
|
+
},
|
|
92
|
+
}),
|
|
93
|
+
]);
|
|
73
94
|
```
|
|
74
95
|
|
|
75
|
-
|
|
96
|
+
Naming: connector operation names and tool names are lowercase-with-underscores. Map with `${args.field}` for tool/operation inputs and `${response.path}` for the response — the parsed JSON body is bound directly to `${response}`, so there is **no `.body` envelope**; use bracket syntax for array indices (`${response.data[0].id}`) — a dotted numeric index like `.0.` is invalid. Declare URL query parameters with the operation-level `query: ["arg"]` array, **not** inside `request` (which builds only the JSON body). `allowedOrigins` must be literal origin URLs (the SSRF allowlist); `baseUrl` may be a `variable(...)` that differs by env.
|
|
97
|
+
|
|
98
|
+
More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. For client credentials use `{ kind: "clientCredentials", tokenUrl, clientId, clientSecret, scopes? }` (RFC-6749 grant); for a non-standard partner token endpoint add `profile: "custom"` with a `custom: { requestFormat, clientIdField, clientSecretField, tokenResponsePath, expirySource }` descriptor. Do not put credential headers in operation `headers`; use connector `auth`. For per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
|
|
99
|
+
|
|
100
|
+
## Design tools for the model
|
|
101
|
+
|
|
102
|
+
Design tools around what a user says, not 1:1 around API endpoints. A raw wrapper per endpoint (`get_task`, `list_tasks`, `close_task`) forces the model to orchestrate low-level calls and to know identifiers the user never sees — an MCP connector, but not a usable product. Instead:
|
|
76
103
|
|
|
77
|
-
|
|
104
|
+
- **Shape by intent.** Name and scope tools for the job to be done — "find my overdue tasks", "complete the task matching this text" — combining multiple backing calls in one recorded flow (`when(...)`) where it helps.
|
|
105
|
+
- **Prefer names/text over raw IDs.** When an action needs an id the user does not know, pair the id-taking operation with a find/search operation that returns model-friendly summaries (id + a human label), so the model resolves text → id itself. Write descriptions that tell the model when to use each tool and how they chain.
|
|
106
|
+
- **Return only what the model needs.** Map the response to a small, typed `output` (a few labelled fields), not the raw API payload.
|
|
78
107
|
|
|
79
|
-
|
|
108
|
+
This example pairs a name resolver with an id-taking action: the model calls `find_tasks` to turn the user’s words into an id, then `complete_task`. It is compile-verified on every `pnpm test`.
|
|
80
109
|
|
|
81
110
|
```ts
|
|
82
111
|
import { connector, secret, server, tool, z } from '@noodleseed/one';
|
|
83
112
|
|
|
84
|
-
const
|
|
85
|
-
|
|
86
|
-
.
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
response: { subject: '${response.data.subject}', status: '${response.data.state}' },
|
|
98
|
-
},
|
|
113
|
+
const tasks = connector('tasks').version('1.0.0').http({
|
|
114
|
+
baseUrl: 'https://api.tasks.example',
|
|
115
|
+
allowedOrigins: ['https://api.tasks.example'],
|
|
116
|
+
auth: { kind: 'bearer', secret: secret('TASKS_TOKEN') },
|
|
117
|
+
operations: {
|
|
118
|
+
search_tasks: {
|
|
119
|
+
type: 'read',
|
|
120
|
+
method: 'GET',
|
|
121
|
+
path: '/tasks',
|
|
122
|
+
query: ['query'],
|
|
123
|
+
input: { query: { type: 'string', required: true } },
|
|
124
|
+
output: { matches: { type: 'array', required: true } },
|
|
125
|
+
response: { matches: '${response.results}' },
|
|
99
126
|
},
|
|
100
|
-
|
|
127
|
+
close_task: {
|
|
128
|
+
type: 'action',
|
|
129
|
+
method: 'POST',
|
|
130
|
+
path: '/tasks/{id}/close',
|
|
131
|
+
input: { id: { type: 'string', required: true } },
|
|
132
|
+
output: { ok: { type: 'boolean', required: true } },
|
|
133
|
+
response: { ok: '${response.ok}' },
|
|
134
|
+
},
|
|
135
|
+
},
|
|
136
|
+
});
|
|
101
137
|
|
|
102
|
-
export default server('
|
|
103
|
-
tool('
|
|
104
|
-
description: '
|
|
105
|
-
input: z.object({
|
|
106
|
-
output: z.object({
|
|
138
|
+
export default server('todo', { title: 'Tasks', version: '1.0.0', use: { tasks } }, [
|
|
139
|
+
tool('find_tasks', {
|
|
140
|
+
description: 'Find tasks whose text matches a query — call this first to resolve a task the user names by text into its id, then pass that id to complete_task.',
|
|
141
|
+
input: z.object({ query: z.string() }),
|
|
142
|
+
output: z.object({ matches: z.array(z.object({ id: z.string(), title: z.string() })) }),
|
|
143
|
+
fulfil: ({ input, connectors }) => {
|
|
144
|
+
const found = connectors.tasks.search_tasks({ query: input.query });
|
|
145
|
+
return { matches: found.matches };
|
|
146
|
+
},
|
|
147
|
+
}),
|
|
148
|
+
tool('complete_task', {
|
|
149
|
+
description: 'Mark a task complete by its id (get the id from find_tasks).',
|
|
150
|
+
input: z.object({ id: z.string() }),
|
|
151
|
+
output: z.object({ ok: z.boolean() }),
|
|
107
152
|
fulfil: ({ input, connectors }) => {
|
|
108
|
-
const
|
|
109
|
-
return {
|
|
153
|
+
const result = connectors.tasks.close_task({ id: input.id });
|
|
154
|
+
return { ok: result.ok };
|
|
110
155
|
},
|
|
111
156
|
}),
|
|
112
157
|
]);
|
|
113
158
|
```
|
|
114
159
|
|
|
115
|
-
|
|
160
|
+
The model never sees a task id from the user; `find_tasks` returns `{ id, title }` summaries it can pick from, then `complete_task` acts by id. Keep write actions (`complete_task`) separate and explicitly described so the host can gate them.
|
|
116
161
|
|
|
117
162
|
## Compute connector example
|
|
118
163
|
|
|
@@ -120,16 +165,16 @@ More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `oauth2ClientCredent
|
|
|
120
165
|
const scoring = connector('scoring').version('1.0.0').compute('normalize', {
|
|
121
166
|
input: { email: { type: "string", required: true }, priority: { type: "string" } },
|
|
122
167
|
output: { score: { type: "number", required: true } },
|
|
123
|
-
calls: {
|
|
168
|
+
calls: { find_customer: 'crm.find_customer' },
|
|
124
169
|
limits: { timeoutMs: 1000, maxHostCalls: 2 },
|
|
125
170
|
run(input, { callOperation }) {
|
|
126
|
-
const customer = callOperation("
|
|
171
|
+
const customer = callOperation("find_customer", { email: input.email }) as { id?: string };
|
|
127
172
|
return { score: customer.id && input.priority === "high" ? 100 : 50 };
|
|
128
173
|
},
|
|
129
174
|
});
|
|
130
175
|
```
|
|
131
176
|
|
|
132
|
-
Compute `run` functions are serialized and sandboxed: no imports, no closure capture, no `fetch`, no `process`. Any backing-system call must be declared in `calls` and invoked through `callOperation`. For conditional flow edges, use `when(...)` in recorded fulfilment instead of native branching on connector outputs.
|
|
177
|
+
Compute `run` functions are serialized and sandboxed: no imports, no closure capture, no `fetch`, no `process`. Any backing-system call must be declared in acyclic `calls` and invoked through `callOperation`. For conditional flow edges, use `when(...)` in recorded fulfilment instead of native branching on connector outputs.
|
|
133
178
|
|
|
134
179
|
## Tests
|
|
135
180
|
|
|
@@ -68,7 +68,7 @@ Minimal, complete, compiling recipes — author in `src/server.ts`, then `noodle
|
|
|
68
68
|
|
|
69
69
|
### Resource
|
|
70
70
|
|
|
71
|
-
`resource(name, { uri, title?, description?, mimeType?, fulfil })`. `fulfil` returns
|
|
71
|
+
`resource(name, { uri, title?, description?, mimeType?, fulfil })`. `fulfil` returns the resource body itself — a plain string, or a bare content entry `{ uri, mimeType, text }` — and the runtime maps it into MCP `contents` for you. Do **not** return a `{ contents: [...] }` wrapper: the runtime already wraps it, so that double-wraps (the whole JSON ends up inside `contents[0].text`). Use a fixed URI for a constant document, or a `{var}` template whose variable arrives on `ctx.input`.
|
|
72
72
|
|
|
73
73
|
```ts
|
|
74
74
|
import { resource } from '@noodleseed/one';
|
|
@@ -78,11 +78,8 @@ resource('changelog', {
|
|
|
78
78
|
uri: 'docs://changelog',
|
|
79
79
|
title: 'Changelog',
|
|
80
80
|
mimeType: 'text/markdown',
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
{ uri: 'docs://changelog', mimeType: 'text/markdown', text: 'Changelog: 1.0.0 first release' },
|
|
84
|
-
],
|
|
85
|
-
}),
|
|
81
|
+
// Return the bare content entry (or just a string); never a { contents: [...] } wrapper.
|
|
82
|
+
fulfil: () => ({ uri: 'docs://changelog', mimeType: 'text/markdown', text: 'Changelog: 1.0.0 first release' }),
|
|
86
83
|
});
|
|
87
84
|
|
|
88
85
|
// {var} URI-template resource: the URI variable arrives on ctx.input (a symbolic ref).
|
|
@@ -91,9 +88,9 @@ resource('ticket', {
|
|
|
91
88
|
title: 'Support ticket',
|
|
92
89
|
mimeType: 'text/markdown',
|
|
93
90
|
fulfil: (ctx) => ({
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
91
|
+
uri: `tickets://${ctx.input.id}`,
|
|
92
|
+
mimeType: 'text/markdown',
|
|
93
|
+
text: `Ticket ${ctx.input.id}`,
|
|
97
94
|
}),
|
|
98
95
|
});
|
|
99
96
|
```
|
|
@@ -177,4 +174,65 @@ export default server('support', { title: 'Support', version: '1.0.0', use: { cr
|
|
|
177
174
|
fulfil: async ({ input }) => ({ echo: input.text }),
|
|
178
175
|
}),
|
|
179
176
|
]);
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### Conditional flow with when()
|
|
180
|
+
|
|
181
|
+
`when(condition, () => record)` records the inner step(s) guarded by a condition instead of a native `if`. `when` is a **free function** (import it), the condition is `ref.equals(scalar)` (equality only — no `<`/`>`/`&&`), and the recorded step is skipped at runtime unless the condition holds. Never write a native `if` on a symbolic ref, and never call a method on one (e.g. `input.name.trim()`) — both silently mis-record or throw; compose strings with a template literal and branch with `when(...)`.
|
|
182
|
+
|
|
183
|
+
```ts
|
|
184
|
+
import { connector, server, tool, when, z } from '@noodleseed/one';
|
|
185
|
+
|
|
186
|
+
// Two read operations; the tracking lookup only runs when the order came back shipped.
|
|
187
|
+
const orders = connector('orders')
|
|
188
|
+
.version('1.0.0')
|
|
189
|
+
.http({
|
|
190
|
+
baseUrl: 'https://orders.example.com',
|
|
191
|
+
allowedOrigins: ['https://orders.example.com'],
|
|
192
|
+
operations: {
|
|
193
|
+
get_order: {
|
|
194
|
+
type: 'read',
|
|
195
|
+
method: 'GET',
|
|
196
|
+
path: '/orders',
|
|
197
|
+
query: ['id'],
|
|
198
|
+
input: { id: { type: 'string', required: true } },
|
|
199
|
+
output: { id: { type: 'string' }, status: { type: 'string' } },
|
|
200
|
+
response: { id: '${response.id}', status: '${response.status}' },
|
|
201
|
+
},
|
|
202
|
+
get_tracking: {
|
|
203
|
+
type: 'read',
|
|
204
|
+
method: 'GET',
|
|
205
|
+
path: '/tracking',
|
|
206
|
+
query: ['order_id'],
|
|
207
|
+
input: { order_id: { type: 'string', required: true } },
|
|
208
|
+
output: { url: { type: 'string' } },
|
|
209
|
+
response: { url: '${response.url}' },
|
|
210
|
+
},
|
|
211
|
+
},
|
|
212
|
+
});
|
|
213
|
+
|
|
214
|
+
export default server('orders_app', { title: 'Orders', version: '1.0.0', use: { orders } }, [
|
|
215
|
+
tool('track_order', {
|
|
216
|
+
description: 'Find shipment tracking for an order.',
|
|
217
|
+
input: z.object({ orderId: z.string() }),
|
|
218
|
+
output: z.object({
|
|
219
|
+
orderId: z.string(),
|
|
220
|
+
status: z.string(),
|
|
221
|
+
trackingUrl: z.string().optional(),
|
|
222
|
+
}),
|
|
223
|
+
fulfil: ({ input, connectors }) => {
|
|
224
|
+
const order = connectors.orders.get_order({ id: input.orderId });
|
|
225
|
+
// Record the tracking step only when order.status === "shipped" (equality-only condition).
|
|
226
|
+
const tracking = when(order.status.equals('shipped'), () =>
|
|
227
|
+
connectors.orders.get_tracking({ order_id: order.id }),
|
|
228
|
+
);
|
|
229
|
+
return {
|
|
230
|
+
orderId: order.id,
|
|
231
|
+
status: order.status,
|
|
232
|
+
// `.optional()` marks a ref that may be absent when its guarding step did not run.
|
|
233
|
+
trackingUrl: tracking.url.optional(),
|
|
234
|
+
};
|
|
235
|
+
},
|
|
236
|
+
}),
|
|
237
|
+
]);
|
|
180
238
|
```
|
|
@@ -25,5 +25,6 @@ For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `n
|
|
|
25
25
|
| `noodle validate` passes but React views fail to bundle (“requires Vite”) | Project dependencies are not installed — widget bundling uses the app-local Vite | Run the project’s package install, then retry `noodle dev` / `noodle deploy` |
|
|
26
26
|
| Hosted endpoint returns 401 to probes | Expected: hosted servers challenge unauthenticated calls with OAuth metadata | Sign in from the host when prompted; widen who may call with `noodle access set` if testers are outside the org |
|
|
27
27
|
| Tools error only after deploy | Runtime/config differences surface hosted (secrets, connector reachability) | Run `noodle smoke`, then `noodle metrics --agent-output` and `noodle events --tool <name> --status tool_error --json`; check `noodle secrets list` scope |
|
|
28
|
-
|
|
|
28
|
+
| A connector tool validates and lists, but returns empty or `undefined` fields | The `response` mapping references a path the API does not return — usually the wrong root (a `.body` segment, when the parsed body is bound directly to `${response}`) or the wrong shape | Run `noodle tools call <name> --args <json>` with the secret set and compare the mapped result to the API’s real JSON; map from `${response.<path>}` (the body is `${response}`, there is no `.body`) and use bracket array indices (`${response.items[0].id}`) |
|
|
29
|
+
| Need to invoke a tool from the terminal | Local tools run in-process; the `noodle` CLI is not a general MCP client for **deployed** URLs (there is no `call <url>` verb) | Locally, `noodle tools call <name> --args <json>` (also `noodle resources read` / `noodle prompts get`) runs the tool against the in-process runtime — with the secret set it executes the connector against the real API, so use it to prove mapped output. For a **deployed** URL use MCP Inspector or `npx @mcpjam/cli@latest tools call --url <url> ...` |
|
|
29
30
|
| One customer/session reports a bad answer or protocol error | The failure may be a model/tool error, host protocol error, or connector/runtime error | Run `noodle metrics --agent-output`, then `noodle events --tool <name> --status tool_error --json`; copy the `sessionId` into `noodle events --session <id> --json`, then match timestamps with `noodle logs` |
|
package/skills/codex/SKILL.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: noodle-seed
|
|
3
3
|
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.
|
|
4
|
-
version: 0.
|
|
5
|
-
hash:
|
|
4
|
+
version: 0.13.0
|
|
5
|
+
hash: 68c2cc25462f5be7
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Noodle Seed
|
|
@@ -20,10 +20,11 @@ This CLI is agent-native: the cold-agent-path commands speak the `--json` envelo
|
|
|
20
20
|
3. **Validate** — `noodle validate --json`; on failure `{ok:false,error:{code,message,fix,next,errors:[{code,path,message}]}}` — the per-field detail is in `error.errors[]`.
|
|
21
21
|
4. **Repair** — fix each `error.errors[]` entry at its `path`, then re-run `noodle validate --json`; `noodle validate --fix-prompt` emits ready-to-apply repair prose. Never freeform re-edit (see `references/compile-errors.md`).
|
|
22
22
|
5. **Smoke** — `noodle test --json`: local compile plus a loopback MCP smoke.
|
|
23
|
-
6. **
|
|
24
|
-
7. **
|
|
25
|
-
8. **
|
|
26
|
-
9. **
|
|
23
|
+
6. **Prove real output** — `validate`/`test` prove a connector tool *compiles and registers*, not that its response mapping returns data. Set the secret locally (`noodle secrets set <NAME> --from-env <ENV>`), then run a live read — `noodle tools call <read_tool> --args '{...}'` executes the connector against the real API in-process — and confirm the mapped fields are populated, not `undefined`, before trusting it. Only run a live write if it is safe/approved.
|
|
24
|
+
7. **Apps/widgets** — `noodle check --json` (add `--target chatgpt|claude`), then `noodle devtools` (see `references/widgets-and-apps.md`).
|
|
25
|
+
8. **Deploy** — `noodle deploy`; auth fails clean with `error.next` = `noodle login` (see `references/deploy-and-ops.md`).
|
|
26
|
+
9. **Wire into a host** — `noodle connect <codex|claude-code|chatgpt>` (prove it in a real host per `references/test-in-hosts.md`; debug symptoms with `references/troubleshooting.md`).
|
|
27
|
+
10. **Health** — `noodle metrics --agent-output`: a health verdict plus the exact next command per attention item.
|
|
27
28
|
|
|
28
29
|
## References
|
|
29
30
|
|
|
@@ -6,8 +6,8 @@
|
|
|
6
6
|
- Fit check
|
|
7
7
|
- Repair loop
|
|
8
8
|
- Connectors
|
|
9
|
-
- HTTP connector example
|
|
10
|
-
-
|
|
9
|
+
- HTTP connector example (full server)
|
|
10
|
+
- Design tools for the model
|
|
11
11
|
- Compute connector example
|
|
12
12
|
- Tests
|
|
13
13
|
- Secrets and variables
|
|
@@ -36,83 +36,128 @@ Declare connectors as data, not imperative code:
|
|
|
36
36
|
|
|
37
37
|
Tools record connector calls into a flow; recording is not execution. Do not branch on runtime outputs with native `if` — use declarative `when(...)` conditions.
|
|
38
38
|
|
|
39
|
-
HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `
|
|
39
|
+
HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, and `delegatedSessionCookie`. Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
|
|
40
40
|
|
|
41
|
-
## HTTP connector example
|
|
41
|
+
## HTTP connector example (full server)
|
|
42
42
|
|
|
43
|
-
The operation mapping in detail: `request`
|
|
43
|
+
Declare the API as data, bind it with `use`, then record calls in tools. The operation mapping in detail: `request` builds the JSON request body, `query: [...]` names the input args sent as URL query parameters, and `response` maps the parsed HTTP body (bound to `${response}`) into your typed `output`. `auth` reads a managed `secret(...)` — never inline a key. This whole example is compile-verified on every `pnpm test`.
|
|
44
44
|
|
|
45
45
|
```ts
|
|
46
|
-
import { connector, secret, variable } from '@noodleseed/one';
|
|
46
|
+
import { connector, secret, variable, server, tool, z } from '@noodleseed/one';
|
|
47
47
|
|
|
48
48
|
const crm = connector('crm').version('1.0.0').http({
|
|
49
49
|
baseUrl: variable('CRM_BASE_URL'),
|
|
50
|
-
allowedOrigins: [
|
|
50
|
+
allowedOrigins: ['https://api.crm.example'],
|
|
51
51
|
auth: { kind: 'bearer', secret: secret('CRM_TOKEN') },
|
|
52
52
|
operations: {
|
|
53
|
-
|
|
53
|
+
find_customer: {
|
|
54
54
|
type: 'read',
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
response: { id:
|
|
55
|
+
method: 'GET',
|
|
56
|
+
path: '/customers',
|
|
57
|
+
query: ['email'],
|
|
58
|
+
input: { email: { type: 'string', required: true } },
|
|
59
|
+
output: { id: { type: 'string', required: true }, name: { type: 'string' } },
|
|
60
|
+
response: { id: '${response.data[0].id}', name: '${response.data[0].name}' },
|
|
61
61
|
},
|
|
62
|
-
|
|
62
|
+
create_ticket: {
|
|
63
63
|
type: 'action',
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
request: {
|
|
69
|
-
response: {
|
|
64
|
+
method: 'POST',
|
|
65
|
+
path: '/tickets',
|
|
66
|
+
input: { customer_id: { type: 'string', required: true }, body: { type: 'string', required: true } },
|
|
67
|
+
output: { ticket_id: { type: 'string', required: true } },
|
|
68
|
+
request: { customer_id: '${args.customer_id}', body: '${args.body}' },
|
|
69
|
+
response: { ticket_id: '${response.id}' },
|
|
70
70
|
},
|
|
71
71
|
},
|
|
72
72
|
});
|
|
73
|
+
|
|
74
|
+
export default server('support', { title: 'Support', version: '1.0.0', use: { crm } }, [
|
|
75
|
+
tool('find_customer', {
|
|
76
|
+
description: 'Find a customer by email address.',
|
|
77
|
+
input: z.object({ email: z.string() }),
|
|
78
|
+
output: z.object({ id: z.string(), name: z.string().optional() }),
|
|
79
|
+
fulfil: ({ input, connectors }) => {
|
|
80
|
+
const customer = connectors.crm.find_customer({ email: input.email });
|
|
81
|
+
return { id: customer.id, name: customer.name };
|
|
82
|
+
},
|
|
83
|
+
}),
|
|
84
|
+
tool('open_ticket', {
|
|
85
|
+
description: 'Open a support ticket for a customer.',
|
|
86
|
+
input: z.object({ customer_id: z.string(), body: z.string() }),
|
|
87
|
+
output: z.object({ ticket_id: z.string() }),
|
|
88
|
+
fulfil: ({ input, connectors }) => {
|
|
89
|
+
const ticket = connectors.crm.create_ticket({ customer_id: input.customer_id, body: input.body });
|
|
90
|
+
return { ticket_id: ticket.ticket_id };
|
|
91
|
+
},
|
|
92
|
+
}),
|
|
93
|
+
]);
|
|
73
94
|
```
|
|
74
95
|
|
|
75
|
-
|
|
96
|
+
Naming: connector operation names and tool names are lowercase-with-underscores. Map with `${args.field}` for tool/operation inputs and `${response.path}` for the response — the parsed JSON body is bound directly to `${response}`, so there is **no `.body` envelope**; use bracket syntax for array indices (`${response.data[0].id}`) — a dotted numeric index like `.0.` is invalid. Declare URL query parameters with the operation-level `query: ["arg"]` array, **not** inside `request` (which builds only the JSON body). `allowedOrigins` must be literal origin URLs (the SSRF allowlist); `baseUrl` may be a `variable(...)` that differs by env.
|
|
97
|
+
|
|
98
|
+
More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. For client credentials use `{ kind: "clientCredentials", tokenUrl, clientId, clientSecret, scopes? }` (RFC-6749 grant); for a non-standard partner token endpoint add `profile: "custom"` with a `custom: { requestFormat, clientIdField, clientSecretField, tokenResponsePath, expirySource }` descriptor. Do not put credential headers in operation `headers`; use connector `auth`. For per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
|
|
99
|
+
|
|
100
|
+
## Design tools for the model
|
|
101
|
+
|
|
102
|
+
Design tools around what a user says, not 1:1 around API endpoints. A raw wrapper per endpoint (`get_task`, `list_tasks`, `close_task`) forces the model to orchestrate low-level calls and to know identifiers the user never sees — an MCP connector, but not a usable product. Instead:
|
|
76
103
|
|
|
77
|
-
|
|
104
|
+
- **Shape by intent.** Name and scope tools for the job to be done — "find my overdue tasks", "complete the task matching this text" — combining multiple backing calls in one recorded flow (`when(...)`) where it helps.
|
|
105
|
+
- **Prefer names/text over raw IDs.** When an action needs an id the user does not know, pair the id-taking operation with a find/search operation that returns model-friendly summaries (id + a human label), so the model resolves text → id itself. Write descriptions that tell the model when to use each tool and how they chain.
|
|
106
|
+
- **Return only what the model needs.** Map the response to a small, typed `output` (a few labelled fields), not the raw API payload.
|
|
78
107
|
|
|
79
|
-
|
|
108
|
+
This example pairs a name resolver with an id-taking action: the model calls `find_tasks` to turn the user’s words into an id, then `complete_task`. It is compile-verified on every `pnpm test`.
|
|
80
109
|
|
|
81
110
|
```ts
|
|
82
111
|
import { connector, secret, server, tool, z } from '@noodleseed/one';
|
|
83
112
|
|
|
84
|
-
const
|
|
85
|
-
|
|
86
|
-
.
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
response: { subject: '${response.data.subject}', status: '${response.data.state}' },
|
|
98
|
-
},
|
|
113
|
+
const tasks = connector('tasks').version('1.0.0').http({
|
|
114
|
+
baseUrl: 'https://api.tasks.example',
|
|
115
|
+
allowedOrigins: ['https://api.tasks.example'],
|
|
116
|
+
auth: { kind: 'bearer', secret: secret('TASKS_TOKEN') },
|
|
117
|
+
operations: {
|
|
118
|
+
search_tasks: {
|
|
119
|
+
type: 'read',
|
|
120
|
+
method: 'GET',
|
|
121
|
+
path: '/tasks',
|
|
122
|
+
query: ['query'],
|
|
123
|
+
input: { query: { type: 'string', required: true } },
|
|
124
|
+
output: { matches: { type: 'array', required: true } },
|
|
125
|
+
response: { matches: '${response.results}' },
|
|
99
126
|
},
|
|
100
|
-
|
|
127
|
+
close_task: {
|
|
128
|
+
type: 'action',
|
|
129
|
+
method: 'POST',
|
|
130
|
+
path: '/tasks/{id}/close',
|
|
131
|
+
input: { id: { type: 'string', required: true } },
|
|
132
|
+
output: { ok: { type: 'boolean', required: true } },
|
|
133
|
+
response: { ok: '${response.ok}' },
|
|
134
|
+
},
|
|
135
|
+
},
|
|
136
|
+
});
|
|
101
137
|
|
|
102
|
-
export default server('
|
|
103
|
-
tool('
|
|
104
|
-
description: '
|
|
105
|
-
input: z.object({
|
|
106
|
-
output: z.object({
|
|
138
|
+
export default server('todo', { title: 'Tasks', version: '1.0.0', use: { tasks } }, [
|
|
139
|
+
tool('find_tasks', {
|
|
140
|
+
description: 'Find tasks whose text matches a query — call this first to resolve a task the user names by text into its id, then pass that id to complete_task.',
|
|
141
|
+
input: z.object({ query: z.string() }),
|
|
142
|
+
output: z.object({ matches: z.array(z.object({ id: z.string(), title: z.string() })) }),
|
|
143
|
+
fulfil: ({ input, connectors }) => {
|
|
144
|
+
const found = connectors.tasks.search_tasks({ query: input.query });
|
|
145
|
+
return { matches: found.matches };
|
|
146
|
+
},
|
|
147
|
+
}),
|
|
148
|
+
tool('complete_task', {
|
|
149
|
+
description: 'Mark a task complete by its id (get the id from find_tasks).',
|
|
150
|
+
input: z.object({ id: z.string() }),
|
|
151
|
+
output: z.object({ ok: z.boolean() }),
|
|
107
152
|
fulfil: ({ input, connectors }) => {
|
|
108
|
-
const
|
|
109
|
-
return {
|
|
153
|
+
const result = connectors.tasks.close_task({ id: input.id });
|
|
154
|
+
return { ok: result.ok };
|
|
110
155
|
},
|
|
111
156
|
}),
|
|
112
157
|
]);
|
|
113
158
|
```
|
|
114
159
|
|
|
115
|
-
|
|
160
|
+
The model never sees a task id from the user; `find_tasks` returns `{ id, title }` summaries it can pick from, then `complete_task` acts by id. Keep write actions (`complete_task`) separate and explicitly described so the host can gate them.
|
|
116
161
|
|
|
117
162
|
## Compute connector example
|
|
118
163
|
|
|
@@ -120,16 +165,16 @@ More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `oauth2ClientCredent
|
|
|
120
165
|
const scoring = connector('scoring').version('1.0.0').compute('normalize', {
|
|
121
166
|
input: { email: { type: "string", required: true }, priority: { type: "string" } },
|
|
122
167
|
output: { score: { type: "number", required: true } },
|
|
123
|
-
calls: {
|
|
168
|
+
calls: { find_customer: 'crm.find_customer' },
|
|
124
169
|
limits: { timeoutMs: 1000, maxHostCalls: 2 },
|
|
125
170
|
run(input, { callOperation }) {
|
|
126
|
-
const customer = callOperation("
|
|
171
|
+
const customer = callOperation("find_customer", { email: input.email }) as { id?: string };
|
|
127
172
|
return { score: customer.id && input.priority === "high" ? 100 : 50 };
|
|
128
173
|
},
|
|
129
174
|
});
|
|
130
175
|
```
|
|
131
176
|
|
|
132
|
-
Compute `run` functions are serialized and sandboxed: no imports, no closure capture, no `fetch`, no `process`. Any backing-system call must be declared in `calls` and invoked through `callOperation`. For conditional flow edges, use `when(...)` in recorded fulfilment instead of native branching on connector outputs.
|
|
177
|
+
Compute `run` functions are serialized and sandboxed: no imports, no closure capture, no `fetch`, no `process`. Any backing-system call must be declared in acyclic `calls` and invoked through `callOperation`. For conditional flow edges, use `when(...)` in recorded fulfilment instead of native branching on connector outputs.
|
|
133
178
|
|
|
134
179
|
## Tests
|
|
135
180
|
|
|
@@ -68,7 +68,7 @@ Minimal, complete, compiling recipes — author in `src/server.ts`, then `noodle
|
|
|
68
68
|
|
|
69
69
|
### Resource
|
|
70
70
|
|
|
71
|
-
`resource(name, { uri, title?, description?, mimeType?, fulfil })`. `fulfil` returns
|
|
71
|
+
`resource(name, { uri, title?, description?, mimeType?, fulfil })`. `fulfil` returns the resource body itself — a plain string, or a bare content entry `{ uri, mimeType, text }` — and the runtime maps it into MCP `contents` for you. Do **not** return a `{ contents: [...] }` wrapper: the runtime already wraps it, so that double-wraps (the whole JSON ends up inside `contents[0].text`). Use a fixed URI for a constant document, or a `{var}` template whose variable arrives on `ctx.input`.
|
|
72
72
|
|
|
73
73
|
```ts
|
|
74
74
|
import { resource } from '@noodleseed/one';
|
|
@@ -78,11 +78,8 @@ resource('changelog', {
|
|
|
78
78
|
uri: 'docs://changelog',
|
|
79
79
|
title: 'Changelog',
|
|
80
80
|
mimeType: 'text/markdown',
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
{ uri: 'docs://changelog', mimeType: 'text/markdown', text: 'Changelog: 1.0.0 first release' },
|
|
84
|
-
],
|
|
85
|
-
}),
|
|
81
|
+
// Return the bare content entry (or just a string); never a { contents: [...] } wrapper.
|
|
82
|
+
fulfil: () => ({ uri: 'docs://changelog', mimeType: 'text/markdown', text: 'Changelog: 1.0.0 first release' }),
|
|
86
83
|
});
|
|
87
84
|
|
|
88
85
|
// {var} URI-template resource: the URI variable arrives on ctx.input (a symbolic ref).
|
|
@@ -91,9 +88,9 @@ resource('ticket', {
|
|
|
91
88
|
title: 'Support ticket',
|
|
92
89
|
mimeType: 'text/markdown',
|
|
93
90
|
fulfil: (ctx) => ({
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
91
|
+
uri: `tickets://${ctx.input.id}`,
|
|
92
|
+
mimeType: 'text/markdown',
|
|
93
|
+
text: `Ticket ${ctx.input.id}`,
|
|
97
94
|
}),
|
|
98
95
|
});
|
|
99
96
|
```
|
|
@@ -177,4 +174,65 @@ export default server('support', { title: 'Support', version: '1.0.0', use: { cr
|
|
|
177
174
|
fulfil: async ({ input }) => ({ echo: input.text }),
|
|
178
175
|
}),
|
|
179
176
|
]);
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### Conditional flow with when()
|
|
180
|
+
|
|
181
|
+
`when(condition, () => record)` records the inner step(s) guarded by a condition instead of a native `if`. `when` is a **free function** (import it), the condition is `ref.equals(scalar)` (equality only — no `<`/`>`/`&&`), and the recorded step is skipped at runtime unless the condition holds. Never write a native `if` on a symbolic ref, and never call a method on one (e.g. `input.name.trim()`) — both silently mis-record or throw; compose strings with a template literal and branch with `when(...)`.
|
|
182
|
+
|
|
183
|
+
```ts
|
|
184
|
+
import { connector, server, tool, when, z } from '@noodleseed/one';
|
|
185
|
+
|
|
186
|
+
// Two read operations; the tracking lookup only runs when the order came back shipped.
|
|
187
|
+
const orders = connector('orders')
|
|
188
|
+
.version('1.0.0')
|
|
189
|
+
.http({
|
|
190
|
+
baseUrl: 'https://orders.example.com',
|
|
191
|
+
allowedOrigins: ['https://orders.example.com'],
|
|
192
|
+
operations: {
|
|
193
|
+
get_order: {
|
|
194
|
+
type: 'read',
|
|
195
|
+
method: 'GET',
|
|
196
|
+
path: '/orders',
|
|
197
|
+
query: ['id'],
|
|
198
|
+
input: { id: { type: 'string', required: true } },
|
|
199
|
+
output: { id: { type: 'string' }, status: { type: 'string' } },
|
|
200
|
+
response: { id: '${response.id}', status: '${response.status}' },
|
|
201
|
+
},
|
|
202
|
+
get_tracking: {
|
|
203
|
+
type: 'read',
|
|
204
|
+
method: 'GET',
|
|
205
|
+
path: '/tracking',
|
|
206
|
+
query: ['order_id'],
|
|
207
|
+
input: { order_id: { type: 'string', required: true } },
|
|
208
|
+
output: { url: { type: 'string' } },
|
|
209
|
+
response: { url: '${response.url}' },
|
|
210
|
+
},
|
|
211
|
+
},
|
|
212
|
+
});
|
|
213
|
+
|
|
214
|
+
export default server('orders_app', { title: 'Orders', version: '1.0.0', use: { orders } }, [
|
|
215
|
+
tool('track_order', {
|
|
216
|
+
description: 'Find shipment tracking for an order.',
|
|
217
|
+
input: z.object({ orderId: z.string() }),
|
|
218
|
+
output: z.object({
|
|
219
|
+
orderId: z.string(),
|
|
220
|
+
status: z.string(),
|
|
221
|
+
trackingUrl: z.string().optional(),
|
|
222
|
+
}),
|
|
223
|
+
fulfil: ({ input, connectors }) => {
|
|
224
|
+
const order = connectors.orders.get_order({ id: input.orderId });
|
|
225
|
+
// Record the tracking step only when order.status === "shipped" (equality-only condition).
|
|
226
|
+
const tracking = when(order.status.equals('shipped'), () =>
|
|
227
|
+
connectors.orders.get_tracking({ order_id: order.id }),
|
|
228
|
+
);
|
|
229
|
+
return {
|
|
230
|
+
orderId: order.id,
|
|
231
|
+
status: order.status,
|
|
232
|
+
// `.optional()` marks a ref that may be absent when its guarding step did not run.
|
|
233
|
+
trackingUrl: tracking.url.optional(),
|
|
234
|
+
};
|
|
235
|
+
},
|
|
236
|
+
}),
|
|
237
|
+
]);
|
|
180
238
|
```
|
|
@@ -25,5 +25,6 @@ For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `n
|
|
|
25
25
|
| `noodle validate` passes but React views fail to bundle (“requires Vite”) | Project dependencies are not installed — widget bundling uses the app-local Vite | Run the project’s package install, then retry `noodle dev` / `noodle deploy` |
|
|
26
26
|
| Hosted endpoint returns 401 to probes | Expected: hosted servers challenge unauthenticated calls with OAuth metadata | Sign in from the host when prompted; widen who may call with `noodle access set` if testers are outside the org |
|
|
27
27
|
| Tools error only after deploy | Runtime/config differences surface hosted (secrets, connector reachability) | Run `noodle smoke`, then `noodle metrics --agent-output` and `noodle events --tool <name> --status tool_error --json`; check `noodle secrets list` scope |
|
|
28
|
-
|
|
|
28
|
+
| A connector tool validates and lists, but returns empty or `undefined` fields | The `response` mapping references a path the API does not return — usually the wrong root (a `.body` segment, when the parsed body is bound directly to `${response}`) or the wrong shape | Run `noodle tools call <name> --args <json>` with the secret set and compare the mapped result to the API’s real JSON; map from `${response.<path>}` (the body is `${response}`, there is no `.body`) and use bracket array indices (`${response.items[0].id}`) |
|
|
29
|
+
| Need to invoke a tool from the terminal | Local tools run in-process; the `noodle` CLI is not a general MCP client for **deployed** URLs (there is no `call <url>` verb) | Locally, `noodle tools call <name> --args <json>` (also `noodle resources read` / `noodle prompts get`) runs the tool against the in-process runtime — with the secret set it executes the connector against the real API, so use it to prove mapped output. For a **deployed** URL use MCP Inspector or `npx @mcpjam/cli@latest tools call --url <url> ...` |
|
|
29
30
|
| One customer/session reports a bad answer or protocol error | The failure may be a model/tool error, host protocol error, or connector/runtime error | Run `noodle metrics --agent-output`, then `noodle events --tool <name> --status tool_error --json`; copy the `sessionId` into `noodle events --session <id> --json`, then match timestamps with `noodle logs` |
|