@roam-research/roam-tools-core 0.6.5 → 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/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/tools.d.ts +12 -3
- package/dist/tools.d.ts.map +1 -1
- package/dist/tools.js +82 -26
- package/dist/types.d.ts +1 -1
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
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"}
|
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[];
|
|
@@ -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,70 +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),
|
|
104
|
+
GUIDELINES_NOTE, CreateBlockSchema, createBlock, { title: "Create blocks", annotations: APPEND }),
|
|
49
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." +
|
|
50
|
-
GUIDELINES_NOTE, UpdateBlockSchema, updateBlock),
|
|
51
|
-
defineTool("delete_block", "Delete a block and all its children." + GUIDELINES_NOTE, DeleteBlockSchema, deleteBlock),
|
|
52
|
-
defineTool("move_block", "Move a block to a new location." + GUIDELINES_NOTE, MoveBlockSchema, moveBlock),
|
|
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 }),
|
|
53
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." +
|
|
54
|
-
GUIDELINES_NOTE, AddCommentSchema, addComment),
|
|
110
|
+
GUIDELINES_NOTE, AddCommentSchema, addComment, { title: "Add comment", annotations: APPEND }),
|
|
55
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." +
|
|
56
|
-
GUIDELINES_NOTE, GetCommentsSchema, getComments),
|
|
57
|
-
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 }),
|
|
58
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." +
|
|
59
|
-
GUIDELINES_NOTE, UpdatePageSchema, updatePage),
|
|
115
|
+
GUIDELINES_NOTE, UpdatePageSchema, updatePage, { title: "Update page", annotations: EDIT }),
|
|
60
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." +
|
|
61
|
-
GUIDELINES_NOTE, SearchSchema, search),
|
|
117
|
+
GUIDELINES_NOTE, SearchSchema, search, { title: "Search", annotations: READ }),
|
|
62
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." +
|
|
63
|
-
GUIDELINES_NOTE, SearchTemplatesSchema, searchTemplates),
|
|
119
|
+
GUIDELINES_NOTE, SearchTemplatesSchema, searchTemplates, { title: "Search templates", annotations: READ }),
|
|
64
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.' +
|
|
65
|
-
GUIDELINES_NOTE, QuerySchema, query),
|
|
121
|
+
GUIDELINES_NOTE, QuerySchema, query, { title: "Run Roam query", annotations: READ }),
|
|
66
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." +
|
|
67
|
-
GUIDELINES_NOTE, DatalogQuerySchema, datalogQuery),
|
|
123
|
+
GUIDELINES_NOTE, DatalogQuerySchema, datalogQuery, { title: "Run datalog query", annotations: READ }),
|
|
68
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." +
|
|
69
|
-
GUIDELINES_NOTE, GetPageSchema, getPage),
|
|
125
|
+
GUIDELINES_NOTE, GetPageSchema, getPage, { title: "Get page", annotations: READ }),
|
|
70
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." +
|
|
71
|
-
GUIDELINES_NOTE, GetBlockSchema, getBlock),
|
|
127
|
+
GUIDELINES_NOTE, GetBlockSchema, getBlock, { title: "Get block", annotations: READ }),
|
|
72
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." +
|
|
73
|
-
GUIDELINES_NOTE, GetBacklinksSchema, getBacklinks),
|
|
129
|
+
GUIDELINES_NOTE, GetBacklinksSchema, getBacklinks, { title: "Get backlinks", annotations: READ }),
|
|
74
130
|
];
|
|
75
131
|
// Desktop UI Tools (require local Roam Desktop — file ops + window/selection introspection;
|
|
76
132
|
// hosted MCP omits these because the parameters/effects assume a local environment).
|
|
77
133
|
export const desktopUiTools = [
|
|
78
|
-
defineTool("get_open_windows", "Get the current view in the main window and all open sidebar windows." + GUIDELINES_NOTE, GetOpenWindowsSchema, getOpenWindows),
|
|
79
|
-
defineTool("get_selection", "Get the currently focused block and any multi-selected blocks." + GUIDELINES_NOTE, GetSelectionSchema, getSelection),
|
|
80
|
-
defineTool("open_main_window", "Navigate to a page or block in the main window." + GUIDELINES_NOTE, OpenMainWindowSchema, openMainWindow),
|
|
81
|
-
defineTool("open_sidebar", "Open a page or block in the right sidebar." + GUIDELINES_NOTE, OpenSidebarSchema, openSidebar),
|
|
82
|
-
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 }),
|
|
83
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)." +
|
|
84
|
-
GUIDELINES_NOTE, FileUploadSchema, uploadFile),
|
|
85
|
-
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 }),
|
|
86
142
|
];
|
|
87
143
|
// Backwards-compatible aggregate of all client tools.
|
|
88
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;
|
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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"}
|