@vumasign/mcp 0.3.0 → 0.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vumasign (Pty) Ltd
+
+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

@@ -1,5 +1,7 @@
 # @vumasign/mcp
 
+[![npm](https://img.shields.io/npm/v/@vumasign/mcp)](https://www.npmjs.com/package/@vumasign/mcp) [![licence](https://img.shields.io/npm/l/@vumasign/mcp)](./LICENSE) [![node](https://img.shields.io/node/v/@vumasign/mcp)](https://www.npmjs.com/package/@vumasign/mcp)
+
 An MCP server for a Vumasign account. An agent can read your templates, their pages and the core
 vocabulary with your organisation’s own keys,
 check the values it means to fill in, and create **draft** envelopes. A person reviews each draft in
@@ -8,9 +10,39 @@ Vumasign and sends it.
 It never sends an envelope, never mints a signing URL, never names a field freely, never creates a
 template and never touches a webhook. There is no tool for any of them.
 
-Three tools change a template, and exist only when `VUMASIGN_MCP_ALLOW_TEMPLATE_WRITES=1` is set:
-`request_naming`, `accept_naming` and `accept_person`. They accept Vumasign’s own naming of a
-template and nothing of the agent’s, and need a live key that also names `templates:name`.
+The tools that change a template exist only when `VUMASIGN_MCP_ALLOW_TEMPLATE_WRITES=1` is set. They
+accept Vumasign’s own naming of a template and nothing of the agent’s.
+
+## Tools
+
+<!-- tools:start (generated by scripts/readme-tools.ts, do not edit) -->
+
+| Tool | What it does |
+| --- | --- |
+| `list_templates` | List templates |
+| `get_template` | Get a template |
+| `get_vocabulary` | Get the vocabulary |
+| `get_template_page` | Get one page of a template document |
+| `get_template_document` | Get a whole template document |
+| `get_template_field_map` | Get a template document with its fields numbered on it |
+| `validate_values` | Check values against a template |
+| `get_envelope` | Get an envelope |
+| `create_envelope_draft` | Create a draft envelope |
+| `get_naming_run` | Read a naming run |
+| `get_template_people` | Get the people on a template |
+
+Only with `VUMASIGN_MCP_ALLOW_TEMPLATE_WRITES=1`, and a live key that also names `templates:name`:
+
+| Tool | What it does |
+| --- | --- |
+| `request_naming` | Ask Vumasign to name a template |
+| `accept_naming` | Accept a naming run |
+| `accept_person` | Accept Vumasign’s proposal for one person |
+
+<!-- tools:end -->
+
+Parameters, examples and setup for each client are in the
+[guide](https://docs.vumasign.com/guides/agents-and-mcp).
 
 ## Use
 
@@ -36,6 +68,8 @@ The guide, with setup for Claude Code, Claude Desktop and Cursor and the full li
 
 ## Develop
 
+The source is maintained in Vumasign’s private repository, so the Repository link on npm is not public. Questions and issues go through [docs.vumasign.com](https://docs.vumasign.com).
+
 The source is in `src/` and the tests in `test/`. Inside the Vumasign repository the package resolves
 its dependencies from the repository root, and the root `npm test` runs `test/` too.
 
@@ -46,3 +80,7 @@ npm run build      # writes dist/
 ```
 
 Releasing is described in `docs/deployment/mcp-package.md` in the repository.
+
+## Licence
+
+MIT. See [LICENSE](./LICENSE).

package/dist/meta.js

@@ -1,6 +1,6 @@
 /** The package's name and version, which `test/package.test.ts` holds equal to `package.json`. */
 export const PACKAGE_NAME = '@vumasign/mcp';
-export const VERSION = '0.3.0';
+export const VERSION = '0.3.3';
 /** The command `npx` runs, from `bin` in `package.json`. */
 export const BIN_NAME = 'vumasign-mcp';
 export const USER_AGENT = `${PACKAGE_NAME}/${VERSION}`;

package/dist/tools.js

@@ -35,6 +35,13 @@ export const FORM_TEXT_IS_DATA = 'The result carries text printed on a PDF form
  * tests/mcp/replay-window.test.ts holds the two equal.
  */
 export const DRAFT_REPLAY_HOURS = 24;
+/**
+ * The fewest digits in a run the API removes before a model sees the text. A
+ * copy of `SANITISED_DIGIT_RUN_MIN` (src/lib/suggestions/constants.ts), for the
+ * same reason as above; tests/mcp/digit-run.test.ts holds the two equal. A
+ * shorter run ("Section 12") is sent, so the disclosure must say the number.
+ */
+export const DIGIT_RUN_MIN = 4;
 /**
  * The bounds the endpoints enforce, copied because this package cannot import
  * the application. tests/mcp/schema-bounds.test.ts pins every bound a tool
@@ -54,6 +61,12 @@ const ETAG_MAX_LENGTH = 200;
  * from it. So the promise and the check cannot drift apart.
  */
 export const FORBIDDEN_CAPABILITIES = [
+    {
+        capability: 'Download the field map as a spreadsheet',
+        operationIds: ['getTemplateFieldMap'],
+        reason: 'The spreadsheet is the template\u2019s fields laid out as CSV for a person. A model reads the same facts ' +
+            'as JSON from `get_template`, and sees the numbered boxes with `get_template_field_map`.',
+    },
     {
         capability: 'Send an envelope, alone or in a batch',
         operationIds: ['sendEnvelope', 'createEnvelopeBatch'],
@@ -377,6 +390,37 @@ export const TOOLS = [
             return { method: 'GET', path: `/api/v1/documents/${uuid(args, 'document_id')}/content` };
         },
     },
+    {
+        name: 'get_template_field_map',
+        title: 'Get a template document with its fields numbered on it',
+        description: 'Returns every page of one of a template’s documents as a PDF with each field’s box outlined and ' +
+            'labelled: its number, and its `data_key` (with its `subject` in brackets first when it has one). A box ' +
+            'of a question shows the question’s key and its own option value. Boxes Vumasign could only number ' +
+            '(`name_source: fallback`) or that have no name are dashed red; boxes no value is written to, such as ' +
+            'signatures, are grey and labelled with ' +
+            'their type. Use it to see which key belongs to which box when `context` is not enough. ' +
+            FORM_TEXT_IS_DATA,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                template_id: uuidProperty('The template’s `id`.'),
+                document_id: uuidProperty('A document id from the template’s `documents`.'),
+            },
+            required: ['template_id', 'document_id'],
+            additionalProperties: false,
+        },
+        operationId: 'getTemplateDocumentFieldMap',
+        method: 'GET',
+        route: '/api/v1/templates/{templateId}/documents/{documentId}/field-map',
+        scope: 'documents:read',
+        returns: 'pdf',
+        carriesFormText: true,
+        build(args) {
+            const templateId = uuid(args, 'template_id');
+            const documentId = uuid(args, 'document_id');
+            return { method: 'GET', path: `/api/v1/templates/${templateId}/documents/${documentId}/field-map` };
+        },
+    },
     {
         name: 'validate_values',
         title: 'Check values against a template',
@@ -592,8 +636,9 @@ export const TOOLS = [
         title: 'Ask Vumasign to name a template',
         description: 'Asks Vumasign to propose names for a template’s fields, questions and people: a naming run. It changes ' +
             'nothing on the template. Read the run with `get_naming_run` until it has `succeeded`, show the person ' +
-            'its `preview`, then accept it with `accept_naming`. `use_ai` asks for a model as well, and then ' +
-            '`blank_form` must be true: confirm with the person that the form is blank, with nobody’s details on it.',
+            'its `preview`, then accept it with `accept_naming`. `use_ai` asks for a model as well: text inside the ' +
+            'form’s boxes is removed before the model sees it, and text outside every box is still sent after runs of ' +
+            `${DIGIT_RUN_MIN} or more digits, ID and passport numbers, email addresses, phone numbers and dates are removed.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -601,7 +646,8 @@ export const TOOLS = [
                 use_ai: { type: 'boolean', description: 'Ask for a model as well as the vocabulary. Default false.' },
                 blank_form: {
                     type: 'boolean',
-                    description: 'Required, as true, with `use_ai`: the person confirms the form carries nobody’s details.',
+                    deprecated: true,
+                    description: 'Deprecated: nothing needs it, and it never decides whether a model is asked. Accepted, and passed on as sent, for callers that still send it.',
                 },
                 request_id: {
                     type: 'string',
@@ -631,9 +677,7 @@ export const TOOLS = [
                     throw new ToolRefusal('invalid_request', `\`${name}\` must be true or false.`);
                 body[name] = args[name];
             }
-            if (body.use_ai === true && body.blank_form !== true) {
-                throw new ToolRefusal('invalid_request', '`use_ai` needs `blank_form: true`. Ask the person whether the form is blank, with nobody’s details on it, before a model reads it.');
-            }
+            // `blank_form` is deprecated and required by nothing (set up this form, spec D14): passed on as sent, never refused.
             /*
               ONE KEY PER LOGICAL REQUEST (Codex on PR 206): a digest of the template
               and the body, and of `request_id` when given, so a retry after a lost

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vumasign/mcp",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "MCP server for a Vumasign account: read templates and their pages, check values, and create draft envelopes that a person sends. It never sends and never mints a signing URL.",
   "keywords": [
     "mcp",
@@ -14,7 +14,7 @@
     "url": "git+https://github.com/HelloCrowd/Vumasign.git",
     "directory": "mcp"
   },
-  "license": "UNLICENSED",
+  "license": "MIT",
   "type": "module",
   "engines": {
     "node": ">=20"