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.

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.

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

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。
• 任意能通过 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。

问题	处理方式
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 / 创建、修改、删除单个条目；删除需确认