@statelyai/mcp 0.3.2 → 0.4.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.
Files changed (6) hide show
  1. package/README.md +61 -5
  2. package/dist/index.cjs +520 -30
  3. package/dist/index.d.cts +166 -1
  4. package/dist/index.d.mts +166 -1
  5. package/dist/index.mjs +515 -31
  6. package/package.json +4 -3
package/dist/index.d.cts CHANGED
@@ -1,5 +1,138 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import { z } from "zod";
2
3
 
4
+ //#region ../api-contract/dist/errors.d.mts
5
+ /**
6
+ * Canonical error codes for the `/api/v1` resource operations. Machine
7
+ * operations keep the flat `{ error: string }` shape above unchanged; the
8
+ * nested envelope below applies to resource operations only.
9
+ */
10
+ declare const resourceErrorCodeSchema: z.ZodEnum<{
11
+ bad_request: "bad_request";
12
+ unauthenticated: "unauthenticated";
13
+ forbidden: "forbidden";
14
+ not_found: "not_found";
15
+ conflict: "conflict";
16
+ payload_too_large: "payload_too_large";
17
+ rate_limited: "rate_limited";
18
+ capability_disabled: "capability_disabled";
19
+ upstream_error: "upstream_error";
20
+ internal_error: "internal_error";
21
+ }>;
22
+ type ResourceErrorCode = z.infer<typeof resourceErrorCodeSchema>;
23
+ /** Factory, matching `createApiErrorResponseSchema`, for per-route OpenAPI components. */
24
+ //#endregion
25
+ //#region ../api-contract/dist/resources.d.mts
26
+ declare const projectSummarySchema: z.ZodObject<{
27
+ projectId: z.ZodString;
28
+ projectVersionId: z.ZodString;
29
+ name: z.ZodString;
30
+ description: z.ZodNullable<z.ZodString>;
31
+ visibility: z.ZodEnum<{
32
+ public: "public";
33
+ unlisted: "unlisted";
34
+ private: "private";
35
+ }>;
36
+ createdAt: z.ZodString;
37
+ updatedAt: z.ZodString;
38
+ }, z.core.$strip>;
39
+ type ProjectSummary = z.infer<typeof projectSummarySchema>;
40
+ declare const projectSchema: z.ZodObject<{
41
+ projectId: z.ZodString;
42
+ projectVersionId: z.ZodString;
43
+ name: z.ZodString;
44
+ description: z.ZodNullable<z.ZodString>;
45
+ visibility: z.ZodEnum<{
46
+ public: "public";
47
+ unlisted: "unlisted";
48
+ private: "private";
49
+ }>;
50
+ createdAt: z.ZodString;
51
+ updatedAt: z.ZodString;
52
+ rootMachineId: z.ZodNullable<z.ZodString>;
53
+ machines: z.ZodArray<z.ZodObject<{
54
+ machineId: z.ZodString;
55
+ }, z.core.$strip>>;
56
+ }, z.core.$strip>;
57
+ type Project = z.infer<typeof projectSchema>;
58
+ /**
59
+ * `name` is optional: the Registry project envelope only returns machine ids.
60
+ * Providers that can supply names cheaply should.
61
+ */
62
+ declare const projectMachineSummarySchema: z.ZodObject<{
63
+ machineId: z.ZodString;
64
+ name: z.ZodOptional<z.ZodString>;
65
+ }, z.core.$strip>;
66
+ type ProjectMachineSummary = z.infer<typeof projectMachineSummarySchema>;
67
+ declare const machineSchema: z.ZodObject<{
68
+ machineId: z.ZodString;
69
+ name: z.ZodString;
70
+ projectId: z.ZodOptional<z.ZodString>;
71
+ projectVersionId: z.ZodString;
72
+ definition: z.ZodUnknown;
73
+ createdAt: z.ZodOptional<z.ZodString>;
74
+ updatedAt: z.ZodOptional<z.ZodString>;
75
+ }, z.core.$strip>;
76
+ type Machine = z.infer<typeof machineSchema>;
77
+ //#endregion
78
+ //#region src/resourceClient.d.ts
79
+ type ResourceCallOptions = {
80
+ signal?: AbortSignal;
81
+ };
82
+ /** Canonical error surfaced by every `ResourceClient` implementation. */
83
+ declare class ResourceClientError extends Error {
84
+ readonly code: ResourceErrorCode;
85
+ readonly issues?: unknown[];
86
+ readonly retryable?: boolean;
87
+ constructor(code: ResourceErrorCode, message: string, options?: {
88
+ issues?: unknown[];
89
+ retryable?: boolean;
90
+ cause?: unknown;
91
+ });
92
+ }
93
+ declare function isResourceClientError(value: unknown): value is ResourceClientError;
94
+ /** Read-only port over the owned `/api/v1` resource contract. */
95
+ type ResourceClient = {
96
+ listProjects(options?: ResourceCallOptions): Promise<ProjectSummary[]>;
97
+ getProject(projectId: string, options?: ResourceCallOptions): Promise<Project>;
98
+ listProjectMachines(projectId: string, options?: ResourceCallOptions): Promise<ProjectMachineSummary[]>;
99
+ getMachine(machineId: string, options?: ResourceCallOptions): Promise<Machine>;
100
+ };
101
+ /**
102
+ * Base URL of the owned v1 resource routes, derived from the same
103
+ * `apiBaseUrl` option the machine tools use.
104
+ *
105
+ * `apiBaseUrl` conventionally already ends in `/api` (the default is
106
+ * `https://editor.stately.ai/api`, and Studio's proxy passes that), so the
107
+ * rules are explicit and never double a segment:
108
+ *
109
+ * - ends in `/v1` -> used as-is
110
+ * - ends in `/api` -> `+ /v1`
111
+ * - anything else (e.g. a bare origin) -> `+ /api/v1`
112
+ */
113
+ declare function resourceApiV1BaseUrl(apiBaseUrl?: string | URL): string;
114
+ type HttpResourceClientOptions = {
115
+ apiBaseUrl?: string | URL; /** Static headers (e.g. a forwarded `Authorization`). */
116
+ headers?: HeadersInit; /** Per-request headers; takes precedence over `headers` when both are set. */
117
+ getHeaders?: () => HeadersInit | Promise<HeadersInit>; /** Injectable for tests. */
118
+ fetch?: typeof fetch;
119
+ };
120
+ /**
121
+ * HTTP-backed `ResourceClient` over the owned routes:
122
+ * `GET /api/v1/projects`, `/api/v1/projects/:projectId`,
123
+ * `/api/v1/projects/:projectId/machines` and `/api/v1/machines/:machineId`.
124
+ */
125
+ declare function createHttpResourceClient(options?: HttpResourceClientOptions): ResourceClient;
126
+ //#endregion
127
+ //#region src/toolCallObserver.d.ts
128
+ type StatelyMcpToolCallEvent = Readonly<{
129
+ toolName: string;
130
+ outcome: 'success' | 'error';
131
+ durationMs: number;
132
+ errorCode?: string;
133
+ }>;
134
+ type StatelyMcpToolCallObserver = (event: StatelyMcpToolCallEvent) => void | Promise<void>;
135
+ //#endregion
3
136
  //#region src/server.d.ts
4
137
  declare const readOnlyAnnotations: {
5
138
  readOnlyHint: boolean;
@@ -14,6 +147,19 @@ type StatelyMcpServerOptions = {
14
147
  credentialProvider?: () => StatelyCredential | undefined | Promise<StatelyCredential | undefined>;
15
148
  authMode?: 'auto' | 'none' | 'bearer';
16
149
  anonymousGraphPathLimit?: number;
150
+ /**
151
+ * Port used by the hosted resource tools (`list_stately_projects` etc.).
152
+ * When omitted, an HTTP-backed client is derived from `apiBaseUrl` and
153
+ * `apiHeaders`/`credentialProvider`. Pass an explicit client to host MCP
154
+ * in-process over a local resource service.
155
+ */
156
+ resourceClient?: ResourceClient; /** Set to `false` to omit the hosted resource tools entirely. */
157
+ includeResourceTools?: boolean;
158
+ /**
159
+ * Optional, content-free tool completion observer supplied by the host.
160
+ * Omitted by default; observer failures never affect tool results.
161
+ */
162
+ onToolCall?: StatelyMcpToolCallObserver;
17
163
  };
18
164
  type StatelyCredential = {
19
165
  type: 'api_key';
@@ -42,6 +188,25 @@ declare function generateTestCode(machineCode: string, paths: GraphPath[]): stri
42
188
  declare function registerStatelyMcpTools(server: McpServer, options?: StatelyMcpServerOptions): McpServer;
43
189
  declare function createStatelyMcpServer(options?: StatelyMcpServerOptions): McpServer;
44
190
  //#endregion
191
+ //#region src/resourceTools.d.ts
192
+ /** Read-only, non-destructive; hosted resources are an open world. */
193
+ declare const resourceReadOnlyAnnotations: {
194
+ readOnlyHint: boolean;
195
+ destructiveHint: boolean;
196
+ idempotentHint: boolean;
197
+ openWorldHint: boolean;
198
+ };
199
+ /**
200
+ * Resolves the client for a call. Returning `undefined` (no service, no
201
+ * credentials, `RESOURCE_PROVIDER=none`) must not break tool listing: the
202
+ * tools stay registered and fail with `capability_disabled` when called.
203
+ */
204
+ type ResourceClientResolver = () => ResourceClient | undefined | Promise<ResourceClient | undefined>;
205
+ type StatelyResourceToolOptions = {
206
+ onToolCall?: StatelyMcpToolCallObserver;
207
+ };
208
+ declare function registerStatelyResourceTools(server: McpServer, resolveClient: ResourceClientResolver, options?: StatelyResourceToolOptions): McpServer;
209
+ //#endregion
45
210
  //#region src/index.d.ts
46
211
  declare function workspaceFromArgv(): string;
47
212
  declare function isCandidate(pathname: string): boolean;
@@ -69,4 +234,4 @@ declare function getDefaultCredential(): Promise<{
69
234
  } | undefined>;
70
235
  declare function createStatelyMcpServer$1(options?: StatelyMcpServerOptions): McpServer;
71
236
  //#endregion
72
- export { type StatelyMcpServerOptions, createStatelyMcpServer as createHostedStatelyMcpServer, createStatelyMcpServer$1 as createStatelyMcpServer, formatForPath, generateTestCode, getDefaultCredential, isCandidate, readOnlyAnnotations, readWorkspaceMachine, registerStatelyMcpTools, walkWorkspace, workspaceFromArgv };
237
+ export { type HttpResourceClientOptions, type ResourceCallOptions, type ResourceClient, ResourceClientError, type ResourceClientResolver, type StatelyMcpServerOptions, type StatelyMcpToolCallEvent, type StatelyMcpToolCallObserver, type StatelyResourceToolOptions, createStatelyMcpServer as createHostedStatelyMcpServer, createHttpResourceClient, createStatelyMcpServer$1 as createStatelyMcpServer, formatForPath, generateTestCode, getDefaultCredential, isCandidate, isResourceClientError, readOnlyAnnotations, readWorkspaceMachine, registerStatelyMcpTools, registerStatelyResourceTools, resourceApiV1BaseUrl, resourceReadOnlyAnnotations, walkWorkspace, workspaceFromArgv };
package/dist/index.d.mts CHANGED
@@ -1,5 +1,138 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import { z } from "zod";
2
3
 
4
+ //#region ../api-contract/dist/errors.d.mts
5
+ /**
6
+ * Canonical error codes for the `/api/v1` resource operations. Machine
7
+ * operations keep the flat `{ error: string }` shape above unchanged; the
8
+ * nested envelope below applies to resource operations only.
9
+ */
10
+ declare const resourceErrorCodeSchema: z.ZodEnum<{
11
+ bad_request: "bad_request";
12
+ unauthenticated: "unauthenticated";
13
+ forbidden: "forbidden";
14
+ not_found: "not_found";
15
+ conflict: "conflict";
16
+ payload_too_large: "payload_too_large";
17
+ rate_limited: "rate_limited";
18
+ capability_disabled: "capability_disabled";
19
+ upstream_error: "upstream_error";
20
+ internal_error: "internal_error";
21
+ }>;
22
+ type ResourceErrorCode = z.infer<typeof resourceErrorCodeSchema>;
23
+ /** Factory, matching `createApiErrorResponseSchema`, for per-route OpenAPI components. */
24
+ //#endregion
25
+ //#region ../api-contract/dist/resources.d.mts
26
+ declare const projectSummarySchema: z.ZodObject<{
27
+ projectId: z.ZodString;
28
+ projectVersionId: z.ZodString;
29
+ name: z.ZodString;
30
+ description: z.ZodNullable<z.ZodString>;
31
+ visibility: z.ZodEnum<{
32
+ public: "public";
33
+ unlisted: "unlisted";
34
+ private: "private";
35
+ }>;
36
+ createdAt: z.ZodString;
37
+ updatedAt: z.ZodString;
38
+ }, z.core.$strip>;
39
+ type ProjectSummary = z.infer<typeof projectSummarySchema>;
40
+ declare const projectSchema: z.ZodObject<{
41
+ projectId: z.ZodString;
42
+ projectVersionId: z.ZodString;
43
+ name: z.ZodString;
44
+ description: z.ZodNullable<z.ZodString>;
45
+ visibility: z.ZodEnum<{
46
+ public: "public";
47
+ unlisted: "unlisted";
48
+ private: "private";
49
+ }>;
50
+ createdAt: z.ZodString;
51
+ updatedAt: z.ZodString;
52
+ rootMachineId: z.ZodNullable<z.ZodString>;
53
+ machines: z.ZodArray<z.ZodObject<{
54
+ machineId: z.ZodString;
55
+ }, z.core.$strip>>;
56
+ }, z.core.$strip>;
57
+ type Project = z.infer<typeof projectSchema>;
58
+ /**
59
+ * `name` is optional: the Registry project envelope only returns machine ids.
60
+ * Providers that can supply names cheaply should.
61
+ */
62
+ declare const projectMachineSummarySchema: z.ZodObject<{
63
+ machineId: z.ZodString;
64
+ name: z.ZodOptional<z.ZodString>;
65
+ }, z.core.$strip>;
66
+ type ProjectMachineSummary = z.infer<typeof projectMachineSummarySchema>;
67
+ declare const machineSchema: z.ZodObject<{
68
+ machineId: z.ZodString;
69
+ name: z.ZodString;
70
+ projectId: z.ZodOptional<z.ZodString>;
71
+ projectVersionId: z.ZodString;
72
+ definition: z.ZodUnknown;
73
+ createdAt: z.ZodOptional<z.ZodString>;
74
+ updatedAt: z.ZodOptional<z.ZodString>;
75
+ }, z.core.$strip>;
76
+ type Machine = z.infer<typeof machineSchema>;
77
+ //#endregion
78
+ //#region src/resourceClient.d.ts
79
+ type ResourceCallOptions = {
80
+ signal?: AbortSignal;
81
+ };
82
+ /** Canonical error surfaced by every `ResourceClient` implementation. */
83
+ declare class ResourceClientError extends Error {
84
+ readonly code: ResourceErrorCode;
85
+ readonly issues?: unknown[];
86
+ readonly retryable?: boolean;
87
+ constructor(code: ResourceErrorCode, message: string, options?: {
88
+ issues?: unknown[];
89
+ retryable?: boolean;
90
+ cause?: unknown;
91
+ });
92
+ }
93
+ declare function isResourceClientError(value: unknown): value is ResourceClientError;
94
+ /** Read-only port over the owned `/api/v1` resource contract. */
95
+ type ResourceClient = {
96
+ listProjects(options?: ResourceCallOptions): Promise<ProjectSummary[]>;
97
+ getProject(projectId: string, options?: ResourceCallOptions): Promise<Project>;
98
+ listProjectMachines(projectId: string, options?: ResourceCallOptions): Promise<ProjectMachineSummary[]>;
99
+ getMachine(machineId: string, options?: ResourceCallOptions): Promise<Machine>;
100
+ };
101
+ /**
102
+ * Base URL of the owned v1 resource routes, derived from the same
103
+ * `apiBaseUrl` option the machine tools use.
104
+ *
105
+ * `apiBaseUrl` conventionally already ends in `/api` (the default is
106
+ * `https://editor.stately.ai/api`, and Studio's proxy passes that), so the
107
+ * rules are explicit and never double a segment:
108
+ *
109
+ * - ends in `/v1` -> used as-is
110
+ * - ends in `/api` -> `+ /v1`
111
+ * - anything else (e.g. a bare origin) -> `+ /api/v1`
112
+ */
113
+ declare function resourceApiV1BaseUrl(apiBaseUrl?: string | URL): string;
114
+ type HttpResourceClientOptions = {
115
+ apiBaseUrl?: string | URL; /** Static headers (e.g. a forwarded `Authorization`). */
116
+ headers?: HeadersInit; /** Per-request headers; takes precedence over `headers` when both are set. */
117
+ getHeaders?: () => HeadersInit | Promise<HeadersInit>; /** Injectable for tests. */
118
+ fetch?: typeof fetch;
119
+ };
120
+ /**
121
+ * HTTP-backed `ResourceClient` over the owned routes:
122
+ * `GET /api/v1/projects`, `/api/v1/projects/:projectId`,
123
+ * `/api/v1/projects/:projectId/machines` and `/api/v1/machines/:machineId`.
124
+ */
125
+ declare function createHttpResourceClient(options?: HttpResourceClientOptions): ResourceClient;
126
+ //#endregion
127
+ //#region src/toolCallObserver.d.ts
128
+ type StatelyMcpToolCallEvent = Readonly<{
129
+ toolName: string;
130
+ outcome: 'success' | 'error';
131
+ durationMs: number;
132
+ errorCode?: string;
133
+ }>;
134
+ type StatelyMcpToolCallObserver = (event: StatelyMcpToolCallEvent) => void | Promise<void>;
135
+ //#endregion
3
136
  //#region src/server.d.ts
4
137
  declare const readOnlyAnnotations: {
5
138
  readOnlyHint: boolean;
@@ -14,6 +147,19 @@ type StatelyMcpServerOptions = {
14
147
  credentialProvider?: () => StatelyCredential | undefined | Promise<StatelyCredential | undefined>;
15
148
  authMode?: 'auto' | 'none' | 'bearer';
16
149
  anonymousGraphPathLimit?: number;
150
+ /**
151
+ * Port used by the hosted resource tools (`list_stately_projects` etc.).
152
+ * When omitted, an HTTP-backed client is derived from `apiBaseUrl` and
153
+ * `apiHeaders`/`credentialProvider`. Pass an explicit client to host MCP
154
+ * in-process over a local resource service.
155
+ */
156
+ resourceClient?: ResourceClient; /** Set to `false` to omit the hosted resource tools entirely. */
157
+ includeResourceTools?: boolean;
158
+ /**
159
+ * Optional, content-free tool completion observer supplied by the host.
160
+ * Omitted by default; observer failures never affect tool results.
161
+ */
162
+ onToolCall?: StatelyMcpToolCallObserver;
17
163
  };
18
164
  type StatelyCredential = {
19
165
  type: 'api_key';
@@ -42,6 +188,25 @@ declare function generateTestCode(machineCode: string, paths: GraphPath[]): stri
42
188
  declare function registerStatelyMcpTools(server: McpServer, options?: StatelyMcpServerOptions): McpServer;
43
189
  declare function createStatelyMcpServer(options?: StatelyMcpServerOptions): McpServer;
44
190
  //#endregion
191
+ //#region src/resourceTools.d.ts
192
+ /** Read-only, non-destructive; hosted resources are an open world. */
193
+ declare const resourceReadOnlyAnnotations: {
194
+ readOnlyHint: boolean;
195
+ destructiveHint: boolean;
196
+ idempotentHint: boolean;
197
+ openWorldHint: boolean;
198
+ };
199
+ /**
200
+ * Resolves the client for a call. Returning `undefined` (no service, no
201
+ * credentials, `RESOURCE_PROVIDER=none`) must not break tool listing: the
202
+ * tools stay registered and fail with `capability_disabled` when called.
203
+ */
204
+ type ResourceClientResolver = () => ResourceClient | undefined | Promise<ResourceClient | undefined>;
205
+ type StatelyResourceToolOptions = {
206
+ onToolCall?: StatelyMcpToolCallObserver;
207
+ };
208
+ declare function registerStatelyResourceTools(server: McpServer, resolveClient: ResourceClientResolver, options?: StatelyResourceToolOptions): McpServer;
209
+ //#endregion
45
210
  //#region src/index.d.ts
46
211
  declare function workspaceFromArgv(): string;
47
212
  declare function isCandidate(pathname: string): boolean;
@@ -69,4 +234,4 @@ declare function getDefaultCredential(): Promise<{
69
234
  } | undefined>;
70
235
  declare function createStatelyMcpServer$1(options?: StatelyMcpServerOptions): McpServer;
71
236
  //#endregion
72
- export { type StatelyMcpServerOptions, createStatelyMcpServer as createHostedStatelyMcpServer, createStatelyMcpServer$1 as createStatelyMcpServer, formatForPath, generateTestCode, getDefaultCredential, isCandidate, readOnlyAnnotations, readWorkspaceMachine, registerStatelyMcpTools, walkWorkspace, workspaceFromArgv };
237
+ export { type HttpResourceClientOptions, type ResourceCallOptions, type ResourceClient, ResourceClientError, type ResourceClientResolver, type StatelyMcpServerOptions, type StatelyMcpToolCallEvent, type StatelyMcpToolCallObserver, type StatelyResourceToolOptions, createStatelyMcpServer as createHostedStatelyMcpServer, createHttpResourceClient, createStatelyMcpServer$1 as createStatelyMcpServer, formatForPath, generateTestCode, getDefaultCredential, isCandidate, isResourceClientError, readOnlyAnnotations, readWorkspaceMachine, registerStatelyMcpTools, registerStatelyResourceTools, resourceApiV1BaseUrl, resourceReadOnlyAnnotations, walkWorkspace, workspaceFromArgv };