npm package: @journai/base-mcp-server
Description: MCP Server for Journai Base — AI agents interact with your knowledge platform
Latest version: 1.0.0

# @journai/base-mcp-server

MCP Server for [Journai Base](https://base.journai.ch) — enables AI agents (Claude Code, Claude Desktop, Cursor) to interact with your knowledge platform.

## Quick Start

Add this to your `.mcp.json` (Claude Code) or MCP client config:

```json
{
  "mcpServers": {
    "journai": {
      "command": "npx",
      "args": ["-y", "@journai/base-mcp-server"],
      "env": {
        "JOURNAI_URL": "https://base.journai.ch",
        "JOURNAI_API_KEY": "jnai_your_api_key_here"
      }
    }
  }
}
```

For local development:

```json
{
  "mcpServers": {
    "journai": {
      "command": "npx",
      "args": ["-y", "@journai/base-mcp-server"],
      "env": {
        "JOURNAI_URL": "http://localhost:3000",
        "JOURNAI_API_KEY": "jnai_your_dev_api_key"
      }
    }
  }
}
```

### Prerequisites

1. A Journai Base account with API key access
2. Create an API key: Go to **Settings > API Keys** and create a key with the scopes you need
3. Node.js >= 18

## Available Tools

### Pages

| Tool | Description | Required Scope |
|------|-------------|----------------|
| `journai_search_pages` | Full-text search across all pages | `search:read` |
| `journai_get_page` | Get a page by ID with full markdown content | `pages:read` |
| `journai_create_page` | Create a new page in a space | `pages:write` |
| `journai_update_page` | Update page title or content (append/prepend/replace) | `pages:write` |
| `journai_list_pages` | List top-level pages in a space | `pages:read` |
| `journai_list_child_pages` | List child pages of a parent page | `pages:read` |
| `journai_duplicate_page` | Duplicate a page within the same space | `pages:write` |
| `journai_move_page` | Move a page (reorder or cross-space) | `pages:write` |
| `journai_copy_page_to_space` | Copy a page to a different space | `pages:write` |

### Spaces

| Tool | Description | Required Scope |
|------|-------------|----------------|
| `journai_get_space` | Get space details by ID | `spaces:read` |
| `journai_list_spaces` | List all spaces you have access to | `spaces:read` |
| `journai_create_space` | Create a new space | `spaces:write` |
| `journai_update_space` | Update space name or description | `spaces:write` |

### Comments

| Tool | Description | Required Scope |
|------|-------------|----------------|
| `journai_get_comments` | Get comments on a page | `comments:read` |
| `journai_create_comment` | Add a comment to a page (plain text) | `comments:write` |
| `journai_update_comment` | Update a comment (plain text) | `comments:write` |

### Search & Other

| Tool | Description | Required Scope |
|------|-------------|----------------|
| `journai_search_suggestions` | Autocomplete search for pages/users | `search:read` |
| `journai_search_attachments` | Search for file attachments | `pages:read` |
| `journai_list_workspace_members` | List workspace members | `workspace:read` |
| `journai_get_current_user` | Get current user and workspace info | `users:read` |

## Resources

| URI Pattern | Description |
|-------------|-------------|
| `page://{pageId}` | Read page content as markdown |
| `space://{spaceId}/pages` | List pages in a space |

## Configuration

| Environment Variable | Required | Description |
|---------------------|----------|-------------|
| `JOURNAI_URL` | Yes | Journai Base instance URL (e.g. `https://base.journai.ch` or `http://localhost:3000`) |
| `JOURNAI_API_KEY` | Yes | API key starting with `jnai_` — create in Settings > API Keys |

### API Key Scopes

Your API key determines what the MCP server can do. Available scopes:

- `pages:read` / `pages:write` — Read and modify pages
- `spaces:read` / `spaces:write` — Read and modify spaces
- `comments:read` / `comments:write` — Read and modify comments
- `search:read` — Search pages and attachments
- `users:read` — View user information
- `workspace:read` — View workspace members

A key with only `pages:read` will get a clear error message when trying to use write tools.

## Development

```bash
git clone https://github.com/journai-ch/journai-base-mcp-server.git
cd journai-base-mcp-server
pnpm install
pnpm dev          # Run with tsx (needs JOURNAI_URL and JOURNAI_API_KEY env vars)
pnpm test         # Run tests
pnpm build        # Build for production
pnpm typecheck    # TypeScript type checking
```

## License

MIT