Skip to main content
Glama
storyai

storyai

by jedikim

storyai

먼저 이걸 여세요 → docs/index.html

브라우저로 열면 문서 일곱 개가 서로 링크로 이어집니다. 한 장으로 다 보고 싶으면 docs/storyai-설계-통합.html. 화면이 궁금하면 docs/07-UI목업.html — 실제로 동작합니다.

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/ bible/ store/     원고·설정집·그래프 저장소
server/ web/                 MCP·REST 코어 + React 검수 UI

문서

docs/index.html을 브라우저로 여세요. 일곱 개 문서가 서로를 참조합니다.

문서

내용

대상

index

전체 지도, 핵심 결정 8개, 현황

모두

01 기획서

문제·근거 숫자·시장 빈틈·사용 시나리오

기획자

02 설계서

데이터 모델·그래프 툴 15개·프로젝트 제어·전파

개발자

03 개발계획서

P0~P6 로드맵·태스크 분해·리스크

개발자

04 기술 스택

선택과 거부의 근거·의존성·참고문헌

개발자

05 구조도

다이어그램 11장

모두

06 UI 설계

화면 명세·컴포넌트·디자인 토큰

디자이너·개발자

07 UI 목업

실제로 동작하는 화면

모두

기계 판독용 스펙

문서가 설명하는 대상이자 구현이 직접 읽는 파일입니다.

spec/ontology.json   노드 18종 · 간선 28종 · 태그 · 삼중 시간축 · 가시성 · 불변식
spec/tools.json      MCP 툴 16개 시그니처 · 예산 · 위험 등급 정책
spec/rules.json      진단 규칙 26개 (Tier 1 결정론 / Tier 2 LLM) · 전파 정책
spec/policy.json     P1 변경 위험 등급 · 잠금 · 캐스케이드 임계값
spec/schema.sql      DDL — 테이블 27 · 뷰 5 · 인덱스 23

sqlite3 store/story.db < spec/schema.sql 로 바로 적용됩니다.

호스트 패키지

Claude Code와 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 를 양쪽 훅이 공통 호출

MCP 연결 확인

저장소에는 Claude Code용 .mcp.json과 Codex용 .codex/config.toml이 모두 들어 있습니다. 처음 열 때 프로젝트를 신뢰하고 MCP 실행을 승인한 다음 연결 상태를 확인합니다.

claude mcp list
codex mcp list

문서 수정

문서는 빌드 산출물입니다. 내용을 고치려면 build/parts/*.part.html을 고치고:

python3 build/build.py

공통 스타일은 build/style.css 한 곳에 있고, 빌드 시 각 문서에 인라인됩니다 — 그래서 문서 하나하나가 자립형이고 어디에 올려도 그대로 렌더됩니다. 의존성은 파이썬 표준 라이브러리뿐입니다.

구현 현황

P0 읽기 전용 인덱스, P1 쓰기 경로, P2 복선·진단, P3 추출·검색, P4 UI, P5 Domino v1, P6 Domino v2·다중 에이전트 운영이 구현되어 있습니다. MCP 도구 16개(그래프 15개 + 프로젝트 제어 1개)를 제공하며, 모든 그래프 쓰기는 제안 기록과 read_set 충돌 판정을 거쳐 단일 SQLite 커밋 레인에서 원자적으로 적용됩니다. P3는 명시적 ID binding manifest와 UTF-8 byte span을 강제하고, BM25와 로컬 sqlite-vec 결과를 RRF로 결합합니다. P4는 같은 코어를 감싼 FastAPI REST 계층과 React Flow 그래프, F–T–P 복선 보드, 이중 시간축, 출처를 구분하는 inline diff 검수 큐를 제공합니다. P5는 역방향 read_set 의존성, typed projection 조기 종료, 깊이·노드 예산과 순환 차단을 적용하고, 결정론적 재도출 결과도 자동 반영하지 않고 cascade Proposal로 남깁니다. P6는 TTL advisory lease, 부모가 있는 에이전트 session branch, 그리고 commit 밖의 durable worker에서 실행되는 Tier-2 재도출을 추가합니다. P0~P6 로드맵이 모두 구현되었습니다.

여러 소설 프로젝트

한 MCP 프로세스는 여러 소설 프로젝트를 등록하고 현재 프로젝트를 전환할 수 있습니다. 각 프로젝트는 독립적인 manuscript/, bible/, spec/, store/story.db를 가지며, 선택 뒤 기존 그래프 도구 15개와 Tier-2 worker는 그 프로젝트에만 작동합니다.

project(mode="current")
project(mode="list")
project(mode="create", name="novel-a", path="/absolute/path/novel-a")
project(mode="register", name="existing", path="/absolute/path/existing")
project(mode="select", name="novel-a")

create는 현재 프로젝트의 spec/을 템플릿으로 복사해 새 프로젝트를 만들고 즉시 선택합니다. register도 완전한 기존 프로젝트를 검증한 뒤 선택합니다. 선택은 기본적으로 시작 프로젝트의 .storyai/projects.json에 원자적으로 저장되어 MCP 재시작 후 복원됩니다. 테스트나 별도 운영 레지스트리는 STORYAI_PROJECTS_FILE로 지정할 수 있습니다. 프로젝트 전환은 진행 중인 다른 MCP 호출이 없을 때 수행하세요.

개발 실행

Python 3.12 이상에서 격리 환경을 만들고 개발 의존성을 설치합니다.

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

설정집 파일 형식은 bible/README.md를 따릅니다. 로더는 명시된 YAML 메타데이터만 읽으며 내용을 추측하거나 자동 추출하지 않습니다.

.venv/bin/python -m server.load_bible
.venv/bin/python -m server.consolidate
.venv/bin/storyai-cascade --limit 100
.venv/bin/python -m pytest
server/run-mcp.sh

UI는 정적 번들을 빌드한 뒤 같은 Python 프로세스에서 실행합니다.

cd web && npm ci && npm run build && cd ..
.venv/bin/storyai-ui

기본 주소는 http://127.0.0.1:8765입니다. 개발 중에는 별도 터미널에서 cd web && npm run dev를 실행하면 /api 요청이 8765 포트로 프록시됩니다. 상단 프로젝트 선택기에서 등록된 소설을 전환하면 그래프·검색·복선·시간축·검수 큐가 선택한 프로젝트 기준으로 다시 로드됩니다. Session처럼 온톨로지에서 internal로 표시된 운영 노드는 서사 그래프·검색·카운트에 노출되지 않습니다. 그래프에서 노드를 선택하면 오른쪽 상세 패널의 설명을 직접 편집할 수 있으며, 저장은 현재 리비전을 기준으로 human/UI propose → commit 경로를 거쳐 편집 이력에 기록됩니다.

원고 추출은 manuscript/**/*.md 옆의 *.story.json을 입력으로 사용합니다. 형식과 LLM 추출 계약은 prompts/v1/에 있으며, ingest는 Proposal만 만들고 자동 커밋하지 않습니다.

마지막 명령은 stdio MCP 서버이므로 터미널에 대기하는 것이 정상입니다. Claude Code와 Codex는 각자의 프로젝트 설정을 통해 동일한 server/run-mcp.sh 엔트리포인트를 실행합니다.

P1 쓰기 계약

propose는 live 그래프를 바꾸지 않습니다. 각 op에는 8자 이상의 고유 idem_key가 필요하고 read_set은 비어 있을 수 없습니다. 최초 Session처럼 기존 노드 근거가 없는 ADD는 현재 graph_state.revision을 { "node": "book", "rev": n }으로 전달합니다.

지원 verb는 ADD · UPDATE · INVALIDATE · LINK · UNLINK입니다. INVALIDATE와 UNLINK는 행을 삭제하지 않고 tx_to를 닫습니다. commit(mode="dry_run")은 실제와 같은 검증·CID·Merkle 계산을 수행한 뒤 전체 트랜잭션을 되돌립니다.

story://session/latest는 가장 최근 Session 노드를 가리킵니다. Session의 props에는 open_threads와 next를 반드시 남겨 다음 호스트가 이어받을 수 있게 합니다.

P2 복선·연속성 계약

Promise의 props.status는 hypothetical → eligible → actualized 순서로만 진행하며 의도적 폐기는 prevented로 끝납니다. eligible에는 T, actualized에는 P가 필요합니다. promises(status=["eligible"])는 F–T–P와 부채, S-Eff, delta-Coh 근사치를 반환합니다.

Fact의 가시성은 visible_to에 viewer, learned_at, pathway를 구조화해 기록합니다. Scene의 props.pre · post · forbid 조건은 subject, field, op, value 형태이며, 발화 사실은 props.claims=[{"speaker": "character/…", "fact": "fact/…"}]로 기록합니다. 이 구조를 사용해야 check가 인지 시점·세계 규칙·사실 충돌을 SQL로 재현 가능하게 판정합니다.

causes, contains, extends의 순환과 Scene당 두 번째 focalizes 간선은 제안 단계에서 거부됩니다. 도달 불가 사건을 포함한 나머지 진단은 commit 결과와 check에서 확인합니다.

P5 Domino 계약

accepted Proposal의 read_set은 proposal_read에 역색인됩니다. 읽었던 노드의 typed projection이 바뀌면 그 결과를 쓴 노드가 dirty가 되며, 최대 깊이 3·노드 40 예산 안에서 위상 순서로 전파됩니다. title, summary, body 같은 산문만 바뀐 경우에는 전파하지 않습니다. 순환은 기본 거부하고, 명시적으로 commit(allow_cycles=true, max_iterations=1..3)을 호출한 경우에만 bounded mode를 사용합니다.

LLM 없는 재도출은 대상 노드 props._derive에 명시한 typed copy만 수행합니다.

{
  "_derive": [{
    "source": "fact/source",
    "source_field": "props.object",
    "target_field": "props.object",
    "transform": "copy"
  }]
}

결과는 live 그래프에 바로 적용되지 않습니다. commit 응답의 cascade.proposals에 actor_kind="cascade"인 새 Proposal이 들어가며, 이를 별도로 검수하고 commit해야 합니다.

P6 운영 계약

동시 작업 전에는 lease(mode="acquire", scope="scene/A2.C14.*", ttl_sec=900, session_id="session/…")로 권고 리스를 얻습니다. 리스는 겹치는 exact/wildcard scope를 충돌로 알리고 만료 항목을 자동 정리하지만, 그래프 쓰기를 강제로 막지는 않습니다. propose(parent_session_id="session/parent")는 새 session branch의 부모와 시작 graph revision을 기록합니다. commit된 revision은 해당 branch head로 이동하고 충돌 거부된 branch는 conflicted로 표시됩니다.

Tier-2가 필요한 대상은 human-origin 노드의 props._rederive에 계약을 둡니다.

{
  "_rederive": [{
    "sources": ["fact/source"],
    "target_field": "summary",
    "instruction": "바뀐 구조 사실에 맞춰 요약을 다시 작성한다.",
    "max_tokens": 1200
  }]
}

commit은 cascade_job만 원자적으로 적재합니다. worker는 최신 human snapshot 전문과 바뀐 source의 typed projection만 provider에 보내며, 직전 cascade 결과는 입력하지 않습니다. provider는 아래 JSON webhook 계약으로 연결합니다.

export STORYAI_REDERIVE_ENDPOINT=https://llm-gateway.example/rederive
export STORYAI_REDERIVE_API_KEY=...
.venv/bin/storyai-cascade --limit 100

요청에는 original_human_node, changed_sources, instruction, target_field, max_tokens가 들어가고 응답은 { "value": ..., "model_id": "provider/model" }입니다. 모델 ID는 Proposal provenance에 보존됩니다. worker 결과 역시 새 actor_kind="cascade" Proposal일 뿐이며 자동 commit되지 않습니다. endpoint는 HTTPS만 허용하고, 로컬 테스트에 한해 loopback HTTP를 허용합니다.

Available Tools

14 tools
checkB
Read-onlyIdempotent

spec/rules.json의 P2 SQL 규칙으로 책 또는 노드 범위의 연속성을 진단합니다. LLM을 호출하지 않으며 노드와 근거를 함께 반환합니다.

Inputs: rules, scope, severity, max_chars, +1 more. Returns: result

commitB
DestructiveIdempotent

저장된 제안을 단일 SQLite 커밋 레인에서 원자적으로 적용하거나 dry_run 합니다. 충돌하면 어떤 변경도 적용하지 않습니다.

Inputs: proposal_id (required), mode. Returns: object

findA
Read-onlyIdempotent

제목·별칭·요약·근거 본문을 BM25, 로컬 sqlite-vec dense, 또는 두 순위의 RRF 결합으로 검색합니다. 외부 임베딩 API를 호출하지 않습니다.

Inputs: q (required), tag, kind, mode, +4 more.

getB
Read-onlyIdempotent

주소로 노드를 읽습니다. brief는 한 줄 요약, full은 구조화 필드, body는 선택한 노드 하나의 근거 원문만 반환합니다.

Inputs: ref (required), as_of, include, max_chars, +1 more.

graph_schemaA
Read-onlyIdempotent

런타임 온톨로지의 노드 타입·간선·태그·진단 규칙을 반환합니다. 스키마를 추측하지 말고 이 도구로 확인하세요.

Inputs: section, max_chars, response_format.

impactB
Read-onlyIdempotent

가상의 필드 변경이 역방향 hard 간선을 따라 영향을 줄 노드와 관련 진단 규칙을 읽기 전용으로 미리 계산합니다.

Inputs: ref (required), change (required), max_depth. Returns: object

ingestB
Idempotent

원고 전체와 명시적 ID binding manifest의 해시·UTF-8 byte span·Scene 분할을 검증하고 증분 변경 Proposal만 만듭니다. live 그래프는 commit 전까지 바뀌지 않습니다.

Inputs: chapter (required), mode. Returns: object

neighborhoodA
Read-onlyIdempotent

의도 검색 seed와 명시적 anchor에서 hard 간선 1-hop을 확장해 token budget 안의 집필 컨텍스트 패킷을 만듭니다.

Inputs: intent (required), as_of, anchors, budget_tokens. Returns: object

outlineA
Read-onlyIdempotent

책 전체 또는 한 주소 아래의 구조를 본문 없이 반환합니다. 항상 넓은 탐색의 첫 단계로 사용하세요.

Inputs: kind, depth, scope, max_chars, +1 more.

promisesA
Read-onlyIdempotent

복선의 F-T-P, 상태, 부채, S-Eff, delta-Coh 근사치를 조회합니다. 집필 전에 eligible 상태만 필터링할 수 있습니다.

Inputs: sort, as_of, status, max_chars, +1 more. Returns: result

proposeA
Idempotent

비어 있지 않은 read_set과 멱등 키가 있는 연산을 변경 제안으로 기록합니다. 이 호출만으로 live 그래프는 바뀌지 않습니다.

Inputs: ops (required), read_set (required), rationale (required), session_id (required), +4 more. Returns: object

queryA
Read-onlyIdempotent

손으로 빚은 도구로 풀기 어려운 분석을 위해 단일 SELECT/WITH SQL을 읽기 전용, 행 제한, 실행 예산과 함께 수행합니다.

Inputs: sql (required), limit, params. Returns: object

refsC
Read-onlyIdempotent

한 노드를 가리키거나 그 노드가 가리키는 관계를 반환합니다. 산문 언급인 soft 간선은 요청할 때만 포함합니다.

Inputs: ref (required), dir, rel, as_of, +3 more.

traceA
Read-onlyIdempotent

한 노드에서 특정 대상 또는 서사 장치까지의 bounded hard-edge 경로를 반환합니다. 관계 종류와 깊이 및 경로 수를 제한할 수 있습니다.

Inputs: from (required), k, to, via, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 14 tools

    Disambiguation4/5

    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 Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A narrative graph engine that enables LLMs to generate, track, and mutate complex fictional worlds while maintaining consistency between factions, characters, and locations. It acts as a specialized RAG framework for storytelling, allowing models to manage thousands of entities without exceeding context limits.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI-driven long-form novel creation and management, including chapter generation, character and timeline tracking, semantic memory retrieval, version savepoints, and deep consistency checking across multiple projects through MCP tools, with support for local LM Studio or any OpenAI-compatible API.
      16
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables long-form web novel writing workflows by ingesting chapters into a state database, running deterministic consistency checks, querying entity histories, replaying extraction results, and retrieving conflict reports via MCP tools.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to create and manage long-form story projects with isolated databases, persistent drafts, canonical continuity checks, controlled updates, and local semantic retrieval through MCP tools, resources, and prompts.
      MIT