npm package: @readables/mcp-server
Description: Model Context Protocol server for readables.ai integration
Author: readables.ai
Latest version: 1.0.11

# Readables MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to save content directly to your readables.ai library.

## Features

- **QR Code Authentication**: Secure authentication using your readables.ai mobile app
- **Content Saving**: Save text, markdown, HTML, and JSON content to your readables.ai library
- **Automatic Processing**: Content is automatically processed and made searchable in your library
- **Zero Configuration**: Works out of the box with any MCP-compatible AI assistant

## Installation

### Using npx (Recommended)

No installation required! Just add the server to your AI assistant's MCP configuration:

```json
{
  "mcpServers": {
    "readables": {
      "command": "npx",
      "args": ["@readables/mcp-server"]
    }
  }
}
```

### Global Installation

```bash
npm install -g @readables/mcp-server
```

Then configure your AI assistant:

```json
{
  "mcpServers": {
    "readables": {
      "command": "readables-mcp"
    }
  }
}
```

## Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "readables": {
      "command": "npx",
      "args": ["@readables/mcp-server"]
    }
  }
}
```

### Environment Variables

- `READABLES_API_KEY`: Optional. Pre-configured API key (skips QR authentication)

## Authentication

### First Time Setup

1. Start your AI assistant with the MCP server configured
2. Say: **"authenticate readables"** to begin authentication
3. The assistant will display a QR code image and session ID
4. Open the readables.ai mobile app and scan the QR code
5. Use the `complete_readables_auth` tool with the provided session ID
6. You can now save content to readables.ai!

### Using Pre-configured API Key

If you have an API key from readables.ai:

```bash
export READABLES_API_KEY="your-api-key-here"
```

Or add it to your shell profile for persistence.

## Usage

Once configured, you can use readables.ai:

### Authentication
- **"authenticate readables"** - Start the authentication process

### Saving Content
- "Save this conversation to readables"
- "Send this code to readables"
- "Store this article in my readables library"
- "Save this research to readables"

The server will automatically:
1. Check if you're authenticated (if not, prompt you to authenticate)
2. Save the content to your readables.ai account
3. Trigger processing for text extraction and analysis
4. Make the content searchable in your library

## Supported Content Types

- **Plain Text** (`text/plain`)
- **Markdown** (`text/markdown`)
- **HTML** (`text/html`)
- **JSON** (`application/json`)

## API

### Tools

#### `authenticate_readables`

Starts the authentication process with readables.ai. Use this when prompted to "authenticate readables".

**Parameters:** None

**Example:**
```typescript
await callTool('authenticate_readables', {});
```

#### `save_to_readables`

Saves content to your readables.ai library. If not authenticated, prompts you to authenticate first.

**Parameters:**
- `content` (required): The content to save
- `title` (optional): Title for the content
- `contentType` (optional): Content type (defaults to `text/plain`)

**Example:**
```typescript
await callTool('save_to_readables', {
  content: 'This is my important note',
  title: 'Important Note',
  contentType: 'text/markdown'
});
```

#### `complete_readables_auth`

Completes the authentication process after scanning the QR code with the readables.ai mobile app.

**Parameters:**
- `sessionId` (required): The session ID provided when the QR code was displayed

**Example:**
```typescript
await callTool('complete_readables_auth', {
  sessionId: 'uuid-session-id-from-qr-response'
});
```

## Troubleshooting

### QR Code Issues

- **QR code too large or not displaying properly**: This was completely fixed in version 1.0.5. QR codes are now displayed as properly sized images. Update to the latest version:
  ```bash
  npx @readables/mcp-server@latest
  ```

- **Error: "qrcode.generate is not a function"**: This was fixed in version 1.0.1+. Make sure you're using the latest version.

- **MCP Protocol Errors / JSON parsing issues**: This was completely fixed in version 1.0.3+. The authentication now works through proper MCP tool responses.

### Authentication Issues

- **QR code not displaying**: Make sure you're using version 1.0.5+ where QR codes are shown as images in the assistant's response
- **QR code not scannable**: The new image-based QR codes (v1.0.5+) are properly sized and easily scannable
- **Authentication not completing**: Use the `complete_readables_auth` tool with the session ID after scanning the QR code

### Authentication Issues

- Ensure you have the readables.ai mobile app installed
- Check that your device has internet connectivity
- Try regenerating the QR code by restarting the authentication flow

### Connection Issues

- Verify the API URL is correct
- Check your internet connection
- Ensure your API key hasn't expired

### Permission Issues

- Make sure you have permission to install npm packages globally (if using global install)
- Try using `npx` instead of global installation

## Development

### Building from Source

```bash
git clone <repository-url>
cd mcp-server
npm install
npm run build
npm start
```

### Publishing to npm

1. **Build the package:**
   ```bash
   cd mcp-server
   npm install
   npm run build
   ```

2. **Test the build:**
   ```bash
   node dist/index.js --help
   ```

   Run the build locally in MCP inspector:
   ```bash
   npx @modelcontextprotocol/inspector node dist/index.js
   ```

3. **Publish to npm:**

   For scoped packages (recommended):
   ```bash
   npm publish --access public
   ```

## License

MIT

## Support

For support, please visit [readables.ai](https://readables.ai) or contact support@readables.ai.