{
  "markdown": "# Red MCP Server\n\nRed is an open-source [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects AI assistants and MCP clients to [Big Red Cloud](https://www.bigredcloud.com) accounting data through a set of controlled MCP tools.\n\nSupported customer platforms today are **ChatGPT**, **Claude**, and **Mistral** (including [Vibe](https://chat.mistral.ai/chat)). Other MCP clients may work technically, but they are not treated as officially supported platforms. Red uses platform detection only for anonymous operational telemetry (see [Privacy-safe telemetry](#privacy-safe-telemetry)).\n\nInstead of calling the Big Red Cloud REST API directly, users work in plain language. The server translates requests into structured API calls and applies safety checks around anything that changes data.\n\nWith Red, a connected user can:\n\n- **Review** Big Red Cloud data with read-only lookups (customers, suppliers, products, invoices, quotes, nominal reports, and more).\n- **Review before posting** — see a plain-English preview of new or changed records before anything is written to Big Red Cloud.\n- **Create, update, delete, batch, or email** records only after explicit confirmation (and only when those capabilities are enabled for the deployment).\n- **Ask Big Red Cloud how-to and training questions** — Red answers using official support articles, customer documentation, screenshots, and webinar resources. These help tools do not require a connected company.\n\n---\n\n## Why open source?\n\nWe believe AI infrastructure should be transparent. Customers should be able to inspect the software that connects their accounting data to AI assistants.\n\nOur competitive advantage is not the connector itself; it is our accounting platform, our expert bookkeeping advice, our customer experience, and the value we build on top of it.\n\nBy open-sourcing Red, we hope to encourage trust, community contributions, and wider adoption of open standards.\n\n---\n\n## Features\n\n- Secure company connection flow (one-time connection page; no credentials in chat)\n- Pre-confirm validation of company connection credentials on the connection page (single-company form or multi-company CSV upload)\n- Partial connection results — invalid keys are rejected before confirm and reported in `failedCompanies`\n- Hosted HTTP `connectionRef` / `activeConnectionRef` so MCP clients can silently reuse a confirmed connection across supported session changes; kept in tool JSON, not shown to end users\n- Request routing for transactional work — action tools expect a short-lived `routeToken` from the router before create/update/delete/batch/email workflows proceed\n- Privacy-safe anonymous operational telemetry (platform, environment, tool name, connected-company count) — see [docs/TELEMETRY.md](docs/TELEMETRY.md)\n- Company readiness check (`brc_company_readiness_check`) for connected companies\n- Read-only Big Red Cloud lookups\n- Customer, supplier, product, sales rep, VAT, and analysis category tools\n- Sales quotes, invoices, credit notes, purchases, payments, and cash tools\n- Preview-before-posting confirmation flow for create, update, delete, and batch actions (email tools use an explicit send confirmation)\n- VAT and transaction safety checks\n- Sales invoice safeguards, including multi-line generated-reference validation, Gross Price Entry `priceBasis` handling, Sales VAT category validation, placeholder product ID blocking, and related preflight checks\n- Session audit log of writes made through the MCP session, plus a downloadable support diagnostic for one connected company\n- Official Big Red Cloud help answers from Freshdesk articles, customer documentation, screenshots, and webinars — no company connection required\n- Local stdio and hosted HTTP transports\n\n---\n\n## Security and safety model\n\nRed is designed so that AI-driven access to accounting data stays controlled and auditable.\n\n- **No credentials in the repository.** Company connection credentials and secrets are never committed. Configuration is supplied at runtime through environment variables.\n- **No credentials in chat.** Company connection credentials must not be pasted into chat. Companies are connected through the secure Red connection page, where credentials are entered directly — not in the chat window.\n- **Session-scoped connections.** A connected company stays available for about the configured session duration and is held in session memory (or an optional shared connection store in hosted deployments). Where supported, connection handling is resilient across MCP session rotation so clients can reuse `connectionRef` / `activeConnectionRef` without asking the user to reconnect.\n- **Pre-confirm validation.** Company connection credentials submitted on the connection page are validated against Big Red Cloud before they are stored. Invalid or expired credentials are not saved; they appear in `failedCompanies` at confirmation time.\n- **Credential invalidation.** Only confirmed authentication failures clear a stored company credential. Endpoint, validation, permission, timeout, and server failures are not treated as an expired API key.\n- **User-facing presentation.** `connectionRef`, session IDs, and other MCP diagnostics are for tool arguments only. Assistants must not show `redconn_…` values or internal connection metadata to normal users unless the user explicitly asks for technical details.\n- **Configurable session duration.** How long connections last is controlled by `BRC_API_KEY_TTL_MINUTES`. User-facing wording (connection page, getting-started text, connection status) is derived from that value — not hardcoded.\n- **Request routing for writes.** Create, update, delete, batch, and email tools require a valid short-lived `routeToken` issued by the request router for the matching workflow. A route token is not permission to post — preview and confirmation still apply.\n- **Explicit confirmation for writes.** Create, update, delete, and batch actions require an explicit confirmation flag after a preview before posting has been shown. Email tools require an explicit send confirmation after an email preview.\n- **Preview before posting.** The first call to a write tool returns a payload preview rather than performing the action. Nothing is written to Big Red Cloud until you confirm.\n- **Read and write are separated.** Read-only lookups are clearly distinct from actions that change data.\n- **Audit log.** Writes made through the MCP session are recorded in a session audit log; read-only lookups are not treated as completed changes. Activity is scoped to currently connected companies. A downloadable support diagnostic can be generated for one connected company at a time; generating it is read-only and does not write to Big Red Cloud.\n- **Deployment flags.** Update, delete, email, batch, and operator/dev tools can each be disabled per deployment. Disabled skill groups are **not registered** with the MCP client for that process, so those tools are hidden rather than callable.\n\n### Sales invoice safety checks\n\nSales invoice handling includes:\n\n- **Gross Price Entry** requires an explicit `priceBasis` of `gross` or `net` so VAT is never guessed.\n- **Sales VAT rates only.** Sales invoices must use a Sales VAT category; purchase VAT rates are blocked, even when the percentage matches.\n- **Placeholder product IDs** (`productId` `0` and `1`) are treated as placeholders and blocked before preview-before-posting and post.\n- **Multi-line generated-reference invoices** (`brc_create_sales_invoice_gen_ref`) require each `productTrans` line to include its own `acEntries` analysis allocation. Line net/VAT/gross reconciliation, analysis allocation totals, header totals, and required product/VAT/analysis fields are validated before posting; failures return structured field-level errors.\n- **`note`** defaults to the customer name unless a note is explicitly provided, and is never set to a product name.\n- **`deliveryTo`** is included only when a delivery address is explicitly provided.\n- **Plain-language results.** Technical HTTP status codes are translated into plain-language messages for users.\n\n---\n\n## Architecture\n\nTwo entry points share one tool registry:\n\n| Entry | File | Transport | Use case |\n| ----- | ---- | --------- | -------- |\n| Local stdio | `src/index.ts` | `StdioServerTransport` | An MCP client spawns `node build/index.js` |\n| Hosted HTTP | `src/remote.ts` | Streamable HTTP on `/mcp` | `npm run start` — one MCP server per session |\n\nKey shared modules:\n\n- `src/server.ts` — MCP server factory and stdio singleton\n- `src/register_all_tools.ts` — central tool registration; skips tools whose skill group is disabled, and wraps write tools with routing and preview-before-posting/confirmation handling\n- `src/config/server_config.ts` — deployment skill gating driven by the `BRC_ALLOW_*` flags\n- `src/config/mcp_config.ts` — MCP server instructions, connection-safety rules, help-answer rules, and connectionRef presentation rules\n- `src/routing/` — request classification and short-lived `routeToken` issuance/validation for transactional tools\n- `src/shared.ts` — Big Red Cloud HTTP client, session-scoped connections, audit log, and helpers\n- `src/read_connection_metadata.ts` — connection status metadata echoed on tool responses (including `activeConnectionRef` for hosted clients)\n- `src/auth/connection_presentation.ts` — user-facing TTL wording and assistant presentation hints\n- `src/auth/credential_validation.ts` — BRC read validation before storing company connection credentials\n- `src/guards/` — transaction, reference, VAT category, product line, and write-confirmation safety checks\n- `src/auth/` — secure connection flow, connection store (memory or Cosmos), connection page, and credential persistence\n- `src/telemetry/` — anonymous client/session identity and platform detection for hosted operational telemetry\n- `src/brc-edu/` — Freshdesk articles, customer documentation, webinar indexes, screenshots, and unified help search\n- `src/edu/` — shared help-resource loading, enrichment, workbook parsing, and storage configuration\n- `src/tools/edu/` — read-only help tools\n- `src/tools/routing/` — request-routing tool registration\n\nDomain logic lives under `src/tools/`, with generic create/update/delete/list/batch helpers in `src/tools/general/`.\n\n### Technology\n\n- TypeScript / Node.js (ES modules)\n- `@modelcontextprotocol/sdk`\n- Zod for tool input validation\n- Express + Streamable HTTP for hosted mode\n\n---\n\n## Requirements\n\n- Use a current LTS version of Node.js.\n- npm (bundled with Node.js).\n\n---\n\n## Installation\n\n```bash\nnpm install\nnpm run build\n```\n\nIf a `.env.example` file is provided, copy it to `.env` and adjust the values:\n\n```bash\ncp .env.example .env\n```\n\nNever commit your `.env` file or any real credentials.\n\n---\n\n## Running\n\nHosted HTTP server:\n\n```bash\nnpm run start\n# Serves the MCP endpoint at http://localhost:3000/mcp\n```\n\nLocal stdio server:\n\n```bash\nnpm run start:local\n```\n\nOpening the HTTP endpoint in a browser without an MCP session returns an error — that is expected.\n\n### MCP client configuration\n\nLocal stdio (the client spawns the process):\n\n```json\n{\n  \"mcpServers\": {\n    \"red-mcp-server\": {\n      \"command\": \"node\",\n      \"args\": [\"build/index.js\"],\n      \"env\": {\n        \"BRC_API_BASE_URL\": \"https://app.bigredcloud.com/api\"\n      }\n    }\n  }\n}\n```\n\nHosted HTTP (production):\n\nFor the hosted Big Red Cloud Red service, customers should use:\n\n`https://red.bigredcloud.com/mcp`\n\n```json\n{\n  \"mcpServers\": {\n    \"red-mcp-server\": {\n      \"url\": \"https://red.bigredcloud.com/mcp\"\n    }\n  }\n}\n```\n\nHosted HTTP (local development):\n\n```json\n{\n  \"mcpServers\": {\n    \"red-mcp-server\": {\n      \"url\": \"http://localhost:3000/mcp\"\n    }\n  }\n}\n```\n\n---\n\n## Development and regression testing\n\n| Script | Command | Purpose |\n| ------ | ------- | ------- |\n| Build | `npm run build` | Compile TypeScript to `build/` |\n| Dev HTTP | `npm run dev` | Run the HTTP server from source with `tsx` |\n| Dev stdio | `npm run dev:local` | Run the stdio server from source with `tsx` |\n| All tests | `npm test` | Build, then run the full test suite |\n| Unit tests | `npm run test:unit` | Unit tests only |\n| Security tests | `npm run test:security` | Security-focused tests |\n| Config tests | `npm run test:config` | Deployment/config tests |\n| Integration tests | `npm run test:integration` | Integration tests |\n| Production audit | `npm run audit:prod` | `npm audit` for production dependencies |\n\nTests cover the safety guards described above, including sales invoice checks, transaction date validation, the secure connection flow (CSV validation, partial confirm, credential invalidation), connectionRef presentation rules, request routing, TTL wording, and response wording.\n\n---\n\n## Environment variables\n\nConfigure the server with environment variables (for example via a `.env` file). The values below are **examples only** and must never contain real secrets or be committed.\n\n```env\n# Big Red Cloud API base URL\nBRC_API_BASE_URL=https://app.bigredcloud.com/api\n\n# HTTP port for hosted mode\nPORT=3000\n\n# Public URL for the secure /connect page (required for hosted deployments)\nBRC_PUBLIC_BASE_URL=https://your-mcp-host.example.com\n\n# MCP session binding lifetime (minutes)\nBRC_MCP_SESSION_TTL_MINUTES=120\n\n# How long stored company credentials stay valid (minutes).\n# Drives credential expiry and user-facing duration wording (e.g. 240 → \"about 4 hours\").\nBRC_API_KEY_TTL_MINUTES=120\n\n# Rate limiting (requests per minute per IP)\nBRC_RATE_LIMIT_REQUESTS_PER_MINUTE=300\n\n# SHA-256 hashes of blocked API keys, comma separated (hashes only, never raw keys)\nBRC_API_KEY_BLACKLIST_SHA256=\n\n# Hosted connection persistence (optional)\n# memory = in-process; cosmos = shared store for multi-instance HTTP\nRED_CONNECT_CONNECTION_STORE=memory\nRED_CONNECT_COSMOS_CONNECTION_STRING=\nRED_CONNECT_COSMOS_DATABASE=red-connect\nRED_CONNECT_COSMOS_CONTAINER=connections\nRED_CONNECT_ENCRYPTION_KEY=\n\n# Set automatically when running the HTTP server (remote.ts)\nRED_CONNECT_HTTP_MODE=true\n```\n\nDeployment skill flags control which categories of tools are registered. When a flag is off, tools in that skill group are skipped at registration and do not appear to MCP clients:\n\n```env\nBRC_ALLOW_READ_SKILLS=true\nBRC_ALLOW_UPDATE_SKILLS=true\nBRC_ALLOW_DELETE_SKILLS=true\nBRC_ALLOW_EMAIL_SKILLS=true\nBRC_ALLOW_BATCH_SKILLS=true\n# Operator-only diagnostics; keep off for normal deployments\nBRC_ALLOW_DEV_MODE=false\n```\n\nYou can review the active customer-facing capability summary at runtime with the `brc_get_deployment_policy` tool (plain-language availability of read, create/change, delete, email, and batch — not a full tool catalogue).\n\n---\n\n## Connecting a company\n\nCustomers should connect companies through the **secure Red connection page**. Company connection credentials must not be sent through chat — they are entered only on the secure Red connection page, not in the chat window.\n\nCustomers can get or regenerate their company API keys in Big Red Cloud under **Administration → API Keys**.\n\nThe flow is:\n\n1. Ask the assistant to start a company connection. It returns a secure connection page link.\n2. On that page, enter a single company **or upload a CSV** for several companies at once. Company connection credentials are entered on the secure page, not in chat.\n3. The server validates each credential against Big Red Cloud **before storing it**. Credentials that fail validation are not saved.\n4. Return to the chat and provide the **confirmation code** shown on the success page.\n5. After confirm, the assistant reports which companies connected and which failed (if any). Invalid credentials appear in `failedCompanies` immediately — you do not need to run a lookup first to discover a bad key.\n\nConnection links are **one-time use**. Connected companies stay available for about the configured session duration (`BRC_API_KEY_TTL_MINUTES`, for example 240 minutes → about four hours), unless you disconnect or the connection expires.\n\n### Hosted HTTP and `connectionRef`\n\nIn hosted HTTP mode (for example Mistral/Vibe), `brc_confirm_company_connection` returns an opaque `connectionRef` in the tool JSON. MCP clients should preserve and silently reuse `connectionRef` / `activeConnectionRef` on later tool calls when the platform rotates session IDs. Connection persistence survives MCP session rotation where supported. This is an implementation detail for the client — **assistants should not show `connectionRef` or `redconn_…` values to end users**. Tool responses include `assistantInstruction` / `presentationHint` fields to reinforce that rule.\n\nHelper tools:\n\n- List connected companies in the session\n- Clear one company connection\n- Clear all company connections\n\n---\n\n## Privacy-safe telemetry\n\nOn hosted deployments, Red may record anonymous operational telemetry so operators can understand approximate usage. Typical dimensions include anonymous client and connection-session identifiers, detected platform, deployment environment, tool name, and connected-company count.\n\nTelemetry does **not** include API keys, credentials, raw `connectionRef` values, authorisation headers, request bodies, or invoice/customer/supplier payloads. Failed Big Red Cloud calls may include safe identifiers such as `company_id` or `record_id`. These metrics are not verified Big Red Cloud user identities (OAuth user identity is not implemented).\n\nDetails for operators and developers: [docs/TELEMETRY.md](docs/TELEMETRY.md).\n\n---\n\n## Tool coverage\n\nRed exposes a focused set of MCP tools, grouped by domain. Exact tool names and their endpoint mappings live in the source code under `src/tools/` and are summarised for developers in [docs/TOOLS.md](docs/TOOLS.md).\n\n- **Company setup and readiness** — company setup configuration, financial year, processing settings, readiness checks, transaction date validation, and account-history document-type resolution.\n- **Customers and suppliers** — list/get/create/update/delete plus opening balances and account transactions.\n- **Products and sales reps** — list/get/create/update/delete and product types.\n- **Sales documents** — quotes, sales invoices, sales credit notes, and sales entries, including generated-reference variants and generating an invoice from a quote.\n- **Purchases and payments** — purchases, payments, cash payments, cash receipts, and bank accounts.\n- **VAT and analysis lookups** — VAT rates, VAT categories, VAT types, analysis categories, accounts, and related reference data.\n- **Nominal reports** — nominal account listings and grouped/multi-company nominal reporting.\n- **Audit and session** — session connection management, the session audit log, and the downloadable support diagnostic.\n- **Help and training** — Freshdesk articles, customer documentation, recorded webinars, upcoming webinars, and screenshot links through read-only help tools. No company connection is required.\n\nBatch variants exist for the main create workflows and apply the same safety checks as the single-record tools.\n\n### Company readiness check\n\n`brc_company_readiness_check` is a read-only overall health check for a connected company. Overall statuses are:\n\n- `ready`\n- `ready_with_warnings`\n- `not_ready`\n- `connection_problem`\n\nIt reviews connection status plus relevant setup such as financial year, transaction date position, active Sales VAT rates, Sales Analysis categories, products, and sales representatives. Missing suppliers is reported as a purchase-setup warning and does **not** block sales-invoice readiness. Manual reference settings are treated as a warning / preflight consideration, not necessarily a blocker.\n\nFor a specific VAT-sensitive workflow (sales invoice, purchase, cash receipt, statement), use `brc_check_transaction_settings` instead — that tool checks one workflow’s processing settings, while readiness scores overall company readiness. Narrower helpers such as `brc_validate_transaction_date`, `brc_get_company_processing_settings`, and `brc_get_company_reference_settings` remain available for focused lookups.\n\n### Support diagnostics\n\n`brc_list_audit_log` shows Red write activity from the current session for currently connected companies. Read-only lookups are not treated as completed changes.\n\n`brc_generate_support_report` creates a downloadable plain-text diagnostic for **one connected company** at a time. If several companies were used, generate a separate report for each. Reports include success/failure and correlation information useful to support. They exclude credentials, API keys, tokens and connection references. Generating a report is read-only and does not write to Big Red Cloud.\n\nDeveloper details: [docs/TOOLS.md](docs/TOOLS.md) and [docs/TELEMETRY.md](docs/TELEMETRY.md).\n\n### Previous-financial-year behaviour\n\nA transaction date outside the current financial year is a **warning**, not an automatic statement that the operation is impossible. After normal preview and confirmation, Red attempts only the supported action. If Big Red Cloud rejects the action or date, Red reports the actual response. Not every historical transaction can be changed.\n\n### Transaction improvements\n\n- Quote confirmation previews, validation and quote-to-invoice generation (`brc_generate_sales_invoice_from_quote`).\n- Cash-receipt VAT handling and ledger preservation on updates.\n- Supported cash-payment fields can be corrected on the existing record through the update workflow.\n- Account-history lines should be resolved to the correct document type (`brc_resolve_book_transaction_type`) before a document-specific lookup or change.\n- Undo, reverse and correct requests are treated as planning first — never as automatic permission to post another transaction.\n\n---\n\n## Help and training resources\n\nRed includes read-only MCP tools for Big Red Cloud help and training questions. They do not require a connected company.\n\nTypical capabilities:\n\n- search official articles, customer documentation, recorded webinars, and upcoming webinars;\n- load full details for a selected resource, including step-by-step guidance and relevant screenshot links where available;\n- answer reserved help-style questions (including `red-help` / `/red-help` style commands) through the help pipeline.\n\nHelp answers may include:\n\n- official Freshdesk articles;\n- customer documentation;\n- relevant screenshots;\n- recorded YouTube training videos;\n- upcoming webinar links.\n\nHelp-resource indexes are supplied by the deployment operator. The public repository does not include Big Red Cloud’s internal content-management or resource-upload workflow.\n\n---\n\n## Known limitations\n\n- Some features depend on how the company is configured in Big Red Cloud.\n- Email sending and some bank write operations may require additional tenant configuration and may be disabled by deployment flags.\n- Generated-reference behaviour can depend on Big Red Cloud tenant settings, and some generated-document endpoints may apply the tenant's current transaction date. A date outside the current financial year is a warning, not an automatic refusal; the Big Red Cloud response is authoritative.\n- Tool availability may vary by deployment policy (disabled skill groups are not registered).\n- Anonymous telemetry counts approximate clients (for example browser/device cookies), not verified individual people.\n- Platform detection may be `unknown` when a client does not provide enough identifying information.\n- Officially supported customer platforms are ChatGPT, Claude, and Mistral/Vibe; other MCP clients are not claimed as supported platforms.\n\n---\n\n## Maintainers\n\nThis project is maintained by the Big Red Cloud software development team.\n\n---\n\n## Status\n\nRed is in BETA.\nRed is an open-source MCP integration for Big Red Cloud and is under active development. Tool availability and behaviour may change between releases, and some capabilities are gated by deployment policy.\n\n---\n\n## License\n\nThis project is licensed under the Apache License 2.0. See LICENSE for details.\n\n---\n\n## Support and responsible disclosure\n\nIf you believe you have found a security issue, please report it to Big Red Cloud's support team.\n",
  "bytes": 24189,
  "sha": "8a9d8dba6662ee4aa7f2a4917a5561ded01625aefcc168d4893557c61892c76b",
  "repo_slug": "bigredcloud/red-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bigredcloud_red_mcp_server_e9aebbdb/readme"
}