# @accos/mcp-server

ACCOS MCP server — Thai accounting OCR via Model Context Protocol.

Connects Claude Desktop, Cursor, Claude Code, n8n, or any MCP-compatible AI
agent to ACCOS so the agent can read Thai receipts, tax invoices, and
withholding tax certificates without you writing glue code.

## Quick start

### 1. Get an API key + secret

Generate a key pair at [accos.app/settings/api-keys](https://accos.app/settings/api-keys).
Both the key (`ak_live_…`) and the secret (`sk_live_…`) are required —
every tool call is HMAC-signed.

### 2. Add to your MCP client

**Claude Desktop** — edit `claude_desktop_config.json`:

```jsonc
{
  "mcpServers": {
    "accos": {
      "command": "npx",
      "args": ["-y", "@accos/mcp-server"],
      "env": {
        "ACCOS_API_KEY": "ak_live_xxx",
        "ACCOS_API_SECRET": "sk_live_xxx"
      }
    }
  }
}
```

**Cursor** — edit `~/.cursor/mcp.json` (same shape).

**Claude Code** — `claude mcp add accos -- npx -y @accos/mcp-server`,
then set the two env vars in your shell.

Restart your agent — ACCOS tools appear in the tool list.

## Tools

| Tool | Cost | Purpose |
|---|---|---|
| `inspect_file` | free | Pre-flight: page count, MIME, advice |
| `read_document` | 1 token | Extract data from a single-page receipt/invoice |
| `verify_tax_id` | 1 token | Validate a 13-digit Thai tax ID against the RD/DBD registry |
| `lookup_master` | 1 token | Search master data (vendors/customers/products) |
| `list_my_templates` | free | List custom templates accessible to this key |
| `estimate_cost` | free | Dry-run the cost of a planned tool call |
| `get_balance` | free | Current token balance + active batches |
| `list_tasks` | free | List open Task Tracker tasks you can see |
| `my_tasks` | free | Open tasks assigned to you |
| `get_task` | free | One task in full (checklist, comments, activity) |
| `set_task_status` | free | Move a task to todo / in_progress / review |

### Task Tracker tools

`list_tasks`, `my_tasks`, and `get_task` read the ACCOS **Task Tracker**
module. They require:

- the API key scope `tasks:read` (tick *"Grant read access to the Task
  Tracker module"* when creating the key), and
- the Task Tracker module enabled on the account.

`set_task_status` additionally requires the scope `tasks:write` and editor
access to the task's project. It can only move a task between `todo`,
`in_progress`, and `review` — closing or cancelling a task stays a human
action in the web app.

Visibility follows **project membership** — you only ever see tasks in
projects you own, are a member of, or that are public. This is enforced
server-side, not by company. Tasks are referenced as `KEY-N`
(e.g. `ACCOS-12`); pass that `ref` to `get_task` for full detail.

## Strict 1-page contract

`read_document` accepts EXACTLY ONE page per call. Multi-page PDFs are
rejected — split them locally first:

```python
# pypdf example
from pypdf import PdfReader, PdfWriter
for i, page in enumerate(PdfReader("input.pdf").pages):
    w = PdfWriter()
    w.add_page(page)
    w.write(f"page_{i}.pdf")
```

```js
// pdf-lib example
import { PDFDocument } from "pdf-lib";
const src = await PDFDocument.load(await fs.readFile("input.pdf"));
for (let i = 0; i < src.getPageCount(); i++) {
  const out = await PDFDocument.create();
  const [pg] = await out.copyPages(src, [i]);
  out.addPage(pg);
  await fs.writeFile(`page_${i}.pdf`, await out.save());
}
```

Then call `read_document` once per page (parallel is fine, max 10 concurrent).

## Destination is mandatory

Every `read_document` call MUST declare where the data is going:

- `ar` — sales invoices your company **issued**
- `ap` — purchase invoices your company **received**
- `wht` — withholding tax certificates (50 ทวิ)
- `custom` — anything else; also pass `template_share_code`

ACCOS never infers this from content. Ask the user if unclear.

## Configuration reference

| env var | required | default |
|---|---|---|
| `ACCOS_API_KEY` | yes | — |
| `ACCOS_API_SECRET` | yes | — |
| `ACCOS_BASE_URL` | no | `https://accos.app` (must be `https://` unless localhost) |
| `ACCOS_TIMEOUT_MS` | no | `60000` |

## License

Apache-2.0