{"id":44514064,"url":"https://github.com/qrcommunication/scell-io-llm-agent","last_synced_at":"2026-05-25T00:11:28.046Z","repository":{"id":334487721,"uuid":"1141307219","full_name":"QrCommunication/scell-io-llm-agent","owner":"QrCommunication","description":"Agent Claude, specialisé dans l'intégration de scell.io","archived":false,"fork":false,"pushed_at":"2026-03-30T08:16:41.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T04:53:03.975Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/QrCommunication.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-24T16:22:34.000Z","updated_at":"2026-03-30T08:16:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/QrCommunication/scell-io-llm-agent","commit_stats":null,"previous_names":["qrcommunication/scell-io-llm-agent"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/QrCommunication/scell-io-llm-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QrCommunication%2Fscell-io-llm-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QrCommunication%2Fscell-io-llm-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QrCommunication%2Fscell-io-llm-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QrCommunication%2Fscell-io-llm-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/QrCommunication","download_url":"https://codeload.github.com/QrCommunication/scell-io-llm-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QrCommunication%2Fscell-io-llm-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31515151,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-13T16:26:33.749Z","updated_at":"2026-05-25T00:11:28.039Z","avatar_url":"https://github.com/QrCommunication.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @scell/mcp-client\n\nMCP (Model Context Protocol) client configuration generator for [Scell.io](https://scell.io) API.\n\nScell.io provides electronic invoicing (Factur-X/UBL/CII, **B2B and B2C**) and simple electronic signatures (eIDAS EU-SES) via API.\n\nFor 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.\n\n## Installation\n\n```bash\nnpm install @scell/mcp-client\n```\n\nOr use directly with npx:\n\n```bash\nnpx @scell/mcp-client claude YOUR_API_KEY\n```\n\n## Quick Start\n\n### Claude Desktop\n\n1. Generate the configuration:\n\n```bash\nnpx @scell/mcp-client claude tk_live_your_api_key_here\n```\n\n2. Save the output to your Claude Desktop config file:\n\n| Platform | Config Path |\n|----------|-------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n3. Restart Claude Desktop\n\n### Cursor IDE\n\n1. Generate the configuration:\n\n```bash\nnpx @scell/mcp-client cursor tk_live_your_api_key_here\n```\n\n2. Save to `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global config)\n\n3. Restart Cursor\n\n### VS Code\n\n1. Generate the configuration:\n\n```bash\nnpx @scell/mcp-client vscode tk_live_your_api_key_here\n```\n\n2. Save to `.vscode/mcp.json` in your project root\n\n3. Restart VS Code\n\n## CLI Usage\n\n```bash\nscell-mcp \u003ccommand\u003e \u003capi-key\u003e [options]\n\nCommands:\n  claude \u003capi-key\u003e     Generate Claude Desktop configuration\n  cursor \u003capi-key\u003e     Generate Cursor IDE configuration\n  vscode \u003capi-key\u003e     Generate VS Code configuration\n  generic \u003capi-key\u003e    Generate generic MCP configuration\n\nOptions:\n  --base-url \u003curl\u003e     Custom API base URL (default: https://api.scell.io/api)\n  --env \u003cenvironment\u003e  Environment: production, staging, development\n  --sandbox            Use sandbox mode (appends /sandbox to base URL)\n  --output \u003cfile\u003e      Write configuration to file instead of stdout\n  --help, -h           Show help message\n  --version, -v        Show version number\n```\n\n### Examples\n\n```bash\n# Generate Claude Desktop config\nscell-mcp claude tk_live_your_api_key_here\n\n# Generate Cursor config with staging environment\nscell-mcp cursor tk_live_your_api_key_here --env staging\n\n# Generate config and save directly to file\nscell-mcp claude tk_live_your_api_key_here --output ~/.config/Claude/claude_desktop_config.json\n\n# Use environment variable for API key\nexport SCELL_API_KEY=tk_live_your_api_key_here\nscell-mcp claude\n```\n\n## Available Tools\n\nOnce configured, your AI assistant will have access to these tools:\n\n### Health \u0026 Authentication\n\n| Tool | Description |\n|------|-------------|\n| `scell_health_check` | Check API health status and service availability |\n| `scell_validate_api_key` | Validate your API key and check permissions |\n\n### Electronic Invoicing\n\n| Tool | Description |\n|------|-------------|\n| `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). |\n| `scell_get_invoice` | Retrieve invoice details by ID |\n| `scell_list_invoices` | List all invoices with filtering and pagination |\n| `scell_download_invoice` | Download invoice as PDF or XML |\n\n### Electronic Signatures\n\n| Tool | Description |\n|------|-------------|\n| `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). |\n| `scell_get_signature` | Get signature request status and details |\n| `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). |\n| `scell_tenant_list_signatures` | **v2.7.0** List signatures for the whole tenant via URL-nested `GET /api/v1/tenant/signatures`. Auth: `sk_*`. Filters: `status`, `environment`, `page`, `per_page`. |\n| `scell_tenant_get_signature` | **v2.7.0** Get a single tenant-scoped signature via `GET /api/v1/tenant/signatures/{id}`. Auth: `sk_*`. |\n| `scell_subtenant_list_signatures` | **v2.7.0** List signatures of one sub-tenant via `GET /api/v1/tenant/sub-tenants/{subTenantId}/signatures`. Auth: `sk_*`. Anti-IDOR. |\n| `scell_subtenant_get_signature` | **v2.7.0** Get a single sub-tenant signature via `GET /api/v1/tenant/sub-tenants/{subTenantId}/signatures/{id}`. Auth: `sk_*`. |\n| `scell_download_signed` | Download the signed document |\n| `scell_cancel_signature` | Cancel a pending signature request |\n| `scell_send_reminder` | Send a reminder to pending signers |\n\n### Account \u0026 Validation\n\n| Tool | Description |\n|------|-------------|\n| `scell_get_balance` | Get account balance and credit information |\n| `scell_validate_siret` | Validate a French SIRET number |\n| `scell_validate_vat` | Validate a European VAT number |\n| `scell_get_audit_trail` | Get the audit trail for a document |\n\n### Fiscal Compliance (tenant key required)\n\nThese tools require a tenant API key (`tk_*`) and provide access to the fiscal compliance features mandated by French law (LF 2026).\n\n| Tool | Description |\n|------|-------------|\n| `scell_get_fiscal_compliance` | Get fiscal compliance dashboard (ISCA status) |\n| `scell_check_fiscal_integrity` | Verify the integrity of the fiscal hash chain |\n| `scell_list_fiscal_closings` | List recent fiscal daily closings |\n| `scell_get_fiscal_attestation` | Generate a fiscal compliance attestation |\n| `scell_list_fiscal_entries` | List fiscal ledger entries with filters |\n| `scell_get_kill_switch_status` | Check the fiscal kill-switch status |\n| `scell_list_fiscal_rules` | List applicable fiscal rules (VAT rates, etc.) |\n| `scell_download_measures_register` | Download the ISCA measures register as PDF |\n| `scell_download_technical_dossier` | Download the ISCA technical dossier as PDF |\n| `scell_download_self_attestation` | Download the ISCA self-attestation as PDF |\n\n### Credit Notes (tenant key required)\n\nThese tools require a tenant API key (`tk_*`) and manage credit notes (avoirs) linked to invoices.\n\n| Tool | Description |\n|------|-------------|\n| `scell_list_credit_notes` | List credit notes with filtering |\n| `scell_get_credit_note` | Get credit note details |\n| `scell_download_credit_note` | Download credit note as PDF |\n| `scell_create_credit_note` | Create a credit note from an invoice |\n| `scell_send_credit_note` | Validate and send a draft credit note |\n| `scell_delete_credit_note` | Delete a draft credit note |\n| `scell_get_remaining_creditable` | Calculate remaining creditable amounts |\n\n### Partner Onboarding (publishable key required)\n\nThese tools require a publishable key (`pk_*`) and handle partner tenant onboarding via SuperPDP's OAuth2 tunnel.\n\n| Tool | Description |\n|------|-------------|\n| `scell_onboarding_create_session` | Create a new onboarding session |\n| `scell_onboarding_get_session` | Get onboarding session status and result |\n| `scell_onboarding_superpdp_authorize` | Start the SuperPDP OAuth2 flow — returns `authorize_url` and `state` |\n| `scell_onboarding_superpdp_callback` | Complete the SuperPDP OAuth2 flow — returns `authorization_code` and tenant |\n\n### Sub-Tenant Lifecycle (master tenant `sk_*` or Bearer required)\n\nThese 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).\n\n| Tool | Description |\n|------|-------------|\n| `scell_get_subtenant_status` | Get the cached SuperPDP onboarding status for a sub-tenant |\n| `scell_refresh_subtenant_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_start_subtenant_superpdp_authorize` to obtain a fresh one.** |\n| `scell_start_subtenant_superpdp_authorize` | **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 }`. |\n| `scell_resume_url` | Regenerate a 7-day signed resume URL for a sub-tenant whose onboarding is not yet `active` |\n| `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). |\n\n### Payment Schedule Tools (since v2.13.0)\n\nThese 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`).\n\n| Tool | Description |\n|------|-------------|\n| `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[]`. |\n| `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. |\n| `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`). |\n| `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. |\n| `scell_convert_quote_schedule_line_to_deposit` | **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'`. |\n| `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. |\n\n### Invoice Email Tool (since v2.13.0)\n\n| Tool | Description |\n|------|-------------|\n| `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`. |\n\n### Branding Tools (since v2.13.0)\n\nEmail branding allows tenants and sub-tenants to customize the logo, primary color, email footer, and signature on all outbound emails (invoice, credit note, quote). 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.\n\n**Important:** `brand_logo_url` is distinct from `logo_url` (the Factur-X PDF logo). `brand_primary_color` must be `#RRGGBB` (6-digit hex, validated server-side).\n\n| Tool | Description |\n|------|-------------|\n| `scell_get_tenant_branding` | Get the current email branding for the master tenant. `GET /api/v1/tenant/branding`. Returns `Branding` with `is_complete` flag and `missing_fields[]`. |\n| `scell_update_tenant_branding` | Update master-tenant email branding fields. `PATCH /api/v1/tenant/branding` with `BrandingInput`. All fields optional; send only what changes. Set to `null` to clear a field. Returns the updated `Branding`. |\n| `scell_get_sub_tenant_branding` | Get email branding for a specific sub-tenant (anti-IDOR scoped). `GET /api/v1/sub-tenants/{id}/branding`. Returns `Branding`. |\n| `scell_update_sub_tenant_branding` | Update email branding for a specific sub-tenant. `PATCH /api/v1/sub-tenants/{id}/branding` with `BrandingInput`. Returns the updated `Branding`. |\n\n## Example Prompts\n\nOnce the MCP server is configured, you can use natural language prompts like:\n\n### Invoice Examples\n\n```\n\"Create an invoice for Acme Corp, SIRET 12345678901234, for consulting services:\n- 10 hours at 150 EUR/hour\n- Due in 30 days\n- Factur-X format\"\n\n\"List all unpaid invoices from the last month\"\n\n\"Download invoice INV-2024-001 as PDF\"\n```\n\n### International Invoicing\n\n```\n\"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€\"\n```\n\n### Signature Examples\n\n```\n\"Create a signature request for the attached contract.\nSend to john.doe@example.com for signature.\"\n\n\"Check the status of signature request sig_abc123\"\n\n\"Send a reminder for all pending signature requests older than 7 days\"\n```\n\n### Fiscal Compliance Examples\n\n```\n\"Show me the fiscal compliance status for my company\"\n\n\"Check the integrity of the fiscal hash chain for January 2026\"\n\n\"List the last 10 daily fiscal closings\"\n\n\"Generate a fiscal attestation for year 2025\"\n```\n\n### Credit Note Examples\n\n```\n\"List all draft credit notes\"\n\n\"Create a total credit note for invoice INV-2026-00042 because of duplicate billing\"\n\n\"Send credit note AV-2026-00003\"\n\n\"How much can still be credited on invoice INV-2026-00015?\"\n```\n\n### Onboarding Examples\n\n```\n\"Start the onboarding process for a new partner tenant\"\n\n\"Get the SuperPDP authorization URL so the partner can connect their account\"\n\n\"Complete the SuperPDP OAuth2 callback with state=abc123 and code=xyz456\"\n\n\"Check the status of onboarding session sess_abc123\"\n```\n\n## Programmatic Usage\n\n```typescript\nimport {\n  generateClaudeDesktopConfig,\n  generateCursorConfig,\n  generateVSCodeConfig,\n  validateConfig,\n  type ScellMcpConfig,\n  type InvoiceInput,\n  type SignatureInput,\n} from '@scell/mcp-client';\n\n// Generate configuration\nconst config: ScellMcpConfig = {\n  apiKey: 'tk_live_your_api_key_here',\n  baseUrl: 'https://api.scell.io/api', // optional\n  environment: 'production', // optional\n};\n\n// Validate configuration\nconst validation = validateConfig(config);\nif (!validation.valid) {\n  console.error('Invalid config:', validation.errors);\n}\n\n// Generate for different clients\nconst claudeConfig = generateClaudeDesktopConfig(config);\nconst cursorConfig = generateCursorConfig(config);\nconst vscodeConfig = generateVSCodeConfig(config);\n\nconsole.log(JSON.stringify(claudeConfig, null, 2));\n```\n\n## Type Definitions\n\nThe package exports comprehensive TypeScript types for working with the Scell.io API:\n\n```typescript\nimport type {\n  // Configuration\n  ScellMcpConfig,\n  McpServerConfig,\n  McpClientConfig,\n\n  // Invoicing\n  Company,\n  InvoiceLine,\n  InvoiceInput,\n  Invoice,\n\n  // Signatures\n  Signer,\n  SignatureInput,\n  SignatureRequest,\n\n  // Results\n  ToolResult,\n  PaginatedResult,\n\n  // Webhooks\n  WebhookEventType,\n  WebhookPayload,\n} from '@scell/mcp-client';\n```\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `SCELL_API_KEY` | Default API key (used if not provided as argument) |\n| `SCELL_BASE_URL` | Default base URL for the API |\n\n## Configuration Structure\n\nThe generated MCP configuration follows this structure:\n\n```json\n{\n  \"mcpServers\": {\n    \"scell\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-http\", \"https://api.scell.io/api\"],\n      \"env\": {\n        \"X-Scell-API-Key\": \"your_api_key\",\n        \"SCELL_API_KEY\": \"your_api_key\",\n        \"SCELL_BASE_URL\": \"https://api.scell.io/api\"\n      }\n    }\n  }\n}\n```\n\n## Getting an API Key\n\n1. Sign up at [scell.io](https://scell.io)\n2. Navigate to Settings \u003e API Keys\n3. Create a new API key with the required permissions\n4. Copy the key (it starts with `tk_live_` or `tk_test_`)\n5. For fiscal and credit note tools, use a tenant API key (starts with `tk_test_` or `tk_live_`)\n\n## Support\n\n- Documentation: [docs.scell.io](https://docs.scell.io)\n- Issues: [GitHub Issues](https://github.com/QrCommunication/scell-io-llm-agent/issues)\n- Email: support@scell.io\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Contributing\n\nContributions are welcome! Please read our contributing guidelines before submitting a pull request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqrcommunication%2Fscell-io-llm-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqrcommunication%2Fscell-io-llm-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqrcommunication%2Fscell-io-llm-agent/lists"}