Skip to main content
Glama
storyai

storyai

by jedikim

storyai

まずこれを開いてください → docs/index.html

ブラウザで開くと、7つのドキュメントが互いにリンクでつながっています。 1枚ですべて見たい場合は 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/ api/ web/        ← 후속 단계에서 채웁니다
server/ bible/ store/        ← P0 조회 + P1 제안/커밋 구현

ドキュメント

docs/index.html をブラウザで開いてください。7つのドキュメントが互いに参照し合っています。

ドキュメント

内容

対象

index

全体マップ、重要決定8件、現状

全員

01 企画書

問題・根拠となる数字・市場の隙間・利用シナリオ

企画者

02 設計書

データモデル・MCPツール15個・バージョン管理・伝播

開発者

03 開発計画書

P0~P6ロードマップ・タスク分解・リスク

開発者

04 技術スタック

採用と拒否の根拠・依存関係・参考文献

開発者

05 構造図

ダイアグラム11枚

全員

06 UI設計

画面仕様・コンポーネント・デザイントークン

デザイナー・開発者

07 UIモックアップ

実際に動作する画面

全員

機械可読用スペック

ドキュメントが説明する対象であり、実装が直接読み取るファイルです。

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 · 인덱스 18

sqlite3 store/story.db < spec/schema.sql でそのまま適用されます。

ホストパッケージ

Claude CodeとCodexの両方で1セットで動作します。

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 の1か所にあり、ビルド時に各ドキュメントへインライン展開されます — そのためドキュメント1つひとつが自己完結型で、どこに置いてもそのままレンダリングされます。 依存関係はPython標準ライブラリのみです。

実装状況

P0 読み取り専用インデックス、P1 書き込みパス、P2 複線・診断、P3 抽出・検索が 実装済みです。MCPツール14個を提供し、すべての書き込みは提案記録と read_set 衝突 判定を経て、単一のSQLiteコミットレーン上で原子的に適用されます。P3は明示的なIDバインディング マニフェストとUTF-8バイトスパンを強制し、BM25とローカルsqlite-vecの結果をRRFで結合します。

次はP4 — UIです。詳細な分解は 開発計画書 §P4 に従います。

開発実行

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/python -m pytest
server/run-mcp.sh

原稿抽出は manuscript/**/*.md の隣にある *.story.json を入力として使用します。形式と LLM抽出契約は prompts/v1/ にあり、ingest はProposalのみを作成し、 自動コミットしません。

最後のコマンドはstdio MCPサーバーであるため、ターミナルで待機するのが正常です。Claude Codeと Codexはそれぞれのプロジェクト設定を通じて、同じ server/run-mcp.sh エントリポイントを 実行します。

P1 書き込み契約

propose はライブグラフを変更しません。各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ごとの2番目の focalizes エッジは提案段階で 拒否されます。到達不能イベントを含む残りの診断は、commit結果と check で確認します。

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