AroFlo MCP

Standalone, production-ready MCP server for AroFlo with first-class request signing and a clean tool surface.

Quick Start

Install (Local)

This repo ships an MCP server executable named aroflo-mcp (stdio transport by default).

Install the server on your machine (puts aroflo-mcp on your PATH via npm link):

make install

If global npm linking is restricted on your machine, skip npm link and run without a global install:

npm run build
node dist/mcp/server.js

Install Into Codex (stdio)

1. Create a local .env (not committed) with your credentials:

cp .env.example .env
# edit .env

2. Register the server in Codex (stores env in ~/.codex/config.toml, not passed as tool args):

make codex-install

make codex-install writes MCP config into ~/.codex/config.toml. If this path is permission-restricted, re-run with appropriate permissions.

3. Verify:

codex mcp get aroflo

Manual Codex Install (Alternative)

If you prefer doing it manually (same env variables, stored in Codex config):

codex mcp add aroflo \
  --env AROFLO_API_BASE_URL=https://api.aroflo.com/ \
  --env AROFLO_ACCEPT=text/json \
  --env AROFLO_SECRET_KEY=... \
  --env AROFLO_UENCODED=... \
  --env AROFLO_PENCODED=... \
  --env AROFLO_ORG_ENCODED=... \
  --env MCP_TRANSPORT=stdio \
  -- "$(command -v node)" "$(pwd)/dist/mcp/server.js"

Notes:

• If Codex (desktop app) hangs starting the server, it is usually a PATH issue (common when Node is installed via nvm and the app is launched outside your shell).
• Fix 1: Launch Codex from a terminal so it inherits your shell PATH (codex app).
• Fix 2: Configure the MCP server to run via an absolute Node path (see docs/runbooks.md).

Development

Install dependencies:

npm ci

Build and test:

npm run test
npm run build

Run server (stdio):

npm run dev

If your environment blocks IPC sockets used by tsx in dev mode, use the built runtime instead:

npm run build
npm run start

Run server (HTTP Streamable transport):

MCP_TRANSPORT=http npm run dev:http

MCP Inspector

To interactively test tools/list and tools/call via the official inspector UI:

make inspector

Project Layout

src/
  auth/
  aroflo/
  mcp/
  utils/
tests/
docs/

Environment

Required variables:

• AROFLO_SECRET_KEY
• AROFLO_UENCODED
• AROFLO_PENCODED
• AROFLO_ORG_ENCODED

Optional variables:

• AROFLO_API_BASE_URL (default: https://api.aroflo.com/)
• AROFLO_ACCEPT (default: text/json)
• AROFLO_HOST_IP
• AROFLO_TIMEOUT_MS (default: 65000)
• AROFLO_MAX_RETRIES (default: 2)
• LOG_LEVEL (default: info)

HTTP Transport

Set MCP_TRANSPORT=http to run an HTTP server (Streamable HTTP transport) at:

• http://${MCP_HTTP_HOST}:${MCP_HTTP_PORT}${MCP_HTTP_PATH}

Using Extracted API Docs (docs/api)

This repo includes a local snapshot of the AroFlo API docs in docs/api/.

The MCP server exposes these markdown files as MCP resources so the client/LLM can look up valid WHERE fields, JOIN areas, etc:

• aroflo://docs/api -> docs/api/README.md
• aroflo://docs/api/<slug> -> docs/api/<slug>.md (example: aroflo://docs/api/quotes)

Example query: list Quotes with acceptance status "Awaiting Decision":

• Tool: aroflo_get_quotes
• Args:

{
  "where": "and|acceptancestatus|=|Awaiting Decision",
  "page": 1,
  "pageSize": 50
}

Example report: open projects with labour hours per task (recommended for progress reporting):

• Tool: aroflo_report_open_projects_with_task_hours
• Args (add optional filters like sinceDateRequested to keep outputs small):

{
  "sinceCreatedUtc": "2025-01-01",
  "sinceDateRequested": "2025-01-01",
  "hoursOnly": true,
  "includeTaskStatus": true,
  "mode": "data"
}

Docs

• docs/aroflo-auth.md
• docs/mcp-tools.md
• docs/examples.md
• docs/runbooks.md
• docs/deployment.md
• docs/api/*