velora

此仓库包含托管服务的公开清单和文档——完整实现作为 Velora 的一部分在生产环境中运行。

Velora — 阿根廷商务 MCP

⚠️ 托管端点暂时离线。 其对接的服务目前已暂停，因此 tools.somosvelora.com 目前会返回 404——下面的清单和工具契约仍然准确，但服务恢复前这些 URL 不会响应。这里的内容并未废弃；我们有意保持文档真实准确。

面向阿根廷的托管式多能力商务工具包——通过一个经过身份验证的端点，提供真实的 AFIP 发票、MercadoPago、物流、目录和 WhatsApp。

Velora 是一个托管的 Model Context Protocol 服务，为 AI Agent 提供在阿根廷运营商务业务的工具：税务发票（AFIP/ARCA）、支付（MercadoPago）、物流（Andreani / PedidosYa）、目录、收银和 WhatsApp 消息——均经过身份验证并按租户隔离。

其他 AFIP MCP 服务也存在（有些可以开具发票，有些只能搜索文档）。Velora 的特色在于组合方案：税务只是多种商务渠道之一——支付、物流、目录、消息——通过一个托管且经过身份验证的端点提供，让 Agent 能运营完整的阿根廷业务，而不只是开具发票。

端点

https://tools.somosvelora.com/api/mcp

传输方式：可流式传输的 HTTP。身份验证：API 密钥（按租户使用 HMAC）或 OAuth 2.1（WorkOS bearer）。任何 MCP 客户端——Claude、OpenAI、Gemini、Cursor 或你自己的 Agent——都可以使用同一个端点。

早期访问期间免费。 在我们接纳首批构建者期间，不收取使用费用——税务和纯工具不会在我们这边运行大模型，因此保持开放的成本很低。

连接

将任何支持远程可流式传输的 HTTP服务的 MCP 客户端指向该端点，并将你的凭据作为标头传入：

{
  "mcpServers": {
    "velora": {
      "type": "http",
      "url": "https://tools.somosvelora.com/api/mcp",
      "headers": {
        "X-API-Key": "<your-key>",
        "X-Business-Id": "<your-business-id>"
      }
    }
  }
}

具体的配置键（type/transport）因客户端而异——请使用客户端的远程/HTTP MCP 服务格式。可通过 somosvelora.com 申请访问权限。

纯税务辅助工具（validate_cuit、split_iva 等）也可在无需身份验证的情况下通过 https://tools.somosvelora.com/api/mcp/public 使用。

工具包

工具包	功能
Fiscal（AFIP/ARCA）	emit_invoice（真实 CAE — Factura A/B/C + 最终消费者），consultar_comprobante / consultar_padron（发票 + 纳税人查询），get_fiscal_readiness。emit_nota（NC/ND）：目前仅支持沙盒 — 正在开发真实的贷项/借项通知单开具功能。
基础工具（始终可用）	validate_cuit，validate_cuil，validate_cbu，build_afip_qr，format_ars，to_afip_date，split_iva，describe_invoice_type，parse_ar_amount
支付	MercadoPago 链接、付款跟踪、付款意向状态
物流	报价 / 创建 / 跟踪货运（Andreani、PedidosYa）
商品目录与库存	创建 / 编辑 / 删除商品，库存录入，批量更新价格
销售与现金	登记销售、退货、收银机流水和余额
客户与供应商	查找 / 更新客户，供应商管理
消息	发送 WhatsApp 文本和模板消息
报表	query_sales — 销售分析
连接	connection_status — 各集成的配置状态（请先调用此工具）

成熟度 / 当前已上线的功能。 emit_invoice（Factura A/B/C + 最终消费者）、查询工具和基础工具均已通过真实 AFIP 环境的生产验证。emit_nota（NC/ND）目前仅在沙盒中开具 — 真实的贷项/借项通知单开具功能尚未接入（它会返回 sandbox: true，绝不会伪造 CAE）。支付、物流和消息工具均是真实工具，需要为每个租户单独配置凭据（连接 MercadoPago / Andreani / WhatsApp）— 在租户完成连接前，这些工具会返回演示数据或优雅地失败，因此在完成配置前，请勿将它们接入生产工作流。只有在完成 ARCA 配置后，emit_invoice 才会开具真实 CAE（请通过 get_fiscal_readiness 检查）；否则它会返回明确标记的沙盒响应（sandbox: true），绝不会将伪造的 CAE 当作真实结果。

完整的机器可读目录 — 向公共端点调用 tools/list（无需身份验证），即可列出所有工具：

curl -s https://tools.somosvelora.com/api/mcp/public \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

为什么需要托管层

AFIP 的 Web 服务（WSAA + WSFE）出了名地难用：需要附加 PKCS#7 CMS 签名、使用弱 DH 的 TLS 握手、按 CUIT 管理证书和令牌，还要应对不断出台的新决议（例如 RG 5616）。Velora 将这些全部封装在简洁、原生适用于 Agent 的工具调用之后，让你无需重新实现整套税务功能 — 这也是开发者在 LATAM 其他地区使用托管层对接政府税务 API 的原因。

状态

• ✅ 已在生产环境验证真实 AFIP 发票开具（为已完成配置的租户实时签发 CAE）。
• ✅ MercadoPago 支付和纯验证 / 格式化工具已上线。
• 🔧 物流和消息功能需要为每个租户单独配置凭据（见上文成熟度）。

链接

• 网站：somosvelora.com
• 工具包端点：tools.somosvelora.com
• 博客（AFIP 集成实录）：somosvelora.com/blog — ⚠️ 目前 /blog 路由不可用，因此会返回 404

---

此仓库是 Velora MCP 服务的公开清单和文档。服务本身托管在云端；此仓库包含 server.json 注册清单和连接文档。

通过指导 Claude Code 构建 — 确定范围、生成内容，并在运行时验证。方法本身才是重点 — 同样的方法还促成了 Mastra（拥有 26k★ 的 TypeScript AI Agent 框架）合并了 2 个修复： #19604、#19610。