@roam-research/roam-tools-core 0.6.4 → 0.6.6
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 +3 -3
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/operations/blocks.d.ts +12 -12
- package/dist/operations/blocks.d.ts.map +1 -1
- package/dist/operations/blocks.js +4 -1
- package/dist/operations/files.d.ts +2 -2
- package/dist/operations/navigation.d.ts +4 -4
- package/dist/operations/pages.d.ts +4 -4
- package/dist/operations/query.d.ts +8 -8
- package/dist/operations/search.d.ts +4 -4
- package/dist/tools.d.ts +14 -5
- package/dist/tools.d.ts.map +1 -1
- package/dist/tools.js +83 -26
- package/dist/types.d.ts +4 -4
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +4 -5
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# @roam-research/roam-tools-core
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The official transport-agnostic core for Roam Research's MCP and CLI tools. Provides the tool registry, schemas, operation functions, and dispatch — but no transport.
|
|
4
4
|
|
|
5
5
|
> **Most users don't want this package directly.** If you want to connect an AI assistant to Roam, install [`@roam-research/roam-mcp`](https://www.npmjs.com/package/@roam-research/roam-mcp). For the command line, install [`@roam-research/roam-cli`](https://www.npmjs.com/package/@roam-research/roam-cli). Both wrap the local Roam Desktop transport ([`@roam-research/roam-tools-local`](https://www.npmjs.com/package/@roam-research/roam-tools-local)) which depends on this package.
|
|
6
6
|
|
|
7
7
|
## Who is this for?
|
|
8
8
|
|
|
9
|
-
This package is for **hosted MCP transports** that talk to Roam through a different backend (e.g.,
|
|
9
|
+
This package is for **hosted MCP transports** that talk to Roam through a different backend (e.g., an authenticated proxy) and want to reuse the same tool registry, Zod schemas, and operation functions without dragging in the local Roam Desktop client or the `~/.roam-tools.json` config reader.
|
|
10
10
|
|
|
11
11
|
## What's in here
|
|
12
12
|
|
|
@@ -25,7 +25,7 @@ This package is for **hosted MCP transports** that talk to Roam through a differ
|
|
|
25
25
|
- `connect` interactive setup — also in `@roam-research/roam-tools-local`.
|
|
26
26
|
- The `list_graphs` and `setup_new_graph` standalone tools — also local.
|
|
27
27
|
|
|
28
|
-
Hosted consumers reimplement these (or substitute their own equivalents — e.g., reading
|
|
28
|
+
Hosted consumers reimplement these (or substitute their own equivalents — e.g., reading grants from a remote store) and inject them via `routeToolCall`'s options.
|
|
29
29
|
|
|
30
30
|
## Documentation
|
|
31
31
|
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export type { CallToolResult, TextContent, ImageContent, GraphType, AccessLevel, GraphConfig, RoamMcpConfig, ToolGraph, ResolvedGraph, RoamActionClient, ErrorCode, RoamApiError, RoamResponse, Block, Page, BlockLocation, WindowType, SidebarWindow, SidebarWindowInfo, FocusedBlock, SelectedBlock, MainWindowViewType, MainWindowView, SearchResultPath, SearchResult, SearchResponse, RecentlyOpenedBlock, RecentlyOpenedItem, DailyNotePagesViewItem, RecentlyEditedPage, SearchSuggestionsResponse, SearchTemplatesResponse, GetPageResponse, GetBlockResponse, Template, QueryResult, QueryResponse, TokenInfoResponse, TokenInfoResult, } from "./types.js";
|
|
1
|
+
export type { CallToolResult, TextContent, ImageContent, GraphType, AccessLevel, GraphConfig, RoamMcpConfig, ToolGraph, ResolvedGraph, RoamActionClient, ErrorCode, RoamApiError, RoamResponse, Block, Page, BlockLocation, WindowType, SidebarWindow, SidebarWindowInfo, FocusedBlock, SelectedBlock, MainWindowViewType, MainWindowView, SearchResultPath, SearchResult, SearchResponse, RecentlyOpenedBlock, RecentlyOpenedItem, DailyNotePagesViewItem, RecentlyEditedPage, SearchSuggestionsResponse, SearchTemplatesResponse, GetPageResponse, GetBlockResponse, Template, QueryResult, QueryResponse, TokenInfoResponse, TokenInfoResult, ToolAnnotations, } from "./types.js";
|
|
2
2
|
export { GraphConfigSchema, RoamMcpConfigSchema, ErrorCodes, RoamError, CONFIG_VERSION, EXPECTED_API_VERSION, textResult, imageResult, errorResult, getErrorMessage, } from "./types.js";
|
|
3
3
|
export { tools, findTool, routeToolCall, contentTools, dataTools, desktopUiTools, defineTool, defineStandaloneTool, } from "./tools.js";
|
|
4
4
|
export type { ToolDefinition, ClientToolDefinition, StandaloneToolDefinition, RouteToolCallOptions, } from "./tools.js";
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,YAAY,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACZ,SAAS,EACT,WAAW,EACX,WAAW,EACX,aAAa,EACb,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,IAAI,EACJ,aAAa,EACb,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,yBAAyB,EACzB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,EACL,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,SAAS,EACT,cAAc,EACd,UAAU,EACV,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,YAAY,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,YAAY,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACZ,SAAS,EACT,WAAW,EACX,WAAW,EACX,aAAa,EACb,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,IAAI,EACJ,aAAa,EACb,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,yBAAyB,EACzB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,EACL,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,SAAS,EACT,cAAc,EACd,UAAU,EACV,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,YAAY,CAAC"}
|
|
@@ -42,16 +42,16 @@ export declare const UpdateBlockSchema: z.ZodObject<{
|
|
|
42
42
|
}, "strip", z.ZodTypeAny, {
|
|
43
43
|
uid: string;
|
|
44
44
|
string?: string | undefined;
|
|
45
|
+
childrenViewType?: "bullet" | "numbered" | "document" | undefined;
|
|
45
46
|
open?: boolean | undefined;
|
|
46
47
|
heading?: number | undefined;
|
|
47
|
-
childrenViewType?: "bullet" | "numbered" | "document" | undefined;
|
|
48
48
|
textAlign?: "left" | "center" | "right" | "justify" | undefined;
|
|
49
49
|
}, {
|
|
50
50
|
uid: string;
|
|
51
51
|
string?: string | undefined;
|
|
52
|
+
childrenViewType?: "bullet" | "numbered" | "document" | undefined;
|
|
52
53
|
open?: boolean | undefined;
|
|
53
54
|
heading?: number | undefined;
|
|
54
|
-
childrenViewType?: "bullet" | "numbered" | "document" | undefined;
|
|
55
55
|
textAlign?: "left" | "center" | "right" | "justify" | undefined;
|
|
56
56
|
}>;
|
|
57
57
|
export declare const DeleteBlockSchema: z.ZodObject<{
|
|
@@ -85,25 +85,25 @@ export declare const GetBacklinksSchema: z.ZodObject<{
|
|
|
85
85
|
includePath: z.ZodOptional<z.ZodBoolean>;
|
|
86
86
|
maxDepth: z.ZodOptional<z.ZodNumber>;
|
|
87
87
|
}, "strip", z.ZodTypeAny, {
|
|
88
|
+
title?: string | undefined;
|
|
88
89
|
sort?: "created-date" | "edited-date" | "daily-note-date" | undefined;
|
|
90
|
+
search?: string | undefined;
|
|
89
91
|
uid?: string | undefined;
|
|
90
|
-
|
|
91
|
-
sortOrder?: "asc" | "desc" | undefined;
|
|
92
|
-
includePath?: boolean | undefined;
|
|
92
|
+
maxDepth?: number | undefined;
|
|
93
93
|
offset?: number | undefined;
|
|
94
94
|
limit?: number | undefined;
|
|
95
|
-
|
|
96
|
-
|
|
95
|
+
sortOrder?: "asc" | "desc" | undefined;
|
|
96
|
+
includePath?: boolean | undefined;
|
|
97
97
|
}, {
|
|
98
|
+
title?: string | undefined;
|
|
98
99
|
sort?: "created-date" | "edited-date" | "daily-note-date" | undefined;
|
|
100
|
+
search?: string | undefined;
|
|
99
101
|
uid?: string | undefined;
|
|
100
|
-
|
|
101
|
-
sortOrder?: "asc" | "desc" | undefined;
|
|
102
|
-
includePath?: boolean | undefined;
|
|
102
|
+
maxDepth?: number | undefined;
|
|
103
103
|
offset?: number | undefined;
|
|
104
104
|
limit?: number | undefined;
|
|
105
|
-
|
|
106
|
-
|
|
105
|
+
sortOrder?: "asc" | "desc" | undefined;
|
|
106
|
+
includePath?: boolean | undefined;
|
|
107
107
|
}>;
|
|
108
108
|
export type CreateBlockParams = z.infer<typeof CreateBlockSchema>;
|
|
109
109
|
export type GetBlockParams = z.infer<typeof GetBlockSchema>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/operations/blocks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAoB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAItF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;EA+B5B,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;EAMzB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;
|
|
1
|
+
{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/operations/blocks.ts"],"names":[],"mappings":"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"}
|
|
@@ -34,7 +34,10 @@ export const GetBlockSchema = z.object({
|
|
|
34
34
|
});
|
|
35
35
|
export const UpdateBlockSchema = z.object({
|
|
36
36
|
uid: z.string().describe("Block UID"),
|
|
37
|
-
string: z
|
|
37
|
+
string: z
|
|
38
|
+
.string()
|
|
39
|
+
.optional()
|
|
40
|
+
.describe("New literal text for this block (the Roam block string, including inline markup like **bold**, [[links]], ((refs))). Set as-is — NOT parsed into nested child blocks. Updates this one block only."),
|
|
38
41
|
open: z.boolean().optional().describe("Collapse state"),
|
|
39
42
|
heading: z.coerce.number().optional().describe("Heading level (0-3)"),
|
|
40
43
|
childrenViewType: z
|
|
@@ -15,14 +15,14 @@ export declare const FileUploadSchema: z.ZodObject<{
|
|
|
15
15
|
filename: z.ZodOptional<z.ZodString>;
|
|
16
16
|
}, "strip", z.ZodTypeAny, {
|
|
17
17
|
url?: string | undefined;
|
|
18
|
-
filePath?: string | undefined;
|
|
19
18
|
base64?: string | undefined;
|
|
19
|
+
filePath?: string | undefined;
|
|
20
20
|
mimetype?: string | undefined;
|
|
21
21
|
filename?: string | undefined;
|
|
22
22
|
}, {
|
|
23
23
|
url?: string | undefined;
|
|
24
|
-
filePath?: string | undefined;
|
|
25
24
|
base64?: string | undefined;
|
|
25
|
+
filePath?: string | undefined;
|
|
26
26
|
mimetype?: string | undefined;
|
|
27
27
|
filename?: string | undefined;
|
|
28
28
|
}>;
|
|
@@ -6,21 +6,21 @@ export declare const OpenMainWindowSchema: z.ZodObject<{
|
|
|
6
6
|
uid: z.ZodOptional<z.ZodString>;
|
|
7
7
|
title: z.ZodOptional<z.ZodString>;
|
|
8
8
|
}, "strip", z.ZodTypeAny, {
|
|
9
|
-
uid?: string | undefined;
|
|
10
9
|
title?: string | undefined;
|
|
11
|
-
}, {
|
|
12
10
|
uid?: string | undefined;
|
|
11
|
+
}, {
|
|
13
12
|
title?: string | undefined;
|
|
13
|
+
uid?: string | undefined;
|
|
14
14
|
}>;
|
|
15
15
|
export declare const OpenSidebarSchema: z.ZodObject<{
|
|
16
16
|
uid: z.ZodString;
|
|
17
17
|
type: z.ZodOptional<z.ZodEnum<["block", "outline", "mentions"]>>;
|
|
18
18
|
}, "strip", z.ZodTypeAny, {
|
|
19
19
|
uid: string;
|
|
20
|
-
type?: "
|
|
20
|
+
type?: "mentions" | "block" | "outline" | undefined;
|
|
21
21
|
}, {
|
|
22
22
|
uid: string;
|
|
23
|
-
type?: "
|
|
23
|
+
type?: "mentions" | "block" | "outline" | undefined;
|
|
24
24
|
}>;
|
|
25
25
|
export type OpenMainWindowParams = z.infer<typeof OpenMainWindowSchema>;
|
|
26
26
|
export type OpenSidebarParams = z.infer<typeof OpenSidebarSchema>;
|
|
@@ -7,13 +7,13 @@ export declare const CreatePageSchema: z.ZodObject<{
|
|
|
7
7
|
childrenViewType: z.ZodOptional<z.ZodEnum<["document", "bullet", "numbered"]>>;
|
|
8
8
|
}, "strip", z.ZodTypeAny, {
|
|
9
9
|
title: string;
|
|
10
|
-
uid?: string | undefined;
|
|
11
10
|
markdown?: string | undefined;
|
|
11
|
+
uid?: string | undefined;
|
|
12
12
|
childrenViewType?: "bullet" | "numbered" | "document" | undefined;
|
|
13
13
|
}, {
|
|
14
14
|
title: string;
|
|
15
|
-
uid?: string | undefined;
|
|
16
15
|
markdown?: string | undefined;
|
|
16
|
+
uid?: string | undefined;
|
|
17
17
|
childrenViewType?: "bullet" | "numbered" | "document" | undefined;
|
|
18
18
|
}>;
|
|
19
19
|
export declare const GetPageSchema: z.ZodObject<{
|
|
@@ -21,12 +21,12 @@ export declare const GetPageSchema: z.ZodObject<{
|
|
|
21
21
|
uid: z.ZodOptional<z.ZodString>;
|
|
22
22
|
maxDepth: z.ZodOptional<z.ZodNumber>;
|
|
23
23
|
}, "strip", z.ZodTypeAny, {
|
|
24
|
-
uid?: string | undefined;
|
|
25
24
|
title?: string | undefined;
|
|
25
|
+
uid?: string | undefined;
|
|
26
26
|
maxDepth?: number | undefined;
|
|
27
27
|
}, {
|
|
28
|
-
uid?: string | undefined;
|
|
29
28
|
title?: string | undefined;
|
|
29
|
+
uid?: string | undefined;
|
|
30
30
|
maxDepth?: number | undefined;
|
|
31
31
|
}>;
|
|
32
32
|
export declare const DeletePageSchema: z.ZodObject<{
|
|
@@ -12,21 +12,21 @@ export declare const QuerySchema: z.ZodObject<{
|
|
|
12
12
|
}, "strip", z.ZodTypeAny, {
|
|
13
13
|
sort?: "created-date" | "edited-date" | "daily-note-date" | undefined;
|
|
14
14
|
uid?: string | undefined;
|
|
15
|
-
|
|
16
|
-
sortOrder?: "asc" | "desc" | undefined;
|
|
17
|
-
includePath?: boolean | undefined;
|
|
15
|
+
maxDepth?: number | undefined;
|
|
18
16
|
offset?: number | undefined;
|
|
19
17
|
limit?: number | undefined;
|
|
20
|
-
|
|
18
|
+
sortOrder?: "asc" | "desc" | undefined;
|
|
19
|
+
includePath?: boolean | undefined;
|
|
20
|
+
query?: string | undefined;
|
|
21
21
|
}, {
|
|
22
22
|
sort?: "created-date" | "edited-date" | "daily-note-date" | undefined;
|
|
23
23
|
uid?: string | undefined;
|
|
24
|
-
|
|
25
|
-
sortOrder?: "asc" | "desc" | undefined;
|
|
26
|
-
includePath?: boolean | undefined;
|
|
24
|
+
maxDepth?: number | undefined;
|
|
27
25
|
offset?: number | undefined;
|
|
28
26
|
limit?: number | undefined;
|
|
29
|
-
|
|
27
|
+
sortOrder?: "asc" | "desc" | undefined;
|
|
28
|
+
includePath?: boolean | undefined;
|
|
29
|
+
query?: string | undefined;
|
|
30
30
|
}>;
|
|
31
31
|
export type QueryParams = z.infer<typeof QuerySchema>;
|
|
32
32
|
export declare function query(client: RoamActionClient, params: QueryParams): Promise<CallToolResult>;
|
|
@@ -9,17 +9,17 @@ export declare const SearchSchema: z.ZodObject<{
|
|
|
9
9
|
maxDepth: z.ZodOptional<z.ZodNumber>;
|
|
10
10
|
}, "strip", z.ZodTypeAny, {
|
|
11
11
|
query: string;
|
|
12
|
-
|
|
12
|
+
maxDepth?: number | undefined;
|
|
13
13
|
offset?: number | undefined;
|
|
14
14
|
limit?: number | undefined;
|
|
15
|
-
|
|
15
|
+
includePath?: boolean | undefined;
|
|
16
16
|
scope?: "pages" | "blocks" | "all" | undefined;
|
|
17
17
|
}, {
|
|
18
18
|
query: string;
|
|
19
|
-
|
|
19
|
+
maxDepth?: number | undefined;
|
|
20
20
|
offset?: number | undefined;
|
|
21
21
|
limit?: number | undefined;
|
|
22
|
-
|
|
22
|
+
includePath?: boolean | undefined;
|
|
23
23
|
scope?: "pages" | "blocks" | "all" | undefined;
|
|
24
24
|
}>;
|
|
25
25
|
export declare const SearchTemplatesSchema: z.ZodObject<{
|
package/dist/tools.d.ts
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
-
import type { CallToolResult, AccessLevel, RoamActionClient, ToolGraph } from "./types.js";
|
|
2
|
+
import type { CallToolResult, AccessLevel, RoamActionClient, ToolGraph, ToolAnnotations } from "./types.js";
|
|
3
3
|
export interface ClientToolDefinition {
|
|
4
4
|
name: string;
|
|
5
5
|
description: string;
|
|
6
6
|
schema: z.ZodObject<z.ZodRawShape>;
|
|
7
7
|
action: (client: RoamActionClient, args: unknown) => Promise<CallToolResult>;
|
|
8
8
|
type: "client";
|
|
9
|
+
title?: string;
|
|
10
|
+
annotations?: ToolAnnotations;
|
|
9
11
|
}
|
|
10
12
|
export interface StandaloneToolDefinition {
|
|
11
13
|
name: string;
|
|
@@ -13,10 +15,16 @@ export interface StandaloneToolDefinition {
|
|
|
13
15
|
schema: z.ZodObject<z.ZodRawShape>;
|
|
14
16
|
action: (args: unknown) => Promise<CallToolResult>;
|
|
15
17
|
type: "standalone";
|
|
18
|
+
title?: string;
|
|
19
|
+
annotations?: ToolAnnotations;
|
|
16
20
|
}
|
|
17
21
|
export type ToolDefinition = ClientToolDefinition | StandaloneToolDefinition;
|
|
18
|
-
|
|
19
|
-
|
|
22
|
+
type ToolMetaArg = {
|
|
23
|
+
title?: string;
|
|
24
|
+
annotations?: ToolAnnotations;
|
|
25
|
+
};
|
|
26
|
+
export declare function defineTool<T extends z.ZodRawShape>(name: string, description: string, schema: z.ZodObject<T>, action: (client: RoamActionClient, args: z.infer<z.ZodObject<T>>) => Promise<CallToolResult>, meta?: ToolMetaArg): ClientToolDefinition;
|
|
27
|
+
export declare function defineStandaloneTool<T extends z.ZodRawShape>(name: string, description: string, schema: z.ZodObject<T>, action: (args: z.infer<z.ZodObject<T>>) => Promise<CallToolResult>, meta?: ToolMetaArg): StandaloneToolDefinition;
|
|
20
28
|
export declare const dataTools: ClientToolDefinition[];
|
|
21
29
|
export declare const desktopUiTools: ClientToolDefinition[];
|
|
22
30
|
export declare const contentTools: ClientToolDefinition[];
|
|
@@ -26,13 +34,13 @@ export interface RouteToolCallOptions {
|
|
|
26
34
|
/**
|
|
27
35
|
* Resolve a graph identifier (nickname/name) to a ToolGraph. Required.
|
|
28
36
|
* Local consumers use the resolver from @roam-research/roam-tools-local;
|
|
29
|
-
* hosted consumers wire their own (e.g., reading
|
|
37
|
+
* hosted consumers wire their own (e.g., reading grants from their own store).
|
|
30
38
|
*/
|
|
31
39
|
resolveGraph: (providedGraph?: string) => Promise<ToolGraph>;
|
|
32
40
|
/**
|
|
33
41
|
* Construct a client for the resolved graph. Required.
|
|
34
42
|
* Local consumers return a RoamClient; hosted consumers return a transport
|
|
35
|
-
* that talks to
|
|
43
|
+
* that talks to their own backend.
|
|
36
44
|
*/
|
|
37
45
|
createClient: (graph: ToolGraph) => Promise<RoamActionClient> | RoamActionClient;
|
|
38
46
|
/**
|
|
@@ -52,4 +60,5 @@ export interface RouteToolCallOptions {
|
|
|
52
60
|
}) => Promise<void>;
|
|
53
61
|
}
|
|
54
62
|
export declare function routeToolCall(toolName: string, args: Record<string, unknown>, options: RouteToolCallOptions): Promise<CallToolResult>;
|
|
63
|
+
export {};
|
|
55
64
|
//# sourceMappingURL=tools.d.ts.map
|
package/dist/tools.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,cAAc,EAEd,WAAW,EACX,gBAAgB,EAChB,SAAS,
|
|
1
|
+
{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
|
package/dist/tools.js
CHANGED
|
@@ -19,69 +19,126 @@ function withGraph(schema) {
|
|
|
19
19
|
return schema.extend(GraphSchema.shape);
|
|
20
20
|
}
|
|
21
21
|
// Helper to create tool with graph parameter
|
|
22
|
-
export function defineTool(name, description, schema, action) {
|
|
22
|
+
export function defineTool(name, description, schema, action, meta) {
|
|
23
23
|
return {
|
|
24
24
|
name,
|
|
25
25
|
description,
|
|
26
26
|
schema: withGraph(schema),
|
|
27
27
|
action: (client, args) => action(client, args),
|
|
28
28
|
type: "client",
|
|
29
|
+
title: meta?.title,
|
|
30
|
+
annotations: meta?.annotations,
|
|
29
31
|
};
|
|
30
32
|
}
|
|
31
33
|
// Helper to create standalone tool (no graph parameter, handles its own resolution)
|
|
32
|
-
export function defineStandaloneTool(name, description, schema, action) {
|
|
34
|
+
export function defineStandaloneTool(name, description, schema, action, meta) {
|
|
33
35
|
return {
|
|
34
36
|
name,
|
|
35
37
|
description,
|
|
36
38
|
schema: schema,
|
|
37
39
|
action: (args) => action(args),
|
|
38
40
|
type: "standalone",
|
|
41
|
+
title: meta?.title,
|
|
42
|
+
annotations: meta?.annotations,
|
|
39
43
|
};
|
|
40
44
|
}
|
|
41
45
|
// Note appended to all client tool descriptions
|
|
42
46
|
const GUIDELINES_NOTE = "\n\n(If you haven't fetched this graph's guidelines yet, call get_graph_guidelines — they may change how to handle this operation.)";
|
|
47
|
+
// ----------------------------------------------------------------------------
|
|
48
|
+
// Annotation presets (MCP tools/list hints), applied inline at each defineTool
|
|
49
|
+
// call below. They help clients label/gate tools correctly (e.g. ChatGPT dev
|
|
50
|
+
// mode, which otherwise defaults every tool to destructive + open-world) and
|
|
51
|
+
// mirror the backend's read/append/edit/delete classification. Hints only — NOT
|
|
52
|
+
// a security boundary; the backend still enforces authorization.
|
|
53
|
+
//
|
|
54
|
+
// readOnlyHint describes effects on the user's GRAPH CONTENT. Incidental local
|
|
55
|
+
// bookkeeping — e.g. get_graph_guidelines syncing token status into
|
|
56
|
+
// ~/.roam-tools.json (the local-sync side flow) — does not flip it; contrast
|
|
57
|
+
// setup_new_graph, whose config write IS its purpose, so it is not read-only.
|
|
58
|
+
//
|
|
59
|
+
// openWorldHint is false for every tool except file_upload (its url path fetches
|
|
60
|
+
// an arbitrary external host server-side).
|
|
61
|
+
// ----------------------------------------------------------------------------
|
|
62
|
+
const READ = {
|
|
63
|
+
readOnlyHint: true,
|
|
64
|
+
destructiveHint: false,
|
|
65
|
+
idempotentHint: true,
|
|
66
|
+
openWorldHint: false,
|
|
67
|
+
};
|
|
68
|
+
const APPEND = {
|
|
69
|
+
readOnlyHint: false,
|
|
70
|
+
destructiveHint: false,
|
|
71
|
+
idempotentHint: false,
|
|
72
|
+
openWorldHint: false,
|
|
73
|
+
};
|
|
74
|
+
// Edits and moves overwrite/relocate existing structure — not "only additive" —
|
|
75
|
+
// so they are destructive; both are idempotent (same args → same end state).
|
|
76
|
+
const EDIT = {
|
|
77
|
+
readOnlyHint: false,
|
|
78
|
+
destructiveHint: true,
|
|
79
|
+
idempotentHint: true,
|
|
80
|
+
openWorldHint: false,
|
|
81
|
+
};
|
|
82
|
+
const DELETE = {
|
|
83
|
+
readOnlyHint: false,
|
|
84
|
+
destructiveHint: true,
|
|
85
|
+
idempotentHint: false,
|
|
86
|
+
openWorldHint: false,
|
|
87
|
+
};
|
|
88
|
+
// open_main_window replaces the main view (idempotent). open_sidebar overrides
|
|
89
|
+
// idempotentHint:false at its call site — ui.rightSidebar.addWindow can add
|
|
90
|
+
// another sidebar pane on repeat. Neither mutates graph data.
|
|
91
|
+
const NAV = {
|
|
92
|
+
readOnlyHint: false,
|
|
93
|
+
destructiveHint: false,
|
|
94
|
+
idempotentHint: true,
|
|
95
|
+
openWorldHint: false,
|
|
96
|
+
};
|
|
97
|
+
// file_upload's url path does a server-side fetch of an arbitrary host.
|
|
98
|
+
const UPLOAD = { ...APPEND, openWorldHint: true };
|
|
43
99
|
// Data Tools (require graph/client; reusable across local + hosted MCP transports)
|
|
44
100
|
export const dataTools = [
|
|
45
|
-
defineTool("get_graph_guidelines", "Returns this graph's agent-facing setup: naming conventions, structural preferences, orientation actions, and any constraints the user has explicitly recorded for AI agents. Call once per graph per session before reading or writing content — skipping it means operating on assumptions the user has already overridden, so your work will likely need to be redone. The `nextSteps` field in the response lists orientation actions to take before proceeding.", GetGuidelinesSchema, getGuidelines),
|
|
46
|
-
defineTool("create_page", "Create a new page in Roam, optionally with markdown content." + GUIDELINES_NOTE, CreatePageSchema, createPage),
|
|
101
|
+
defineTool("get_graph_guidelines", "Returns this graph's agent-facing setup: naming conventions, structural preferences, orientation actions, and any constraints the user has explicitly recorded for AI agents. Call once per graph per session before reading or writing content — skipping it means operating on assumptions the user has already overridden, so your work will likely need to be redone. The `nextSteps` field in the response lists orientation actions to take before proceeding.", GetGuidelinesSchema, getGuidelines, { title: "Get graph guidelines", annotations: READ }),
|
|
102
|
+
defineTool("create_page", "Create a new page in Roam, optionally with markdown content." + GUIDELINES_NOTE, CreatePageSchema, createPage, { title: "Create page", annotations: APPEND }),
|
|
47
103
|
defineTool("create_block", "Create blocks from markdown content. Target by parentUid, pageTitle, or dailyNotePage (page created if needed). Use nestUnder to insert under a specific child block. Supports nested bulleted lists via markdown indentation." +
|
|
48
|
-
GUIDELINES_NOTE, CreateBlockSchema, createBlock),
|
|
49
|
-
defineTool("update_block", "Update
|
|
50
|
-
|
|
51
|
-
defineTool("
|
|
104
|
+
GUIDELINES_NOTE, CreateBlockSchema, createBlock, { title: "Create blocks", annotations: APPEND }),
|
|
105
|
+
defineTool("update_block", "Update a single existing block's text and display properties (heading, collapse, alignment, children view type). Affects only the block with `uid`: `string` sets that block's literal text — it is NOT expanded into child blocks (unlike create_block/create_page), and the block's existing children are left untouched. To add or restructure children, use create_block / move_block / delete_block." +
|
|
106
|
+
GUIDELINES_NOTE, UpdateBlockSchema, updateBlock, { title: "Update block", annotations: EDIT }),
|
|
107
|
+
defineTool("delete_block", "Delete a block and all its children." + GUIDELINES_NOTE, DeleteBlockSchema, deleteBlock, { title: "Delete block", annotations: DELETE }),
|
|
108
|
+
defineTool("move_block", "Move a block to a new location." + GUIDELINES_NOTE, MoveBlockSchema, moveBlock, { title: "Move block", annotations: EDIT }),
|
|
52
109
|
defineTool("add_comment", "Add a comment to a block (comment thread, NOT a child block). Prefer `comment` for simple text; use `commentMarkdown` for structured content. Same-day calls on the same block append to your existing comment." +
|
|
53
|
-
GUIDELINES_NOTE, AddCommentSchema, addComment),
|
|
110
|
+
GUIDELINES_NOTE, AddCommentSchema, addComment, { title: "Add comment", annotations: APPEND }),
|
|
54
111
|
defineTool("get_comments", "Get comments on a block with author, timestamps, and edit info. If singleEditableUid is set, the comment can be edited with update_block. Only works for blocks, not pages." +
|
|
55
|
-
GUIDELINES_NOTE, GetCommentsSchema, getComments),
|
|
56
|
-
defineTool("delete_page", "Delete a page and all its contents." + GUIDELINES_NOTE, DeletePageSchema, deletePage),
|
|
112
|
+
GUIDELINES_NOTE, GetCommentsSchema, getComments, { title: "Get comments", annotations: READ }),
|
|
113
|
+
defineTool("delete_page", "Delete a page and all its contents." + GUIDELINES_NOTE, DeletePageSchema, deletePage, { title: "Delete page", annotations: DELETE }),
|
|
57
114
|
defineTool("update_page", "Update a page's title or children view type. Set mergePages to true if renaming to a title that already exists." +
|
|
58
|
-
GUIDELINES_NOTE, UpdatePageSchema, updatePage),
|
|
115
|
+
GUIDELINES_NOTE, UpdatePageSchema, updatePage, { title: "Update page", annotations: EDIT }),
|
|
59
116
|
defineTool("search", "Search for pages and blocks by text. Returns paginated results with markdown content and optional breadcrumb paths. Call with an empty query to get recently edited and viewed content — useful for understanding what the user is currently working on." +
|
|
60
|
-
GUIDELINES_NOTE, SearchSchema, search),
|
|
117
|
+
GUIDELINES_NOTE, SearchSchema, search, { title: "Search", annotations: READ }),
|
|
61
118
|
defineTool("search_templates", "Search Roam templates by name. When the user mentions 'my X template' or 'the X template', use this tool to find it. Templates are user-created reusable content blocks tagged with [[roam/templates]]. Returns template name, uid, and content as markdown." +
|
|
62
|
-
GUIDELINES_NOTE, SearchTemplatesSchema, searchTemplates),
|
|
119
|
+
GUIDELINES_NOTE, SearchTemplatesSchema, searchTemplates, { title: "Search templates", annotations: READ }),
|
|
63
120
|
defineTool("roam_query", 'Execute a Roam query ({{query: }} or {{[[query]]: }} blocks, NOT Datalog). Two modes: (1) UID mode - pass a block UID containing a query component to run it with saved settings/filters; (2) Query mode - pass a raw query string like "{and: [[TODO]] {not: [[DONE]]}}". Returns paginated results with markdown content.' +
|
|
64
|
-
GUIDELINES_NOTE, QuerySchema, query),
|
|
121
|
+
GUIDELINES_NOTE, QuerySchema, query, { title: "Run Roam query", annotations: READ }),
|
|
65
122
|
defineTool("datalog_query", "Execute a datomic-style datalog query against the graph's datascript database. Supported clauses: :find, :where, :in, and :timeout (ms). Inputs are positional parameters bound to :in variables after $. Write specific :where clauses to keep results bounded." +
|
|
66
|
-
GUIDELINES_NOTE, DatalogQuerySchema, datalogQuery),
|
|
123
|
+
GUIDELINES_NOTE, DatalogQuerySchema, datalogQuery, { title: "Run datalog query", annotations: READ }),
|
|
67
124
|
defineTool("get_page", "Get a page's content as markdown. Returns content with <roam> metadata tags containing UIDs - use these for follow-up operations but strip them when showing content to the user. Show remaining content verbatim, never paraphrase. Use maxDepth for large pages." +
|
|
68
|
-
GUIDELINES_NOTE, GetPageSchema, getPage),
|
|
125
|
+
GUIDELINES_NOTE, GetPageSchema, getPage, { title: "Get page", annotations: READ }),
|
|
69
126
|
defineTool("get_block", "Get a block's content as markdown. Returns content with <roam> metadata tags containing UIDs - use these for follow-up operations but strip them when showing content to the user. Show remaining content verbatim, never paraphrase. Use maxDepth for large blocks." +
|
|
70
|
-
GUIDELINES_NOTE, GetBlockSchema, getBlock),
|
|
127
|
+
GUIDELINES_NOTE, GetBlockSchema, getBlock, { title: "Get block", annotations: READ }),
|
|
71
128
|
defineTool("get_backlinks", "Get paginated backlinks (linked references) for a page or block, formatted as markdown. Returns total count and results with optional breadcrumb paths." +
|
|
72
|
-
GUIDELINES_NOTE, GetBacklinksSchema, getBacklinks),
|
|
129
|
+
GUIDELINES_NOTE, GetBacklinksSchema, getBacklinks, { title: "Get backlinks", annotations: READ }),
|
|
73
130
|
];
|
|
74
131
|
// Desktop UI Tools (require local Roam Desktop — file ops + window/selection introspection;
|
|
75
132
|
// hosted MCP omits these because the parameters/effects assume a local environment).
|
|
76
133
|
export const desktopUiTools = [
|
|
77
|
-
defineTool("get_open_windows", "Get the current view in the main window and all open sidebar windows." + GUIDELINES_NOTE, GetOpenWindowsSchema, getOpenWindows),
|
|
78
|
-
defineTool("get_selection", "Get the currently focused block and any multi-selected blocks." + GUIDELINES_NOTE, GetSelectionSchema, getSelection),
|
|
79
|
-
defineTool("open_main_window", "Navigate to a page or block in the main window." + GUIDELINES_NOTE, OpenMainWindowSchema, openMainWindow),
|
|
80
|
-
defineTool("open_sidebar", "Open a page or block in the right sidebar." + GUIDELINES_NOTE, OpenSidebarSchema, openSidebar),
|
|
81
|
-
defineTool("file_get", "Fetch a file hosted on Roam (handles decryption for encrypted graphs)." + GUIDELINES_NOTE, FileGetSchema, getFile),
|
|
134
|
+
defineTool("get_open_windows", "Get the current view in the main window and all open sidebar windows." + GUIDELINES_NOTE, GetOpenWindowsSchema, getOpenWindows, { title: "Get open windows", annotations: READ }),
|
|
135
|
+
defineTool("get_selection", "Get the currently focused block and any multi-selected blocks." + GUIDELINES_NOTE, GetSelectionSchema, getSelection, { title: "Get selection", annotations: READ }),
|
|
136
|
+
defineTool("open_main_window", "Navigate to a page or block in the main window." + GUIDELINES_NOTE, OpenMainWindowSchema, openMainWindow, { title: "Open in main window", annotations: NAV }),
|
|
137
|
+
defineTool("open_sidebar", "Open a page or block in the right sidebar." + GUIDELINES_NOTE, OpenSidebarSchema, openSidebar, { title: "Open in sidebar", annotations: { ...NAV, idempotentHint: false } }),
|
|
138
|
+
defineTool("file_get", "Fetch a file hosted on Roam (handles decryption for encrypted graphs)." + GUIDELINES_NOTE, FileGetSchema, getFile, { title: "Get file", annotations: READ }),
|
|
82
139
|
defineTool("file_upload", "Upload a file to Roam. Returns the Firebase storage URL. Usually you'll want to create a new block with the file as markdown: ``. Provide ONE of: filePath (preferred - local file, server reads directly), url (remote URL, server fetches), or base64 (raw data, fallback for sandboxed clients)." +
|
|
83
|
-
GUIDELINES_NOTE, FileUploadSchema, uploadFile),
|
|
84
|
-
defineTool("file_delete", "Delete a file hosted on Roam." + GUIDELINES_NOTE, FileDeleteSchema, deleteFile),
|
|
140
|
+
GUIDELINES_NOTE, FileUploadSchema, uploadFile, { title: "Upload file", annotations: UPLOAD }),
|
|
141
|
+
defineTool("file_delete", "Delete a file hosted on Roam." + GUIDELINES_NOTE, FileDeleteSchema, deleteFile, { title: "Delete file", annotations: DELETE }),
|
|
85
142
|
];
|
|
86
143
|
// Backwards-compatible aggregate of all client tools.
|
|
87
144
|
export const contentTools = [...dataTools, ...desktopUiTools];
|
package/dist/types.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export type { CallToolResult, TextContent, ImageContent } from "@modelcontextprotocol/sdk/types.js";
|
|
1
|
+
export type { CallToolResult, TextContent, ImageContent, ToolAnnotations, } from "@modelcontextprotocol/sdk/types.js";
|
|
2
2
|
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
|
|
3
3
|
import { z } from "zod";
|
|
4
4
|
export declare function textResult(value: unknown): CallToolResult;
|
|
@@ -14,8 +14,8 @@ export declare const GraphConfigSchema: z.ZodObject<{
|
|
|
14
14
|
accessLevel: z.ZodOptional<z.ZodEnum<["read-only", "read-append", "full"]>>;
|
|
15
15
|
lastKnownTokenStatus: z.ZodOptional<z.ZodEnum<["active", "revoked"]>>;
|
|
16
16
|
}, "strip", z.ZodTypeAny, {
|
|
17
|
-
name: string;
|
|
18
17
|
type: "hosted" | "offline";
|
|
18
|
+
name: string;
|
|
19
19
|
token: string;
|
|
20
20
|
nickname: string;
|
|
21
21
|
accessLevel?: "read-only" | "read-append" | "full" | undefined;
|
|
@@ -39,8 +39,8 @@ export declare const RoamMcpConfigSchema: z.ZodObject<{
|
|
|
39
39
|
accessLevel: z.ZodOptional<z.ZodEnum<["read-only", "read-append", "full"]>>;
|
|
40
40
|
lastKnownTokenStatus: z.ZodOptional<z.ZodEnum<["active", "revoked"]>>;
|
|
41
41
|
}, "strip", z.ZodTypeAny, {
|
|
42
|
-
name: string;
|
|
43
42
|
type: "hosted" | "offline";
|
|
43
|
+
name: string;
|
|
44
44
|
token: string;
|
|
45
45
|
nickname: string;
|
|
46
46
|
accessLevel?: "read-only" | "read-append" | "full" | undefined;
|
|
@@ -55,8 +55,8 @@ export declare const RoamMcpConfigSchema: z.ZodObject<{
|
|
|
55
55
|
}>, "many">;
|
|
56
56
|
}, "strip", z.ZodTypeAny, {
|
|
57
57
|
graphs: {
|
|
58
|
-
name: string;
|
|
59
58
|
type: "hosted" | "offline";
|
|
59
|
+
name: string;
|
|
60
60
|
token: string;
|
|
61
61
|
nickname: string;
|
|
62
62
|
accessLevel?: "read-only" | "read-append" | "full" | undefined;
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,YAAY,
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
|
package/dist/types.js
CHANGED
|
@@ -71,11 +71,10 @@ export const ErrorCodes = {
|
|
|
71
71
|
GRAPH_NOT_SELECTED: "GRAPH_NOT_SELECTED",
|
|
72
72
|
CONNECTION_FAILED: "CONNECTION_FAILED",
|
|
73
73
|
CONFIG_TOO_NEW: "CONFIG_TOO_NEW",
|
|
74
|
-
// Cloud-transport codes — emitted by
|
|
75
|
-
//
|
|
76
|
-
//
|
|
77
|
-
|
|
78
|
-
INSUFFICIENT_PERMISSION: "INSUFFICIENT_PERMISSION", // 403 — Picker grant existed in RTDB but Roam-side graph access has been revoked since (firebase.graph/readable? or writeable? returned false). Distinct from TOKEN_NOT_FOUND ("never authorized"): INSUFFICIENT_PERMISSION = "ask user to re-grant"; TOKEN_NOT_FOUND = "pick a different graph or grant fresh access".
|
|
74
|
+
// Cloud-transport codes — emitted by the hosted client against its own
|
|
75
|
+
// backend. Local does not emit these today.
|
|
76
|
+
MISSING_AUTH: "MISSING_AUTH", // 401 — Hosted auth gate failed (no token, malformed token, or invalid signature/issuer/audience). Same agent semantics as MISSING_TOKEN; distinct for operational telemetry across transports.
|
|
77
|
+
INSUFFICIENT_PERMISSION: "INSUFFICIENT_PERMISSION", // 403 — A prior grant existed but Roam-side graph access has been revoked since. Distinct from TOKEN_NOT_FOUND ("never authorized"): INSUFFICIENT_PERMISSION = "ask user to re-grant"; TOKEN_NOT_FOUND = "pick a different graph or grant fresh access".
|
|
79
78
|
NOT_IMPLEMENTED: "NOT_IMPLEMENTED", // 501 — Action recognized in dispatch but handler not yet wired (Phase 3 backlog). Distinct from ACTION_NOT_AVAILABLE: NOT_IMPLEMENTED implies "will work eventually"; ACTION_NOT_AVAILABLE implies "not available on this transport, period".
|
|
80
79
|
GRAPH_UNSUPPORTED: "GRAPH_UNSUPPORTED", // 400 — Encrypted graph rejection (backend can't decrypt). Agent should not retry; instruct user the graph type isn't supported via cloud transport.
|
|
81
80
|
ACTION_NOT_AVAILABLE: "ACTION_NOT_AVAILABLE", // 501 — Action symbol absent from cloud's dispatch entirely (typo OR action like file.upload that's local-only and intentionally not on cloud). Same agent semantics as UNKNOWN_ACTION (which is local-API 404); distinct for operational telemetry across transports.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@roam-research/roam-tools-core",
|
|
3
|
-
"version": "0.6.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.6.6",
|
|
4
|
+
"description": "Official transport-agnostic core for Roam Research MCP and CLI tools",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
7
7
|
"url": "git+https://github.com/Roam-Research/roam-tools.git",
|