Skip to content

QrCommunication/scell-io-llm-agent

Repository files navigation

@scell/mcp-client

MCP (Model Context Protocol) client configuration generator for Scell.io API.

Scell.io provides electronic invoicing (Factur-X/UBL/CII, B2B and B2C) and simple electronic signatures (eIDAS EU-SES) via API.

For B2C invoices, set buyer.isIndividual = true (or buyerIsIndividual: true at top-level) — SIRET / vatNumber / legal_id become optional and the generated Factur-X is BR-CO-26 EN16931 compliant.

Installation

npm install @scell/mcp-client

Or use directly with npx:

npx @scell/mcp-client claude YOUR_API_KEY

Quick Start

Claude Desktop

  1. Generate the configuration:
npx @scell/mcp-client claude tk_live_your_api_key_here
  1. Save the output to your Claude Desktop config file:
Platform Config Path
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json
  1. Restart Claude Desktop

Cursor IDE

  1. Generate the configuration:
npx @scell/mcp-client cursor tk_live_your_api_key_here
  1. Save to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global config)

  2. Restart Cursor

VS Code

  1. Generate the configuration:
npx @scell/mcp-client vscode tk_live_your_api_key_here
  1. Save to .vscode/mcp.json in your project root

  2. Restart VS Code

CLI Usage

scell-mcp <command> <api-key> [options]

Commands:
  claude <api-key>     Generate Claude Desktop configuration
  cursor <api-key>     Generate Cursor IDE configuration
  vscode <api-key>     Generate VS Code configuration
  generic <api-key>    Generate generic MCP configuration

Options:
  --base-url <url>     Custom API base URL (default: https://api.scell.io/api)
  --env <environment>  Environment: production, staging, development
  --sandbox            Use sandbox mode (appends /sandbox to base URL)
  --output <file>      Write configuration to file instead of stdout
  --help, -h           Show help message
  --version, -v        Show version number

Examples

# Generate Claude Desktop config
scell-mcp claude tk_live_your_api_key_here

# Generate Cursor config with staging environment
scell-mcp cursor tk_live_your_api_key_here --env staging

# Generate config and save directly to file
scell-mcp claude tk_live_your_api_key_here --output ~/.config/Claude/claude_desktop_config.json

# Use environment variable for API key
export SCELL_API_KEY=tk_live_your_api_key_here
scell-mcp claude

Available Tools

Once configured, your AI assistant will have access to 148 tools (all prefixed scell_). The canonical tool names are defined server-side; the tables below group a representative selection by domain.

Health & Authentication

Tool Description
scell_health_check Check API health status and service availability
scell_validate_api_key Validate your API key and check permissions

Electronic Invoicing

Tool Description
scell_create_invoice Create a new electronic invoice (Factur-X, UBL, or CII format). Optional sub_tenant_id in the payload scopes the invoice to a sub-tenant of the calling tenant (anti-IDOR enforced server-side).
scell_get_invoice Retrieve invoice details by ID
scell_list_invoices List all invoices with filtering and pagination
scell_download_invoice Download invoice as PDF or XML

Electronic Signatures

Tool Description
scell_create_signature Create a new signature request. Optional sub_tenant_id in the payload scopes the request to a sub-tenant of the calling tenant (anti-IDOR enforced server-side). v2.17.0: supports multi-document bundles via the optional attachments[] array (max 10 PJ, 20 Mo cumulated) — signature positions, mentions and initials positions can target a specific document via documentIndex (0 = main document, 1..N = attachment N). v2.27.0: each signature position accepts an optional signerIndex (0-based, mapped to signer_index) to assign it to a specific signer; the EU-SES API allows multiple positions per signer (N entries sharing the same signerIndex).
scell_get_signature Get signature request status and details
scell_list_signatures List signature requests (GET /api/v1/signatures, tenant-scoped via the API key). Filters: status, environment, sub_tenant_id, page, per_page. The legacy company_id filter was removed in the 2026-05-11 backend refonte (api_keys.company_id dropped).
scell_download_signed Download the signed document
scell_cancel_signature Cancel a pending signature request
scell_send_reminder Send a reminder to pending signers

Account & Validation

Tool Description
scell_get_balance Get account balance and credit information
scell_validate_siret Validate a French SIRET number
scell_validate_vat Validate a European VAT number
scell_get_audit_trail Get the audit trail for a document

Fiscal Compliance (tenant key required)

These tools require a tenant API key (tk_*) and provide access to the fiscal compliance features mandated by French law (LF 2026).

Tool Description
scell_get_fiscal_compliance Get fiscal compliance dashboard (ISCA status)
scell_check_fiscal_integrity Verify the integrity of the fiscal hash chain
scell_list_fiscal_closings List recent fiscal daily closings
scell_get_fiscal_attestation Generate a fiscal compliance attestation
scell_list_fiscal_entries List fiscal ledger entries with filters
scell_get_kill_switch_status Check the fiscal kill-switch status
scell_list_fiscal_rules List applicable fiscal rules (VAT rates, etc.)

Credit Notes (tenant key required)

These tools require a tenant API key (tk_*) and manage credit notes (avoirs) linked to invoices.

Tool Description
scell_list_credit_notes List credit notes with filtering
scell_get_credit_note Get credit note details
scell_download_credit_note Download credit note as PDF
scell_create_credit_note Create a credit note from an invoice
scell_send_credit_note Validate and send a draft credit note
scell_delete_credit_note Delete a draft credit note
scell_get_remaining_creditable Calculate remaining creditable amounts

Partner Onboarding (publishable key required)

These tools require a publishable key (pk_*) and handle partner tenant onboarding via SuperPDP's OAuth2 tunnel.

Tool Description
scell_create_onboarding_session Create a new onboarding session
scell_get_onboarding_session Get onboarding session status and result
scell_authorize_onboarding_superpdp Start the SuperPDP OAuth2 flow — returns authorize_url and state

Sub-Tenant Lifecycle (master tenant sk_* or Bearer required)

These tools manage existing sub-tenants of the calling tenant. They are scoped strictly to the caller (anti-IDOR — 403 if the id does not belong to the API key's tenant).

Tool Description
scell_get_subtenant_superpdp_status Get the cached SuperPDP onboarding status for a sub-tenant
scell_refresh_subtenant_superpdp_status Force a fresh poll of SuperPDP (rate-limited 1/min). Returns 422 MISSING_ACCESS_TOKEN + authorize_url if the sub-tenant never granted access (or the token expired). The LLM should present that URL to the user, or call scell_authorize_subtenant_superpdp to obtain a fresh one.
scell_authorize_subtenant_superpdp v2.9.0 Start a SuperPDP OAuth2 flow for an existing sub-tenant whose access token is missing. POST /api/v1/tenant/sub-tenants/{id}/superpdp-authorize{ authorize_url, state }.
scell_get_subtenant_resume_url Regenerate a 7-day signed resume URL for a sub-tenant whose onboarding is not yet active
scell_delete_sub_tenant v2.9.0 Delete a sub-tenant via DELETE /api/v1/tenant/sub-tenants/{id}. Optional cascade: boolean to drop attached Companies atomically. Returns { message, companies_deleted } on success. Possible 422 codes the LLM should surface clearly: SUB_TENANT_HAS_COMPANIES (retry with cascade=true after user confirmation) and SUB_TENANT_HAS_FISCAL_ENTRIES (refusal — ISCA compliance, no force flag; propose to mark inactive instead).
scell_disconnect_subtenant_superpdp v3.1.0 Disconnect a sub-tenant from SuperPDP via POST /api/v1/tenant/sub-tenants/{id}/superpdp-disconnect. Revokes the SuperPDP tokens and resets onboarding_status to pending_superpdp. Already-issued invoices stay immutable (ISCA); future B2B invoices fall back to paper mode until reconnection. Returns the updated sub-tenant summary.
scell_reconnect_subtenant_superpdp v3.1.0 Reconnect a sub-tenant to SuperPDP via POST /api/v1/tenant/sub-tenants/{id}/superpdp-reconnect. Equivalent to a disconnect followed by a fresh authorize_url in a single call → { authorize_url, state }. Present that URL to the user to re-grant access.
scell_mint_subtenant_widget_token v3.1.0 Mint a signed widget token via POST /api/v1/tenant/sub-tenants/{id}/superpdp-widget-token. Returns a signed, single-sub-tenant-scoped URL (24h TTL, anti-IDOR HMAC) for the <scell-onboarding mode="superpdp" resume-token="..."> web component. Optional reset: boolean disconnects the sub-tenant before minting the token.

Payment Schedule Tools (since v2.13.0)

These tools manage the échéancier de paiement attached to an accepted quote. An échéancier is a contractual payment plan composed of lines (percent or fixed amount, by due date or milestone text). Lines are immutable once the quote is signed (accepted).

Tool Description
scell_set_quote_payment_schedule Create or replace the full payment schedule of a quote atomically. POST /api/v1/quotes/{id}/payment-schedule with { lines: PaymentScheduleLineInput[] }. Blocked if the quote is accepted/converted/cancelled. Returns the full list of PaymentScheduleLine[].
scell_patch_quote_payment_schedule Partial update — add, update, or remove schedule lines in a single atomic call. PATCH /api/v1/quotes/{id}/payment-schedule with { add?, update?, remove? }. Only pending lines can be updated or removed.
scell_delete_quote_payment_schedule Delete all lines from a quote's schedule. DELETE /api/v1/quotes/{id}/payment-schedule. Only allowed when the quote is in draft or sent status (no line is invoiced).
scell_get_quote_payment_summary Real-time tracker of invoiced vs. remaining amounts for a quote with an échéancier. GET /api/v1/quotes/{id}/payment-summary. Returns PaymentSummary with gross/net invoiced, remaining TTC %, overdue lines, and SuperPDP enrichment per invoice.
scell_convert_schedule_line_to_invoice Convert a specific pending line into a deposit invoice. POST /api/v1/quotes/{id}/payment-schedule/lines/{line_id}/convert. Optional overrides: due_date, label, send_email (auto-validates and sends). Returns Invoice with invoice_type='deposit'.
scell_list_payment_schedule_presets List preset schedules (e.g. 30/70, 50/50, 30/30/40, 3 monthly instalments). GET /api/v1/payment-schedule/presets. Returns PaymentSchedulePreset[] with ready-to-use lines arrays. Suggest these to users before they create a custom schedule.

Invoice Email Tool (since v2.13.0)

Tool Description
scell_send_invoice_by_email Send an invoice to the buyer by email. POST /api/v1/invoices/{id}/send-by-email. Optional overrides: recipient_email, cc[], message. If the invoice is draft, it is automatically validated before sending (equivalent to a draft → validated transition). The recipient is resolved in cascade: explicit override → buyer_billing_email snapshot → buyer_email snapshot → quote buyer email → 422 BUYER_HAS_NO_EMAIL if none. Returns InvoiceSendByEmailResult with sent_to, sent_at, message_id, cc.

Branding Tools

Email branding lets tenants and sub-tenants customize the logo, primary color, email footer, and signature on all outbound emails (invoice delivery, reminders, signature requests). When all required fields (brand_logo_url, brand_primary_color, brand_email_footer) are set, the tenant's / sub-tenant's branding replaces the Scell.io default; otherwise the default branding is used as fallback. Each tool targets the master tenant by default, OR a sub-tenant when sub_tenant_id is provided (anti-IDOR — must belong to the caller).

Important: brand_logo_url is distinct from logo_url (the Factur-X PDF logo, managed via invoice templates or Company.logo_url). brand_primary_color must be #RRGGBB (6-digit hex, validated server-side).

Tool Description
scell_get_tenant_branding Get the current email branding. GET /api/v1/branding/tenant (no sub_tenant_id) OR GET /api/v1/branding/sub-tenants/{id}. Returns Branding with is_complete flag, missing_fields[], brand_email_enabled (boolean — false = emails sent with the default channel branding) and computed_email_footer (string|null, read-only — footer computed from the company identity, used at render time when brand_email_footer is empty).
scell_update_tenant_branding Update email branding fields. PUT /api/v1/branding/tenant OR PUT /api/v1/branding/sub-tenants/{id} with any subset of { brand_logo_url, brand_primary_color, brand_email_footer, brand_email_signature, brand_email_enabled }. Pass null to clear a nullable field. Returns the updated Branding.
scell_get_tenant_branding_logo_upload_url Get a pre-signed S3 PUT URL for the branding logo (PNG/JPEG). POST /api/v1/branding/tenant/logo-upload-url OR .../sub-tenants/{id}/logo-upload-url with { mime_type }. Returns { url, public_url, expires_at, headers } — PUT the file to url, then call scell_update_tenant_branding with brand_logo_url = public_url. Direct multipart alternative: POST /api/v1/branding/tenant/logo OR POST /api/v1/branding/sub-tenants/{id}/logo with a multipart field logo (jpeg/png/webp/svg/svgz, max 2 MB) — returns the flat Branding object directly.
scell_preview_tenant_branding Render a live preview of the branded email before any send. GET /api/v1/branding/tenant/preview OR .../sub-tenants/{id}/preview. The Accept header negotiates the format: text/html (default — ideal for an <iframe srcdoc> UI preview) or application/pdf. Optional non-persisted query overrides: brand_primary_color (#RRGGBB), brand_email_footer, brand_email_signature, brand_logo_url. Use after scell_update_tenant_branding / scell_get_tenant_branding_logo_upload_url so the user can visually confirm logo, color, footer and signature.

Document Preview & Template Colors (since v3.2.0)

Tool Description
scell_preview_document Render a live HTML preview of a draft document (invoice, credit note or quote) using the real template, branding and legal mentions of the issuing company — nothing is persisted. POST /api/v1/documents/preview. Body: type ('invoice' | 'credit_note' | 'quote', required), document_number?, buyer?, lines? (max 200, [{description, quantity, unit_price, tax_rate}]), issue_date?, due_date? (YYYY-MM-DD), currency? (ISO 4217), notes?, payment_terms? (≤2000 chars each). Auth: sk_*. Returns raw text/html (Cache-Control: no-store). 422 on validation error.
scell_derive_template_colors_from_email_logo Extract the dominant primary/accent colors from the tenant's email branding logo (brand_logo_url) and apply them to the tenant's default invoice template (created on the fly if missing). POST /api/v1/invoice-templates/derive-colors-from-email-logo. No body. Auth: sk_*. Returns { data: InvoiceTemplate }. 404 if no email logo is configured; 422 if the logo is unreachable or only has neutral colors.

Invoice templates is_enabled (since v3.2.0): InvoiceTemplate now carries is_enabled (boolean, default true). When false, the template is skipped by the resolution cascade and the system template is used instead — set it via scell_create_invoice_template / scell_update_invoice_template.

Recurring Invoices (since v2.32.0)

A recurring invoice is an abonnement: a template invoice + a recurrence rule. On each due date Scell.io generates one occurrence — a real invoice billed to the buyer. emission_mode='auto_send' submits each occurrence to the PDP (PEPPOL / SuperPDP) and emails the buyer; emission_mode='draft' (default) creates a draft for human review. The schedule runs until the recurrence end is reached (end_mode), or it is paused/cancelled. Tenant-scoped (anti-IDOR); already generated occurrences are immutable on the ISCA ledger.

Tool Description
scell_list_recurring_invoices List recurring invoice schedules. GET /api/v1/recurring-invoices. Filters: status (active/paused/completed/cancelled), sub_tenant_id, page, per_page.
scell_get_recurring_invoice Retrieve a schedule by UUID. GET /api/v1/recurring-invoices/{id}.
scell_create_recurring_invoice Create a schedule. POST /api/v1/recurring-invoices. Body: title, buyer (buyer_id or inline), lines[], recurrence (interval_unit/interval_count/day_of_month/day_of_week), start_date, end_mode (never/on_date/after_occurrences), emission_mode (draft/auto_send). Clarify the recurrence end with the user; day_of_month=31 clamps to the last day of short months; each occurrence bills the buyer.
scell_update_recurring_invoice Partial update. PUT /api/v1/recurring-invoices/{id}. Affects future occurrences only.
scell_delete_recurring_invoice Delete a schedule. DELETE /api/v1/recurring-invoices/{id}.
scell_pause_recurring_invoice Suspend an active schedule. POST /api/v1/recurring-invoices/{id}/pause.
scell_activate_recurring_invoice Resume a paused schedule. POST /api/v1/recurring-invoices/{id}/activate.
scell_cancel_recurring_invoice Terminal cancellation. POST /api/v1/recurring-invoices/{id}/cancel.
scell_run_recurring_invoice_now Trigger an off-cycle occurrence immediately. POST /api/v1/recurring-invoices/{id}/run-now. With auto_send this bills the buyer right away.

Product Catalog (since v2.35.0)

A reusable catalog of products/services (label, unit price, default VAT rate, unit…), scoped strictly by (tenant_id, sub_tenant_id) — same scoping policy as the buyers registry. Reference a product via productId on an invoice/quote line to pre-fill it; mutating a product never alters previously emitted invoices (snapshot, ISCA). Products can be grouped into categories.

Tool Description
scell_list_products List catalog products. GET /api/v1/products. Filters: q, revenue_category (goods/service/accommodation), product_category_id, is_active, sub_tenant_id, page, per_page. Returns PaginatedResult<Product>.
scell_get_product Retrieve a product by UUID. GET /api/v1/products/{id}. 404 outside caller scope (anti-IDOR).
scell_create_product Create a catalog product. POST /api/v1/products. Body: name (required), unit_price_ht (required), product_category_id?, description?, sku?, revenue_category?, unit? (default C62), default_tax_rate?, default_discount_rate?, currency? (default EUR), is_active?, sub_tenant_id?, metadata?, notes?. Returns Product (201).
scell_update_product Partial update. PATCH /api/v1/products/{id} (full PUT also accepted). Does NOT propagate to issued invoices (ISCA).
scell_delete_product Delete a product. DELETE /api/v1/products/{id}. Historic invoice snapshots remain intact. Returns 204.
scell_list_product_categories List categories. GET /api/v1/product-categories. Filters: q, sub_tenant_id, page, per_page. Returns PaginatedResult<ProductCategory>.
scell_get_product_category Retrieve a category by UUID. GET /api/v1/product-categories/{id}.
scell_create_product_category Create a category. POST /api/v1/product-categories. Body: name (required), color? (#RRGGBB), description?, position?, sub_tenant_id?, metadata?. Returns ProductCategory (201).
scell_update_product_category Partial update. PATCH /api/v1/product-categories/{id} (full PUT also accepted).
scell_delete_product_category Delete a category. DELETE /api/v1/product-categories/{id}. Returns 204.

Invoice/quote line catalog fields (since v2.35.0, optional): productId (pre-fills the line from a product → product_id), saveToCatalog (upsert the line as a product → save_to_catalog), productCategoryId (file the saved product under a category → product_category_id).

Example Prompts

Once the MCP server is configured, you can use natural language prompts like:

Invoice Examples

"Create an invoice for Acme Corp, SIRET 12345678901234, for consulting services:
- 10 hours at 150 EUR/hour
- Due in 30 days
- Factur-X format"

"List all unpaid invoices from the last month"

"Download invoice INV-2024-001 as PDF"

International Invoicing

"Create an invoice for a Belgian client Entreprise Belge SPRL with VAT number BE0123456789, address 15 Avenue Louise 1050 Bruxelles Belgium, for consulting services 10h at 150€"

Signature Examples

"Create a signature request for the attached contract.
Send to john.doe@example.com for signature."

"Check the status of signature request sig_abc123"

"Send a reminder for all pending signature requests older than 7 days"

Multi-document signature (since v2.17.0)

// Bundle a contract + 2 annexes in a single signature request.
// The backend merges them into a single signable PDF before submission.
const input: SignatureInput = {
  title: 'Contrat de prestation + annexes',
  document: mainContractBase64,
  document_name: 'contrat.pdf',
  attachments: [
    { document: annexAPdfBase64, documentName: 'annexe-A.pdf' },
    { document: annexBPdfBase64, documentName: 'annexe-B.pdf' },
  ],
  signers: [
    { first_name: 'Jean', last_name: 'Dupont',
      email: 'jean.dupont@example.com', auth_method: 'email' },
  ],
  signature_positions: [
    // Signature on the main contract (last page)
    { documentIndex: 0, page: 3, x: 10, y: 80, unit: 'percent' },
    // Signature on the second annex (Annex B)
    { documentIndex: 2, page: 1, x: 10, y: 80, unit: 'percent' },
  ],
};

Fiscal Compliance Examples

"Show me the fiscal compliance status for my company"

"Check the integrity of the fiscal hash chain for January 2026"

"List the last 10 daily fiscal closings"

"Generate a fiscal attestation for year 2025"

Credit Note Examples

"List all draft credit notes"

"Create a total credit note for invoice INV-2026-00042 because of duplicate billing"

"Send credit note AV-2026-00003"

"How much can still be credited on invoice INV-2026-00015?"

Onboarding Examples

"Start the onboarding process for a new partner tenant"

"Get the SuperPDP authorization URL so the partner can connect their account"

"Complete the SuperPDP OAuth2 callback with state=abc123 and code=xyz456"

"Check the status of onboarding session sess_abc123"

Programmatic Usage

import {
  generateClaudeDesktopConfig,
  generateCursorConfig,
  generateVSCodeConfig,
  validateConfig,
  type ScellMcpConfig,
  type InvoiceInput,
  type SignatureInput,
} from '@scell/mcp-client';

// Generate configuration
const config: ScellMcpConfig = {
  apiKey: 'tk_live_your_api_key_here',
  baseUrl: 'https://api.scell.io/api', // optional
  environment: 'production', // optional
};

// Validate configuration
const validation = validateConfig(config);
if (!validation.valid) {
  console.error('Invalid config:', validation.errors);
}

// Generate for different clients
const claudeConfig = generateClaudeDesktopConfig(config);
const cursorConfig = generateCursorConfig(config);
const vscodeConfig = generateVSCodeConfig(config);

console.log(JSON.stringify(claudeConfig, null, 2));

Type Definitions

The package exports comprehensive TypeScript types for working with the Scell.io API:

import type {
  // Configuration
  ScellMcpConfig,
  McpServerConfig,
  McpClientConfig,

  // Invoicing
  Company,
  InvoiceLine,
  InvoiceInput,
  Invoice,

  // Signatures
  Signer,
  SignatureInput,
  SignatureAttachment,
  SignatureRequest,

  // Results
  ToolResult,
  PaginatedResult,

  // Webhooks
  WebhookEventType,
  WebhookPayload,
} from '@scell/mcp-client';

Environment Variables

Variable Description
SCELL_API_KEY Default API key (used if not provided as argument)
SCELL_BASE_URL Default base URL for the API

Configuration Structure

The generated MCP configuration follows this structure:

{
  "mcpServers": {
    "scell": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-http", "https://api.scell.io/api"],
      "env": {
        "X-Scell-API-Key": "your_api_key",
        "SCELL_API_KEY": "your_api_key",
        "SCELL_BASE_URL": "https://api.scell.io/api"
      }
    }
  }
}

Getting an API Key

  1. Sign up at scell.io
  2. Navigate to Settings > API Keys
  3. Create a new API key with the required permissions
  4. Copy the key (it starts with tk_live_ or tk_test_)
  5. For fiscal and credit note tools, use a tenant API key (starts with tk_test_ or tk_live_)

Support

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

About

Agent Claude, specialisé dans l'intégration de scell.io

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors