# 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`):

```bash
make install
```

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

```bash
npm run build
node dist/mcp/server.js
```

### Install Into Codex (stdio)

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

```bash
cp .env.example .env
# edit .env
```

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

```bash
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:

```bash
codex mcp get aroflo
```

### Manual Codex Install (Alternative)

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

```bash
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:

```bash
npm ci
```

Build and test:

```bash
npm run test
npm run build
```

Run server (stdio):

```bash
npm run dev
```

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

```bash
npm run build
npm run start
```

Run server (HTTP Streamable transport):

```bash
MCP_TRANSPORT=http npm run dev:http
```

## MCP Inspector

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

```bash
make inspector
```

## Project Layout

```text
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:

```json
{
  "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):

```json
{
  "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/*`