Skip to main content
Glama
README.md
# extractdesk

Your Dokyumi organisation's document extraction, from your own machine. extractdesk is a local forwarding client for the hosted Dokyumi MCP service: it answers `tools/list` locally from the captured tool definitions and forwards every call to Dokyumi, returning the results exactly as the service sends them back.

The surface is your connected organisation's own workspace: its profile, its saved extraction schemas, ready-made workflow starters, a preflight check for processing access and document limits, the saved extraction history with its review queue, CSV/XLSX export of selected results, and extraction of an attached document against a saved schema. Nothing is cached, stored or computed locally — the package is a pipe, not an extractor.

## The tools

- **`dokyumi_account`** — Return the profile represented by the connected Dokyumi credentials, with a stable opaque ID and account label. No parameters.
- **`dokyumi_list_schemas`** — List the active extraction schemas saved in your connected organisation. Use it before extracting a document to choose a schema. No parameters; it does not create schemas.
- **`dokyumi_get_extraction`** — Retrieve one saved extraction by `extraction_id`, including extracted fields, confidence and validation errors.
- **`dokyumi_list_starters`** — Find and preview ready-made document schemas by `query` or `category`, paged with `limit`/`offset`. Includes fields, review checks and explicitly synthetic examples. No upload or credit use.
- **`dokyumi_save_starter`** — After the user agrees to save a previewed starter, create its schema within the plan limit or reuse the same slug without overwriting saved fields. Requires `workflow_slug` and `confirm_create`.
- **`dokyumi_preflight_extraction`** — Read current processing access, page and schema limits, and optionally check a saved schema via `schema_slug`. It does not upload, reserve credits, or start extraction.
- **`dokyumi_list_extractions`** — Find owner-scoped extraction history by filename, schema, status, or review-needed/failed results. Does not retry work or spend credits.
- **`dokyumi_export_extractions`** — Get a browser-authenticated CSV or XLSX download for 1–50 selected completed or review-needed results (`extraction_ids`, `format`).
- **`dokyumi_extract_document`** — Extract an authorized attached PDF or image using a saved schema (`schema_slug`, plus a reusable `request_key` for retries). Supply exactly one of `file` or `file_inline`; for subscription workspaces the user's agreement to use existing credits is required before `use_existing_credits` is set, and BYOK workspaces confirm separate provider charges instead.

## Install and run

As an MCP server via npm:

```bash
npx -y @reneturcios/extractdesk mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "extractdesk": {
      "command": "npx",
      "args": ["-y", "@reneturcios/extractdesk", "mcp"]
    }
  }
}
```

As a container:

```bash
docker run -i ghcr.io/cloudcorprecords/extractdesk
docker run --rm ghcr.io/cloudcorprecords/extractdesk dokyumi_list_schemas '{}'
```

## CLI

One binary serves both the command line and the MCP server. Each tool is a subcommand taking a single JSON string with that tool's arguments:

```bash
extractdesk dokyumi_account '{}'
extractdesk dokyumi_list_starters '{"category":"Finance","limit":5}'
extractdesk dokyumi_get_extraction '{"extraction_id":"00000000-0000-0000-0000-000000000000"}'
extractdesk --version
```

Exit codes: `0` when the forwarded call succeeds, `1` when the upstream result is an error, and `2` for usage problems such as an unknown subcommand or a malformed JSON argument.

## Configuration

- `DOKYUMI_MCP_URL` — Overrides the upstream endpoint. The default is the pinned hosted endpoint, `https://dokyumi.com/mcp`. (The override variable is a reconstruction added by this rebuild.)

The upstream's registry record declares no headers, so extractdesk never sends an authentication header — the tool surface was captured keyless and every request goes out with only the JSON-RPC content headers (plus the session header once the upstream issues one).

Upstream failures — a JSON-RPC error from the service, a non-2xx response, an unreadable body, or a request that fails outright — are reported to the caller as an error result whose text starts with `extractdesk error:`.

## How forwarding works

The first forwarded call opens a session: an `initialize` request (protocol version `2025-03-26`), followed by a `notifications/initialized` notification, then the `tools/call` itself. If the service answers the initialize request with an `Mcp-Session-Id` header, that value is carried on every later request, and the open session is reused for the rest of the process. Replies are accepted either as plain JSON or as server-sent events. Successful results pass through verbatim, including any `isError` flag and any extra fields the service includes.

## Development

```bash
npm install
npm run build   # tsc -> dist/ (dist/cli.js is the bin)
npm test        # tsx --test test/*.test.ts — stubbed upstream, no network
npm run dev     # run the CLI from source
```

The test suite checks the served tool list against the captured surface, exercises the session handshake and its reuse, asserts that no `Authorization` header is ever sent under any environment, and verifies that arguments go upstream untouched and results come back untouched.

## License

MIT — see `LICENSE`. Copyright (c) 2026 Rene Turcios.