@canveo/mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - 2026-08-31
+
+- Publish-ready npm package `@canveo/mcp` (stdio MCP server for any MCP client).
+- Keep `canveo-cursor-mcp` as a CLI alias for existing local configs.
+- Add MIT license, CI, and a tagged GitHub Release workflow for `npm publish`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Canveo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @canveo/mcp
+
+Canveo’s [Model Context Protocol](https://modelcontextprotocol.io/) server. It is a **local stdio process**, not an AWS service. Any MCP client can spawn it; it then calls the existing Canveo API (`cvback`) with a Personal Access Token.
+
+## What it does
+
+| Tool | Purpose |
+| --- | --- |
+| `canveo.listPlaybooks` | List playbooks for the authenticated org |
+| `canveo.reviewDoc` | Upload a local `.docx`, run compliance assessment, write redlined `.docx` + assessment JSON |
+
+The server does not host contracts. Upload, analysis, and export run on Canveo’s existing API (already deployed on AWS). This package only needs to be published to **npm**.
+
+## Install / run
+
+Requires Node 20+.
+
+```bash
+npx -y @canveo/mcp
+```
+
+Or, after `npm i -g @canveo/mcp`:
+
+```bash
+canveo-mcp
+```
+
+`canveo-cursor-mcp` is the same binary (compat alias).
+
+## Environment
+
+| Variable | Required | Example |
+| --- | --- | --- |
+| `CANVEO_API_URL` | yes | `https://api.canveo.net/api` |
+| `CANVEO_PAT` | yes | PAT from Canveo **Settings → Personal access tokens** |
+| `CANVEO_WEB_URL` | no | `https://app.canveo.net` (used for agreement deep links) |
+| `CANVEO_OUTPUT_DIR` | no | `canveo-output` |
+
+Never commit the PAT.
+
+## Client config
+
+Cursor, Claude Desktop, VS Code Copilot, and other MCP hosts all use the same shape: spawn this package and pass env.
+
+### Cursor (plugin)
+
+The `canveo-cursor-plugin` repo ships `.mcp.json` that runs `npx -y @canveo/mcp`.
+
+### Cursor / Claude Desktop / other stdio clients
+
+```json
+{
+  "mcpServers": {
+    "canveo": {
+      "command": "npx",
+      "args": ["-y", "@canveo/mcp"],
+      "env": {
+        "CANVEO_API_URL": "https://api.canveo.net/api",
+        "CANVEO_PAT": "cvpat_...",
+        "CANVEO_WEB_URL": "https://app.canveo.net"
+      }
+    }
+  }
+}
+```
+
+Local development (unpublished):
+
+```json
+{
+  "mcpServers": {
+    "canveo": {
+      "command": "node",
+      "args": ["/absolute/path/to/canveo-mcp/index.js"],
+      "env": {
+        "CANVEO_API_URL": "https://api.canveo.net/api",
+        "CANVEO_PAT": "cvpat_..."
+      }
+    }
+  }
+}
+```
+
+## Publish to npm (maintainers)
+
+This is **not** a Terraform/ECS deploy.
+
+1. Create the public npm org/scope `@canveo` if it does not exist.
+2. Add repo secret `NPM_TOKEN` (Automation token with publish rights on `@canveo`).
+3. Bump `version` in `package.json`.
+4. Create a GitHub Release tagged `v0.1.0` (must match `package.json`). The **Publish npm** workflow runs `npm publish --access public`.
+
+Manual fallback:
+
+```bash
+npm login
+npm test
+npm publish --access public
+```
+
+## Development
+
+```bash
+npm ci
+npm test
+npm run pack:check
+```
+
+Related: `cvback` (API), `canveo-cursor-plugin` (Cursor wrapper), `cv` (web app).

package/index.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const packageJson = JSON.parse(
+  readFileSync(new URL("./package.json", import.meta.url), "utf8")
+);
+const SERVER_NAME = "canveo-mcp";
+const SERVER_VERSION = packageJson.version;
+
+const API_URL = process.env.CANVEO_API_URL || "";
+const API_TOKEN = process.env.CANVEO_PAT || "";
+const WEB_URL = process.env.CANVEO_WEB_URL || "";
+const DEFAULT_OUTPUT_DIR = process.env.CANVEO_OUTPUT_DIR || "canveo-output";
+const POLL_INTERVAL_MS = Number(process.env.CANVEO_POLL_INTERVAL_MS || 2000);
+const POLL_TIMEOUT_MS = Number(process.env.CANVEO_POLL_TIMEOUT_MS || 600000);
+
+/**
+ * @param {string} route
+ * @param {RequestInit} [options]
+ */
+async function canveoApi(route, options = {}) {
+  const url = `${API_URL.replace(/\/$/, "")}/${route.replace(/^\//, "")}`;
+  const headers = {
+    Authorization: `Bearer ${API_TOKEN}`,
+    ...(options.body ? { "Content-Type": "application/json" } : {}),
+    ...(options.headers || {}),
+  };
+
+  const response = await fetch(url, { ...options, headers });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) {
+    throw new Error(
+      `Canveo API error (${response.status}) on ${route}: ${
+        payload?.message || response.statusText
+      }`
+    );
+  }
+  return payload;
+}
+
+/**
+ * @param {string} uploadUrl
+ * @param {Buffer} fileBuffer
+ * @param {string} contentType
+ */
+async function uploadFileToSignedUrl(uploadUrl, fileBuffer, contentType) {
+  const response = await fetch(uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": contentType },
+    body: fileBuffer,
+  });
+  if (!response.ok) {
+    throw new Error(`Signed URL upload failed (${response.status}).`);
+  }
+}
+
+/**
+ * @param {string} url
+ */
+async function downloadBuffer(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download file (${response.status}).`);
+  }
+  const arr = await response.arrayBuffer();
+  return Buffer.from(arr);
+}
+
+/**
+ * @param {string} originalVersionId
+ * @param {Record<string, unknown> | null} reviewOptions
+ */
+async function startAnalysis(originalVersionId, reviewOptions = null) {
+  const payload = {
+    extractMetadata: true,
+    topicsAndPropertiesTagging: true,
+    complianceAssessment: true,
+    reviewOptions:
+      reviewOptions && typeof reviewOptions === "object" ? reviewOptions : null,
+  };
+  const result = await canveoApi(`/agrv/${originalVersionId}/analyze`, {
+    method: "POST",
+    body: JSON.stringify(payload),
+  });
+  return result?.data?.id || result?.data?.jobId || null;
+}
+
+/**
+ * @param {string} jobId
+ */
+async function waitForAnalysis(jobId) {
+  const started = Date.now();
+  while (Date.now() - started < POLL_TIMEOUT_MS) {
+    const status = await canveoApi(`/analysis-jobs/status/${jobId}`, {
+      method: "GET",
+    });
+    const data = status?.data || {};
+    if (data.status === "finished") {
+      return data?.versions?.finalVersionId || data?.versions?.workingVersionId;
+    }
+    if (data.status === "error" || data.status === "cancelled") {
+      throw new Error(`Analysis job ended with status "${data.status}".`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+  throw new Error("Timed out waiting for analysis job completion.");
+}
+
+/**
+ * @param {string} filePath
+ * @param {string | undefined} playbookId
+ * @param {Record<string, unknown>} options
+ * @param {string | undefined} outputDir
+ */
+async function reviewDoc(filePath, playbookId, options, outputDir) {
+  const absolutePath = path.resolve(filePath);
+  const inputName = path.basename(absolutePath);
+  const outputBase = inputName.replace(/\.[^.]+$/, "");
+  const resolvedOutputDir = path.resolve(outputDir || DEFAULT_OUTPUT_DIR);
+  await fs.mkdir(resolvedOutputDir, { recursive: true });
+
+  const fileBuffer = await fs.readFile(absolutePath);
+  const contentType =
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+
+  const signedUpload = await canveoApi("/upload/signedUrl", {
+    method: "POST",
+    body: JSON.stringify({
+      contentType,
+      bucketAlias: "documents",
+    }),
+  });
+  const uploadData = signedUpload?.data || {};
+  await uploadFileToSignedUrl(uploadData.uploadSignedUrl, fileBuffer, contentType);
+
+  const created = await canveoApi("/cursor/review-doc", {
+    method: "POST",
+    body: JSON.stringify({
+      sourceS3Key: uploadData.key,
+      fileName: inputName,
+      playbookId: playbookId || undefined,
+      options: options || {},
+    }),
+  });
+  const agreementId = created?.data?.agreementId || null;
+  const originalVersionId = created?.data?.originalVersionId || null;
+  if (!originalVersionId) {
+    throw new Error("No originalVersionId returned by /cursor/review-doc.");
+  }
+
+  const jobId = await startAnalysis(originalVersionId, options);
+  if (!jobId) {
+    throw new Error("No jobId returned when starting analysis.");
+  }
+
+  const finalVersionId = await waitForAnalysis(String(jobId));
+  if (!finalVersionId) {
+    throw new Error("No finalVersionId found for completed analysis job.");
+  }
+
+  const exportData = await canveoApi(
+    `/cursor/review-doc/export/${finalVersionId}`,
+    {
+      method: "GET",
+    }
+  );
+  const downloadUrl = exportData?.data?.downloadUrl;
+  if (!downloadUrl) {
+    throw new Error("No downloadUrl returned by export endpoint.");
+  }
+
+  const docBuffer = await downloadBuffer(downloadUrl);
+  const outputDocxPath = path.join(resolvedOutputDir, `${outputBase}-redlined.docx`);
+  await fs.writeFile(outputDocxPath, docBuffer);
+
+  const assessment = await canveoApi(
+    `/compliance-assessments/version/${finalVersionId}`,
+    {
+      method: "GET",
+    }
+  );
+  const outputJsonPath = path.join(
+    resolvedOutputDir,
+    `${outputBase}-assessment.json`
+  );
+  await fs.writeFile(outputJsonPath, JSON.stringify(assessment?.data || {}, null, 2));
+
+  return {
+    outputDocxPath,
+    outputJsonPath,
+    agreementId,
+    finalVersionId,
+    agreementUrl:
+      WEB_URL && agreementId
+        ? `${WEB_URL.replace(/\/$/, "")}/agreements/${agreementId}`
+        : null,
+  };
+}
+
+export async function startMcpServer() {
+  if (!API_URL || !API_TOKEN) {
+    throw new Error(
+      "Missing CANVEO_API_URL or CANVEO_PAT environment variables."
+    );
+  }
+
+  const server = new Server(
+    {
+      name: SERVER_NAME,
+      version: SERVER_VERSION,
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: "canveo.listPlaybooks",
+        description: "List active Canveo playbooks for the current organization.",
+        inputSchema: { type: "object", properties: {} },
+      },
+      {
+        name: "canveo.reviewDoc",
+        description:
+          "Upload a local .docx, run compliance assessment, and save redlined .docx + assessment JSON locally.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            filePath: { type: "string" },
+            playbookId: { type: "string" },
+            options: { type: "object" },
+            outputDir: { type: "string" },
+          },
+          required: ["filePath"],
+        },
+      },
+    ],
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+
+    if (name === "canveo.listPlaybooks") {
+      const data = await canveoApi("/playbook", { method: "GET" });
+      const playbooks = Array.isArray(data?.data) ? data.data : [];
+
+      const enriched = await Promise.all(
+        playbooks.map(async (playbook) => {
+          const id = playbook?._id;
+          if (!id) return playbook;
+          try {
+            const latest = await canveoApi(`/playbook/${id}/versions/latest`, {
+              method: "GET",
+            });
+            return {
+              ...playbook,
+              latestVersion: latest?.data || null,
+            };
+          } catch {
+            return playbook;
+          }
+        })
+      );
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(enriched, null, 2) },
+        ],
+      };
+    }
+
+    if (name === "canveo.reviewDoc") {
+      const result = await reviewDoc(
+        String(args.filePath),
+        typeof args.playbookId === "string" ? args.playbookId : undefined,
+        typeof args.options === "object" && args.options ? args.options : {},
+        typeof args.outputDir === "string" ? args.outputDir : undefined
+      );
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+
+    throw new Error(`Unknown tool: ${name}`);
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  const currentFile = fileURLToPath(import.meta.url);
+  if (process.env.CANVEO_MCP_DEBUG === "true") {
+    console.error(`Canveo MCP started from ${currentFile}`);
+  }
+}
+
+const isDirectRun =
+  Boolean(process.argv[1]) &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isDirectRun) {
+  try {
+    await startMcpServer();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+export { reviewDoc, waitForAnalysis, startAnalysis, SERVER_NAME, SERVER_VERSION };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@canveo/mcp",
+  "version": "0.1.0",
+  "description": "Canveo Model Context Protocol server for contract review, creation, sending, and signing. Works with any MCP client (Cursor, Claude Desktop, VS Code, and others).",
+  "type": "module",
+  "license": "MIT",
+  "author": "Canveo",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "canveo",
+    "contracts",
+    "compliance",
+    "review"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getcanveo/canveo-mcp.git"
+  },
+  "homepage": "https://github.com/getcanveo/canveo-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/getcanveo/canveo-mcp/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "canveo-mcp": "./index.js",
+    "canveo-cursor-mcp": "./index.js"
+  },
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "vitest --run",
+    "pack:check": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.7"
+  }
+}