# molt-mcp

A Model Context Protocol (MCP) server that provides LLM access to [molt-md](https://molt-md.com), an encrypted markdown document hosting service. **Turn your markdown files into an LLM-accessible knowledge base** by uploading them to molt-md and accessing them through this MCP server. Your AI assistant can read, update, and manage encrypted markdown documents organized in workspaces.

## Features

- **Markdown → MCP Server** - Organize your markdown files into LLM-accessible storage with workspaces (free while in beta)
- **Full API Coverage** - Every molt-md endpoint exposed as an MCP tool
- **Encrypted Storage** - End-to-end encryption with AES-256-GCM
- **Read/Write Key Support** - Permission enforcement via the API's dual-key model
- **Workspace Management** - Bundle and organize multiple documents
- **Partial Fetches** - Efficient document previews with line-limited reads
- **Version Control** - Optimistic concurrency control with ETag support

## Installation

Install directly from GitHub using `uvx`:

```bash
uvx --from git+https://github.com/bndkts/molt-md-mcp molt-mcp
```

Or install from source for development:

```bash
git clone https://github.com/bndkts/molt-md-mcp.git
cd molt-md-mcp
uv pip install -e .
```

## Configuration

### Claude Desktop

Add to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "molt-md": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/bndkts/molt-md-mcp", "molt-mcp"],
      "env": {
        "MOLT_API_KEY": "your-api-key-here",
        "MOLT_WORKSPACE_ID": "your-workspace-id-here"
      }
    }
  }
}
```

### Environment Variables

- **`MOLT_API_KEY`** (required) - Your molt-md write key or read key (obtained by creating a document)
- **`MOLT_WORKSPACE_ID`** (optional) - Access documents through a specific workspace
- **`MOLT_BASE_URL`** (optional) - API base URL (defaults to `https://api.molt-md.com/api/v1`; use `http://localhost:8000/api/v1` for local development)

### Permission Model

The server passes your configured key to the molt-md API on every request:

- **Write key** → All operations succeed (read + create + update + delete)
- **Read key** → Read operations succeed; write operations return `403 Forbidden` from the API

## Available Tools

### Read-Only Tools (Available with both key types)

- **`health_check`** - Check if the molt-md API is available
- **`get_metrics`** - Get database statistics (document and workspace counts)
- **`read_doc`** - Read a document's decrypted content
  - Supports partial fetches with `lines` parameter
  - Returns JSON with metadata or plain markdown
- **`read_workspace`** - Read a workspace's content (name and entries)
  - Supports preview generation with `preview_lines` parameter

### Write Tools (Require write key)

#### Document Operations
- **`create_doc`** - Create a new encrypted document
  - Returns document ID, write key, and read key
- **`update_doc`** - Replace a document's entire content
  - Supports optimistic locking with `if_match` (version ETag)
- **`append_doc`** - Append content to the end of a document
  - Supports optimistic locking with `if_match`
- **`delete_doc`** - Permanently delete a document

#### Workspace Operations
- **`create_workspace`** - Create a new workspace to bundle documents
  - Returns workspace ID, write key, and read key
- **`update_workspace`** - Replace a workspace's content (name and entries)
  - Supports optimistic locking with `if_match`
- **`delete_workspace`** - Permanently delete a workspace
  - Does not delete referenced documents

## Usage Examples

### Basic Document Operations

```
User: Create a new document with the title "Meeting Notes"
Assistant: [Uses create_doc tool] → Returns doc ID and keys

User: Read that document
Assistant: [Uses read_doc tool with the doc ID]

User: Append a new section to the document
Assistant: [Uses append_doc tool]
```

### Workspace Management

```
User: Create a workspace called "Project Alpha" with these two documents
Assistant: [Uses create_workspace tool with document IDs and keys]

User: Show me a preview of all documents in the workspace
Assistant: [Uses read_workspace with preview_lines=1]
```

### Partial Fetches for Efficiency

```
User: Show me just the title of document xyz
Assistant: [Uses read_doc with lines=1 and as_markdown=true]
```

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/bndkts/molt-md-mcp.git
cd molt-md-mcp

# Install dependencies
uv pip install -e .

# Run the server
molt-mcp
```

### Testing

**With local molt-md API:**

```bash
# Start the molt-md API server first (in another terminal)
cd /path/to/molt-md
cargo run  # or your preferred method

# Create a test document to get keys
curl -X POST http://localhost:8000/api/v1/docs \
  -H "Content-Type: application/json" \
  -d '{"content": "# Test Document"}'
# Save the write_key and id from the response

# Run the MCP server
export MOLT_BASE_URL="http://localhost:8000/api/v1"
export MOLT_API_KEY="your-write-key-here"
npx @modelcontextprotocol/inspector molt-mcp
```

**With production molt-md API:**

```bash
# Create a test document to get keys
curl -X POST https://api.molt-md.com/api/v1/docs \
  -H "Content-Type: application/json" \
  -d '{"content": "# Test Document"}'
# Save the write_key from the response

# Run the MCP server
export MOLT_API_KEY="your-write-key-here"
npx @modelcontextprotocol/inspector molt-mcp
```

## Security Notes

- **Never commit API keys to version control**
- **Keys are shown only once** during document/workspace creation - save them securely
- **Read keys** can be safely shared for read-only collaborators
- **Write keys** provide full access - share only with trusted editors
- **Lost keys** cannot be recovered - the content becomes permanently inaccessible

## Architecture

This is a thin wrapper around the molt-md REST API:

1. **FastMCP** handles the MCP protocol and tool registration
2. **httpx** makes async HTTP requests with connection pooling
3. **Environment config** provides API key and optional workspace context
4. **UUID validation** and **ETag formatting** ensure correct API usage

## Links

- **molt-md**: [https://molt-md.com](https://molt-md.com)
- **MCP Specification**: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)
- **FastMCP**: [https://github.com/jlowin/fastmcp](https://github.com/jlowin/fastmcp)

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

---

Built with ❤️ for the Model Context Protocol ecosystem