OpenFic MCP

English · 中文 · Tool catalog / 工具清单

OpenFic MCP is a standalone Model Context Protocol 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.

• 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:

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:

Copy-Item .env.example .env

Edit .env to point to OpenFic.

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.

{
  "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.

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:

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:

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:

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 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

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.

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

Related MCP server: OpenProject CE MCP

中文

使用条件

• 可访问的 OpenFic 0.9.2 后端：可以在本机、Docker、服务器，或 OpenFic 桌面应用所使用的后端中运行。

• Python 3.12+ 与 uv。

• 任意能通过 stdio 启动本地命令的 MCP 客户端。

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

安装与连接

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

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

Windows PowerShell 请改用：

Copy-Item .env.example .env

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

OPENFIC_BASE_URL=http://127.0.0.1:8000

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

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

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

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

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

权限与删除保护

默认只读：

OPENFIC_MCP_READ_ONLY=true
OPENFIC_MCP_WRITE_SCOPES=

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

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 中登记已有映射：

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 构建的是由 MCP 宿主启动的 stdio 容器，不是需要对外暴露端口的无认证服务。

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

验证与排错

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

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

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

Tool catalog / 工具清单