This server is the storyai MCP/REST core for querying and safely editing a novel's story graph, continuity state, and project data.
Read nodes and structure: use get, outline, refs, and trace to fetch nodes, navigate hierarchy, follow relationships, and find bounded paths.
Search the story database: find supports lexical, semantic, and hybrid search over titles, aliases, summaries, and rationale text, with optional tag/kind filters and time-based as_of queries.
Run continuity diagnostics: check runs deterministic SQL rules from spec/rules.json across a book or node scope and returns findings without calling an LLM.
Inspect schema and runtime ontology: graph_schema returns node kinds, edges, tags, and diagnostic rules so agents don't guess the model.
Explore plotlines: promises queries Foreshadow–Thread–Payoff status, debt, scene efficiency, and coherence approximations.
Build writing context: neighborhood creates token-budgeted context packets from an intent seed plus explicit anchors via 1-hop hard edges.
Predict change impact: impact simulates a field change and calculates affected nodes via reverse hard edges, read-only.
Propose safe edits: propose records non-empty read_set operations with idempotency keys; it never mutates the live graph directly.
Commit atomically: commit applies or dry-runs saved proposals in a single SQLite commit lane, with conflict detection and cascade proposals for re-derivation.
Ingest manuscripts: ingest validates chapter text, ID binding manifests, UTF-8 byte spans, and scene splits, then creates incremental Proposals only.
Run ad-hoc SQL: query executes read-only, row-limited, budgeted SELECT/WITH queries for custom analysis.
Multi-project support: through project tools and the README, the server can register, create, select, and list novel projects, isolating manuscript/bible/spec/story.db per project.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@storyai Which scenes does Han Do-young appear in?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Open this first →
docs/index.htmlOpening it in a browser links the seven documents to one another. To view everything in a single page, use
docs/storyai-설계-통합.html. If you're curious about the screens,docs/07-UI목업.html— it actually works.
Related MCP server: Novel Workspace MCP
docs/ 읽을 것. 설계 문서 7종 + 통합본
spec/ 구현이 읽을 것. 온톨로지·툴·규칙·DDL (JSON + SQL)
build/ 문서를 고칠 때. parts/ 수정 후 build.py 실행
skills/ 에이전트가 읽을 것. 집필·검수·설정집 3종
hooks/ 자동 검사 트리거. Claude Code / Codex 각각
AGENTS.md 에이전트 지침 단일 소스 ★ 양쪽 호스트가 읽음
manuscript/ api/ web/ ← 후속 단계에서 채웁니다
server/ bible/ store/ ← P0 조회 + P1 제안/커밋 구현Open docs/index.html in a browser. The seven documents reference one another.
Document | Contents | Audience |
Overall map, 8 key decisions, current status | Everyone | |
Problem·supporting numbers·market gap·usage scenarios | Planner | |
Data model·15 MCP tools·versioning·propagation | Developer | |
P0~P6 roadmap·task breakdown·risks | Developer | |
Rationale for choices and rejections·dependencies·references | Developer | |
11 diagrams | Everyone | |
Screen specs·components·design tokens | Designer·Developer | |
Actually working screens | Everyone |
The files that the documents describe and that the implementation reads directly.
spec/ontology.json 노드 18종 · 간선 28종 · 태그 · 삼중 시간축 · 가시성 · 불변식
spec/tools.json MCP 툴 15개 시그니처 · 예산 · 위험 등급 정책
spec/rules.json 진단 규칙 26개 (Tier 1 결정론 / Tier 2 LLM) · 전파 정책
spec/policy.json P1 변경 위험 등급 · 잠금 · 캐스케이드 임계값
spec/schema.sql DDL — 테이블 22 · 뷰 5 · 인덱스 18Applied immediately with sqlite3 store/story.db < spec/schema.sql.
Works as a single set on both Claude Code and Codex.
plugin.json agent-plugins 스키마 — Codex가 우선 인식
.claude-plugin/plugin.json Claude Code 매니페스트 — Codex도 폴백으로 읽음
.mcp.json Claude Code용 프로젝트 MCP 설정
.codex/config.toml Codex용 프로젝트 MCP 설정
AGENTS.md ★ 에이전트 지침 단일 소스. 양쪽이 읽음
CLAUDE.md AGENTS.md를 가리키는 한 줄
skills/ Agent Skills 규격 6필드만 — 양쪽 + 46개 호스트
hooks/ run-check.sh 를 양쪽 훅이 공통 호출The repository contains both .mcp.json for Claude Code and .codex/config.toml for Codex.
When you first open it, trust the project, approve MCP execution, and then verify the connection status.
claude mcp list
codex mcp listThe documents are build artifacts. To change the content, edit build/parts/*.part.html and:
python3 build/build.pyThe shared style lives in a single place, build/style.css, and is inlined into each document at build time —
which is why each document is self-contained and renders as-is wherever you host it.
The only dependency is the Python standard library.
P0 read-only index, P1 write path, P2 dual-line·diagnostics, and P3 extraction·search are
implemented. It provides 14 MCP tools, and every write goes through proposal logging and read_set conflict
adjudication before being applied atomically in a single SQLite commit lane. P3 enforces an explicit ID binding
manifest and UTF-8 byte spans, and combines BM25 with local sqlite-vec results via RRF.
Next up is P4 — UI. For the detailed breakdown, follow 개발계획서 §P4.
Create an isolated environment on Python 3.12 or later and install development dependencies.
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'The config file format follows bible/README.md. The loader reads only the
explicitly specified YAML metadata and does not guess or auto-extract content.
.venv/bin/python -m server.load_bible
.venv/bin/python -m server.consolidate
.venv/bin/python -m pytest
server/run-mcp.shManuscript extraction uses *.story.json files next to manuscript/**/*.md as input. The format and
LLM extraction contract live in prompts/v1/, and ingest only creates Proposals —
it does not auto-commit.
The last command is a stdio MCP server, so it waiting in the terminal is normal. Claude Code and
Codex both run the same server/run-mcp.sh entrypoint through their respective project settings.
propose does not mutate the live graph. Each op requires a unique idem_key of 8+ characters,
and read_set cannot be empty. For an ADD with no basis in existing nodes — like the initial Session —
the current graph_state.revision is passed as { "node": "book", "rev": n }.
Supported verbs are ADD · UPDATE · INVALIDATE · LINK · UNLINK. INVALIDATE and
UNLINK do not delete rows; they close tx_to. commit(mode="dry_run") performs the same
validation, CID, and Merkle calculations as the real thing, then rolls back the entire transaction.
story://session/latest points to the most recent Session node. The Session's props must
retain open_threads and next so the next host can pick up where it left off.
A Promise's props.status only advances in the order hypothetical → eligible → actualized,
and an intentional discard ends in prevented. eligible requires T, and actualized requires P.
promises(status=["eligible"]) returns F–T–P, debts, S-Eff, and delta-Coh approximations.
Fact visibility records viewer, learned_at, and pathway in visible_to. A Scene's
props.pre · post · forbid conditions take the form subject, field, op, value, and utterance facts
are recorded as props.claims=[{"speaker": "character/…", "fact": "fact/…"}]. Using this structure
lets check adjudicate perception timing, world rules, and fact conflicts reproducibly in SQL.
Cycles in causes, contains, and extends, plus a second focalizes edge per Scene, are
rejected at the proposal stage. The remaining diagnostics, including unreachable events, are
verified in the commit result and via check.
spec/rules.json의 P2 SQL 규칙으로 책 또는 노드 범위의 연속성을 진단합니다. LLM을 호출하지 않으며 노드와 근거를 함께 반환합니다.
Inputs: rules, scope, severity, max_chars, +1 more. Returns: result
저장된 제안을 단일 SQLite 커밋 레인에서 원자적으로 적용하거나 dry_run 합니다. 충돌하면 어떤 변경도 적용하지 않습니다.
Inputs: proposal_id (required), mode. Returns: object
제목·별칭·요약·근거 본문을 BM25, 로컬 sqlite-vec dense, 또는 두 순위의 RRF 결합으로 검색합니다. 외부 임베딩 API를 호출하지 않습니다.
Inputs: q (required), tag, kind, mode, +4 more.
주소로 노드를 읽습니다. brief는 한 줄 요약, full은 구조화 필드, body는 선택한 노드 하나의 근거 원문만 반환합니다.
Inputs: ref (required), as_of, include, max_chars, +1 more.
런타임 온톨로지의 노드 타입·간선·태그·진단 규칙을 반환합니다. 스키마를 추측하지 말고 이 도구로 확인하세요.
Inputs: section, max_chars, response_format.
가상의 필드 변경이 역방향 hard 간선을 따라 영향을 줄 노드와 관련 진단 규칙을 읽기 전용으로 미리 계산합니다.
Inputs: ref (required), change (required), max_depth. Returns: object
원고 전체와 명시적 ID binding manifest의 해시·UTF-8 byte span·Scene 분할을 검증하고 증분 변경 Proposal만 만듭니다. live 그래프는 commit 전까지 바뀌지 않습니다.
Inputs: chapter (required), mode. Returns: object
의도 검색 seed와 명시적 anchor에서 hard 간선 1-hop을 확장해 token budget 안의 집필 컨텍스트 패킷을 만듭니다.
Inputs: intent (required), as_of, anchors, budget_tokens. Returns: object
책 전체 또는 한 주소 아래의 구조를 본문 없이 반환합니다. 항상 넓은 탐색의 첫 단계로 사용하세요.
Inputs: kind, depth, scope, max_chars, +1 more.
복선의 F-T-P, 상태, 부채, S-Eff, delta-Coh 근사치를 조회합니다. 집필 전에 eligible 상태만 필터링할 수 있습니다.
Inputs: sort, as_of, status, max_chars, +1 more. Returns: result
비어 있지 않은 read_set과 멱등 키가 있는 연산을 변경 제안으로 기록합니다. 이 호출만으로 live 그래프는 바뀌지 않습니다.
Inputs: ops (required), read_set (required), rationale (required), session_id (required), +4 more. Returns: object
손으로 빚은 도구로 풀기 어려운 분석을 위해 단일 SELECT/WITH SQL을 읽기 전용, 행 제한, 실행 예산과 함께 수행합니다.
Inputs: sql (required), limit, params. Returns: object
한 노드를 가리키거나 그 노드가 가리키는 관계를 반환합니다. 산문 언급인 soft 간선은 요청할 때만 포함합니다.
Inputs: ref (required), dir, rel, as_of, +3 more.
한 노드에서 특정 대상 또는 서사 장치까지의 bounded hard-edge 경로를 반환합니다. 관계 종류와 깊이 및 경로 수를 제한할 수 있습니다.
Inputs: from (required), k, to, via, +1 more. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 14 tools
Each tool targets a clearly distinct operation: search (find), read (get, outline), graph navigation (refs, trace, neighborhood), diagnostics (check, impact), and staged writes (ingest, propose, commit). Minor overlap exists between ingest/propose (both create proposals) and check/impact (both diagnostic), but the descriptions draw clear boundaries.
Naming is mixed: most tools use imperative verbs (get, find, check, commit, propose, ingest, trace, query), but several are nouns or abbreviations (outline, promises, refs, neighborhood, graph_schema). The pattern is readable but inconsistent across verb and noun conventions.
14 tools is on the higher end but reasonable given the rich domain of narrative graph management, continuity diagnostics, foreshadowing, and staged write workflows. Each tool appears to earn its place, though the count leans toward the heavy side of the ideal range.
The surface covers the full lifecycle well: reading (get, outline), search (find, query), graph navigation (refs, trace, neighborhood), schema introspection (graph_schema), diagnostics (check, impact), and staged writes (ingest, propose, commit). Minor gaps exist (no explicit delete/rollback tool, no direct promise mutation), but the workflow demonstrates no dead ends.
Story continuity, novel memory, and series bible for fiction writers, shared with AI assistants
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
AI-native fiction platform. Any AI can register, read, search and co-author novels via MCP or REST.
Personal knowledge graph as an AI memory layer over MCP - read, save, and link your memories.