@melra/sdk 0.3.0-alpha.4 → 0.3.0-alpha.5
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 +94 -0
- package/dist/index.d.ts +5 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +20 -3
- package/dist/index.js.map +1 -1
- package/dist/index.test.js +83 -3
- package/dist/index.test.js.map +1 -1
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# @melra/sdk
|
|
2
|
+
|
|
3
|
+
TypeScript client for [MELRA](https://github.com/XAGI-Lab/melra), a local-only
|
|
4
|
+
MCP server that turns one tool call into a governed, verified, receipted task.
|
|
5
|
+
|
|
6
|
+
The client spawns a MELRA server over stdio and speaks the task and workflow
|
|
7
|
+
tools for you, so you work with typed requests instead of raw MCP plumbing.
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @melra/sdk
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Plan, approve, execute
|
|
14
|
+
|
|
15
|
+
Planning never executes. A mutation comes back with a task-scoped approval
|
|
16
|
+
challenge whose exact phrase you must echo to run it.
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import { MelraClient } from "@melra/sdk";
|
|
20
|
+
|
|
21
|
+
const melra = await MelraClient.connect();
|
|
22
|
+
|
|
23
|
+
const task = await melra.plan({
|
|
24
|
+
goal: "Record the release note",
|
|
25
|
+
operation: {
|
|
26
|
+
kind: "file",
|
|
27
|
+
action: "write",
|
|
28
|
+
path: "NOTES.md",
|
|
29
|
+
content: "0.3 is out.\n",
|
|
30
|
+
},
|
|
31
|
+
constraints: [],
|
|
32
|
+
forbiddenEffects: [],
|
|
33
|
+
requiredEvidence: [{ type: "file_exists", path: "NOTES.md" }],
|
|
34
|
+
budget: { maxDurationMs: 10_000, maxRetries: 0 },
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
const approval = task.approval as
|
|
38
|
+
| { approvalId: string; phrase: string }
|
|
39
|
+
| undefined;
|
|
40
|
+
const result = await melra.execute(
|
|
41
|
+
task.id as string,
|
|
42
|
+
approval && { approvalId: approval.approvalId, phrase: approval.phrase },
|
|
43
|
+
);
|
|
44
|
+
|
|
45
|
+
console.log(result.task);
|
|
46
|
+
await melra.close();
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`requiredEvidence` is what decides success. A write that reported success but
|
|
50
|
+
left no file is `partial`, never `verified_success` — the verifier checks the
|
|
51
|
+
world, not the adapter's own claim. Leave `constraints` empty: freeform prose is
|
|
52
|
+
not enforceable, so a non-empty array is denied outright.
|
|
53
|
+
|
|
54
|
+
## Connecting to a specific server
|
|
55
|
+
|
|
56
|
+
`connect()` runs `melra serve` from your `PATH` by default. Point it anywhere:
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
const melra = await MelraClient.connect({
|
|
60
|
+
command: "npx",
|
|
61
|
+
args: ["-y", "@melra/cli@alpha", "serve"],
|
|
62
|
+
env: { MELRA_WORKSPACE: "/path/to/project" },
|
|
63
|
+
});
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Workflows
|
|
67
|
+
|
|
68
|
+
`planWorkflow`, `advanceWorkflow`, `workflowStatus`, `cancelWorkflow`, and
|
|
69
|
+
`controlWorkflow` drive the durable graph. Every node that does work goes through
|
|
70
|
+
the same policy, approval, verification, and receipt path as a single task, so
|
|
71
|
+
nothing is bypassed by composing.
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
const run = await melra.planWorkflow(definition);
|
|
75
|
+
await melra.advanceWorkflow(run.id, approvals, [
|
|
76
|
+
{ nodeId: "ask-owner", value: "ship it" },
|
|
77
|
+
]);
|
|
78
|
+
await melra.controlWorkflow(run.id, "pause");
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Advancing is resumable: call it until the run reaches a terminal status. Effects
|
|
82
|
+
are deduplicated by idempotency key across restarts, so a crashed advance does
|
|
83
|
+
not repeat work it already committed.
|
|
84
|
+
|
|
85
|
+
## Other exports
|
|
86
|
+
|
|
87
|
+
`parseMelraToolResult` unwraps a raw MCP tool result into the parsed JSON payload
|
|
88
|
+
and throws the server's error text when the call failed — useful if you talk to
|
|
89
|
+
the tools through your own MCP client.
|
|
90
|
+
|
|
91
|
+
Requires Node.js 22 or newer. Full documentation:
|
|
92
|
+
[github.com/XAGI-Lab/melra](https://github.com/XAGI-Lab/melra)
|
|
93
|
+
|
|
94
|
+
Apache-2.0
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type WorkflowAdvanceResult, type
|
|
1
|
+
import { type WorkflowAdvanceResult, type WorkflowDefinitionInput, type WorkflowInput, type WorkflowRun, type ApprovalResponse, type TaskRequestInput } from "@melra/protocol";
|
|
2
2
|
export interface MelraClientOptions {
|
|
3
3
|
command?: string;
|
|
4
4
|
args?: string[];
|
|
@@ -14,7 +14,7 @@ export declare class MelraClient {
|
|
|
14
14
|
static connect(options?: MelraClientOptions): Promise<MelraClient>;
|
|
15
15
|
private call;
|
|
16
16
|
capabilities(): Promise<Record<string, unknown>>;
|
|
17
|
-
plan(request:
|
|
17
|
+
plan(request: TaskRequestInput): Promise<Record<string, unknown>>;
|
|
18
18
|
execute(taskId: string, approval?: ApprovalResponse): Promise<Record<string, unknown>>;
|
|
19
19
|
status(taskId: string): Promise<Record<string, unknown>>;
|
|
20
20
|
cancel(taskId: string): Promise<Record<string, unknown>>;
|
|
@@ -22,10 +22,11 @@ export declare class MelraClient {
|
|
|
22
22
|
taskId?: string;
|
|
23
23
|
receiptId?: string;
|
|
24
24
|
}): Promise<Record<string, unknown>>;
|
|
25
|
-
planWorkflow(definition:
|
|
26
|
-
advanceWorkflow(workflowId: string, approvals?: ApprovalResponse[]): Promise<WorkflowAdvanceResult>;
|
|
25
|
+
planWorkflow(definition: WorkflowDefinitionInput): Promise<WorkflowRun>;
|
|
26
|
+
advanceWorkflow(workflowId: string, approvals?: ApprovalResponse[], inputs?: WorkflowInput[]): Promise<WorkflowAdvanceResult>;
|
|
27
27
|
workflowStatus(workflowId: string): Promise<WorkflowRun>;
|
|
28
28
|
cancelWorkflow(workflowId: string): Promise<WorkflowRun>;
|
|
29
|
+
controlWorkflow(workflowId: string, action: "pause" | "resume" | "suspend"): Promise<WorkflowRun>;
|
|
29
30
|
close(): Promise<void>;
|
|
30
31
|
}
|
|
31
32
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAQL,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAOD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAS7E;AAED,qBAAa,WAAW;IACF,OAAO,CAAC,QAAQ,CAAC,MAAM;IAA3C,OAAO;WAEM,OAAO,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC;YAgB9D,IAAI;IASZ,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAQhD,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAQjE,OAAO,CACX,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAO7B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIxD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIxD,OAAO,CAAC,KAAK,EAAE;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAc9B,YAAY,CAChB,UAAU,EAAE,uBAAuB,GAClC,OAAO,CAAC,WAAW,CAAC;IASjB,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,gBAAgB,EAAO,EAClC,MAAM,GAAE,aAAa,EAAO,GAC3B,OAAO,CAAC,qBAAqB,CAAC;IAW3B,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAOxD,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAOxD,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,GACrC,OAAO,CAAC,WAAW,CAAC;IAOjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}
|
package/dist/index.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
// SPDX-License-Identifier: Apache-2.0
|
|
3
3
|
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
4
4
|
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
|
|
5
|
-
import { WorkflowAdvanceInputSchema, WorkflowAdvanceResultSchema, WorkflowDefinitionSchema, WorkflowIdInputSchema, WorkflowRunSchema, } from "@melra/protocol";
|
|
5
|
+
import { WorkflowAdvanceInputSchema, WorkflowAdvanceResultSchema, WorkflowControlInputSchema, WorkflowDefinitionSchema, WorkflowIdInputSchema, WorkflowRunSchema, TaskRequestSchema, } from "@melra/protocol";
|
|
6
6
|
export function parseMelraToolResult(result) {
|
|
7
7
|
const response = result;
|
|
8
8
|
const text = response.content?.find((item) => item.type === "text")?.text;
|
|
@@ -38,8 +38,13 @@ export class MelraClient {
|
|
|
38
38
|
async capabilities() {
|
|
39
39
|
return await this.call("melra_capabilities", {});
|
|
40
40
|
}
|
|
41
|
+
// Takes the pre-defaults shape and parses, the same way `planWorkflow` does.
|
|
42
|
+
// `TaskRequest` is what the schema produces, so requiring it would make every
|
|
43
|
+
// caller restate `encoding`, `recursive`, and `maxSteps` by hand to satisfy
|
|
44
|
+
// the compiler — defaults the schema already knows.
|
|
41
45
|
async plan(request) {
|
|
42
|
-
|
|
46
|
+
const parsed = TaskRequestSchema.parse(request);
|
|
47
|
+
return await this.call("melra_plan", parsed);
|
|
43
48
|
}
|
|
44
49
|
async execute(taskId, approval) {
|
|
45
50
|
return await this.call("melra_execute", {
|
|
@@ -54,21 +59,29 @@ export class MelraClient {
|
|
|
54
59
|
return await this.call("melra_task_cancel", { taskId });
|
|
55
60
|
}
|
|
56
61
|
async receipt(input) {
|
|
62
|
+
// The server says the same thing, but saying it here costs no round trip and
|
|
63
|
+
// matches the Python SDK.
|
|
64
|
+
if (input.taskId === undefined && input.receiptId === undefined) {
|
|
65
|
+
throw new Error("taskId or receiptId is required");
|
|
66
|
+
}
|
|
57
67
|
return await this.call("melra_receipt", {
|
|
58
68
|
...(input.taskId === undefined ? {} : { taskId: input.taskId }),
|
|
59
69
|
...(input.receiptId === undefined ? {} : { receiptId: input.receiptId }),
|
|
60
70
|
});
|
|
61
71
|
}
|
|
72
|
+
// Same reason as `plan`: this is the shape an author writes, not the shape the
|
|
73
|
+
// schema produces.
|
|
62
74
|
async planWorkflow(definition) {
|
|
63
75
|
const parsed = WorkflowDefinitionSchema.parse(definition);
|
|
64
76
|
return WorkflowRunSchema.parse(await this.call("melra_workflow_plan", {
|
|
65
77
|
definition: parsed,
|
|
66
78
|
}));
|
|
67
79
|
}
|
|
68
|
-
async advanceWorkflow(workflowId, approvals = []) {
|
|
80
|
+
async advanceWorkflow(workflowId, approvals = [], inputs = []) {
|
|
69
81
|
const parsed = WorkflowAdvanceInputSchema.parse({
|
|
70
82
|
workflowId,
|
|
71
83
|
approvals,
|
|
84
|
+
inputs,
|
|
72
85
|
});
|
|
73
86
|
return WorkflowAdvanceResultSchema.parse(await this.call("melra_workflow_advance", parsed));
|
|
74
87
|
}
|
|
@@ -80,6 +93,10 @@ export class MelraClient {
|
|
|
80
93
|
const parsed = WorkflowIdInputSchema.parse({ workflowId });
|
|
81
94
|
return WorkflowRunSchema.parse(await this.call("melra_workflow_cancel", parsed));
|
|
82
95
|
}
|
|
96
|
+
async controlWorkflow(workflowId, action) {
|
|
97
|
+
const parsed = WorkflowControlInputSchema.parse({ workflowId, action });
|
|
98
|
+
return WorkflowRunSchema.parse(await this.call("melra_workflow_control", parsed));
|
|
99
|
+
}
|
|
83
100
|
async close() {
|
|
84
101
|
await this.client.close();
|
|
85
102
|
}
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,sCAAsC;AAEtC,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/dist/index.test.js
CHANGED
|
@@ -17,7 +17,7 @@ describe("TypeScript SDK result parsing", () => {
|
|
|
17
17
|
});
|
|
18
18
|
});
|
|
19
19
|
describe("TypeScript workflow SDK", () => {
|
|
20
|
-
it("calls the
|
|
20
|
+
it("calls the exact workflow tools with typed arguments", async () => {
|
|
21
21
|
const workflowId = "11111111-1111-4111-8111-111111111111";
|
|
22
22
|
const traceId = "22222222-2222-4222-8222-222222222222";
|
|
23
23
|
const definition = WorkflowDefinitionSchema.parse({
|
|
@@ -66,9 +66,14 @@ describe("TypeScript workflow SDK", () => {
|
|
|
66
66
|
approvalId: "44444444-4444-4444-8444-444444444444",
|
|
67
67
|
phrase: "APPROVE exact",
|
|
68
68
|
};
|
|
69
|
+
const answer = {
|
|
70
|
+
nodeId: "inspect",
|
|
71
|
+
value: "ship it",
|
|
72
|
+
};
|
|
69
73
|
await client.planWorkflow(definition);
|
|
70
|
-
await client.advanceWorkflow(workflowId, [approval]);
|
|
74
|
+
await client.advanceWorkflow(workflowId, [approval], [answer]);
|
|
71
75
|
await client.workflowStatus(workflowId);
|
|
76
|
+
await client.controlWorkflow(workflowId, "pause");
|
|
72
77
|
await client.cancelWorkflow(workflowId);
|
|
73
78
|
expect(callTool.mock.calls.map(([input]) => input)).toEqual([
|
|
74
79
|
{
|
|
@@ -77,17 +82,92 @@ describe("TypeScript workflow SDK", () => {
|
|
|
77
82
|
},
|
|
78
83
|
{
|
|
79
84
|
name: "melra_workflow_advance",
|
|
80
|
-
arguments: { workflowId, approvals: [approval] },
|
|
85
|
+
arguments: { workflowId, approvals: [approval], inputs: [answer] },
|
|
81
86
|
},
|
|
82
87
|
{
|
|
83
88
|
name: "melra_workflow_status",
|
|
84
89
|
arguments: { workflowId },
|
|
85
90
|
},
|
|
91
|
+
{
|
|
92
|
+
name: "melra_workflow_control",
|
|
93
|
+
arguments: { workflowId, action: "pause" },
|
|
94
|
+
},
|
|
86
95
|
{
|
|
87
96
|
name: "melra_workflow_cancel",
|
|
88
97
|
arguments: { workflowId },
|
|
89
98
|
},
|
|
90
99
|
]);
|
|
91
100
|
});
|
|
101
|
+
it("plans a definition written by hand, defaults and all", async () => {
|
|
102
|
+
const run = {
|
|
103
|
+
schemaVersion: "1.0.0",
|
|
104
|
+
id: "55555555-5555-4555-8555-555555555555",
|
|
105
|
+
definitionId: "66666666-6666-4666-8666-666666666666",
|
|
106
|
+
definitionVersion: 1,
|
|
107
|
+
status: "planned",
|
|
108
|
+
stateVersion: 2,
|
|
109
|
+
nodes: { inspect: { status: "pending", taskIds: [] } },
|
|
110
|
+
traceId: "77777777-7777-4777-8777-777777777777",
|
|
111
|
+
createdAt: "2026-08-08T12:00:00.000Z",
|
|
112
|
+
updatedAt: "2026-08-08T12:00:00.000Z",
|
|
113
|
+
};
|
|
114
|
+
const callTool = vi.fn(async (_input) => ({
|
|
115
|
+
content: [{ type: "text", text: JSON.stringify(run) }],
|
|
116
|
+
}));
|
|
117
|
+
const client = new MelraClient({ callTool, async close() { } });
|
|
118
|
+
// No `dependsOn`, `constraints`, `forbiddenEffects`, `requiredEvidence`, or
|
|
119
|
+
// `budget`. Requiring those would mean writing out `constraints: []` — where
|
|
120
|
+
// any other value is a policy deny — just to satisfy the compiler.
|
|
121
|
+
await client.planWorkflow({
|
|
122
|
+
schemaVersion: "1.0.0",
|
|
123
|
+
id: run.definitionId,
|
|
124
|
+
version: 1,
|
|
125
|
+
name: "Handwritten workflow",
|
|
126
|
+
nodes: [
|
|
127
|
+
{
|
|
128
|
+
id: "inspect",
|
|
129
|
+
type: "operation",
|
|
130
|
+
request: {
|
|
131
|
+
goal: "Inspect",
|
|
132
|
+
operation: { kind: "system", action: "info" },
|
|
133
|
+
},
|
|
134
|
+
},
|
|
135
|
+
],
|
|
136
|
+
});
|
|
137
|
+
// The server still receives the complete definition, so the defaults are
|
|
138
|
+
// applied once here rather than differing per caller.
|
|
139
|
+
expect(callTool.mock.calls[0]?.[0]).toEqual({
|
|
140
|
+
name: "melra_workflow_plan",
|
|
141
|
+
arguments: {
|
|
142
|
+
definition: {
|
|
143
|
+
schemaVersion: "1.0.0",
|
|
144
|
+
id: run.definitionId,
|
|
145
|
+
version: 1,
|
|
146
|
+
name: "Handwritten workflow",
|
|
147
|
+
nodes: [
|
|
148
|
+
{
|
|
149
|
+
id: "inspect",
|
|
150
|
+
type: "operation",
|
|
151
|
+
dependsOn: [],
|
|
152
|
+
request: {
|
|
153
|
+
goal: "Inspect",
|
|
154
|
+
operation: { kind: "system", action: "info" },
|
|
155
|
+
constraints: [],
|
|
156
|
+
forbiddenEffects: [],
|
|
157
|
+
requiredEvidence: [],
|
|
158
|
+
budget: { maxSteps: 10, maxDurationMs: 120_000, maxRetries: 2 },
|
|
159
|
+
},
|
|
160
|
+
},
|
|
161
|
+
],
|
|
162
|
+
},
|
|
163
|
+
},
|
|
164
|
+
});
|
|
165
|
+
});
|
|
166
|
+
it("names the missing receipt selector without a round trip", async () => {
|
|
167
|
+
const callTool = vi.fn();
|
|
168
|
+
const client = new MelraClient({ callTool, async close() { } });
|
|
169
|
+
await expect(client.receipt({})).rejects.toThrow("taskId or receiptId is required");
|
|
170
|
+
expect(callTool).not.toHaveBeenCalled();
|
|
171
|
+
});
|
|
92
172
|
});
|
|
93
173
|
//# sourceMappingURL=index.test.js.map
|
package/dist/index.test.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,sCAAsC;AAEtC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE/D,QAAQ,CAAC,+BAA+B,EAAE,GAAG,EAAE;IAC7C,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,CACJ,oBAAoB,CAAC;YACnB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC;SACvD,CAAC,CACH,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,GAAG,EAAE,CACV,oBAAoB,CAAC;YACnB,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC;SACvD,CAAC,CACH,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,EAAE,CAAC,
|
|
1
|
+
{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@melra/sdk",
|
|
3
|
-
"version": "0.3.0-alpha.
|
|
3
|
+
"version": "0.3.0-alpha.5",
|
|
4
4
|
"description": "TypeScript task and workflow client SDK for MELRA.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
],
|
|
23
23
|
"dependencies": {
|
|
24
24
|
"@modelcontextprotocol/sdk": "1.30.0",
|
|
25
|
-
"@melra/protocol": "0.3.0-alpha.
|
|
25
|
+
"@melra/protocol": "0.3.0-alpha.5"
|
|
26
26
|
},
|
|
27
27
|
"scripts": {
|
|
28
28
|
"build": "tsc -p tsconfig.json",
|