@signdocs-brasil/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SignDocs Brasil
+
+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,121 @@
+# SignDocs Brasil — MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for the
+**SignDocs Brasil** e-signature API. It lets MCP-capable AI clients (Claude
+Desktop, Claude Code, Cursor, …) create signing sessions, manage multi-signer
+envelopes, upload/download documents, verify signatures, and manage webhooks —
+the same action catalog as the official n8n, Zapier, and Make.com integrations.
+
+It is a thin adapter over the official [`@signdocs-brasil/api`](https://www.npmjs.com/package/@signdocs-brasil/api)
+SDK, which owns OAuth2 token exchange, caching, retries, and error handling.
+
+## Install
+
+```bash
+npm install -g @signdocs-brasil/mcp-server   # or run on demand with npx
+```
+
+## Credentials
+
+Create an API credential in the SignDocs dashboard (app.signdocs.com.br → API)
+and expose it as environment variables:
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `SIGNDOCS_CLIENT_ID` | yes | — | OAuth2 client id |
+| `SIGNDOCS_CLIENT_SECRET` | yes | — | OAuth2 client secret |
+| `SIGNDOCS_ENVIRONMENT` | no | `hml` | `hml` (staging) or `production` |
+| `SIGNDOCS_BASE_URL` | no | derived | override the resolved base URL |
+| `SIGNDOCS_SCOPES` | no | full set | space-separated scope override |
+
+> Start in `hml`. HML data expires after ~7 days and is safe for testing.
+> Switch to `production` only when you intend to create real, legally-binding
+> signatures.
+
+## Connect an AI client
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "signdocs": {
+      "command": "npx",
+      "args": ["-y", "@signdocs-brasil/mcp-server"],
+      "env": {
+        "SIGNDOCS_CLIENT_ID": "your_client_id",
+        "SIGNDOCS_CLIENT_SECRET": "your_client_secret",
+        "SIGNDOCS_ENVIRONMENT": "hml"
+      }
+    }
+  }
+}
+```
+
+**Claude Code**:
+
+```bash
+claude mcp add signdocs \
+  -e SIGNDOCS_CLIENT_ID=your_client_id \
+  -e SIGNDOCS_CLIENT_SECRET=your_client_secret \
+  -e SIGNDOCS_ENVIRONMENT=hml \
+  -- npx -y @signdocs-brasil/mcp-server
+```
+
+## Tools
+
+| Tool | Action | Safety |
+|---|---|---|
+| `create_signing_session` | Create single-signer session, returns `signingUrl` | ⚠️ binding + quota |
+| `get_signing_session_status` | Poll session status | read |
+| `get_signing_session` | Full session bootstrap | read |
+| `list_signing_sessions` | List by status | read |
+| `cancel_signing_session` | Cancel a session | ⚠️ irreversible |
+| `resend_signing_session_otp` | Resend OTP | write |
+| `create_envelope` | Multi-signer envelope | ⚠️ binding + quota |
+| `get_envelope` | Envelope details | read |
+| `add_session_to_envelope` | Add a signer, returns `signingUrl` | ⚠️ binding + quota |
+| `get_envelope_combined_stamp` | Combined stamped PDF URL | read |
+| `upload_document` | Attach a PDF to a transaction | write |
+| `download_document` | Presigned download URLs | read |
+| `list_transactions` | Search/list transactions | read |
+| `get_transaction` | Transaction details | read |
+| `cancel_transaction` | Cancel a transaction | ⚠️ irreversible |
+| `get_evidence` | Cryptographic evidence | read |
+| `verify_evidence` | Public evidence verification | read |
+| `verify_envelope` | Public envelope verification | read |
+| `verify_document` | Detect signatures in a PDF | ⚠️ PROD-only + quota |
+| `register_webhook` / `list_webhooks` / `delete_webhook` / `test_webhook` | Webhook management | mixed |
+
+⚠️ tools carry `destructiveHint` annotations **and** a warning in their
+description so compliant clients prompt the human before invoking them.
+Annotations are only hints — review your client's auto-approval settings.
+
+### Not yet exposed
+Trust sessions (`/v1/trust-sessions`) and `resend-invite` are not in
+`@signdocs-brasil/api` v1.6.1 yet; they'll be added when the SDK supports them.
+Digital ICP-Brasil A1 signing runs through the lower-level transaction/advance
+flow rather than a hosted-session profile.
+
+## Resources
+
+The server exposes grounding resources the model can read on demand:
+
+- `signdocs://quickstart` — the minimal signing flow + safety notes
+- `signdocs://policy-profiles` — valid `policyProfile` values and CUSTOM steps
+- `signdocs://webhook-events` — all subscribable event types
+
+## Development
+
+```bash
+npm install
+npm run build      # tsc → dist/
+npm test           # vitest (pure unit tests, no network)
+npm run inspect    # build + launch MCP Inspector against the stdio server
+```
+
+## Roadmap
+
+- **v0.1 (this release):** local stdio server, full tool catalog, env credentials.
+- **Phase 2:** remote Streamable-HTTP transport with per-tenant OAuth (the tool
+  layer is already transport-agnostic — see `src/http/server.ts`).

package/dist/annotations.d.ts

@@ -0,0 +1,31 @@
+/**
+ * MCP tool annotation presets. These are *hints* — clients MAY use them to
+ * decide whether to auto-run a tool or prompt the human first. Because not
+ * every client honors them, binding/quota tools ALSO carry an explicit warning
+ * sentence in their `description` (see tools/*.ts).
+ *
+ * @see https://modelcontextprotocol.io/specification — Tool annotations
+ */
+export interface ToolAnnotations {
+    title?: string;
+    /** Tool does not modify state. */
+    readOnlyHint?: boolean;
+    /** Tool may perform irreversible / consequential changes → clients should confirm. */
+    destructiveHint?: boolean;
+    /** Repeated identical calls have no additional effect. */
+    idempotentHint?: boolean;
+    /** Tool talks to an external system (always true here — it's a remote API). */
+    openWorldHint?: boolean;
+}
+/** Pure reads (status, get, list, public verification). */
+export declare const READ_ONLY: ToolAnnotations;
+/** Writes that are not legally binding nor irreversible (upload, resend OTP, register webhook). */
+export declare const WRITE_SAFE: ToolAnnotations;
+/**
+ * Legally-binding, quota-consuming, or irreversible actions
+ * (create signing session/envelope, cancel, verify-document).
+ * Clients SHOULD prompt the human before invoking.
+ */
+export declare const DESTRUCTIVE: ToolAnnotations;
+/** Prefix prepended to descriptions of binding/quota tools so even annotation-blind clients surface the risk. */
+export declare const CONFIRM_WARNING: string;

package/dist/annotations.js

@@ -0,0 +1,29 @@
+/** Pure reads (status, get, list, public verification). */
+export const READ_ONLY = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+/** Writes that are not legally binding nor irreversible (upload, resend OTP, register webhook). */
+export const WRITE_SAFE = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+/**
+ * Legally-binding, quota-consuming, or irreversible actions
+ * (create signing session/envelope, cancel, verify-document).
+ * Clients SHOULD prompt the human before invoking.
+ */
+export const DESTRUCTIVE = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+/** Prefix prepended to descriptions of binding/quota tools so even annotation-blind clients surface the risk. */
+export const CONFIRM_WARNING = '⚠️ This performs a consequential, possibly irreversible action (legally-binding signature ' +
+    'request and/or quota consumption). Confirm with the human before calling. ';
+//# sourceMappingURL=annotations.js.map

package/dist/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAoBA,2DAA2D;AAC3D,MAAM,CAAC,MAAM,SAAS,GAAoB;IACxC,YAAY,EAAE,IAAI;IAClB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,IAAI;CACpB,CAAC;AAEF,mGAAmG;AACnG,MAAM,CAAC,MAAM,UAAU,GAAoB;IACzC,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,IAAI;CACpB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAoB;IAC1C,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,IAAI;IACrB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,IAAI;CACpB,CAAC;AAEF,iHAAiH;AACjH,MAAM,CAAC,MAAM,eAAe,GAC1B,4FAA4F;IAC5F,4EAA4E,CAAC"}

package/dist/bin/stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/stdio.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from '../server.js';
+/**
+ * stdio entrypoint. AI clients (Claude Desktop/Code, Cursor, …) launch this
+ * binary and speak MCP over stdin/stdout. NEVER write to stdout here — it is
+ * the protocol channel; diagnostics go to stderr.
+ */
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write('[signdocs-mcp] server started on stdio\n');
+}
+main().catch((err) => {
+    process.stderr.write(`[signdocs-mcp] fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=stdio.js.map

package/dist/bin/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/bin/stdio.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;GAIG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;AACnE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,35 @@
+import { SignDocsBrasilClient } from '@signdocs-brasil/api';
+/**
+ * Thin wrapper that turns environment variables into a configured
+ * {@link SignDocsBrasilClient}. The official SDK owns the OAuth2
+ * `client_credentials` exchange, token caching, retries and RFC-7807
+ * error parsing — this module only resolves config and memoizes the client.
+ */
+export type Environment = 'production' | 'hml';
+/**
+ * Full read/write scope set. `verification:write` is only authorized for
+ * PRODUCTION credentials, but the token endpoint silently filters out any
+ * scope the credential isn't entitled to, so requesting it everywhere is safe.
+ */
+export declare const DEFAULT_SCOPES: string[];
+export interface ResolvedEnv {
+    clientId: string;
+    clientSecret: string;
+    environment: Environment;
+    baseUrl: string;
+    scopes: string[];
+}
+export declare function resolveEnvironment(raw?: string): Environment;
+export declare function getBaseUrl(environment: Environment, override?: string): string;
+export declare function readEnv(env?: NodeJS.ProcessEnv): ResolvedEnv;
+/** Lazily build and memoize the SDK client. Throws if credentials are missing. */
+export declare function getClient(env?: NodeJS.ProcessEnv): SignDocsBrasilClient;
+/** The resolved environment behind the active client (for diagnostics/guards). */
+export declare function getResolvedEnv(env?: NodeJS.ProcessEnv): ResolvedEnv;
+/** Reset memoized state — used by tests. */
+export declare function resetClientCache(): void;
+/**
+ * Assemble the shareable signing link. A session's `url` alone is NOT the
+ * link — it must carry the one-time embed token (`clientSecret`) as `?cs=`.
+ */
+export declare function buildSigningUrl(url: string, clientSecret: string): string;

package/dist/client.js

@@ -0,0 +1,80 @@
+import { SignDocsBrasilClient } from '@signdocs-brasil/api';
+const BASE_URLS = {
+    production: 'https://api.signdocs.com.br',
+    // NOTE: HML uses the dash form (api-hml), NOT api.hml.
+    hml: 'https://api-hml.signdocs.com.br',
+};
+/**
+ * Full read/write scope set. `verification:write` is only authorized for
+ * PRODUCTION credentials, but the token endpoint silently filters out any
+ * scope the credential isn't entitled to, so requesting it everywhere is safe.
+ */
+export const DEFAULT_SCOPES = [
+    'transactions:read',
+    'transactions:write',
+    'steps:write',
+    'evidence:read',
+    'webhooks:write',
+    'verification:write',
+];
+export function resolveEnvironment(raw) {
+    const v = (raw ?? 'hml').trim().toLowerCase();
+    if (v === 'production' || v === 'prod')
+        return 'production';
+    if (v === 'hml' || v === 'homologacao' || v === 'homologação' || v === 'staging')
+        return 'hml';
+    throw new Error(`Invalid SIGNDOCS_ENVIRONMENT "${raw}". Use "production" or "hml".`);
+}
+export function getBaseUrl(environment, override) {
+    const trimmed = override?.trim();
+    return trimmed ? trimmed : BASE_URLS[environment];
+}
+export function readEnv(env = process.env) {
+    const clientId = env.SIGNDOCS_CLIENT_ID?.trim();
+    const clientSecret = env.SIGNDOCS_CLIENT_SECRET?.trim();
+    if (!clientId || !clientSecret) {
+        throw new Error('Missing SignDocs credentials. Set SIGNDOCS_CLIENT_ID and SIGNDOCS_CLIENT_SECRET ' +
+            '(get them from app.signdocs.com.br → API).');
+    }
+    const environment = resolveEnvironment(env.SIGNDOCS_ENVIRONMENT);
+    const baseUrl = getBaseUrl(environment, env.SIGNDOCS_BASE_URL);
+    const scopesRaw = env.SIGNDOCS_SCOPES?.trim();
+    const scopes = scopesRaw ? scopesRaw.split(/\s+/) : DEFAULT_SCOPES;
+    return { clientId, clientSecret, environment, baseUrl, scopes };
+}
+let cached;
+let cachedEnv;
+/** Lazily build and memoize the SDK client. Throws if credentials are missing. */
+export function getClient(env = process.env) {
+    if (cached)
+        return cached;
+    const cfg = readEnv(env);
+    cachedEnv = cfg;
+    cached = new SignDocsBrasilClient({
+        clientId: cfg.clientId,
+        clientSecret: cfg.clientSecret,
+        baseUrl: cfg.baseUrl,
+        scopes: cfg.scopes,
+    });
+    return cached;
+}
+/** The resolved environment behind the active client (for diagnostics/guards). */
+export function getResolvedEnv(env = process.env) {
+    if (cachedEnv)
+        return cachedEnv;
+    cachedEnv = readEnv(env);
+    return cachedEnv;
+}
+/** Reset memoized state — used by tests. */
+export function resetClientCache() {
+    cached = undefined;
+    cachedEnv = undefined;
+}
+/**
+ * Assemble the shareable signing link. A session's `url` alone is NOT the
+ * link — it must carry the one-time embed token (`clientSecret`) as `?cs=`.
+ */
+export function buildSigningUrl(url, clientSecret) {
+    return `${url}?cs=${encodeURIComponent(clientSecret)}`;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/http/server.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Phase 2 — remote Streamable-HTTP transport (designed, not yet built).
+ *
+ * The tool/resource layer in ../server.ts is deliberately transport-agnostic,
+ * so going remote is purely an entrypoint + auth concern:
+ *
+ *   import { StreamableHTTPServerTransport } from
+ *     '@modelcontextprotocol/sdk/server/streamableHttp.js';
+ *   const server = createServer();
+ *   const transport = new StreamableHTTPServerTransport({ ...});
+ *   await server.connect(transport);
+ *   // node:http handler → transport.handleRequest(req, res, body)
+ *
+ * Open design decisions to settle before implementing (see plan):
+ *
+ *  1. AUTH / MULTI-TENANCY. Unlike stdio (one set of env credentials), a
+ *     hosted server serves many tenants. The MCP server should act as an
+ *     OAuth Resource Server: each connecting AI presents its own SignDocs
+ *     bearer token (issued by the existing /oauth2/token AS). Validate it with
+ *     the same ES256/KMS verifier external-api uses (auth-middleware.ts) and
+ *     build a PER-REQUEST SDK client scoped to that tenant — do NOT reuse the
+ *     process-wide getClient() singleton, which would cross tenant boundaries.
+ *
+ *  2. DEPLOYMENT. Reuse the external-api Lambda + API Gateway pattern via a new
+ *     NestedStack (the Core stack is at the CFN 500-resource limit — follow the
+ *     EnvelopeHandlersStack precedent), or a small container behind the same WAF.
+ *
+ *  3. SESSION MODE. Stateless (sessionIdGenerator: undefined) fits serverless;
+ *     confirm against the MCP spec version current at build time, plus DCR /
+ *     protected-resource metadata discovery needs.
+ *
+ * Intentionally not wired up yet so the v0.1 stdio package stays dependency-light.
+ */
+export declare function createHttpServer(): never;

package/dist/http/server.js

@@ -0,0 +1,38 @@
+/**
+ * Phase 2 — remote Streamable-HTTP transport (designed, not yet built).
+ *
+ * The tool/resource layer in ../server.ts is deliberately transport-agnostic,
+ * so going remote is purely an entrypoint + auth concern:
+ *
+ *   import { StreamableHTTPServerTransport } from
+ *     '@modelcontextprotocol/sdk/server/streamableHttp.js';
+ *   const server = createServer();
+ *   const transport = new StreamableHTTPServerTransport({ ...});
+ *   await server.connect(transport);
+ *   // node:http handler → transport.handleRequest(req, res, body)
+ *
+ * Open design decisions to settle before implementing (see plan):
+ *
+ *  1. AUTH / MULTI-TENANCY. Unlike stdio (one set of env credentials), a
+ *     hosted server serves many tenants. The MCP server should act as an
+ *     OAuth Resource Server: each connecting AI presents its own SignDocs
+ *     bearer token (issued by the existing /oauth2/token AS). Validate it with
+ *     the same ES256/KMS verifier external-api uses (auth-middleware.ts) and
+ *     build a PER-REQUEST SDK client scoped to that tenant — do NOT reuse the
+ *     process-wide getClient() singleton, which would cross tenant boundaries.
+ *
+ *  2. DEPLOYMENT. Reuse the external-api Lambda + API Gateway pattern via a new
+ *     NestedStack (the Core stack is at the CFN 500-resource limit — follow the
+ *     EnvelopeHandlersStack precedent), or a small container behind the same WAF.
+ *
+ *  3. SESSION MODE. Stateless (sessionIdGenerator: undefined) fits serverless;
+ *     confirm against the MCP spec version current at build time, plus DCR /
+ *     protected-resource metadata discovery needs.
+ *
+ * Intentionally not wired up yet so the v0.1 stdio package stays dependency-light.
+ */
+export function createHttpServer() {
+    throw new Error('Remote HTTP transport is not implemented in v0.1. Use the stdio entrypoint (bin/stdio.ts). ' +
+        'See src/http/server.ts for the Phase 2 design.');
+}
+//# sourceMappingURL=server.js.map

package/dist/http/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/http/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,IAAI,KAAK,CACb,6FAA6F;QAC3F,gDAAgD,CACnD,CAAC;AACJ,CAAC"}

package/dist/resources.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerResources(server: McpServer): void;

package/dist/resources.js

@@ -0,0 +1,91 @@
+/**
+ * Static MCP resources that ground the agent so it calls tools correctly
+ * without guessing. Content is inlined (no filesystem/sibling-repo coupling)
+ * so the published package is self-contained.
+ */
+const POLICY_PROFILES = `# SignDocs policy profiles
+
+Pass one of these as \`policyProfile\` when creating a signing session or
+adding an envelope signer. An invalid value returns HTTP 400.
+
+| profile               | steps                                   | typical use |
+|-----------------------|-----------------------------------------|-------------|
+| CLICK_ONLY            | clickwrap acceptance                    | low-risk consent |
+| CLICK_PLUS_OTP        | clickwrap + e-mail/SMS one-time code    | standard e-signature |
+| BIOMETRIC             | facial liveness + match                 | high-assurance identity |
+| BIOMETRIC_PLUS_OTP    | biometric + OTP                         | strongest hosted assurance |
+| CUSTOM                | caller-defined ordered steps            | supply \`customSteps\` |
+
+When \`policyProfile=CUSTOM\`, set \`customSteps\` to an ordered list of step
+types, e.g. ["CLICKWRAP","OTP","BIOMETRIC_LIVENESS","BIOMETRIC_MATCH"].
+
+Digital ICP-Brasil A1 certificate signing is exposed through the transaction/
+advance flow (step type DIGITAL_CERTIFICATE), not as a hosted-session profile.
+`;
+const QUICKSTART = `# SignDocs MCP quickstart
+
+Most integrations need only the high-level **signing session** flow:
+
+1. \`create_signing_session\` with purpose=DOCUMENT_SIGNATURE, a policyProfile,
+   the signer, and the base64 PDF (\`documentBase64\`). The result includes a
+   ready-to-share **signingUrl** (the session url + one-time embed token).
+2. Deliver the signingUrl to the signer (or pass \`owner.email\` so SignDocs
+   e-mails them automatically), or subscribe to webhooks for completion.
+3. Poll \`get_signing_session_status\` (or rely on webhooks) until COMPLETED.
+4. The COMPLETED status carries an \`evidenceId\` — verify it publicly with
+   \`verify_evidence\`.
+
+Multiple signers on one document → use \`create_envelope\` then
+\`add_session_to_envelope\` once per signer (signerIndex 0..N-1).
+
+Environment: set SIGNDOCS_ENVIRONMENT=hml (default) for testing or
+=production for live, binding signatures. HML data expires after ~7 days and
+the verify_document tool is production-only.
+
+⚠️ create_/add_/cancel_ tools take real, quota-consuming, often
+legally-binding actions. Confirm with the human before invoking them.
+`;
+const WEBHOOK_EVENTS = `# SignDocs webhook events
+
+Subscribe via \`register_webhook\`. Payloads are signed with HMAC-SHA256 using
+the secret returned at registration (300s replay tolerance).
+
+TRANSACTION.CREATED, TRANSACTION.COMPLETED, TRANSACTION.CANCELLED,
+TRANSACTION.FAILED, TRANSACTION.EXPIRED
+STEP.STARTED, STEP.COMPLETED, STEP.FAILED
+SIGNING_SESSION.CREATED, SIGNING_SESSION.COMPLETED, SIGNING_SESSION.CANCELLED,
+SIGNING_SESSION.EXPIRED
+ENVELOPE.CREATED, ENVELOPE.ALL_SIGNED, ENVELOPE.EXPIRED
+QUOTA.WARNING, API.DEPRECATION_NOTICE
+`;
+const RESOURCES = [
+    {
+        uri: 'signdocs://policy-profiles',
+        name: 'policy-profiles',
+        title: 'SignDocs policy profiles',
+        description: 'Valid policyProfile values and CUSTOM step types.',
+        text: POLICY_PROFILES,
+    },
+    {
+        uri: 'signdocs://quickstart',
+        name: 'quickstart',
+        title: 'SignDocs MCP quickstart',
+        description: 'The minimal signing-session flow and safety notes.',
+        text: QUICKSTART,
+    },
+    {
+        uri: 'signdocs://webhook-events',
+        name: 'webhook-events',
+        title: 'SignDocs webhook events',
+        description: 'All subscribable webhook event types.',
+        text: WEBHOOK_EVENTS,
+    },
+];
+export function registerResources(server) {
+    for (const r of RESOURCES) {
+        server.registerResource(r.name, r.uri, { title: r.title, description: r.description, mimeType: 'text/markdown' }, async (uri) => ({
+            contents: [{ uri: uri.href, mimeType: 'text/markdown', text: r.text }],
+        }));
+    }
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;CAkBvB,CAAC;AAEF,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBlB,CAAC;AAEF,MAAM,cAAc,GAAG;;;;;;;;;;;;CAYtB,CAAC;AAUF,MAAM,SAAS,GAAqB;IAClC;QACE,GAAG,EAAE,4BAA4B;QACjC,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,0BAA0B;QACjC,WAAW,EAAE,mDAAmD;QAChE,IAAI,EAAE,eAAe;KACtB;IACD;QACE,GAAG,EAAE,uBAAuB;QAC5B,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,yBAAyB;QAChC,WAAW,EAAE,oDAAoD;QACjE,IAAI,EAAE,UAAU;KACjB;IACD;QACE,GAAG,EAAE,2BAA2B;QAChC,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,yBAAyB;QAChC,WAAW,EAAE,uCAAuC;QACpD,IAAI,EAAE,cAAc;KACrB;CACF,CAAC;AAEF,MAAM,UAAU,iBAAiB,CAAC,MAAiB;IACjD,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,MAAM,CAAC,gBAAgB,CACrB,CAAC,CAAC,IAAI,EACN,CAAC,CAAC,GAAG,EACL,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,QAAQ,EAAE,eAAe,EAAE,EACzE,KAAK,EAAE,GAAQ,EAAE,EAAE,CAAC,CAAC;YACnB,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;SACvE,CAAC,CACH,CAAC;IACJ,CAAC;AACH,CAAC"}