# OpenWebUI MCP Server

A Model Context Protocol (MCP) server for managing projects, notes, and knowledge bases in [OpenWebUI](https://github.com/open-webui/open-webui).

## Overview

`open-webui-mcp` provides a bridge between LLMs and your OpenWebUI workspace. It allows models to:
- List and manage projects.
- Create and update project-specific notes.
- Associate knowledge bases with projects.
- Propose and apply updates to project configurations based on chat history.
- Upload files directly to knowledge bases.

## Prerequisites

- [Bun](https://bun.sh/) (v1.0+)
- [OpenWebUI](https://github.com/open-webui/open-webui) instance
- [OpenRouter](https://openrouter.ai/) API key

## Quick Start

1. Clone and install:
   ```bash
   git clone https://github.com/your-repo/open-webui-mcp.git
   cd open-webui-mcp
   bun install
   ```

2. Configure environment variables:
   ```bash
   export OPENWEBUI_BASE_URL="http://localhost:3000"
   export OPENWEBUI_API_KEY="your-api-key"
   export OPENROUTER_API_KEY="your-openrouter-key"
   ```

3. Build and run:
   ```bash
   bun run build
   bun run start
   ```

## Project Mapping

The server uses a `projects.json` file to map project IDs to OpenWebUI folders and resources. This allows for a structured way to manage project-specific context.

### Example `projects.json`
```json
{
  "version": "1.0",
  "projects": [
    {
      "id": "project-1",
      "name": "My Project",
      "folder_id": "folder-uuid",
      "note_ids": [],
      "knowledge_base_ids": []
    }
  ]
}
```

## Safety Model (Propose/Evaluate/Apply)

To ensure safe updates to project configurations, the server implements a three-step workflow:

1. **Propose**: The model analyzes a conversation and generates a `ProposedChangeSet`.
2. **Evaluate**: An LLM (via OpenRouter) evaluates the proposal for safety and relevance, assigning a score (0-1).
3. **Apply**: If the proposal is deemed safe (score > threshold), it can be applied to the project.

## Documentation

- [Setup Guide](docs/SETUP.md)
- [Tool Reference](docs/TOOLS.md)

## Troubleshooting

- **Connection Errors**: Ensure `OPENWEBUI_BASE_URL` is accessible and the API key is correct.
- **Permission Denied**: Check if your OpenWebUI API key has sufficient permissions to manage folders, notes, and knowledge bases.
- **Evaluation Failures**: Ensure your `OPENROUTER_API_KEY` is valid and has credits.
- **Missing Projects**: Verify that `projects.json` exists in your `DATA_DIR` and is valid JSON.