CargoDoc Integrator - AP/MCP

🌟 Overview

This component, named AverbePorto-MCP, functions as an intermediary server adhering to the Model Context Protocol (MCP). Its primary role is to establish a secure conduit to the proprietary AverbePorto system, specifically designed to streamline authentication procedures and expedite the submission of required cargo insurance documentation utilizing integrated Artificial Intelligence (AI) frameworks.

🌐 Accessing the Web Portal

To interact manually with the source system:

1. Navigate to https://www.averbeporto.com.br.
2. Authenticate using your established user credentials.
3. Within the portal, capabilities include:
   • Key generation for API access credentials located under User Registration.
   • Programmatic dispatch of XML-formatted documents.
   • Querying of ANTT (National Land Transportation Agency) protocols.
   • Comprehensive tracking and administration of active cargo insurance endorsements.

🤖 AI Integration via MCP Server Deployment

Installation using Smithery

For streamlined, automatic deployment of the averbeporto-mcp service for use with Claude Desktop:

bash npx -y @smithery/cli install @GHSix/averbeporto-mcp --client claude

Claude Desktop Configuration

1. Modify the configuration file: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (MacOS).

2. Incorporate the following structure under the appropriate section:

   { "mcpServers": { "AverbePorto-MCP": { "command": "node", "args": ["/caminho/para/AverbePorto-MCP/build/index.js"] } } }

3. The MCP service will initialize automatically upon subsequent conversation startup.

Configuration for Cursor, Roo Code and Similar Environments

1. Establish a configuration file, such as .cursor/mcp.json or .roo/mcp.json, within your project directory:

   { "mcpServers": { "AverbePorto-MCP": { "command": "node", "args": ["/caminho/para/AverbePorto-MCP/build/index.js"], "disabled": false, "alwaysAllow": [ "login", "consultProtocol", "upload", "retrieveDocument", "decomposeKey" ] } } }

2. The server will launch dynamically as required during the session.

Github Copilot Integration Setup

1. With Copilot active in your IDE, generate the file .vscode/mcp.json:

{ "inputs": [ { "type": "promptString", "id": "averbeporto-user", "description": "AverbePorto API Username" }, { "type": "promptString", "id": "averbeporto-pass", "description": "AverbePorto API Password", "password": true } ], "servers": { "AverbePorto-MCP": { "command": "node", "args": ["/caminho/para/AverbePorto-MCP/build/index.js"], "env": { "AVERBEPORTO_USER": "${input:averbeporto-user}", "AVERBEPORTO_PASS": "${input:averbeporto-pass}" } } } }

1. Your IDE will prompt for secure credential entry upon the initial execution attempt.
2. Copilot will then recognize available MCP calls, offering context-aware suggestions for:
   • API session establishment.
   • XML file submissions.
   • ANTT regulatory reference lookups.
3. Credentials will be securely injected into the necessary API calls.

📚 Exposed Functionality for AI Agents

This AverbePorto-MCP interface exposes the following callable utilities:

• login: Establishes authenticated session access.
• Inputs: user, pass

• Output: sessionId (Session Identifier)

• upload: Transmits specified documentation.

• Inputs: sessionId, filePath, recipient (optional), version (optional)

• Output: uploadId

• consultProtocol: Queries regulatory protocols based on associated keys or vice versa.

• Inputs: sessionId, keys, protocols, outputFormat, download, delimiter

• Supported Output Formats: json, xml, csv

• retrieveDocument: Fetches archived submission records.

• Required Inputs:

  • sessionId: Credential derived from the login function.
  • modDoc: Document category (e.g., DI, MDF-e, CT-e, NF-e, Minuta CT-e).
  • dtStart & dtLimit: Date range specification in YYYY-MM-DD format.
  • dtType: Temporal filter type (Options: Update, Emission, Send); default is Send.
  • Optional Filtering Parameters: numDoc, emit, rem, exped, receb, dest, toma, importador, representante, prot, taxId.
  • Pagination Controls: page, start, limit.
  • Supplementary Parameters: relation, modal, valid.

• decomposeKey: Parses and breaks down access keys for detailed inspection.

• Input: key (The 44-digit access code for NF-e, CT-e, or MDF-e).

🔒 Security Posture

• Authentication must rely exclusively on API tokens provisioned via the User Registration module.
• User credentials must be kept confidential.
• The generated sessionId must not be shared.
• Ensure all operational interactions utilize secure communication channels.
• Regularly apply updates to the MCP service layer.