Metadata-Version: 2.4
Name: docmost-mcp
Version: 1.0.1
Summary: A Model Context Protocol (MCP) server for Docmost — the open-source collaborative wiki.
Project-URL: Homepage, https://github.com/Dev789/docmost-mcp-server
Project-URL: Documentation, https://github.com/Dev789/docmost-mcp-server#readme
Project-URL: Repository, https://github.com/Dev789/docmost-mcp-server
Project-URL: Issues, https://github.com/Dev789/docmost-mcp-server/issues
Author: Dev Joshi
License: MIT
License-File: LICENSE
Keywords: ai,docmost,documentation,mcp,wiki
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic-settings>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 📚 Docmost MCP Server

A **Model Context Protocol (MCP)** server that connects any LLM client to your [Docmost](https://docmost.com) wiki. Search, read, create, update, and delete documentation pages — all through natural language.

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/docmost-mcp.svg)](https://pypi.org/project/docmost-mcp/)

---

## ✨ Features

| Tool | Description |
|---|---|
| `search_docmost` | Full-text search across all pages |
| `get_page` | Read page content (Markdown / HTML / JSON) |
| `create_page` | Create a new page with optional content |
| `update_page` | Update title/content (replace, append, prepend) |
| `delete_page` | Soft-delete or permanently remove a page |
| `list_spaces` | List all accessible spaces |
| `get_space_info` | Get space details and permissions |
| `list_space_pages` | Browse the page hierarchy in a space |
| `import_page` | Import Markdown as a new page |

---

## 🚀 Quick Start

### 1. Install

```bash
pip install docmost-mcp
```

### 2. Configure

Create a `.env` file (or set environment variables):

**Community Edition** (email/password login):
```env
DOCMOST_BASE_URL=https://docmost.example.com
DOCMOST_EMAIL=your@email.com
DOCMOST_PASSWORD=your-password
```

**Enterprise / Business Edition** (API token):
```env
DOCMOST_BASE_URL=https://docmost.example.com
DOCMOST_API_TOKEN=dk_live_xxxxxxxxxxxxx
```

### 3. Run

```bash
docmost-mcp
```

Or as a Python module:

```bash
python -m docmost_mcp
```

---

## 🔌 Integration with MCP Clients

### Claude Desktop / Cursor / Windsurf

Add this to your MCP client configuration:

```json
{
  "mcpServers": {
    "docmost": {
      "command": "docmost-mcp",
      "env": {
        "DOCMOST_BASE_URL": "https://docmost.example.com",
        "DOCMOST_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

> **Tip:** If you installed with `pip`, use the full path to the `docmost-mcp` executable. Find it with: `which docmost-mcp` (macOS/Linux) or `where docmost-mcp` (Windows).

---

## 🏗️ Architecture

```
src/docmost_mcp/
├── __init__.py         # Package metadata and version
├── __main__.py         # CLI entry point
├── config.py           # Environment validation (Pydantic BaseSettings)
├── exceptions.py       # Custom exception hierarchy
├── client.py           # Async Docmost API client (httpx)
└── server.py           # MCP tool definitions (FastMCP)
```

### Design Principles

1. **Fail Fast** — Configuration is validated at startup. Missing env vars crash immediately with a clear error, not mid-request.
2. **One Client, Many Tools** — A single `DocmostClient` with connection pooling handles all API calls. No per-request client creation.
3. **Typed Exceptions** — Every failure mode has its own exception class (`DocmostAuthError`, `DocmostNotFoundError`, etc.) for precise error messages.
4. **LLM-Friendly Errors** — MCP tools catch exceptions and return descriptive strings, never raw tracebacks.
5. **Dual Auth** — Supports both API token (Enterprise) and email/password login (Community) with automatic session refresh.

---

## 🔐 Authentication

### Community Edition

Uses `POST /api/auth/login` to obtain a session cookie. The server automatically re-authenticates on 401 (session expired).

Required env vars: `DOCMOST_BASE_URL`, `DOCMOST_EMAIL`, `DOCMOST_PASSWORD`

### Enterprise / Business Edition

Uses `Authorization: Bearer <token>` header. Generate an API token from your Docmost admin panel.

Required env vars: `DOCMOST_BASE_URL`, `DOCMOST_API_TOKEN`

> If **both** are configured, the API token takes precedence (no login round-trip needed).

---

## 🛠️ Development

```bash
# Clone the repo
git clone https://github.com/Dev789/docmost-mcp-server.git
cd docmost-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install in editable mode
pip install -e .

# Run
docmost-mcp
```

---

## 📄 License

[MIT](LICENSE) — free to use, modify, and distribute.
