@tenonhq/dovetail-mcp 0.0.9 → 0.0.11

package/dist/registry.d.ts

@@ -6,8 +6,15 @@
  * Dependencies are passed in by the caller — server.ts builds them from
  * loadConfig(), tests inject mocks. This split keeps registry.ts pure of
  * env access.
+ *
+ * Every descriptor carries MCP tool annotations (readOnlyHint / destructiveHint
+ * / idempotentHint) — untrusted behavioural hints per the MCP spec. They are
+ * informational to permission UX, but Claude Code already uses readOnlyHint to
+ * schedule read-only tools concurrently, and hosts that gate on destructiveHint
+ * get correct confirmation behaviour for free.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import type { ClickUpDeps } from "./tools/clickup";
 import type { GmailDeps } from "./tools/gmail";
@@ -26,6 +33,7 @@ interface ToolDescriptor {
     name: ToolName;
     description: string;
     shape: z.ZodRawShape;
+    annotations: ToolAnnotations;
     handler: (args: any) => Promise<any>;
 }
 export declare function registerAllTools(server: McpServer, deps: RegistryDeps): void;

package/dist/registry.js

@@ -7,6 +7,12 @@
  * Dependencies are passed in by the caller — server.ts builds them from
  * loadConfig(), tests inject mocks. This split keeps registry.ts pure of
  * env access.
+ *
+ * Every descriptor carries MCP tool annotations (readOnlyHint / destructiveHint
+ * / idempotentHint) — untrusted behavioural hints per the MCP spec. They are
+ * informational to permission UX, but Claude Code already uses readOnlyHint to
+ * schedule read-only tools concurrently, and hosts that gate on destructiveHint
+ * get correct confirmation behaviour for free.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TOOL_NAMES = void 0;
@@ -41,6 +47,28 @@ exports.TOOL_NAMES = [
     "calendar_get_event",
     "servicenow_query_table"
 ];
+// Annotation presets. All tools reach external services (ClickUp/Gmail/
+// Calendar/ServiceNow), so openWorldHint stays at its spec default of true.
+var READ_ONLY = { readOnlyHint: true };
+// A write that overwrites existing state (re-running with the same args
+// converges, so it is idempotent but still destructive).
+var WRITE_OVERWRITE = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true
+};
+// A purely additive create (re-running produces another record).
+var WRITE_CREATE = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false
+};
+// A purely additive, idempotent link (re-running is a no-op).
+var WRITE_ADDITIVE_IDEMPOTENT = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true
+};
 function buildDescriptors(deps) {
     var clickupReady = !!deps.clickup;
     var googleReady = !!deps.gmail && !!deps.calendar;
@@ -49,6 +77,7 @@ function buildDescriptors(deps) {
             name: "clickup_list_tasks",
             description: "List ClickUp tasks assigned to the authenticated user, grouped by status. teamId optional if CLICKUP_TEAM_ID is set.",
             shape: clickup_1.clickupListTasksSchema.shape,
+            annotations: READ_ONLY,
             handler: requireConfig(clickupReady, "ClickUp", deps.missingDescription, function (args) {
                 return (0, clickup_2.clickupListTasks)(args, deps.clickup);
             })
@@ -57,6 +86,7 @@ function buildDescriptors(deps) {
             name: "clickup_get_task",
             description: "Fetch a single ClickUp task by ID.",
             shape: clickup_1.clickupGetTaskSchema.shape,
+            annotations: READ_ONLY,
             handler: requireConfig(clickupReady, "ClickUp", deps.missingDescription, function (args) {
                 return (0, clickup_2.clickupGetTask)(args, deps.clickup);
             })
@@ -65,6 +95,7 @@ function buildDescriptors(deps) {
             name: "clickup_search_tasks",
             description: "Search team tasks by substring match against task name/description. teamId optional if CLICKUP_TEAM_ID is set.",
             shape: clickup_1.clickupSearchTasksSchema.shape,
+            annotations: READ_ONLY,
             handler: requireConfig(clickupReady, "ClickUp", deps.missingDescription, function (args) {
                 return (0, clickup_2.clickupSearchTasks)(args, deps.clickup);
             })
@@ -73,6 +104,7 @@ function buildDescriptors(deps) {
             name: "clickup_get_team_sync",
             description: "Returns a structured JSON team sync with the 7-stage pipeline (Blocked, In Progress, In Review, QA, UAT, Ready for Release, Done) plus unmapped statuses and unassigned tasks.",
             shape: clickup_1.clickupGetTeamSyncSchema.shape,
+            annotations: READ_ONLY,
             handler: requireConfig(clickupReady, "ClickUp", deps.missingDescription, function (args) {
                 return (0, clickup_2.clickupGetTeamSync)(args, deps.clickup);
             })
@@ -81,6 +113,7 @@ function buildDescriptors(deps) {
             name: "clickup_update_task",
             description: "Gated write: update a ClickUp task (name, markdownContent, status, priority). Requires SINC_MCP_WRITES_ENABLE=1; returns a dry-run preview unless confirm:true. Use customTaskIds:true + teamId to target a custom ID like DEV-225.",
             shape: clickup_1.clickupUpdateTaskSchema.shape,
+            annotations: WRITE_OVERWRITE,
             handler: requireConfig(clickupReady, "ClickUp", deps.missingDescription, function (args) {
                 return (0, clickup_write_1.clickupUpdateTask)(args, deps.clickup);
             })
@@ -89,6 +122,7 @@ function buildDescriptors(deps) {
             name: "clickup_set_custom_field",
             description: "Gated write: set one custom-field value on a task (POST /task/{id}/field/{fieldId}). Requires SINC_MCP_WRITES_ENABLE=1; dry-run unless confirm:true. value shape: string for text/url, option id for drop_down, { add:[], rem:[] } for users.",
             shape: clickup_1.clickupSetCustomFieldSchema.shape,
+            annotations: WRITE_OVERWRITE,
             handler: requireConfig(clickupReady, "ClickUp", deps.missingDescription, function (args) {
                 return (0, clickup_write_1.clickupSetCustomField)(args, deps.clickup);
             })
@@ -97,6 +131,7 @@ function buildDescriptors(deps) {
             name: "clickup_create_task",
             description: "Gated write: create a ClickUp task in a list (markdownContent, status, priority, assignees, customFields). Requires SINC_MCP_WRITES_ENABLE=1; dry-run unless confirm:true.",
             shape: clickup_1.clickupCreateTaskSchema.shape,
+            annotations: WRITE_CREATE,
             handler: requireConfig(clickupReady, "ClickUp", deps.missingDescription, function (args) {
                 return (0, clickup_write_1.clickupCreateTask)(args, deps.clickup);
             })
@@ -105,6 +140,7 @@ function buildDescriptors(deps) {
             name: "clickup_link_tasks",
             description: "Gated write: link two ClickUp tasks (POST /task/{id}/link/{linksTo}). Requires SINC_MCP_WRITES_ENABLE=1; dry-run unless confirm:true. Use customTaskIds:true + teamId for custom IDs.",
             shape: clickup_1.clickupLinkTasksSchema.shape,
+            annotations: WRITE_ADDITIVE_IDEMPOTENT,
             handler: requireConfig(clickupReady, "ClickUp", deps.missingDescription, function (args) {
                 return (0, clickup_write_1.clickupLinkTasks)(args, deps.clickup);
             })
@@ -113,6 +149,7 @@ function buildDescriptors(deps) {
             name: "gmail_get_unread",
             description: "Fetch unread emails from the inbox.",
             shape: gmail_1.gmailGetUnreadSchema.shape,
+            annotations: READ_ONLY,
             handler: requireConfig(googleReady, "Google (Gmail)", deps.missingDescription, function (args) {
                 return (0, gmail_2.gmailGetUnread)(args, deps.gmail);
             })
@@ -121,6 +158,7 @@ function buildDescriptors(deps) {
             name: "gmail_get_starred",
             description: "Fetch starred emails.",
             shape: gmail_1.gmailGetStarredSchema.shape,
+            annotations: READ_ONLY,
             handler: requireConfig(googleReady, "Google (Gmail)", deps.missingDescription, function (args) {
                 return (0, gmail_2.gmailGetStarred)(args, deps.gmail);
             })
@@ -129,6 +167,7 @@ function buildDescriptors(deps) {
             name: "gmail_search",
             description: "Search emails using Gmail query syntax (e.g. 'from:alice has:attachment').",
             shape: gmail_1.gmailSearchSchema.shape,
+            annotations: READ_ONLY,
             handler: requireConfig(googleReady, "Google (Gmail)", deps.missingDescription, function (args) {
                 return (0, gmail_2.gmailSearch)(args, deps.gmail);
             })
@@ -137,6 +176,7 @@ function buildDescriptors(deps) {
             name: "gmail_get_action_required",
             description: "Fetch unread action-required emails matched against subject patterns and labels (defaults: 'action required', 'urgent', 'asap', 'time sensitive').",
             shape: gmail_1.gmailGetActionRequiredSchema.shape,
+            annotations: READ_ONLY,
             handler: requireConfig(googleReady, "Google (Gmail)", deps.missingDescription, function (args) {
                 return (0, gmail_2.gmailGetActionRequired)(args, deps.gmail);
             })
@@ -145,6 +185,7 @@ function buildDescriptors(deps) {
             name: "calendar_get_today",
             description: "Fetch today's calendar events.",
             shape: calendar_1.calendarGetTodaySchema.shape,
+            annotations: READ_ONLY,
             handler: requireConfig(googleReady, "Google (Calendar)", deps.missingDescription, function (args) {
                 return (0, calendar_2.calendarGetToday)(args, deps.calendar);
             })
@@ -153,6 +194,7 @@ function buildDescriptors(deps) {
             name: "calendar_get_week",
             description: "Fetch the next 7 days of calendar events.",
             shape: calendar_1.calendarGetWeekSchema.shape,
+            annotations: READ_ONLY,
             handler: requireConfig(googleReady, "Google (Calendar)", deps.missingDescription, function (args) {
                 return (0, calendar_2.calendarGetWeek)(args, deps.calendar);
             })
@@ -161,6 +203,7 @@ function buildDescriptors(deps) {
             name: "calendar_get_event",
             description: "Fetch a single calendar event by ID.",
             shape: calendar_1.calendarGetEventSchema.shape,
+            annotations: READ_ONLY,
             handler: requireConfig(googleReady, "Google (Calendar)", deps.missingDescription, function (args) {
                 return (0, calendar_2.calendarGetEvent)(args, deps.calendar);
             })
@@ -169,6 +212,7 @@ function buildDescriptors(deps) {
             name: "servicenow_query_table",
             description: "Read-only GET against the ServiceNow Table API. Required: table (lower-case identifier), sysparm_query (ServiceNow encoded query). Optional: fields[] limits the columns returned, limit caps row count (default 100, max 1000). Tables on the deny list (sys_user_password, sys_credential, etc.) are rejected unless SINC_MCP_SN_TABLE_OVERRIDE=<table> is set.",
             shape: servicenow_1.servicenowQueryTableSchema.shape,
+            annotations: READ_ONLY,
             handler: function (args) {
                 return (0, servicenow_2.servicenowQueryTable)(args, deps.servicenow);
             }
@@ -196,7 +240,8 @@ function registerOne(server, desc) {
     // when a heterogeneous descriptor list feeds the same call site.
     server.registerTool(desc.name, {
         description: desc.description,
-        inputSchema: desc.shape
+        inputSchema: desc.shape,
+        annotations: desc.annotations
     }, async function (args) {
         try {
             var result = await (0, telemetry_1.withTelemetry)(desc.name, args, function () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenonhq/dovetail-mcp",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "MCP server exposing read tools for ClickUp / Gmail / Calendar / ServiceNow plus gated ClickUp writes, backed by the Dovetail integration packages.",
   "main": "./dist/index.js",
   "bin": {
@@ -21,7 +21,7 @@
     "@tenonhq/dovetail-gmail": "~0.0.11",
     "@tenonhq/dovetail-google-auth": "~0.0.12",
     "@tenonhq/dovetail-google-calendar": "~0.0.11",
-    "@tenonhq/dovetail-servicenow": "~0.0.15",
+    "@tenonhq/dovetail-servicenow": "~0.0.16",
     "dotenv": "^16.3.1",
     "zod": "^3.23.0"
   },