npm package: @hachiai/mcp-doculytix
Description: MCP Server for document Q&A using HachiAI LLM API — extract information from documents via prompts
Latest version: 1.0.3

# mcp-doculytix

MCP Server for document Q&A — extract information from documents using HachiAI's Doculytix API.

Upload a document (PDF, image, etc.) with a prompt and get structured answers back as JSON. Files larger than 1MB are automatically uploaded to the server first for efficient processing.

## Quick Start

### Via npx (recommended)

```bash
DOC_MCP_API_KEY=your-api-key npx @hachiai/mcp-doculytix
```

### Via local install

```bash
npm install
npm run build
node build/index.js
```

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `DOC_MCP_API_KEY` | Yes | — | Your HachiAI API key (JWT token from the Doculytix dashboard) |
| `DOC_MCP_BASE_URL` | No | `https://docx.hachiai.com` | API base URL |
| `DOC_MCP_POLL_INTERVAL_MS` | No | `3000` | Polling interval in ms |
| `DOC_MCP_MAX_POLL_ATTEMPTS` | No | `120` | Max polling attempts before timeout |

## MCP Client Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcp-doculytix": {
      "command": "npx",
      "args": ["-y", "@hachiai/mcp-doculytix"],
      "env": {
        "DOC_MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP config:

```json
{
  "mcpServers": {
    "mcp-doculytix": {
      "command": "npx",
      "args": ["-y", "@hachiai/mcp-doculytix"],
      "env": {
        "DOC_MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Local build

```json
{
  "mcpServers": {
    "mcp-doculytix": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-doculytix/build/index.js"],
      "env": {
        "DOC_MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Tools

### `document_qna`

Submit a document with a prompt and get the raw response from the backend. Does not poll — returns the `trace_id` immediately.

**Input:**
- `file_path` (string, required) — Absolute path to the document file
- `prompt` (string, required) — The question or extraction prompt

**Output:** Raw JSON response from the backend (includes `trace_id`).

### `check_trace_status`

Check the current status of a previously submitted document processing job.

**Input:**
- `trace_id` (string, required) — The trace ID from a previous submission

**Output:** Raw JSON response from the backend trace endpoint (includes `status`, `request_response`, `value`, etc.).

### `ask_document`

Ask a natural language question about a document and get a clean, meaningful answer. Submits the document, polls until processing is complete, and extracts only the relevant answer.

**Input:**
- `file_path` (string, required) — Absolute path to the document file
- `question` (string, required) — A natural language question about the document

**Output:** JSON with `success` and `answer` fields containing the extracted result.

## API Flow

1. **Upload** (files > 1MB) — `POST /api/proxy/upload` with file → returns `{ "file_path": "..." }`
2. **Submit** — `POST /api/proxy/qna-async` with file (or `file_path`) + query → returns `{ "trace_id": "..." }`
3. **Poll** — `GET /api/proxy/trace/{trace_id}` until status is `fulfilled` or `failed`

## Development

```bash
npm install
npm run build
npm test
npm run test:coverage
```

## License

MIT