@neon/tools 2.14.4 → 2.15.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/README.md +78 -1
- package/dist/effect.d.ts +22 -0
- package/dist/effect.d.ts.map +1 -0
- package/dist/effect.js +3 -0
- package/dist/generated/output.gen.d.ts +3418 -0
- package/dist/generated/output.gen.d.ts.map +1 -0
- package/dist/generated/output.gen.js +1498 -0
- package/dist/lib/custom/auth-config.d.ts +63 -1
- package/dist/lib/custom/auth-config.d.ts.map +1 -1
- package/dist/lib/custom/auth-config.js +21 -1
- package/dist/lib/custom/docs.d.ts +32 -2
- package/dist/lib/custom/docs.d.ts.map +1 -1
- package/dist/lib/custom/docs.js +16 -1
- package/dist/lib/custom/feedback.d.ts +7 -2
- package/dist/lib/custom/feedback.d.ts.map +1 -1
- package/dist/lib/custom/feedback.js +2 -0
- package/dist/lib/custom/fetch.d.ts +15 -1
- package/dist/lib/custom/fetch.d.ts.map +1 -1
- package/dist/lib/custom/fetch.js +9 -1
- package/dist/lib/custom/organizations.d.ts +23 -1
- package/dist/lib/custom/organizations.d.ts.map +1 -1
- package/dist/lib/custom/organizations.js +2 -0
- package/dist/lib/custom/resources.d.ts +15 -1
- package/dist/lib/custom/resources.d.ts.map +1 -1
- package/dist/lib/custom/resources.js +7 -1
- package/dist/lib/custom/sql/connection.js +1 -1
- package/dist/lib/custom/sql/describe-branch.d.ts +99 -1
- package/dist/lib/custom/sql/describe-branch.d.ts.map +1 -1
- package/dist/lib/custom/sql/describe-branch.js +9 -0
- package/dist/lib/custom/sql/inspect/inspect.d.ts +27 -1
- package/dist/lib/custom/sql/inspect/inspect.d.ts.map +1 -1
- package/dist/lib/custom/sql/inspect/inspect.js +15 -1
- package/dist/lib/custom/sql/migrations.d.ts +46 -2
- package/dist/lib/custom/sql/migrations.d.ts.map +1 -1
- package/dist/lib/custom/sql/migrations.js +26 -2
- package/dist/lib/custom/sql/query-tuning.d.ts +90 -2
- package/dist/lib/custom/sql/query-tuning.d.ts.map +1 -1
- package/dist/lib/custom/sql/query-tuning.js +28 -3
- package/dist/lib/custom/sql/run.d.ts +30 -3
- package/dist/lib/custom/sql/run.d.ts.map +1 -1
- package/dist/lib/custom/sql/run.js +11 -1
- package/dist/lib/custom/sql/schema.d.ts +76 -2
- package/dist/lib/custom/sql/schema.d.ts.map +1 -1
- package/dist/lib/custom/sql/schema.js +31 -2
- package/dist/lib/custom/sql/slow-queries.d.ts +15 -1
- package/dist/lib/custom/sql/slow-queries.d.ts.map +1 -1
- package/dist/lib/custom/sql/slow-queries.js +9 -1
- package/dist/lib/effect/errors.d.ts +51 -0
- package/dist/lib/effect/errors.d.ts.map +1 -0
- package/dist/lib/effect/errors.js +37 -0
- package/dist/lib/effect/tools.d.ts +56 -0
- package/dist/lib/effect/tools.d.ts.map +1 -0
- package/dist/lib/effect/tools.js +67 -0
- package/dist/lib/ergonomic/bind.d.ts +20 -6
- package/dist/lib/ergonomic/bind.d.ts.map +1 -1
- package/dist/lib/ergonomic/bind.js +2 -1
- package/dist/lib/ergonomic/catalog.d.ts +5333 -172
- package/dist/lib/ergonomic/catalog.d.ts.map +1 -1
- package/dist/lib/ergonomic/catalog.js +186 -1
- package/dist/lib/ergonomic/composed.d.ts +866 -12
- package/dist/lib/ergonomic/composed.d.ts.map +1 -1
- package/dist/lib/ergonomic/composed.js +34 -0
- package/dist/lib/mcp-json-schema.d.ts +20 -0
- package/dist/lib/mcp-json-schema.d.ts.map +1 -1
- package/dist/lib/mcp-json-schema.js +89 -1
- package/dist/lib/mcp-register.d.ts +1 -1
- package/dist/lib/mcp-register.d.ts.map +1 -1
- package/dist/lib/mcp-register.js +2 -1
- package/dist/lib/operation.d.ts +6 -1
- package/dist/lib/operation.d.ts.map +1 -1
- package/dist/mcp-v1.d.ts.map +1 -1
- package/dist/mcp-v1.js +3 -1
- package/dist/mcp.d.ts +3 -3
- package/dist/mcp.d.ts.map +1 -1
- package/dist/mcp.js +3 -3
- package/dist/operations.gen.d.ts +194 -194
- package/package.json +22 -3
package/README.md
CHANGED
|
@@ -94,7 +94,7 @@ await tools["projects.list"].execute(
|
|
|
94
94
|
);
|
|
95
95
|
```
|
|
96
96
|
|
|
97
|
-
Each tool includes its Zod 4 `inputSchema`, published `id`, title, description, safety annotations, stability metadata, and `execute()`. Inputs are snake_case at the tool boundary. `execute()` strictly validates the input, rejects unknown fields, and returns typed, JSON-safe `{ data }`. Neon SDK errors remain typed and are thrown to the caller.
|
|
97
|
+
Each tool includes its Zod 4 `inputSchema` and `outputSchema`, published `id`, title, description, safety annotations, stability metadata, and `execute()`. Inputs are snake_case at the tool boundary. `execute()` strictly validates the input, rejects unknown fields, and returns typed, JSON-safe `{ data }`. Neon SDK errors remain typed and are thrown to the caller.
|
|
98
98
|
|
|
99
99
|
Paginated lists call `.all()` and return the item array. Do not pass a cursor; those fields are omitted from the input schema.
|
|
100
100
|
|
|
@@ -423,6 +423,49 @@ registerNeonTools(server, tools);
|
|
|
423
423
|
|
|
424
424
|
`registerNeonTools` publishes that catalog. MCP 2 `inputSchema` is JSON Schema without `$schema`. Generated fields have types, enums, `required`, and constraints, and no OpenAPI property docs. Fields this package described with `.describe()` (`pooled`, `finalize`, `zip`) keep that copy.
|
|
425
425
|
|
|
426
|
+
Every tool also publishes an `outputSchema` for its `structuredContent`, `{ data }`:
|
|
427
|
+
|
|
428
|
+
```json
|
|
429
|
+
{
|
|
430
|
+
"type": "object",
|
|
431
|
+
"properties": {
|
|
432
|
+
"data": {
|
|
433
|
+
"type": "array",
|
|
434
|
+
"items": {
|
|
435
|
+
"type": "object",
|
|
436
|
+
"properties": {
|
|
437
|
+
"id": { "type": "string" },
|
|
438
|
+
"name": { "type": "string" },
|
|
439
|
+
"default": { "type": "boolean" },
|
|
440
|
+
"parent_id": { "type": ["string", "null"] },
|
|
441
|
+
"created_by": { "type": ["object", "null"] }
|
|
442
|
+
},
|
|
443
|
+
"required": ["id", "name", "default"]
|
|
444
|
+
}
|
|
445
|
+
}
|
|
446
|
+
},
|
|
447
|
+
"required": ["data"]
|
|
448
|
+
}
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
That is an excerpt of `list_branches`. The schema types the fields of `data`, or of each list item, and stops there: a nested object is `{ "type": "object" }`. Enums are strings and extra fields are allowed, so a new API value or field still validates. Descriptions appear only where this package wrote them. The server checks every successful result against this schema, the same check a validating MCP client runs; a result that breaks it becomes an `isError` result reading `Output validation error`. Failures return `{ error }` and are not checked.
|
|
452
|
+
|
|
453
|
+
`tool.outputSchema` is the full Zod schema of `data`. Hosts that register tools themselves can publish the same compact form:
|
|
454
|
+
|
|
455
|
+
```ts
|
|
456
|
+
import { toMcpOutputJsonSchema, toMcpOutputSchema } from "@neon/tools/mcp";
|
|
457
|
+
|
|
458
|
+
const json = toMcpOutputJsonSchema(tool.outputSchema); // JSON Schema of { data }
|
|
459
|
+
const standard = toMcpOutputSchema(tool.outputSchema); // Standard Schema for MCP 2 registerTool
|
|
460
|
+
|
|
461
|
+
// A host that removes fields from results before returning them
|
|
462
|
+
const stripped = toMcpOutputSchema(tool.outputSchema, {
|
|
463
|
+
omit: ["connectionString", "password"],
|
|
464
|
+
});
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
`omit` drops those names from the schema at every level, including from `required`.
|
|
468
|
+
|
|
426
469
|
Hosts that convert Zod themselves:
|
|
427
470
|
|
|
428
471
|
```ts
|
|
@@ -508,6 +551,40 @@ const createProject = createTool(configs.create_and_connect_projects);
|
|
|
508
551
|
|
|
509
552
|
The adapter maps approval requirements to Mastra's `requireApproval` field and forwards its abort signal. Credentials are the constructor `apiKey` (a string or a callback invoked on every request).
|
|
510
553
|
|
|
554
|
+
## Effect
|
|
555
|
+
|
|
556
|
+
`@neon/tools/effect` runs the same tools as [Effect](https://effect.website) v4 Effects. Install the optional peer dependencies `effect` and `@neon/effect`; the other entry points don't need them.
|
|
557
|
+
|
|
558
|
+
```ts
|
|
559
|
+
import { createNeonTools } from "@neon/tools";
|
|
560
|
+
import { retryReadOnlyNetworkFailures, toEffectTools } from "@neon/tools/effect";
|
|
561
|
+
import { Effect } from "effect";
|
|
562
|
+
|
|
563
|
+
const tools = toEffectTools(
|
|
564
|
+
createNeonTools({ tools: ["projects.list", "projects.get"] as const }),
|
|
565
|
+
{ retry: retryReadOnlyNetworkFailures },
|
|
566
|
+
);
|
|
567
|
+
|
|
568
|
+
const project = tools["projects.get"]
|
|
569
|
+
.execute({ project_id: "my-project-id" }, { apiKey })
|
|
570
|
+
.pipe(Effect.catchTag("NeonNotFoundError", () => Effect.succeed(undefined)));
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
`toEffectTools` keeps every tool field and replaces `execute`, which returns `Effect<NeonToolResult, NeonToolError>` with a span named `NeonTools.<id>`. The execution context is the one above without `signal`: interrupting the fiber cancels the call.
|
|
574
|
+
|
|
575
|
+
The span records every failure's tag as `error.type` and fails only for the server's: invalid input, a statement Postgres rejected, and any 4xx from the Neon API keep it ok. `NeonClientError` fails it, since the SDK uses it for malformed responses as well as its own validation. A `NeonSqlError` whose SQLSTATE class is 08, 40, 53, 55, 57, 58, F0, or XX (connection, rollback, resources, operator, system, or internal errors) fails it. `neon.tool.attempts` counts the attempts, and `neon.tool.retried_error.type` names the failure a retry recovered from.
|
|
576
|
+
|
|
577
|
+
| Error / `_tag` | When |
|
|
578
|
+
| --- | --- |
|
|
579
|
+
| `NeonEffectError` members (`NeonAuthError`, `NeonNotFoundError`, `NeonNetworkError`, …) | The Neon API or SDK failed; see [`@neon/effect`](../effect/README.md#errors) |
|
|
580
|
+
| `NeonToolInputError` | The input failed the tool's schema; `issues` lists why |
|
|
581
|
+
| `NeonSqlError` | Postgres rejected the statement; `code` is the SQLSTATE, with `position`, `detail`, `hint`, `where` |
|
|
582
|
+
| `NeonSqlConnectionError` | The SQL endpoint failed before Postgres answered |
|
|
583
|
+
|
|
584
|
+
Anything else a tool throws becomes a defect. `toNeonToolError` is the mapping, for promise code you wrap yourself.
|
|
585
|
+
|
|
586
|
+
Retries are off unless you pass `retry`. The SDK already retries 423, 429, and 503 responses and honours `Retry-After`. `retryReadOnlyNetworkFailures` retries a read-only tool that got no response, twice with jittered exponential backoff from 200 ms; mutations are never retried, since one may have reached the API. A retry runs the whole tool again, including `onExecute` hooks and every page of a list. Pass your own `NeonToolRetryPolicy` (`schedule`, `times`, `shouldRetry`) for a different policy. Whatever it says, the adapter only retries read-only tools and never a 423, 429, or 503 response.
|
|
587
|
+
|
|
511
588
|
## Safety and binary data
|
|
512
589
|
|
|
513
590
|
Every non-read operation requires approval. Generated non-read operations are conservatively marked as potentially destructive; `migrations.prepare` and `queryTuning.prepare` (which write only to a new temporary branch) and `feedback.send` are not. Reads that return connection credentials also require approval.
|
package/dist/effect.d.ts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@neon/tools/effect` — run Neon tools as Effects: typed errors, interruption that
|
|
3
|
+
* cancels the call, a span per tool, and opt-in retries.
|
|
4
|
+
*
|
|
5
|
+
* Requires the optional peer dependencies `effect` and `@neon/effect`.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```ts
|
|
9
|
+
* import { createNeonTools } from "@neon/tools";
|
|
10
|
+
* import { toEffectTools } from "@neon/tools/effect";
|
|
11
|
+
* import { Effect } from "effect";
|
|
12
|
+
*
|
|
13
|
+
* const tools = toEffectTools(createNeonTools({ tools: ["projects.list"] }));
|
|
14
|
+
*
|
|
15
|
+
* const program = tools["projects.list"]
|
|
16
|
+
* .execute({}, { apiKey: process.env.NEON_API_KEY })
|
|
17
|
+
* .pipe(Effect.catchTag("NeonAuthError", () => Effect.succeed(undefined)));
|
|
18
|
+
* ```
|
|
19
|
+
*/
|
|
20
|
+
export { NeonSqlConnectionError, NeonSqlError, type NeonToolError, NeonToolInputError, toNeonToolError, } from "./lib/effect/errors.js";
|
|
21
|
+
export { type EffectToolOptions, type ExecutableNeonTool, type NeonEffectTool, type NeonEffectToolContext, type NeonEffectTools, type NeonToolRetryPolicy, retryReadOnlyNetworkFailures, toEffectTool, toEffectTools, } from "./lib/effect/tools.js";
|
|
22
|
+
//# sourceMappingURL=effect.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../src/effect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,sBAAsB,EACtB,YAAY,EACZ,KAAK,aAAa,EAClB,kBAAkB,EAClB,eAAe,GACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACN,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,4BAA4B,EAC5B,YAAY,EACZ,aAAa,GACb,MAAM,uBAAuB,CAAC"}
|
package/dist/effect.js
ADDED
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import { NeonSqlConnectionError, NeonSqlError, NeonToolInputError, toNeonToolError } from "./lib/effect/errors.js";
|
|
2
|
+
import { retryReadOnlyNetworkFailures, toEffectTool, toEffectTools } from "./lib/effect/tools.js";
|
|
3
|
+
export { NeonSqlConnectionError, NeonSqlError, NeonToolInputError, retryReadOnlyNetworkFailures, toEffectTool, toEffectTools, toNeonToolError };
|