npm package: @mauro.pelizzari-doki/doki-mcp-client
Description: MCP Server for Doki - Document Intelligence Platform. Integrates Claude Desktop/Code with Doki for document management.
Author: Doki Team
Latest version: 1.0.2

# Doki MCP Server

MCP (Model Context Protocol) server for integrating Claude Desktop/Code with Doki.

**Version 2.0** - Now uses JSON-RPC transport for full MCP protocol compliance.

[![npm version](https://img.shields.io/npm/v/@mauro.pelizzari-doki/doki-mcp-client.svg)](https://www.npmjs.com/package/@mauro.pelizzari-doki/doki-mcp-client)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **67+ tools** dynamically loaded from the Doki server
- **JSON-RPC transport** via `/mcp` endpoint
- **OAuth 2.0** authentication with PKCE (recommended)
- **PAT** authentication for API access
- **Auto token refresh** for seamless experience

## Installation

### From npm (Recommended)

```bash
npm install -g @mauro.pelizzari-doki/doki-mcp-client
```

### From source

```bash
git clone https://github.com/doki-app/doki.git
cd doki/mcp-client
npm install
```

## Setup

### Configure Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

#### Option A: OAuth Authentication (Recommended)

**Using npx (no global install needed):**

```json
{
  "mcpServers": {
    "doki": {
      "command": "npx",
      "args": ["-y", "@mauro.pelizzari-doki/doki-mcp-client"],
      "env": {
        "DOKI_URL": "https://doki-app.duckdns.org"
      }
    }
  }
}
```

**Using global install:**

```json
{
  "mcpServers": {
    "doki": {
      "command": "doki-mcp",
      "env": {
        "DOKI_URL": "https://doki-app.duckdns.org"
      }
    }
  }
}
```

**Using local source:**

```json
{
  "mcpServers": {
    "doki": {
      "command": "node",
      "args": ["/FULL/PATH/TO/doki/mcp-client/src/index.js"],
      "env": {
        "DOKI_URL": "https://doki-app.duckdns.org"
      }
    }
  }
}
```

When you first use a Doki tool, a browser window will open for Keycloak login. After authentication, the tokens are saved locally and refreshed automatically.

#### Option B: PAT Authentication

1. Create a PAT in Doki (Settings > API Tokens)
2. Configure Claude Desktop:

```json
{
  "mcpServers": {
    "doki": {
      "command": "npx",
      "args": ["-y", "@mauro.pelizzari-doki/doki-mcp-client"],
      "env": {
        "DOKI_URL": "https://doki-app.duckdns.org",
        "DOKI_API_TOKEN": "doki_pat_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

### Configure Claude Code

Add to your Claude Code MCP settings (`~/.claude/claude_code_mcp_settings.json`):

```json
{
  "mcpServers": {
    "doki": {
      "command": "npx",
      "args": ["-y", "@mauro.pelizzari-doki/doki-mcp-client"],
      "env": {
        "DOKI_URL": "https://doki-app.duckdns.org"
      }
    }
  }
}
```

Or with PAT authentication:

```json
{
  "mcpServers": {
    "doki": {
      "command": "npx",
      "args": ["-y", "@mauro.pelizzari-doki/doki-mcp-client"],
      "env": {
        "DOKI_URL": "https://doki-app.duckdns.org",
        "DOKI_API_TOKEN": "doki_pat_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

### Restart Claude

Close and reopen Claude Desktop/Code after configuration changes.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│  Claude Desktop / Claude Code                               │
└────────────────────────┬────────────────────────────────────┘
                         │ stdio (MCP SDK)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  doki-mcp-client (this package)                             │
│  - Proxies tool calls to Doki                               │
│  - Handles OAuth/PAT authentication                         │
│  - Dynamically fetches available tools                      │
└────────────────────────┬────────────────────────────────────┘
                         │ JSON-RPC over HTTP
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  Doki Server (/mcp endpoint)                                │
│  - McpServer (JSON-RPC handler)                             │
│  - McpTools (67+ tool implementations)                      │
└─────────────────────────────────────────────────────────────┘
```

## How OAuth Works

1. When you first call a Doki tool (e.g., "list my Doki projects")
2. The MCP server starts a local callback server on port 9876
3. A browser opens with the Keycloak login page
4. After you authenticate, Keycloak redirects to `localhost:9876/callback`
5. The MCP server exchanges the code for tokens
6. Tokens are saved to `~/.doki-mcp/tokens.json`
7. Subsequent calls use the saved token (auto-refreshed when expired)

To re-authenticate, delete `~/.doki-mcp/tokens.json` and restart Claude.

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `DOKI_URL` | Doki server URL | `https://doki-app.duckdns.org` |
| `DOKI_API_TOKEN` | PAT token (enables PAT mode) | - |
| `AUTH_MODE` | Force auth mode: `oauth` or `pat` | Auto-detect |
| `OAUTH_CLIENT_ID` | Keycloak client ID | `doki-mcp` |
| `OAUTH_CALLBACK_PORT` | Local callback port | `9876` |

## Available Tools

Tools are dynamically loaded from the server. Currently available:

### Projects
- `list_projects` - List all projects in the organization
- `get_project` - Get project details
- `create_project` - Create a new project
- `update_project` - Update project details
- `delete_project` - Delete a project

### Artifacts
- `list_artifacts` - List artifacts in a project
- `get_artifact` - Get artifact with full content
- `create_artifact` - Create new artifact from template
- `update_artifact_content` - Update a section's content
- `update_artifact_name` - Update artifact name
- `update_artifact_status` - Change artifact status
- `delete_artifact` - Delete an artifact
- `export_artifact_docx` - Get DOCX download URL
- `list_available_sections` - List optional sections
- `add_artifact_section` - Add a section to artifact
- `remove_artifact_section` - Remove a section

### Paragraphs
- `list_paragraphs` - List paragraphs in an artifact
- `create_paragraph` - Create a new paragraph
- `update_paragraph` - Update paragraph content
- `reorder_paragraphs` - Reorder paragraphs
- `delete_paragraph` - Delete a paragraph

### Questions
- `list_artifact_questions` - List questions for an artifact
- `get_artifact_question` - Get question details
- `create_artifact_question` - Create a question
- `update_artifact_question` - Update/answer a question
- `delete_artifact_question` - Delete a question

### Tasks
- `list_artifact_tasks` - List tasks for an artifact
- `get_artifact_task` - Get task details
- `create_artifact_task` - Create a task
- `update_artifact_task` - Update a task
- `delete_artifact_task` - Delete a task

### Knowledge Sources
- `list_knowledge_sources` - List uploaded documents
- `get_knowledge_source` - Get document content
- `get_ingestion_status` - Check processing status
- `update_knowledge_source` - Update metadata
- `delete_knowledge_source` - Delete a source
- `retry_knowledge_processing` - Retry failed processing
- `download_knowledge_source` - Get download URL

### Templates
- `list_templates` - List available templates
- `get_template` - Get template with sections
- `create_template` - Create a new template
- `update_template` - Update template
- `delete_template` - Delete a template
- `list_template_sections` - (via get_template)
- `create_template_section` - Add a section
- `update_template_section` - Update a section
- `delete_template_section` - Delete a section
- `list_template_versions` - List version history
- `restore_template_version` - Restore a version

### Clients
- `list_clients` - List all clients
- `create_client` - Create a new client

### Project Members
- `list_project_members` - List project members
- `add_project_member` - Add a member
- `update_project_member` - Update member role
- `remove_project_member` - Remove a member

### Dashboard
- `get_my_tasks` - Get tasks assigned to you
- `get_recent_activities` - Get recent activities

### Activities
- `list_artifact_activities` - Get activity log

### Organization
- `get_organization` - Get organization info
- `get_organization_members` - List members

### Settings
- `get_llm_settings` - Get LLM configuration
- `update_llm_settings` - Update LLM settings
- `get_pdf_styles` - Get PDF export styles
- `update_pdf_styles` - Update PDF styles

### Utilities
- `list_doki_roles` - List available doki roles
- `list_template_icons` - List available icons
- `list_template_groups` - List template groups
- `create_template_group` - Create a group

## Troubleshooting

### OAuth flow doesn't start
- Check that port 9876 is not in use
- Try setting a different port: `OAUTH_CALLBACK_PORT=9999`

### "Authentication failed"
- Delete `~/.doki-mcp/tokens.json` and retry
- Check that `DOKI_URL` is correct and reachable

### Browser doesn't open
- Manually open the URL shown in stderr
- On Linux, ensure `xdg-open` is installed

### Tools not loading
- Check server logs for connection errors
- Verify the Doki server is running and accessible

## Testing

```bash
# Test with OAuth (will open browser)
DOKI_URL=https://doki-app.duckdns.org node src/index.js

# Test with PAT
DOKI_API_TOKEN=doki_pat_xxx node src/index.js
```

## Changelog

### v2.0.0
- Migrated from REST API to JSON-RPC transport
- Dynamic tool loading from server (no more hardcoded tools)
- Full MCP protocol compliance
- 67+ tools available

### v1.0.0
- Initial release with REST API backend
- 20 hardcoded tools