@tenonhq/dovetail-mcp 0.0.1

package/README.md

@@ -0,0 +1,167 @@
+# @tenonhq/dovetail-mcp
+
+MCP server exposing **read-only** ClickUp / Gmail / Google Calendar / ServiceNow
+tools backed by the existing Dovetail integration packages. Phase 1 — write
+operations are deliberately out of scope (see PRD).
+
+## Install
+
+```bash
+npm i @tenonhq/dovetail-mcp
+```
+
+Node 20 LTS required.
+
+## Environment variables
+
+The server reads `.env` of the **calling** project (e.g. CTO repo). It boots
+even if some integrations are missing — calls to those tools just return a
+clear "not configured" error.
+
+| Variable                    | Required by                  |
+|-----------------------------|------------------------------|
+| `CLICKUP_API_TOKEN`         | All `clickup_*` tools        |
+| `CLICKUP_TEAM_ID`           | Optional default for `clickup_list_tasks`/`clickup_search_tasks`/`clickup_get_team_sync` |
+| `GOOGLE_CLIENT_ID`          | All `gmail_*` and `calendar_*` tools |
+| `GOOGLE_CLIENT_SECRET`      | (same)                       |
+| `GOOGLE_REFRESH_TOKEN`      | (same)                       |
+| `SN_INSTANCE` (or `SN_DEV_INSTANCE`/`SN_PROD_INSTANCE`) | `servicenow_query_table` |
+| `SN_USER` (or `SN_DEV_USERNAME`/`SN_PROD_USERNAME`) | (same)            |
+| `SN_PASSWORD` (or `SN_DEV_PASSWORD`/`SN_PROD_PASSWORD`) | (same)         |
+| `SINC_MCP_SN_TABLE_DENY`    | Override default deny list (comma-separated) |
+| `SINC_MCP_SN_TABLE_OVERRIDE`| Allow specific denied tables (comma-separated) |
+| `SINC_MCP_TELEMETRY_DISABLE`| `1`/`true` to skip telemetry writes |
+| `SINC_MCP_TELEMETRY_PATH`   | Override `~/.dovetail-mcp/telemetry.jsonl` |
+
+> **OAuth scope warning:** Dovetail's existing Google refresh tokens are
+> issued with **write-capable** scopes (`gmail.modify`, `calendar`).
+> dovetail-mcp enforces read-only at the handler level (we never import the
+> upstream write functions and ESLint blocks new such imports), but the token
+> itself can write Gmail/Calendar. Re-running `dovetail-google-auth` setup
+> with `gmail.readonly` + `calendar.readonly` scopes is recommended for
+> defence-in-depth and is tracked separately.
+
+## Tools (12)
+
+| Tool                            | Purpose                                        |
+|---------------------------------|------------------------------------------------|
+| `clickup_list_tasks`            | Tasks assigned to the authenticated user       |
+| `clickup_get_task`              | Fetch a single task by ID                      |
+| `clickup_search_tasks`          | Substring search across team tasks             |
+| `clickup_get_team_sync`         | 7-stage pipeline JSON (Blocked → Ready for Release) |
+| `gmail_get_unread`              | Unread inbox emails                            |
+| `gmail_get_starred`             | Starred emails                                 |
+| `gmail_search`                  | Gmail query syntax                             |
+| `gmail_get_action_required`    | Unread emails matching action-required patterns|
+| `calendar_get_today`            | Today's events                                 |
+| `calendar_get_week`             | Next 7 days                                    |
+| `calendar_get_event`            | Single event by ID                             |
+| `servicenow_query_table`        | Table API GET (deny-listed tables blocked)     |
+
+ServiceNow deny-list (default): `sys_user_password`, `sys_user_token`,
+`sys_credential`, `sys_secret`, `sys_user_grmember`, `sys_audit`. Override
+per-table with `SINC_MCP_SN_TABLE_OVERRIDE=table_a,table_b`.
+
+## Run
+
+```bash
+# stdio transport (intended use under an MCP client like Claude Code)
+npx @tenonhq/dovetail-mcp
+
+# Smoke check — list tools and exit, no transport
+npx @tenonhq/dovetail-mcp --smoke
+```
+
+## Wiring into Claude Code (CTO repo)
+
+Add the server entry to `.claude/mcp.json` in the consuming project:
+
+```jsonc
+{
+  "mcpServers": {
+    "dovetail": {
+      "command": "npx",
+      "args": ["-y", "@tenonhq/dovetail-mcp"]
+    }
+  }
+}
+```
+
+Until the package is published, point at a local build instead:
+
+```jsonc
+{
+  "mcpServers": {
+    "dovetail": {
+      "command": "node",
+      "args": ["/absolute/path/to/Dovetail/packages/dovetail-mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+Tools are deferred-by-default — they appear in `ToolSearch` but their schemas
+load on demand. Per the CTO `CLAUDE.md` MCP policy, hoist to always-loaded
+only after telemetry shows >30% session usage.
+
+## Agent doc additions
+
+Add a one-liner to each consuming agent's prompt:
+
+- `task-manager.md`: "ClickUp `clickup_*` MCP tools (under the `dovetail`
+  server) are available for live task queries instead of the cron'd
+  `context/clickup-tasks.md`."
+- `cto-briefer.md`: "Live data: `gmail_*`, `calendar_*`, `clickup_*` MCP tools
+  on the `dovetail` server. Prefer them over the cron'd context markdown when
+  freshness matters."
+- `decision-advisor.md`: "Calendar / ClickUp MCP tools on the `dovetail`
+  server are available for context-rich reasoning."
+
+## Telemetry
+
+Every tool call appends one JSON line to `~/.dovetail-mcp/telemetry.jsonl`
+(file mode `0600`, dir mode `0700`):
+
+```jsonl
+{"ts":"2026-05-08T17:30:00.000Z","tool":"clickup_list_tasks","args":{"teamId":"123"},"durationMs":420,"success":true}
+{"ts":"2026-05-08T17:30:01.000Z","tool":"gmail_search","args":{"query":"from:alice"},"durationMs":250,"success":true}
+```
+
+### Redaction
+
+- `body` / `html` / `text` / `content` keys → `"[REDACTED:body]"`.
+- Token-bearing keys (`token`, `password`, `refresh_token`, `access_token`,
+  `client_secret`, `apiKey`, `api_key`, `clickup_api_token`, `authorization`,
+  `auth`) → `"[REDACTED]"`.
+- Email-shaped strings → `first3***@domain.tld`.
+- Free-form strings >200 chars → `sha256:<first 12 hex>`.
+- Query strings (`query`, `q`, `sysparm_query`, `subjectPatterns`, `labels`,
+  `statuses`) are kept verbatim — they're operational signal.
+
+Disable with `SINC_MCP_TELEMETRY_DISABLE=1`. Override the path with
+`SINC_MCP_TELEMETRY_PATH=/tmp/foo.jsonl`. Rotate manually for v1.
+
+## Read-only enforcement
+
+Three layers:
+
+1. **Imports.** Tool modules import only the read functions from each upstream
+   Dovetail package; write functions are never imported.
+2. **ESLint** (`.eslintrc.json` `no-restricted-imports`) blocks import of any
+   write function from `dovetail-clickup` / `dovetail-gmail` /
+   `dovetail-google-calendar` / `dovetail-servicenow`.
+3. **Static scan test** (`src/tests/readonly-imports.test.ts`) reads every
+   `src/tools/*.ts` and asserts no occurrence of forbidden symbols, including
+   `client.claude.*` (the ServiceNow write namespace, which can't be blocked
+   at the import level since it's a property access).
+
+## Troubleshooting
+
+- **"ClickUp is not configured — Missing required environment variables …"**
+  Set `CLICKUP_API_TOKEN`. The server boots without it; only `clickup_*` calls
+  fail until it's set.
+- **"Google authentication failed (… ). Your refresh token may be expired or
+  revoked."** Re-run `npm run setup` in `@tenonhq/dovetail-google-auth`.
+- **"Table 'X' is in the default deny list."** Add the table to
+  `SINC_MCP_SN_TABLE_OVERRIDE` (comma-separated) only after confirming the
+  read is intentional.

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Aggregates env-var requirements across the four integrations into a single
+ * loadConfig() so users see every missing var at once instead of fixing them
+ * one at a time. ServiceNow's createClient() handles its own env precedence
+ * (SN_* > SN_DEV_* > SN_PROD_*) — we surface its error verbatim.
+ *
+ * The ServiceNow deny-list defaults to tables that disclose secrets or audit
+ * data on read; users opt in with SINC_MCP_SN_TABLE_OVERRIDE.
+ */
+export interface ClickUpConfig {
+    token: string;
+    defaultTeamId?: string;
+}
+export interface GoogleConfig {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+}
+export interface ServiceNowSafetyConfig {
+    denyTables: string[];
+    overrideTables: string[];
+}
+export interface SincMcpConfig {
+    clickup?: ClickUpConfig;
+    google?: GoogleConfig;
+    servicenowSafety: ServiceNowSafetyConfig;
+}
+export interface ConfigLoadResult {
+    config: SincMcpConfig;
+    missing: {
+        clickup: string[];
+        google: string[];
+    };
+}
+export declare function loadConfig(): ConfigLoadResult;
+export declare function formatMissingEnvError(missing: {
+    clickup: string[];
+    google: string[];
+}): string;

package/dist/config.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Aggregates env-var requirements across the four integrations into a single
+ * loadConfig() so users see every missing var at once instead of fixing them
+ * one at a time. ServiceNow's createClient() handles its own env precedence
+ * (SN_* > SN_DEV_* > SN_PROD_*) — we surface its error verbatim.
+ *
+ * The ServiceNow deny-list defaults to tables that disclose secrets or audit
+ * data on read; users opt in with SINC_MCP_SN_TABLE_OVERRIDE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.formatMissingEnvError = formatMissingEnvError;
+var DEFAULT_DENY_TABLES = [
+    "sys_user_password",
+    "sys_user_token",
+    "sys_credential",
+    "sys_secret",
+    "sys_user_grmember",
+    "sys_audit"
+];
+function loadConfig() {
+    var clickupMissing = collectClickupMissing();
+    var googleMissing = collectGoogleMissing();
+    var clickup;
+    if (clickupMissing.length === 0) {
+        clickup = {
+            token: process.env.CLICKUP_API_TOKEN,
+            defaultTeamId: process.env.CLICKUP_TEAM_ID || undefined
+        };
+    }
+    var google;
+    if (googleMissing.length === 0) {
+        google = {
+            clientId: process.env.GOOGLE_CLIENT_ID,
+            clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+            refreshToken: process.env.GOOGLE_REFRESH_TOKEN
+        };
+    }
+    return {
+        config: {
+            clickup: clickup,
+            google: google,
+            servicenowSafety: loadServiceNowSafety()
+        },
+        missing: { clickup: clickupMissing, google: googleMissing }
+    };
+}
+function collectClickupMissing() {
+    var missing = [];
+    if (!process.env.CLICKUP_API_TOKEN)
+        missing.push("CLICKUP_API_TOKEN");
+    return missing;
+}
+function collectGoogleMissing() {
+    var missing = [];
+    if (!process.env.GOOGLE_CLIENT_ID)
+        missing.push("GOOGLE_CLIENT_ID");
+    if (!process.env.GOOGLE_CLIENT_SECRET)
+        missing.push("GOOGLE_CLIENT_SECRET");
+    if (!process.env.GOOGLE_REFRESH_TOKEN)
+        missing.push("GOOGLE_REFRESH_TOKEN");
+    return missing;
+}
+function loadServiceNowSafety() {
+    var deny = process.env.SINC_MCP_SN_TABLE_DENY
+        ? splitCsv(process.env.SINC_MCP_SN_TABLE_DENY)
+        : DEFAULT_DENY_TABLES.slice();
+    var override = process.env.SINC_MCP_SN_TABLE_OVERRIDE
+        ? splitCsv(process.env.SINC_MCP_SN_TABLE_OVERRIDE)
+        : [];
+    return { denyTables: deny, overrideTables: override };
+}
+function splitCsv(s) {
+    var raw = s.split(",");
+    var out = [];
+    for (var i = 0; i < raw.length; i++) {
+        var trimmed = raw[i].trim();
+        if (trimmed)
+            out.push(trimmed);
+    }
+    return out;
+}
+function formatMissingEnvError(missing) {
+    var parts = [];
+    if (missing.clickup.length > 0) {
+        parts.push("ClickUp: " + missing.clickup.join(", "));
+    }
+    if (missing.google.length > 0) {
+        parts.push("Google (Gmail/Calendar): " + missing.google.join(", "));
+    }
+    return "Missing required environment variables — " + parts.join("; ") + ".";
+}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Maps thrown errors from upstream Dovetail packages into MCP tool-result
+ * shapes. Upstream packages already produce remediation-friendly messages
+ * (e.g. handleAuthError in dovetail-google-auth) — preserve them verbatim.
+ */
+export interface ToolError {
+    message: string;
+    retryable: boolean;
+}
+export declare function mapToolError(err: unknown): ToolError;

package/dist/errors.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Maps thrown errors from upstream Dovetail packages into MCP tool-result
+ * shapes. Upstream packages already produce remediation-friendly messages
+ * (e.g. handleAuthError in dovetail-google-auth) — preserve them verbatim.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapToolError = mapToolError;
+function mapToolError(err) {
+    var message = err instanceof Error ? err.message : String(err);
+    var retryable = isRetryable(message);
+    return { message: message, retryable: retryable };
+}
+function isRetryable(message) {
+    var m = message.toLowerCase();
+    if (m.indexOf("rate limit") !== -1)
+        return true;
+    if (m.indexOf("429") !== -1)
+        return true;
+    if (m.indexOf("network") !== -1)
+        return true;
+    if (m.indexOf("etimedout") !== -1)
+        return true;
+    if (m.indexOf("econnreset") !== -1)
+        return true;
+    if (m.indexOf("retries exhausted") !== -1)
+        return true;
+    return false;
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @tenonhq/dovetail-mcp
+ *
+ * MCP server exposing read-only tools for ClickUp, Gmail, Google Calendar,
+ * and ServiceNow, backed by the existing Dovetail integration packages.
+ *
+ * Library exports here are consumed by tests and by alternate hosts
+ * (e.g. an HTTP transport in the future). The bin entry lives in server.ts.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServiceNowSafetyConfig } from "./config";
+import type { ClickUpConfig, GoogleConfig, SincMcpConfig } from "./config";
+import { TOOL_NAMES } from "./registry";
+import type { ToolName, RegistryDeps } from "./registry";
+export { TOOL_NAMES };
+export type { ToolName, SincMcpConfig, ClickUpConfig, GoogleConfig, ServiceNowSafetyConfig };
+export interface CreateServerOptions {
+    /** Override loaded config; tests pass mocks here. */
+    registryDeps?: RegistryDeps;
+    /** Override server name shown to MCP clients. */
+    serverName?: string;
+    /** Override package version reported to MCP clients. */
+    serverVersion?: string;
+}
+export declare function createServer(options?: CreateServerOptions): McpServer;
+export declare function buildDepsFromEnv(): RegistryDeps;

package/dist/index.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * @tenonhq/dovetail-mcp
+ *
+ * MCP server exposing read-only tools for ClickUp, Gmail, Google Calendar,
+ * and ServiceNow, backed by the existing Dovetail integration packages.
+ *
+ * Library exports here are consumed by tests and by alternate hosts
+ * (e.g. an HTTP transport in the future). The bin entry lives in server.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_NAMES = void 0;
+exports.createServer = createServer;
+exports.buildDepsFromEnv = buildDepsFromEnv;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const config_1 = require("./config");
+const registry_1 = require("./registry");
+Object.defineProperty(exports, "TOOL_NAMES", { enumerable: true, get: function () { return registry_1.TOOL_NAMES; } });
+function createServer(options = {}) {
+    var server = new mcp_js_1.McpServer({
+        name: options.serverName || "dovetail-mcp",
+        version: options.serverVersion || "0.0.1"
+    });
+    var deps = options.registryDeps || buildDepsFromEnv();
+    (0, registry_1.registerAllTools)(server, deps);
+    return server;
+}
+function buildDepsFromEnv() {
+    var loaded = (0, config_1.loadConfig)();
+    var missingDescription;
+    var hasMissing = loaded.missing.clickup.length > 0 || loaded.missing.google.length > 0;
+    if (hasMissing) {
+        missingDescription = (0, config_1.formatMissingEnvError)(loaded.missing);
+    }
+    var deps = {
+        servicenow: { safety: loaded.config.servicenowSafety },
+        missingDescription: missingDescription
+    };
+    if (loaded.config.clickup) {
+        deps.clickup = { config: loaded.config.clickup };
+    }
+    if (loaded.config.google) {
+        deps.gmail = { config: loaded.config.google };
+        deps.calendar = { config: loaded.config.google };
+    }
+    return deps;
+}

package/dist/redact.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Argument redaction for telemetry events.
+ *
+ * Pure functions only — testable without filesystem or env access. The goal is
+ * to keep operational signal (tool shape, query strings, IDs) while removing
+ * PII (email bodies, full email addresses) and credentials (tokens, passwords).
+ */
+export declare function redactArgs(args: unknown): unknown;

package/dist/redact.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Argument redaction for telemetry events.
+ *
+ * Pure functions only — testable without filesystem or env access. The goal is
+ * to keep operational signal (tool shape, query strings, IDs) while removing
+ * PII (email bodies, full email addresses) and credentials (tokens, passwords).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactArgs = redactArgs;
+const crypto = __importStar(require("crypto"));
+var TOKEN_KEYS = [
+    "token",
+    "password",
+    "refresh_token",
+    "refreshtoken",
+    "access_token",
+    "accesstoken",
+    "client_secret",
+    "clientsecret",
+    "apikey",
+    "api_key",
+    "clickup_api_token",
+    "authorization",
+    "auth"
+];
+var BODY_KEYS = ["body", "html", "text", "content"];
+var QUERY_KEYS = [
+    "query",
+    "q",
+    "sysparm_query",
+    "subjectpatterns",
+    "labels",
+    "statuses"
+];
+var EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+function redactArgs(args) {
+    return walk(args, "");
+}
+function walk(value, keyPath) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === "string") {
+        return redactString(value, keyPath);
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        var out = [];
+        for (var i = 0; i < value.length; i++) {
+            out.push(walk(value[i], keyPath));
+        }
+        return out;
+    }
+    if (typeof value === "object") {
+        var record = value;
+        var result = {};
+        var keys = Object.keys(record);
+        for (var k = 0; k < keys.length; k++) {
+            var key = keys[k];
+            var lowered = key.toLowerCase();
+            if (TOKEN_KEYS.indexOf(lowered) !== -1) {
+                result[key] = "[REDACTED]";
+                continue;
+            }
+            if (BODY_KEYS.indexOf(lowered) !== -1 && typeof record[key] === "string") {
+                result[key] = "[REDACTED:body]";
+                continue;
+            }
+            result[key] = walk(record[key], lowered);
+        }
+        return result;
+    }
+    return value;
+}
+function redactString(value, keyPath) {
+    if (QUERY_KEYS.indexOf(keyPath) !== -1) {
+        return value;
+    }
+    if (EMAIL_RE.test(value)) {
+        return maskEmail(value);
+    }
+    if (value.length > 200) {
+        return "sha256:" + sha256First12(value);
+    }
+    return value;
+}
+function maskEmail(addr) {
+    var at = addr.indexOf("@");
+    if (at < 0) {
+        return addr;
+    }
+    var local = addr.substring(0, at);
+    var domain = addr.substring(at + 1);
+    var prefix = local.length <= 3 ? local : local.substring(0, 3);
+    return prefix + "***@" + domain;
+}
+function sha256First12(s) {
+    return crypto.createHash("sha256").update(s, "utf8").digest("hex").substring(0, 12);
+}

package/dist/registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tool registration glue. Exports TOOL_NAMES (the canonical 12-tuple) and
+ * registerAllTools(), which wires every handler with telemetry + JSON
+ * serialization for MCP transport.
+ *
+ * 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.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ClickUpDeps } from "./tools/clickup";
+import type { GmailDeps } from "./tools/gmail";
+import type { CalendarDeps } from "./tools/calendar";
+import type { ServiceNowDeps } from "./tools/servicenow";
+export declare var TOOL_NAMES: readonly ["clickup_list_tasks", "clickup_get_task", "clickup_search_tasks", "clickup_get_team_sync", "gmail_get_unread", "gmail_get_starred", "gmail_search", "gmail_get_action_required", "calendar_get_today", "calendar_get_week", "calendar_get_event", "servicenow_query_table"];
+export type ToolName = typeof TOOL_NAMES[number];
+export interface RegistryDeps {
+    clickup?: ClickUpDeps;
+    gmail?: GmailDeps;
+    calendar?: CalendarDeps;
+    servicenow: ServiceNowDeps;
+    missingDescription?: string;
+}
+interface ToolDescriptor {
+    name: ToolName;
+    description: string;
+    shape: z.ZodRawShape;
+    handler: (args: any) => Promise<any>;
+}
+export declare function registerAllTools(server: McpServer, deps: RegistryDeps): void;
+export declare function buildDescriptorsForTests(deps: RegistryDeps): ToolDescriptor[];
+export {};