@mgcrea/mcp-apple-core 1.14.0 → 1.16.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/dist/index.d.ts +143 -21
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +816 -132
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,26 +1,8 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
2
|
import { DatabaseSync } from "node:sqlite";
|
|
3
3
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
name: string;
|
|
7
|
-
version: string;
|
|
8
|
-
};
|
|
9
|
-
type BuildInfo = PackageIdentity & {
|
|
10
|
-
gitCommit: string;
|
|
11
|
-
gitCommitDate: string;
|
|
12
|
-
};
|
|
13
|
-
/**
|
|
14
|
-
* Read a package's own name and version at startup, so they are always accurate
|
|
15
|
-
* rather than baked in at build time.
|
|
16
|
-
*
|
|
17
|
-
* Callers pass their own `new URL("../package.json", import.meta.url)`: resolving
|
|
18
|
-
* it here would find *this* package, not theirs. The git fields stay with the
|
|
19
|
-
* caller too, because `__GIT_COMMIT__` is substituted by whichever bundler build
|
|
20
|
-
* compiles the file that mentions it.
|
|
21
|
-
*/
|
|
22
|
-
declare const readPackageIdentity: (packageJsonUrl: URL, fallback: PackageIdentity) => PackageIdentity;
|
|
23
|
-
//#endregion
|
|
4
|
+
import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
|
|
5
|
+
import { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
|
|
24
6
|
//#region src/errors.d.ts
|
|
25
7
|
/**
|
|
26
8
|
* Error taxonomy shared by every Apple-app server.
|
|
@@ -104,6 +86,106 @@ declare class PreconditionError extends AppleAutomationError {
|
|
|
104
86
|
readonly name: string;
|
|
105
87
|
}
|
|
106
88
|
//#endregion
|
|
89
|
+
//#region src/ax.d.ts
|
|
90
|
+
type AxCall = {
|
|
91
|
+
/** Tool name, e.g. `apple_desktop_find_elements`. */
|
|
92
|
+
readonly tool: string;
|
|
93
|
+
readonly args: Record<string, unknown>;
|
|
94
|
+
};
|
|
95
|
+
type AxChannel = {
|
|
96
|
+
/**
|
|
97
|
+
* Call one desktop tool and return its parsed JSON body.
|
|
98
|
+
*
|
|
99
|
+
* Calls are serialised. The wire is one socket carrying newline-delimited
|
|
100
|
+
* JSON-RPC, and the driver's handle store is shared mutable state on the other
|
|
101
|
+
* end, so overlapping two walks would interleave both.
|
|
102
|
+
*/
|
|
103
|
+
call(request: AxCall): Promise<unknown>;
|
|
104
|
+
close(): void;
|
|
105
|
+
};
|
|
106
|
+
/**
|
|
107
|
+
* The app is there and said no, or stopped answering.
|
|
108
|
+
*
|
|
109
|
+
* Distinct from the null `openAxChannel` returns, which means there is no app
|
|
110
|
+
* to ask — see the note there on why those two must not collapse.
|
|
111
|
+
*/
|
|
112
|
+
declare class AxChannelError extends AppleAutomationError {
|
|
113
|
+
readonly name: string;
|
|
114
|
+
constructor(surface: SurfaceContext, message: string);
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* Open the channel, or return null when this server is not hosted by the app.
|
|
118
|
+
*
|
|
119
|
+
* Null and a throw are different answers and the difference is the whole
|
|
120
|
+
* contract: null means "there is no app here, use your other lane", a throw
|
|
121
|
+
* means "there is an app and it said no", which a caller must report rather
|
|
122
|
+
* than paper over.
|
|
123
|
+
*/
|
|
124
|
+
declare const openAxChannel: (surface: SurfaceContext, env?: NodeJS.ProcessEnv) => AxChannel | null;
|
|
125
|
+
/**
|
|
126
|
+
* Whether a person touched the machine while a sequence was running.
|
|
127
|
+
*
|
|
128
|
+
* Driving an interface is the one capability here that COMPETES with whoever is
|
|
129
|
+
* using the Mac: a keystroke goes to whatever is frontmost and a click goes to a
|
|
130
|
+
* screen point, so somebody typing during a paste does not slow it down, it
|
|
131
|
+
* corrupts it.
|
|
132
|
+
*
|
|
133
|
+
* The comparison is what makes this work. `secondsSinceInput` on its own cannot
|
|
134
|
+
* tell "they typed just before we started" from "they typed into the middle of
|
|
135
|
+
* it" — but a sequence that ran for five seconds and ends with two seconds since
|
|
136
|
+
* the last input knows the input landed inside it.
|
|
137
|
+
*
|
|
138
|
+
* **This exists because of a misdiagnosis, not a theory.** Two runs of the Maps
|
|
139
|
+
* lane were blamed on interference and turned out to be bugs in the lane; one
|
|
140
|
+
* was blamed on the lane and turned out to be interference. Neither could be
|
|
141
|
+
* told apart from the outside, and a failure that names the wrong cause sends
|
|
142
|
+
* the next hour in the wrong direction.
|
|
143
|
+
*/
|
|
144
|
+
type Interference = {
|
|
145
|
+
/** True when input arrived after the sequence began. */
|
|
146
|
+
disturbed: boolean;
|
|
147
|
+
secondsSinceInput: number;
|
|
148
|
+
elapsedSeconds: number;
|
|
149
|
+
};
|
|
150
|
+
type InterferenceWatch = {
|
|
151
|
+
check(): Promise<Interference | null>;
|
|
152
|
+
};
|
|
153
|
+
/**
|
|
154
|
+
* Start watching. `check()` answers for the span since this call.
|
|
155
|
+
*
|
|
156
|
+
* Returns null from `check()` when the question could not be asked at all,
|
|
157
|
+
* which is not the same as "undisturbed" and must not be reported as it.
|
|
158
|
+
*/
|
|
159
|
+
declare const watchInterference: (channel: AxChannel) => InterferenceWatch;
|
|
160
|
+
/**
|
|
161
|
+
* The sentence to append to a failure, or "" when nothing useful can be said.
|
|
162
|
+
*
|
|
163
|
+
* Deliberately says nothing when the machine was quiet: a failure that reads
|
|
164
|
+
* "nobody touched it" invites the reader to stop looking, and the point of this
|
|
165
|
+
* is to send them to the RIGHT place rather than to reassure them.
|
|
166
|
+
*/
|
|
167
|
+
declare const interferenceNote: (found: Interference | null) => string;
|
|
168
|
+
//#endregion
|
|
169
|
+
//#region src/build-info.d.ts
|
|
170
|
+
type PackageIdentity = {
|
|
171
|
+
name: string;
|
|
172
|
+
version: string;
|
|
173
|
+
};
|
|
174
|
+
type BuildInfo = PackageIdentity & {
|
|
175
|
+
gitCommit: string;
|
|
176
|
+
gitCommitDate: string;
|
|
177
|
+
};
|
|
178
|
+
/**
|
|
179
|
+
* Read a package's own name and version at startup, so they are always accurate
|
|
180
|
+
* rather than baked in at build time.
|
|
181
|
+
*
|
|
182
|
+
* Callers pass their own `new URL("../package.json", import.meta.url)`: resolving
|
|
183
|
+
* it here would find *this* package, not theirs. The git fields stay with the
|
|
184
|
+
* caller too, because `__GIT_COMMIT__` is substituted by whichever bundler build
|
|
185
|
+
* compiles the file that mentions it.
|
|
186
|
+
*/
|
|
187
|
+
declare const readPackageIdentity: (packageJsonUrl: URL, fallback: PackageIdentity) => PackageIdentity;
|
|
188
|
+
//#endregion
|
|
107
189
|
//#region src/osascript.d.ts
|
|
108
190
|
type Logger = {
|
|
109
191
|
debug?: (...args: unknown[]) => void;
|
|
@@ -293,6 +375,7 @@ declare const parseList: (v: string | undefined) => string[] | undefined;
|
|
|
293
375
|
declare const BaseConfigSchema: z.ZodObject<{
|
|
294
376
|
allowWrites: z.ZodDefault<z.ZodBoolean>;
|
|
295
377
|
exposePrompts: z.ZodDefault<z.ZodBoolean>;
|
|
378
|
+
lazyTools: z.ZodDefault<z.ZodBoolean>;
|
|
296
379
|
debug: z.ZodDefault<z.ZodBoolean>;
|
|
297
380
|
osascriptPath: z.ZodDefault<z.ZodString>;
|
|
298
381
|
osascriptTimeoutMs: z.ZodDefault<z.ZodNumber>;
|
|
@@ -306,6 +389,25 @@ declare const BaseConfigSchema: z.ZodObject<{
|
|
|
306
389
|
*/
|
|
307
390
|
declare const parseConfig: <T extends z.ZodType>(schema: T, raw: Record<string, unknown>) => z.infer<T>;
|
|
308
391
|
//#endregion
|
|
392
|
+
//#region src/facade.d.ts
|
|
393
|
+
type LazyToolsOptions = {
|
|
394
|
+
/** Surface id as in surfaces.json, e.g. "mail". Prefixes every facade name. */
|
|
395
|
+
surface: string;
|
|
396
|
+
/** Display name, e.g. "Mail". Used only in the facade's own descriptions. */
|
|
397
|
+
displayName: string;
|
|
398
|
+
lazy: boolean;
|
|
399
|
+
allowWrites: boolean;
|
|
400
|
+
};
|
|
401
|
+
/**
|
|
402
|
+
* Register a surface's tools, either directly or behind the facade.
|
|
403
|
+
*
|
|
404
|
+
* The callback takes `allowWrites` rather than closing over it so the facade
|
|
405
|
+
* can run it a second time with the gate forced shut and learn which tools are
|
|
406
|
+
* writes. Everything else it needs — the client, the config — it closes over as
|
|
407
|
+
* before.
|
|
408
|
+
*/
|
|
409
|
+
declare const withLazyTools: (server: McpServer, opts: LazyToolsOptions, register: (target: McpServer, allowWrites: boolean) => void) => void;
|
|
410
|
+
//#endregion
|
|
309
411
|
//#region src/fs.d.ts
|
|
310
412
|
/**
|
|
311
413
|
* Facts about a TCC-protected file.
|
|
@@ -337,6 +439,26 @@ type StoreFacts = FileFacts & {
|
|
|
337
439
|
*/
|
|
338
440
|
declare const describeStore: (path: string) => StoreFacts;
|
|
339
441
|
//#endregion
|
|
442
|
+
//#region src/listing.d.ts
|
|
443
|
+
/**
|
|
444
|
+
* Strip generated boilerplate from a `tools/list` reply, passing every other
|
|
445
|
+
* message through untouched.
|
|
446
|
+
*
|
|
447
|
+
* Copies rather than mutates. The SDK hands out the registered tool's own
|
|
448
|
+
* schema object, and deleting a key from it would edit the server's state from
|
|
449
|
+
* a function whose job is to shape one reply.
|
|
450
|
+
*/
|
|
451
|
+
declare const trimToolListing: (message: JSONRPCMessage) => JSONRPCMessage;
|
|
452
|
+
/**
|
|
453
|
+
* Wrap a transport so every listing it sends is trimmed on the way out.
|
|
454
|
+
*
|
|
455
|
+
* Mutates and returns the transport it was given rather than proxying it: the
|
|
456
|
+
* SDK's `connect` reaches for `onmessage`, `onclose` and `onerror` on the very
|
|
457
|
+
* object it was handed, and a Proxy or a subclass would have to keep those in
|
|
458
|
+
* sync for no gain.
|
|
459
|
+
*/
|
|
460
|
+
declare const withTrimmedListing: <T extends Transport>(transport: T) => T;
|
|
461
|
+
//#endregion
|
|
340
462
|
//#region src/prompts.d.ts
|
|
341
463
|
/**
|
|
342
464
|
* The workflow prompts.
|
|
@@ -658,5 +780,5 @@ declare const limitArg: z.ZodOptional<z.ZodNumber>;
|
|
|
658
780
|
declare const resolveLimit: (limit: number | undefined, maxResults: number, fallback?: number) => number;
|
|
659
781
|
declare const confirmArg: z.ZodLiteral<true>;
|
|
660
782
|
//#endregion
|
|
661
|
-
export { type Aggregation, AppBusyError, AppNotRunningError, AppleAutomationError, BaseConfigSchema, type Bucket, type BuildInfo, CORE_DATA_EPOCH_OFFSET, type CodeConfidence, type CodeMatch, type ExecImpl, type ExtractOptions, type FileFacts, IndexUnavailableError, type JxaEnvelope, type Logger, type OpenOptions, type OpenedStore, type OsascriptOptions, type OsascriptRunner, OsascriptTimeoutError, type PackageIdentity, PlatformError, PreconditionError, type Projected, type PromptContext, ProtocolError, RESOURCE_SCHEME, type ReadOnlyMode, type ResourceReader, SchemaDriftError, type StdioServerOptions, type StoreFacts, type SurfaceContext, type SurfaceResourceOptions, TccDeniedError, type ToolResult, type WorkflowPrompt, WritesDisabledError, assertStaticScript, columnsOf, compact, confirmArg, createOsascriptRunner, describeAggregation, describeStore, detectEpoch, escapeLike, extractCode, fail, fingerprintSchema, groupByArg, inspectFile, limitArg, mapOsaError, ok, okText, openReadOnly, parseBool, parseConfig, parseIntOpt, parseList, project, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, runStdioServer, selectArg, surfaceUri, tableMap, toFailure, toFileUri, trimmed, withBusyRetry, wrap, wrapResult };
|
|
783
|
+
export { type Aggregation, AppBusyError, AppNotRunningError, AppleAutomationError, type AxCall, type AxChannel, AxChannelError, BaseConfigSchema, type Bucket, type BuildInfo, CORE_DATA_EPOCH_OFFSET, type CodeConfidence, type CodeMatch, type ExecImpl, type ExtractOptions, type FileFacts, IndexUnavailableError, type Interference, type InterferenceWatch, type JxaEnvelope, type LazyToolsOptions, type Logger, type OpenOptions, type OpenedStore, type OsascriptOptions, type OsascriptRunner, OsascriptTimeoutError, type PackageIdentity, PlatformError, PreconditionError, type Projected, type PromptContext, ProtocolError, RESOURCE_SCHEME, type ReadOnlyMode, type ResourceReader, SchemaDriftError, type StdioServerOptions, type StoreFacts, type SurfaceContext, type SurfaceResourceOptions, TccDeniedError, type ToolResult, type WorkflowPrompt, WritesDisabledError, assertStaticScript, columnsOf, compact, confirmArg, createOsascriptRunner, describeAggregation, describeStore, detectEpoch, escapeLike, extractCode, fail, fingerprintSchema, groupByArg, inspectFile, interferenceNote, limitArg, mapOsaError, ok, okText, openAxChannel, openReadOnly, parseBool, parseConfig, parseIntOpt, parseList, project, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, runStdioServer, selectArg, surfaceUri, tableMap, toFailure, toFileUri, trimToolListing, trimmed, watchInterference, withBusyRetry, withLazyTools, withTrimmedListing, wrap, wrapResult };
|
|
662
784
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/errors.ts","../src/ax.ts","../src/build-info.ts","../src/osascript.ts","../src/cli.ts","../src/codes.ts","../src/config.ts","../src/facade.ts","../src/fs.ts","../src/listing.ts","../src/prompts.ts","../src/query.ts","../src/resources.ts","../src/schema.ts","../src/sqlite.ts","../src/tools.ts"],"mappings":"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"}
|