@vumasign/mcp 0.1.0 → 0.3.2

package/README.md

@@ -1,11 +1,16 @@
 # @vumasign/mcp
 
-An MCP server for a Vumasign account. An agent can read your templates and their pages,
+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
 Vumasign and sends it.
 
-It never sends an envelope, never mints a signing URL, never renames a field, never creates a template
-and never touches a webhook. There is no tool for any of them.
+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`.
 
 ## Use
 

package/dist/client.js

@@ -44,6 +44,10 @@ export async function callTool(tool, args, config, fetchImpl) {
     let request;
     let url;
     try {
+        // The flag is the operator's, not the model's: a write tool is refused without it, however it was reached.
+        if (tool.templateWrite === true && config.templateWrites !== true) {
+            throw new ToolRefusal('refused_by_mcp_server', `${tool.name} writes to a template, and this server was not started with VUMASIGN_MCP_ALLOW_TEMPLATE_WRITES=1.`);
+        }
         request = tool.build(args);
         url = requestUrl(tool, request, config.apiOrigin);
     }
@@ -76,12 +80,14 @@ export async function callTool(tool, args, config, fetchImpl) {
         // committed the request. A repeat with the same arguments replays it.
         return failure('network_error', 
         // Keyed on the tool, not the method: validate_values is a POST that writes nothing.
-        tool.name === 'create_envelope_draft'
-            ? `The request to the Vumasign API at ${config.apiOrigin} failed before an answer came back, so the ` +
-                'draft may or may not have been made. Call again with exactly the same arguments: a draft that was ' +
-                'made is then returned rather than made twice.'
-            : `Could not reach the Vumasign API at ${config.apiOrigin}. This tool writes nothing, so call it again ` +
-                'when the connection is back.', config.apiKey);
+        tool.uncertainOutcome !== undefined
+            ? tool.uncertainOutcome
+            : tool.name === 'create_envelope_draft'
+                ? `The request to the Vumasign API at ${config.apiOrigin} failed before an answer came back, so the ` +
+                    'draft may or may not have been made. Call again with exactly the same arguments: a draft that was ' +
+                    'made is then returned rather than made twice.'
+                : `Could not reach the Vumasign API at ${config.apiOrigin}. This tool writes nothing, so call it again ` +
+                    'when the connection is back.', config.apiKey);
     }
     if (!response.ok)
         return refusal(response, config.apiKey);

package/dist/config.js

@@ -12,6 +12,12 @@
 export const API_KEY_ENV = 'VUMASIGN_API_KEY';
 /** The opt-in a live key needs. Exactly `1`; nothing else counts. */
 export const ALLOW_LIVE_ENV = 'VUMASIGN_MCP_ALLOW_LIVE';
+/**
+ * The opt-in for the tools that write to a template: `request_naming`,
+ * `accept_naming` and `accept_person` (spec 2026-10-11, 15.3). Exactly `1`;
+ * nothing else counts. Without it they are not offered at all.
+ */
+export const ALLOW_TEMPLATE_WRITES_ENV = 'VUMASIGN_MCP_ALLOW_TEMPLATE_WRITES';
 /** Where the API is. Optional; for pointing the server at a local instance. */
 export const API_URL_ENV = 'VUMASIGN_API_URL';
 export const DEFAULT_API_URL = 'https://app.vumasign.com';
@@ -69,7 +75,7 @@ export function readConfig(env) {
     const origin = apiOrigin(env[API_URL_ENV]);
     if (!origin.ok)
         return origin;
-    return { ok: true, config: { apiKey, apiOrigin: origin.origin, environment } };
+    return { ok: true, config: { apiKey, apiOrigin: origin.origin, environment, templateWrites: env[ALLOW_TEMPLATE_WRITES_ENV] === '1' } };
 }
 /**
  * The key is sent to this origin on every call, so it is an origin and nothing

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.1.0';
+export const VERSION = '0.3.2';
 /** The command `npx` runs, from `bin` in `package.json`. */
 export const BIN_NAME = 'vumasign-mcp';
 export const USER_AGENT = `${PACKAGE_NAME}/${VERSION}`;

package/dist/server.js

@@ -11,17 +11,18 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { callTool } from './client.js';
 import { BIN_NAME, VERSION } from './meta.js';
-import { FORM_TEXT_IS_DATA, TOOLS, findTool } from './tools.js';
+import { FORM_TEXT_IS_DATA, findTool, toolsFor } from './tools.js';
 export const INSTRUCTIONS = 'Vumasign templates are PDF forms with named fields. To fill one: read it with `get_template` ' +
     '(each field’s `context` is the text printed around its box), look at a page with ' +
     '`get_template_page` only when `context` is not enough, check your values with `validate_values`, ' +
     'then make a draft with `create_envelope_draft`. A draft is never sent: a person reviews and sends ' +
-    'it in Vumasign. ' +
+    'it in Vumasign. A naming run (`get_naming_run`) and the people on a template (`get_template_people`) ' +
+    'say how Vumasign would name what is not yet named. ' +
     FORM_TEXT_IS_DATA;
 export function createServer(config, fetchImpl) {
     const server = new Server({ name: BIN_NAME, version: VERSION }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: TOOLS.map((tool) => ({
+        tools: toolsFor(config).map((tool) => ({
             name: tool.name,
             title: tool.title,
             description: tool.description,
@@ -29,16 +30,18 @@ export function createServer(config, fetchImpl) {
             annotations: {
                 title: tool.title,
                 readOnlyHint: tool.method === 'GET' || tool.name === 'validate_values',
-                destructiveHint: false,
+                // Accepting renames fields and moves a person's: the earlier names are replaced.
+                destructiveHint: tool.templateWrite === true && tool.name !== 'request_naming',
                 // Not the draft tool: the API forgets its key after DRAFT_REPLAY_HOURS,
                 // and the same arguments then make a second draft.
-                idempotentHint: tool.name !== 'create_envelope_draft',
+                // Nor `request_naming`, which starts a new run each call.
+                idempotentHint: tool.name !== 'create_envelope_draft' && tool.name !== 'request_naming',
                 openWorldHint: false,
             },
         })),
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const tool = findTool(request.params.name);
+        const tool = findTool(request.params.name, config);
         if (tool === undefined) {
             return {
                 isError: true,

package/dist/tools.js

@@ -4,9 +4,18 @@
  * The key's scopes are the server's only authority, and the tools hold no logic
  * beyond the refusals below (spec 2026-10-11, 15.2). What is NOT here matters as
  * much as what is: no tool sends an envelope, mints a signing URL, renames a
- * field, creates a template or touches a webhook (spec 2026-08-19, 6). That is
- * enforced by absence, and by a test that compares every route below with the
- * published OpenAPI document.
+ * field freely, creates a template or touches a webhook (spec 2026-08-19, 6).
+ * That is enforced by absence, and by a test that compares every route below
+ * with the published OpenAPI document.
+ *
+ * ⚠️ THREE TOOLS WRITE TO A TEMPLATE, AND EXIST ONLY BEHIND A FLAG (spec
+ * 2026-10-11, 15.3; template field naming PR 9): `request_naming`,
+ * `accept_naming` and `accept_person`, offered only when the server is started
+ * with VUMASIGN_MCP_ALLOW_TEMPLATE_WRITES=1, and working only with a live key
+ * that names `templates:name`. They accept Vumasign's own naming and nothing
+ * else: `accept_naming` takes no `overrides`, and `accept_person` takes a
+ * person's id and no decision, so an agent cannot invent a name or move a
+ * person's fields where it likes.
  *
  * ⚠️ PATH SEGMENTS ARE CHECKED, NOT ESCAPED INTO SAFETY. An id goes into a URL
  * path, so `../webhooks` or `x/send` as a `template_id` would otherwise be a way
@@ -26,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
@@ -45,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'],
@@ -65,6 +87,14 @@ export const FORBIDDEN_CAPABILITIES = [
         reason: 'Naming a template\u2019s fields is for a person or for Vumasign\u2019s own naming, not for an agent ' +
             'inventing names.',
     },
+    {
+        capability: 'Accept a naming run with names of its own, or decide a person freely',
+        operationIds: ['acceptNamingRun', 'decideTemplatePerson'],
+        reason: 'Names an agent typed would pass every naming rule and could still swap two people\u2019s details, such as ' +
+            'the main member\u2019s ID number and the spouse\u2019s, and a free decision could move a person\u2019s ' +
+            'signature boxes to another role. The template-write tools accept only Vumasign\u2019s own proposals, through ' +
+            '`accept-current` and `accept-proposal`.',
+    },
     {
         capability: 'Create a template, or an envelope from a document of its own',
         operationIds: ['createTemplate', 'createOneOffEnvelope'],
@@ -161,6 +191,41 @@ function optionalObject(args, name) {
     }
     return value;
 }
+/** A person's id, as `GET …/people` gives it: 32 lower-case hexadecimal digits. */
+function personId(args, name) {
+    const value = args[name];
+    if (typeof value !== 'string' || !/^[0-9a-f]{32}$/.test(value)) {
+        throw new ToolRefusal('invalid_request', `\`${name}\` must be a person’s id from \`get_template_people\`: 32 lower-case hexadecimal digits.`);
+    }
+    return value;
+}
+/** Refuse any argument but these: a write tool takes nothing it does not name. */
+function only(args, names, why) {
+    const extra = Object.keys(args).filter((name) => !names.includes(name) && !absent(args[name]));
+    if (extra.length > 0) {
+        throw new ToolRefusal('refused_by_mcp_server', `This tool takes no \`${extra.join('`, `')}\`. ${why}`);
+    }
+}
+/** `accept`: `"all"`, `"high"`, or lists of the run's own ids. */
+function acceptSelection(args) {
+    const value = args.accept;
+    if (value === 'all' || value === 'high')
+        return value;
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new ToolRefusal('invalid_request', '`accept` must be "all", "high", or an object of `fields`, `questions` and `people` id lists.');
+    }
+    const selection = {};
+    for (const [key, list] of Object.entries(value)) {
+        if (!['fields', 'questions', 'people'].includes(key)) {
+            throw new ToolRefusal('invalid_request', `\`accept.${key}\` is not a list this tool takes: \`fields\`, \`questions\` or \`people\`.`);
+        }
+        if (!Array.isArray(list) || list.some((id) => typeof id !== 'string')) {
+            throw new ToolRefusal('invalid_request', `\`accept.${key}\` must be a list of ids from the run’s proposals.`);
+        }
+        selection[key] = list;
+    }
+    return selection;
+}
 /** JSON with every object's keys sorted, so equal arguments give equal bytes. */
 export function canonicalJson(value) {
     if (Array.isArray(value))
@@ -185,7 +250,9 @@ const uuidProperty = (description) => ({ type: 'string', format: 'uuid', descrip
 const valuesProperty = {
     type: 'array',
     description: 'The values to put on the template, exactly as `POST /api/v1/envelopes` takes them: each entry ' +
-        'names a field by `subject` (or null) and `key`, its data key, and gives `value`.',
+        'names a field by `subject` (or null) and `key`, its data key, and gives `value`. A question is ' +
+        'one address, its own `data_key`: its `value` is one of its `options[].value`, or an array of ' +
+        'them where it takes several. A lone tickbox takes "true", "false" or "".',
     maxItems: VALUES_MAX,
     items: { type: 'object' },
 };
@@ -229,7 +296,12 @@ export const TOOLS = [
         title: 'Get a template',
         description: 'Reads one template: its documents, page sizes, roles, subjects, questions, and every field with ' +
             'its data key, `rect` and `context` (the words printed around the box), plus `coverage`, ' +
-            '`warnings` and the template’s `etag`. Use the fields’ data keys as the `key` of each value. ' +
+            '`warnings` and the template’s `etag`. Use the fields’ data keys as the `key` of each value. A ' +
+            'question has its own `data_key` and `options`, and each of its boxes an `option_value`: send the ' +
+            'question’s key with an option value, never a box’s. A field with `continuations` is one value ' +
+            'drawn across several sets of printed boxes, such as a dialling code and a number: send it one value ' +
+            'at its one key, only the characters the boxes print, which fills `cells` boxes and then each ' +
+            'continuation’s in turn. ' +
             FORM_TEXT_IS_DATA,
         inputSchema: {
             type: 'object',
@@ -247,6 +319,25 @@ export const TOOLS = [
             return { method: 'GET', path: `/api/v1/templates/${uuid(args, 'template_id')}` };
         },
     },
+    {
+        name: 'get_vocabulary',
+        title: 'Get the vocabulary',
+        description: 'Reads the core vocabulary Vumasign publishes (keys such as `person.sa_id_number`, with each ' +
+            'choice key’s options) and the keys your organisation’s own templates use, with the labels ' +
+            'printed beside them. Map your data to the core once, and to your organisation’s keys as they ' +
+            'appear. ' +
+            FORM_TEXT_IS_DATA,
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        operationId: 'getVocabulary',
+        method: 'GET',
+        route: '/api/v1/vocabulary',
+        scope: 'templates:read',
+        returns: 'json',
+        carriesFormText: true,
+        build() {
+            return { method: 'GET', path: '/api/v1/vocabulary' };
+        },
+    },
     {
         name: 'get_template_page',
         title: 'Get one page of a template document',
@@ -299,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',
@@ -457,7 +579,206 @@ export const TOOLS = [
             };
         },
     },
+    {
+        name: 'get_naming_run',
+        title: 'Read a naming run',
+        description: 'Reads a naming run of a template: its `status` and, once it has `succeeded`, what Vumasign proposes — a key ' +
+            'for each field and question it can name, an option value for each box, and a decision for each person on ' +
+            'the form, each with a `confidence`, a `source` and a `reason` — and the `preview` of what accepting ' +
+            'everything would produce. A run is produced within a minute or two of being requested: read it again ' +
+            'while it is `queued` or `running`. ' +
+            FORM_TEXT_IS_DATA,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                template_id: uuidProperty('The template’s id.'),
+                run_id: uuidProperty('The run’s id, from `request_naming` or from the template’s upload.'),
+            },
+            required: ['template_id', 'run_id'],
+            additionalProperties: false,
+        },
+        operationId: 'getNamingRun',
+        method: 'GET',
+        route: '/api/v1/templates/{templateId}/naming-runs/{runId}',
+        scope: 'templates:read',
+        returns: 'json',
+        carriesFormText: true,
+        build(args) {
+            return { method: 'GET', path: `/api/v1/templates/${uuid(args, 'template_id')}/naming-runs/${uuid(args, 'run_id')}` };
+        },
+    },
+    {
+        name: 'get_template_people',
+        title: 'Get the people on a template',
+        description: 'Lists the people a template is about or signed by — a heading such as “Spouse” or “Dependant 2”, or the ' +
+            'caption under a signature line — each with a stable `id`, the decision Vumasign proposes and why, the ' +
+            'decisions it may take, the fields in that part of the form, and what already exists for it. It writes ' +
+            'nothing. ' +
+            FORM_TEXT_IS_DATA,
+        inputSchema: {
+            type: 'object',
+            properties: { template_id: uuidProperty('The template’s id.') },
+            required: ['template_id'],
+            additionalProperties: false,
+        },
+        operationId: 'listTemplatePeople',
+        method: 'GET',
+        route: '/api/v1/templates/{templateId}/people',
+        scope: 'templates:read',
+        returns: 'json',
+        carriesFormText: true,
+        build(args) {
+            return { method: 'GET', path: `/api/v1/templates/${uuid(args, 'template_id')}/people` };
+        },
+    },
+    {
+        name: 'request_naming',
+        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: 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: {
+                template_id: uuidProperty('The template’s id.'),
+                use_ai: { type: 'boolean', description: 'Ask for a model as well as the vocabulary. Default false.' },
+                blank_form: {
+                    type: 'boolean',
+                    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',
+                    description: 'Leave it out normally: calling again with the same arguments within ' +
+                        `${DRAFT_REPLAY_HOURS} hours returns the run the first call started. To ask for a fresh run on purpose (the ` +
+                        'template changed, so accepting the first was refused), pass any new value here.',
+                },
+            },
+            required: ['template_id'],
+            additionalProperties: false,
+        },
+        operationId: 'requestNamingRun',
+        method: 'POST',
+        route: '/api/v1/templates/{templateId}/naming-runs',
+        scope: 'templates:name',
+        returns: 'json',
+        carriesFormText: false,
+        templateWrite: true,
+        uncertainOutcome: 'The request to the Vumasign API failed before an answer came back, so a naming run may or may not have been started. Call again with exactly the same arguments: a run that was started is then returned rather than started twice.',
+        build(args) {
+            const templateId = uuid(args, 'template_id');
+            const body = {};
+            for (const name of ['use_ai', 'blank_form']) {
+                if (absent(args[name]))
+                    continue;
+                if (typeof args[name] !== 'boolean')
+                    throw new ToolRefusal('invalid_request', `\`${name}\` must be true or false.`);
+                body[name] = args[name];
+            }
+            // `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
+              answer replays the run the first call started rather than starting a
+              second. A fresh run is asked for with a new `request_id`.
+            */
+            const requestId = optionalString(args, 'request_id');
+            const digest = createHash('sha256')
+                .update(canonicalJson({ template_id: templateId, body, ...(requestId === undefined ? {} : { request_id: requestId }) }))
+                .digest('hex');
+            return { method: 'POST', path: `/api/v1/templates/${templateId}/naming-runs`, body, headers: { 'Idempotency-Key': `vumasign-mcp-naming-${digest}` } };
+        },
+    },
+    {
+        name: 'accept_naming',
+        title: 'Accept a naming run',
+        description: 'Applies a naming run’s own proposals to the template, all of them or some, in one change — if the template ' +
+            'has not changed since the run was made; if it has, request a new run. Show the person the run’s `preview` ' +
+            'first. `accept` is "all", "high" (only high-confidence proposals, never a model’s, and no person), or lists ' +
+            'of the run’s own ids. It takes no names of its own: to name a field differently, the person does it in ' +
+            'Vumasign.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                template_id: uuidProperty('The template’s id.'),
+                run_id: uuidProperty('The run’s id.'),
+                accept: {
+                    description: '"all", "high", or `{ "fields": [...], "questions": [...], "people": [...] }` with ids from the run’s proposals.',
+                    anyOf: [
+                        { type: 'string', enum: ['all', 'high'] },
+                        {
+                            type: 'object',
+                            properties: {
+                                fields: { type: 'array', items: { type: 'string' } },
+                                questions: { type: 'array', items: { type: 'string' } },
+                                people: { type: 'array', items: { type: 'string' } },
+                            },
+                            additionalProperties: false,
+                        },
+                    ],
+                },
+            },
+            required: ['template_id', 'run_id', 'accept'],
+            additionalProperties: false,
+        },
+        operationId: 'acceptNamingRunCurrent',
+        method: 'POST',
+        route: '/api/v1/templates/{templateId}/naming-runs/{runId}/accept-current',
+        scope: 'templates:name',
+        returns: 'json',
+        carriesFormText: true,
+        templateWrite: true,
+        uncertainOutcome: 'The request to the Vumasign API failed before an answer came back, so the run’s names may or may not have been applied to the template. Do not simply retry: read the template with `get_template` (or the run with `get_naming_run`) first. If they were applied, the template has changed and accepting again is refused as `template_changed`.',
+        build(args) {
+            // ⚠️ NO OVERRIDES, WHATEVER IT IS ASKED (spec 2026-10-11, 15.3): only Vumasign's own proposals.
+            only(args, ['template_id', 'run_id', 'accept'], 'It accepts only the run’s own proposals; a person names a field differently in Vumasign.');
+            const templateId = uuid(args, 'template_id');
+            const runId = uuid(args, 'run_id');
+            return {
+                method: 'POST',
+                path: `/api/v1/templates/${templateId}/naming-runs/${runId}/accept-current`,
+                body: { accept: acceptSelection(args) },
+            };
+        },
+    },
+    {
+        name: 'accept_person',
+        title: 'Accept Vumasign’s proposal for one person',
+        description: 'Applies Vumasign’s own current proposal for one person on a template — the decision `get_template_people` ' +
+            'shows as `proposed` — which sets up the subject and signing role it names and moves that person’s fields ' +
+            'to them. It takes the person’s id and nothing else: it cannot choose a different decision. If the proposal ' +
+            'has changed or would change nothing, it is refused; read the people again.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                template_id: uuidProperty('The template’s id.'),
+                person_id: { type: 'string', pattern: '^[0-9a-f]{32}$', description: 'The person’s `id`, from `get_template_people`.' },
+            },
+            required: ['template_id', 'person_id'],
+            additionalProperties: false,
+        },
+        operationId: 'acceptTemplatePersonProposal',
+        method: 'POST',
+        route: '/api/v1/templates/{templateId}/people/{personId}/accept-proposal',
+        scope: 'templates:name',
+        returns: 'json',
+        carriesFormText: true,
+        templateWrite: true,
+        uncertainOutcome: 'The request to the Vumasign API failed before an answer came back, so the decision for this person may or may not have been applied. Do not simply retry: read the people with `get_template_people` and look at this person’s `current` first. If it was applied, accepting again is refused as `proposal_changed`.',
+        build(args) {
+            // ⚠️ NO DECISION OF THE AGENT'S OWN (spec 2026-10-11, 15.3): the server applies its own proposal.
+            only(args, ['template_id', 'person_id'], 'It applies Vumasign’s own proposal for the person; a person decides otherwise in Vumasign.');
+            const templateId = uuid(args, 'template_id');
+            return { method: 'POST', path: `/api/v1/templates/${templateId}/people/${personId(args, 'person_id')}/accept-proposal` };
+        },
+    },
 ];
+/** The tools a server started with `config` offers: the template-write tools only behind their flag. */
+export function toolsFor(config) {
+    return TOOLS.filter((tool) => tool.templateWrite !== true || config.templateWrites === true);
+}
 /** The route as a pattern: each `{placeholder}` is one path segment and nothing else. */
 export function routePattern(route) {
     const escaped = route
@@ -466,6 +787,7 @@ export function routePattern(route) {
         .join('[^/]+');
     return new RegExp(`^${escaped}$`);
 }
-export function findTool(name) {
-    return TOOLS.find((tool) => tool.name === name);
+/** A tool this server offers, by name: a template-write tool only when `config` allows them. */
+export function findTool(name, config = {}) {
+    return toolsFor(config).find((tool) => tool.name === name);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vumasign/mcp",
-  "version": "0.1.0",
+  "version": "0.3.2",
   "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",