# OpenFic MCP

[English](#english) · [中文](#中文) · [Tool catalog / 工具清单](#tool-catalog--工具清单)

OpenFic MCP is a standalone [Model Context Protocol](https://modelcontextprotocol.io/) server for OpenFic. It communicates only through OpenFic's public HTTP API. It does not read the database or import OpenFic backend code.

## English

### What you need

- A reachable OpenFic 0.9.2 backend. It may run locally, in Docker, on a server, or behind the OpenFic desktop application.
- Python 3.12+ and [uv](https://docs.astral.sh/uv/).
- Any MCP client that can launch a local command through `stdio`.

OpenFic and this MCP do not need to share a machine, folder, or container. The MCP only needs to reach the OpenFic HTTP address.

### Install

Clone or download this repository, then create a local configuration file:

```bash
git clone https://github.com/handsomer89/Openfic-MCP.git
cd Openfic-MCP
uv sync --extra dev
cp .env.example .env
```

On Windows PowerShell, use this copy command instead:

```powershell
Copy-Item .env.example .env
```

Edit `.env` to point to OpenFic.

| OpenFic location | Example configuration |
| --- | --- |
| Same computer, default port | `OPENFIC_BASE_URL=http://127.0.0.1:8000` |
| Another computer, Docker host, reverse proxy, or server | `OPENFIC_BASE_URL=http://openfic.example:8000` and `OPENFIC_ALLOW_NON_LOOPBACK=true` |

Keep `OPENFIC_API_PREFIX=/api/v1` unless your OpenFic deployment uses a different API prefix.

### Connect an MCP client

Use the following process configuration in your MCP client. Replace the directory with the absolute path to this repository; on Windows, use the absolute path to `uv.exe` when `uv` is not on `PATH`.

```json
{
  "command": "uv",
  "args": ["run", "--directory", "/absolute/path/to/Openfic-MCP", "openfic-mcp"]
}
```

This server uses `stdio`: the client starts it as a child process, sends MCP messages over standard input, and receives responses on standard output. Restart the client after changing `.env` or its MCP configuration. Vendor-specific examples are in [docs/client-config.md](docs/client-config.md).

Call `openfic_health` after connecting. A healthy OpenFic 0.9.2 backend is ready for the supported tools below.

### Permissions and deletion safety

The default configuration is read-only:

```dotenv
OPENFIC_MCP_READ_ONLY=true
OPENFIC_MCP_WRITE_SCOPES=
```

To enable only the write groups you need, change the file and restart the MCP client:

```dotenv
OPENFIC_MCP_READ_ONLY=false
OPENFIC_MCP_WRITE_SCOPES=chapters,characters,notes
```

Available groups are `projects`, `volumes`, `chapters`, `characters`, `notes`, and `worldbooks`. Write tools are registered only for selected groups.

`delete_chapter`, `delete_character`, `delete_note`, `delete_note_category`, and `delete_worldbook_entry` are irreversible. Each requires its write group and the explicit argument `confirm=true`. There are intentionally no project, volume, or whole-worldbook deletion tools.

### Read a project's worldbook without an ID

OpenFic's upstream project-worldbook lookup can create an empty worldbook when none exists. This MCP deliberately avoids that endpoint. To enable safe project-based worldbook reading, configure known relationships locally:

```dotenv
OPENFIC_PROJECT_WORLDBOOKS={"project-id":"world-info-id"}
```

Restart the client and use `read_project_worldbook(project_id)`. It returns the configured worldbook and entry bodies without creating anything.

### Docker and desktop apps

- **OpenFic in Docker:** set `OPENFIC_BASE_URL` to an address reachable from the MCP process. If both containers are on the same Docker network, use the OpenFic service name and port. If MCP runs on the host, use the Docker-published host address and port.
- **OpenFic desktop application:** point the MCP at the same backend URL used by the app. Some desktop applications choose a new local port at each launch; update `OPENFIC_BASE_URL` and restart the MCP client when that happens.
- **MCP in Docker:** [compose.mcp.yml](compose.mcp.yml) builds a `stdio` MCP container for an MCP-capable host to launch. It is not an unauthenticated public API service.

The optional HTTP MCP transport has no authentication. Do not expose it to a LAN or the internet; `stdio` is the recommended transport.

### Verify and troubleshoot

```bash
uv run ruff check .
uv run mypy src
uv run pytest
```

Windows users can also run `./scripts/check-openfic.ps1` to test the configured OpenFic endpoint.

| Problem | Fix |
| --- | --- |
| `openfic_health` cannot connect | Check that OpenFic is running and that `OPENFIC_BASE_URL`, port, and API prefix are correct. Set `OPENFIC_ALLOW_NON_LOOPBACK=true` only for a trusted non-local address. |
| Tools do not appear | Confirm the client starts this repository's `openfic-mcp` command, then restart the client. |
| Write tools do not appear | Set `OPENFIC_MCP_READ_ONLY=false`, add the required write group, and restart the client. |
| Deletion is rejected | Use the exact item ID and pass `confirm=true`. |
| Chapter update conflicts | Read the chapter again and pass its latest `updated_at` as `expected_updated_at`. |
| Project worldbook cannot be read | Add `OPENFIC_PROJECT_WORLDBOOKS` and restart the client. |

Never commit `.env`. It can contain private server addresses and local permission choices; commit `.env.example` instead.

## 中文

### 使用条件

- 可访问的 OpenFic 0.9.2 后端：可以在本机、Docker、服务器，或 OpenFic 桌面应用所使用的后端中运行。
- Python 3.12+ 与 [uv](https://docs.astral.sh/uv/)。
- 任意能通过 `stdio` 启动本地命令的 MCP 客户端。

OpenFic 与 MCP 不必在同一台设备、目录或容器中；MCP 只需要能访问 OpenFic 的 HTTP 地址。

### 安装与连接

克隆或下载本仓库后，安装依赖并创建本地配置：

```bash
git clone https://github.com/handsomer89/Openfic-MCP.git
cd Openfic-MCP
uv sync --extra dev
cp .env.example .env
```

Windows PowerShell 请改用：

```powershell
Copy-Item .env.example .env
```

编辑 `.env`。本机默认 OpenFic 使用：

```dotenv
OPENFIC_BASE_URL=http://127.0.0.1:8000
```

若 OpenFic 在另一台设备、Docker 宿主机、反向代理或服务器上，填写可访问的实际地址，并显式允许非本机地址：

```dotenv
OPENFIC_BASE_URL=http://openfic.example:8000
OPENFIC_ALLOW_NON_LOOPBACK=true
```

在你所用 MCP 客户端中配置以下进程。将目录改为本仓库的绝对路径；若系统找不到 `uv`，请将 `command` 改为 `uv` 或 `uv.exe` 的绝对路径。

```json
{
  "command": "uv",
  "args": ["run", "--directory", "/Openfic-MCP 的绝对路径", "openfic-mcp"]
}
```

本服务使用 `stdio`：客户端将它作为子进程启动。修改 `.env` 或客户端配置后，必须重启 MCP 客户端。不同客户端的配置示例见 [docs/client-config.md](docs/client-config.md)。连接后先调用 `openfic_health` 检查 OpenFic 状态与版本。

### 权限与删除保护

默认只读：

```dotenv
OPENFIC_MCP_READ_ONLY=true
OPENFIC_MCP_WRITE_SCOPES=
```

需要写入时，只开放实际需要的类别并重启客户端：

```dotenv
OPENFIC_MCP_READ_ONLY=false
OPENFIC_MCP_WRITE_SCOPES=chapters,characters,notes
```

可选类别：`projects`（项目）、`volumes`（卷）、`chapters`（章节）、`characters`（角色）、`notes`（笔记）、`worldbooks`（世界书）。只有已开放类别的写入工具会出现。

`delete_chapter`、`delete_character`、`delete_note`、`delete_note_category`、`delete_worldbook_entry` 都不可恢复；每次调用必须同时开放对应类别，并传入 `confirm=true`。本 MCP 没有项目、卷或整本世界书的删除工具。

### 让 AI 直接读取项目世界书

OpenFic 上游的“按项目获取世界书”接口可能在世界书不存在时创建空数据。本 MCP 不调用该接口。请在本地 `.env` 中登记已有映射：

```dotenv
OPENFIC_PROJECT_WORLDBOOKS={"项目ID":"world_info_id"}
```

重启客户端后使用 `read_project_worldbook(project_id)`；它会读取已配置世界书与条目正文，不会创建世界书。

### Docker 与桌面应用

- **Docker 中的 OpenFic：** `OPENFIC_BASE_URL` 填写 MCP 进程能够访问的地址。两个容器处于同一 Docker 网络时，可填写 OpenFic 服务名和端口；MCP 运行在宿主机时，填写 Docker 映射到宿主机的地址与端口。
- **OpenFic 桌面应用：** MCP 与桌面应用连接同一个后端即可编辑同一份数据。若桌面应用每次启动时动态分配本机端口，请同步更新 `OPENFIC_BASE_URL` 并重启 MCP 客户端。
- **Docker 中的 MCP：** [compose.mcp.yml](compose.mcp.yml) 构建的是由 MCP 宿主启动的 `stdio` 容器，不是需要对外暴露端口的无认证服务。

可选 HTTP MCP 传输没有认证，不应暴露到局域网或公网；推荐使用默认 `stdio`。

### 验证与排错

```bash
uv run ruff check .
uv run mypy src
uv run pytest
```

Windows 可额外运行 `./scripts/check-openfic.ps1` 检查当前 `.env` 指向的 OpenFic。

| 问题 | 处理方式 |
| --- | --- |
| `openfic_health` 无法连接 | 检查 OpenFic 是否运行、地址/端口/API 前缀是否正确；仅在可信的非本机地址上设为 `OPENFIC_ALLOW_NON_LOOPBACK=true`。 |
| 客户端没有工具 | 确认客户端启动的是本仓库的 `openfic-mcp`，然后重启客户端。 |
| 没有写入工具 | 设置 `OPENFIC_MCP_READ_ONLY=false`、加入所需类别，并重启客户端。 |
| 删除被拒绝 | 使用正确的条目 ID，并传入 `confirm=true`。 |
| 更新章节冲突 | 重新读取章节，并将最新 `updated_at` 作为 `expected_updated_at` 传入。 |
| 不能按项目读取世界书 | 设置 `OPENFIC_PROJECT_WORLDBOOKS` 后重启客户端。 |

请勿提交 `.env`；它可能包含私有服务器地址和本地权限选择。应提交 `.env.example` 作为配置模板。

## Tool catalog / 工具清单

| Area / 分类 | Tool / 工具名 | Purpose / 用途 |
| --- | --- | --- |
| System / 系统 | `openfic_health` | Check OpenFic status and version / 检查 OpenFic 状态与版本 |
| Projects / 项目 | `list_projects`, `get_project`, `get_project_summary` | List, inspect, and summarize projects / 列出、读取与汇总项目 |
| Projects / 项目 | `create_project`, `update_project` | Create and update projects / 创建与修改项目 |
| Volumes / 卷 | `list_volumes`, `get_volume` | List and inspect volumes / 列出与读取卷 |
| Volumes / 卷 | `create_volume`, `update_volume` | Create and update volumes / 创建与修改卷 |
| Chapters / 章节 | `list_chapters`, `get_chapter`, `search_chapters` | Read outline, body, and search text / 读取目录、正文与搜索 |
| Chapters / 章节 | `create_chapter`, `update_chapter`, `move_chapter` | Create, update, and move chapters / 创建、修改与移动章节 |
| Chapters / 章节 | `delete_chapter` | Delete one chapter; requires `confirm=true` / 删除单章；需 `confirm=true` |
| Summaries / 摘要 | `list_chapter_summaries`, `list_long_term_summaries` | Read chapter and interval summaries / 读取章节与区间摘要 |
| Characters / 角色 | `list_characters`, `get_character`, `search_characters` | List, inspect, and search characters / 列出、读取与搜索角色 |
| Characters / 角色 | `create_character`, `update_character`, `delete_character` | Create, update, delete one character; deletion requires `confirm=true` / 创建、修改、删除单个角色；删除需确认 |
| Notes / 笔记 | `list_notes`, `get_note`, `search_notes` | Read note tree, body, and search / 读取笔记树、正文与搜索 |
| Notes / 笔记 | `create_note`, `update_note`, `delete_note` | Create, update, delete one note; deletion requires `confirm=true` / 创建、修改、删除单条笔记；删除需确认 |
| Notes / 笔记 | `create_note_category`, `update_note_category`, `delete_note_category` | Create, rename, delete one category; deletion requires `confirm=true` / 创建、重命名、删除分类；删除需确认 |
| Worldbooks / 世界书 | `get_worldbook`, `read_project_worldbook` | Read by ID or configured project / 按 ID 或已配置项目读取 |
| Worldbooks / 世界书 | `list_worldbook_entries`, `get_worldbook_entry`, `search_worldbook_entries` | List, read, and search entries / 列表、读取与搜索条目 |
| Worldbooks / 世界书 | `create_worldbook_entry`, `update_worldbook_entry`, `delete_worldbook_entry` | Create, update, delete one entry; deletion requires `confirm=true` / 创建、修改、删除单个条目；删除需确认 |