Reorganise by feature, rename to Novelly, add Aspire and a pre-push hook

The layered split into Domain/Application/Infrastructure/Api was forcing organisation by layer: adding one capability meant touching four projects and four folders that each held a slice of it. Those four projects are now one feature-organised Novelly.Api, where each folder — Projects, Characters, Chapters, Beats, Scenes, Tags, Agent — holds its entity, DTOs, service and endpoints together. Common/ holds what genuinely crosses features (the patch semantics, the two exception types, DraftStatus) and Data/ holds the DbContext and migrations. Six .NET projects become five: the three layer projects are gone, and Novelly.AppHost and Novelly.ServiceDefaults are new. - Namespaces move from NovelSoftware.* to Novelly.*, including the entity type names recorded in the EF model snapshots. The migration ids are untouched, so an existing novel.db still migrates cleanly — verified against a fresh file. - Aspire orchestration mirrors the mic-check setup: the AppHost starts the API on :5080 and the Vite dev server on :5173, and the API picks up OpenTelemetry, health checks and service discovery from ServiceDefaults. /health and /alive now answer in development. - A Husky pre-push hook runs scripts/ci/prepush.sh: build, test, then a web build. The scripts are plain bash so CI can run the same steps. - The MCP server's env var is now NOVELLY_API_URL. Verified beyond the build: 44 tests pass, the web client builds, the API was exercised over curl (project/chapter/beat/tag round trip, tag cross-reference, 503 on the agent without a key while conversation listing still returns 200), the MCP server was driven over stdio JSON-RPC (26 tools, errors still surface the API's own message rather than being flattened), and the AppHost was run to confirm both resources come up and Vite proxies /api through to the API. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S56bfZMGe1hnhpWP4CjjNw
2026-08-06 12:11:20 -07:00
parent 30e0c6926e
commit 725758ccd9
120 changed files with 811 additions and 421 deletions
@@ -0,0 +1,71 @@
+using System.ComponentModel;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+
+namespace Novelly.Mcp.Tools;
+
+[McpServerToolType]
+public static class BeatTools
+{
+    [McpServerTool(Name = "get_chapter_outline")]
+    [Description("Read a chapter's outline: its beats in order. Each beat is one row — a short "
+                 + "title, whose beat it is, what happened, and what it sets up. The chapter's "
+                 + "summary paragraph sits on the chapter itself, via get_chapter.")]
+    public static Task<CallToolResult> GetChapterOutline(
+        NovelApiClient api,
+        [Description("The chapter's id.")] Guid chapterId,
+        CancellationToken ct) =>
+        api.GetAsync($"/api/chapters/{chapterId}/beats", ct);
+
+    [McpServerTool(Name = "create_beat")]
+    [Description("Add a beat to a chapter's outline. Keep the title to three to five words — it "
+                 + "is a handle, not a sentence; detail belongs in whatHappened and whatsNext.")]
+    public static Task<CallToolResult> CreateBeat(
+        NovelApiClient api,
+        [Description("The chapter's id.")] Guid chapterId,
+        [Description("Three to five words naming the beat.")] string title,
+        CancellationToken ct,
+        [Description("Position in the chapter. Appended to the end when omitted.")] int? sortOrder = null,
+        [Description("Id of the character whose beat this is.")] Guid? characterId = null,
+        [Description("The event itself.")] string? whatHappened = null,
+        [Description("What it sets in motion — the hook into the next beat.")] string? whatsNext = null,
+        [Description("Id of the scene this beat will be written into, if decided.")] Guid? sceneId = null,
+        [Description("Tags for cross-referencing. Unknown tags are created.")] string[]? tags = null) =>
+        api.PostAsync($"/api/chapters/{chapterId}/beats",
+            new { title, sortOrder, characterId, whatHappened, whatsNext, sceneId, tags }, ct);
+
+    [McpServerTool(Name = "update_beat")]
+    [Description("Revise a beat. Only the fields you supply change. Supplying a tag list replaces "
+                 + "the beat's tags outright, so include the ones you want to keep.")]
+    public static Task<CallToolResult> UpdateBeat(
+        NovelApiClient api,
+        [Description("The beat's id.")] Guid beatId,
+        CancellationToken ct,
+        [Description("Three to five words naming the beat.")] string? title = null,
+        [Description("Position in the chapter.")] int? sortOrder = null,
+        [Description("Id of the character whose beat this is.")] Guid? characterId = null,
+        [Description("The event itself.")] string? whatHappened = null,
+        [Description("What it sets in motion.")] string? whatsNext = null,
+        [Description("Id of the scene this beat will be written into.")] Guid? sceneId = null,
+        [Description("Tags for cross-referencing. Replaces the existing tags.")] string[]? tags = null) =>
+        api.PatchAsync($"/api/beats/{beatId}",
+            new { title, sortOrder, characterId, whatHappened, whatsNext, sceneId, tags }, ct);
+
+    [McpServerTool(Name = "delete_beat")]
+    [Description("Remove a beat from a chapter's outline. Confirm with the writer first.")]
+    public static Task<CallToolResult> DeleteBeat(
+        NovelApiClient api,
+        [Description("The beat's id.")] Guid beatId,
+        CancellationToken ct) =>
+        api.DeleteAsync($"/api/beats/{beatId}", ct);
+
+    [McpServerTool(Name = "reorder_beats")]
+    [Description("Renumber a chapter's beats to match the order given. List every beat id in the "
+                 + "order wanted; any left out keep their relative position at the end.")]
+    public static Task<CallToolResult> ReorderBeats(
+        NovelApiClient api,
+        [Description("The chapter's id.")] Guid chapterId,
+        [Description("Beat ids in their new order.")] Guid[] beatIds,
+        CancellationToken ct) =>
+        api.PostAsync($"/api/chapters/{chapterId}/beats/reorder", new { beatIds }, ct);
+}
@@ -0,0 +1,124 @@
+using System.ComponentModel;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+
+namespace Novelly.Mcp.Tools;
+
+[McpServerToolType]
+public static class CharacterTools
+{
+    [McpServerTool(Name = "list_characters")]
+    [Description("List a project's character dossiers in full, including their relationships.")]
+    public static Task<CallToolResult> ListCharacters(
+        NovelApiClient api,
+        [Description("The project's id.")] Guid projectId,
+        CancellationToken ct) =>
+        api.GetAsync($"/api/projects/{projectId}/characters", ct);
+
+    [McpServerTool(Name = "get_character")]
+    [Description("Read one character's dossier.")]
+    public static Task<CallToolResult> GetCharacter(
+        NovelApiClient api,
+        [Description("The character's id.")] Guid characterId,
+        CancellationToken ct) =>
+        api.GetAsync($"/api/characters/{characterId}", ct);
+
+    [McpServerTool(Name = "create_character")]
+    [Description("Add a character dossier to a project. Name is the only requirement — leave a field "
+                 + "blank when the writer has not decided it yet rather than inventing detail.")]
+    public static Task<CallToolResult> CreateCharacter(
+        NovelApiClient api,
+        [Description("The project's id.")] Guid projectId,
+        [Description("The character's name.")] string name,
+        CancellationToken ct,
+        [Description("Protagonist, Antagonist, Deuteragonist, Supporting, Minor, Mentor, LoveInterest or Foil.")]
+        string? role = null,
+        [Description("Age, exact or approximate.")] string? age = null,
+        [Description("The pronouns this character uses.")] string? pronouns = null,
+        [Description("What they do.")] string? occupation = null,
+        [Description("How they look.")] string? appearance = null,
+        [Description("Temperament, habits, how they treat people.")] string? personality = null,
+        [Description("History that shapes who they are now.")] string? backstory = null,
+        [Description("What they consciously pursue.")] string? want = null,
+        [Description("What they actually need, usually at odds with what they want.")] string? need = null,
+        [Description("The war inside them.")] string? internalConflict = null,
+        [Description("What in the world opposes them.")] string? externalConflict = null,
+        [Description("How they change over the course of the book.")] string? arcSummary = null,
+        [Description("Speech patterns and register that make their dialogue theirs.")] string? voice = null,
+        [Description("Anything else worth recording.")] string? notes = null,
+        [Description("Tags for cross-referencing. Unknown tags are created.")] string[]? tags = null) =>
+        api.PostAsync($"/api/projects/{projectId}/characters", new
+        {
+            name,
+            role = role ?? "Supporting",
+            age,
+            pronouns,
+            occupation,
+            appearance,
+            personality,
+            backstory,
+            want,
+            need,
+            internalConflict,
+            externalConflict,
+            arcSummary,
+            voice,
+            notes,
+            tags
+        }, ct);
+
+    [McpServerTool(Name = "update_character")]
+    [Description("Revise an existing character dossier. Only the fields you supply change.")]
+    public static Task<CallToolResult> UpdateCharacter(
+        NovelApiClient api,
+        [Description("The character's id.")] Guid characterId,
+        CancellationToken ct,
+        [Description("New name.")] string? name = null,
+        [Description("Protagonist, Antagonist, Deuteragonist, Supporting, Minor, Mentor, LoveInterest or Foil.")]
+        string? role = null,
+        [Description("Age, exact or approximate.")] string? age = null,
+        [Description("The pronouns this character uses.")] string? pronouns = null,
+        [Description("What they do.")] string? occupation = null,
+        [Description("How they look.")] string? appearance = null,
+        [Description("Temperament, habits, how they treat people.")] string? personality = null,
+        [Description("History that shapes who they are now.")] string? backstory = null,
+        [Description("What they consciously pursue.")] string? want = null,
+        [Description("What they actually need.")] string? need = null,
+        [Description("The war inside them.")] string? internalConflict = null,
+        [Description("What in the world opposes them.")] string? externalConflict = null,
+        [Description("How they change over the course of the book.")] string? arcSummary = null,
+        [Description("Speech patterns and register.")] string? voice = null,
+        [Description("Anything else worth recording.")] string? notes = null,
+        [Description("Tags for cross-referencing. Replaces the existing tags.")] string[]? tags = null) =>
+        api.PatchAsync($"/api/characters/{characterId}", new
+        {
+            name,
+            role,
+            age,
+            pronouns,
+            occupation,
+            appearance,
+            personality,
+            backstory,
+            want,
+            need,
+            internalConflict,
+            externalConflict,
+            arcSummary,
+            voice,
+            notes,
+            tags
+        }, ct);
+
+    [McpServerTool(Name = "relate_characters")]
+    [Description("Record a relationship from one character to another in the same project.")]
+    public static Task<CallToolResult> RelateCharacters(
+        NovelApiClient api,
+        [Description("Id of the character the relationship belongs to.")] Guid characterId,
+        [Description("Id of the character they are related to.")] Guid relatedCharacterId,
+        [Description("How they are related, e.g. 'sister', 'rival', 'former mentor'.")] string relationshipType,
+        CancellationToken ct,
+        [Description("What the relationship is like, and where it is headed.")] string? description = null) =>
+        api.PostAsync($"/api/characters/{characterId}/relationships",
+            new { relatedCharacterId, relationshipType, description }, ct);
+}
@@ -0,0 +1,139 @@
+using System.ComponentModel;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+
+namespace Novelly.Mcp.Tools;
+
+[McpServerToolType]
+public static class ManuscriptTools
+{
+    [McpServerTool(Name = "list_chapters")]
+    [Description("List a project's chapters in manuscript order, with scene and word counts.")]
+    public static Task<CallToolResult> ListChapters(
+        NovelApiClient api,
+        [Description("The project's id.")] Guid projectId,
+        CancellationToken ct) =>
+        api.GetAsync($"/api/projects/{projectId}/chapters", ct);
+
+    [McpServerTool(Name = "get_chapter")]
+    [Description("Read one chapter in full, including every scene and any drafted prose.")]
+    public static Task<CallToolResult> GetChapter(
+        NovelApiClient api,
+        [Description("The chapter's id.")] Guid chapterId,
+        CancellationToken ct) =>
+        api.GetAsync($"/api/chapters/{chapterId}", ct);
+
+    [McpServerTool(Name = "create_chapter")]
+    [Description("Add a chapter to a project. It goes at the end of the manuscript unless you supply a number.")]
+    public static Task<CallToolResult> CreateChapter(
+        NovelApiClient api,
+        [Description("The project's id.")] Guid projectId,
+        [Description("Chapter title.")] string title,
+        CancellationToken ct,
+        [Description("Position in the manuscript, 1-based.")] int? number = null,
+        [Description("The chapter's outline summary paragraph.")] string? summary = null,
+        [Description("Id of the point-of-view character.")] Guid? povCharacterId = null,
+        [Description("Where and when the chapter takes place.")] string? setting = null,
+        [Description("Planned, Outlined, Drafted, Revised or Final.")] string? status = null,
+        [Description("Target length in words.")] int? targetWordCount = null,
+        [Description("Tags for cross-referencing. Unknown tags are created.")] string[]? tags = null) =>
+        api.PostAsync($"/api/projects/{projectId}/chapters", new
+        {
+            title,
+            number,
+            summary,
+            povCharacterId,
+            setting,
+            status = status ?? "Planned",
+            targetWordCount,
+            tags
+        }, ct);
+
+    [McpServerTool(Name = "update_chapter")]
+    [Description("Revise a chapter's title, number, summary, POV character, setting, notes or status.")]
+    public static Task<CallToolResult> UpdateChapter(
+        NovelApiClient api,
+        [Description("The chapter's id.")] Guid chapterId,
+        CancellationToken ct,
+        [Description("New title.")] string? title = null,
+        [Description("Position in the manuscript.")] int? number = null,
+        [Description("The chapter's outline summary paragraph.")] string? summary = null,
+        [Description("Id of the point-of-view character.")] Guid? povCharacterId = null,
+        [Description("Where and when the chapter takes place.")] string? setting = null,
+        [Description("Anything else worth recording.")] string? notes = null,
+        [Description("Planned, Outlined, Drafted, Revised or Final.")] string? status = null,
+        [Description("Target length in words.")] int? targetWordCount = null,
+        [Description("Tags for cross-referencing. Replaces the existing tags.")] string[]? tags = null) =>
+        api.PatchAsync($"/api/chapters/{chapterId}",
+            new { title, number, summary, povCharacterId, setting, notes, status, targetWordCount, tags }, ct);
+
+    [McpServerTool(Name = "list_scenes")]
+    [Description("List a chapter's scenes in order.")]
+    public static Task<CallToolResult> ListScenes(
+        NovelApiClient api,
+        [Description("The chapter's id.")] Guid chapterId,
+        CancellationToken ct) =>
+        api.GetAsync($"/api/chapters/{chapterId}/scenes", ct);
+
+    [McpServerTool(Name = "create_scene")]
+    [Description("Add a scene to a chapter. The goal/conflict/outcome trio is what makes a scene "
+                 + "draftable later, so fill those in when there is enough to work with.")]
+    public static Task<CallToolResult> CreateScene(
+        NovelApiClient api,
+        [Description("The chapter's id.")] Guid chapterId,
+        [Description("Scene title.")] string title,
+        CancellationToken ct,
+        [Description("Position within the chapter. Appended to the end when omitted.")] int? sortOrder = null,
+        [Description("What happens in the scene.")] string? summary = null,
+        [Description("What the POV character is trying to achieve.")] string? goal = null,
+        [Description("What stands in the way.")] string? conflict = null,
+        [Description("How it lands, and what it costs.")] string? outcome = null,
+        [Description("Id of the point-of-view character.")] Guid? povCharacterId = null,
+        [Description("Where the scene takes place.")] string? location = null,
+        [Description("Drafted prose for the scene, if you are writing it now.")] string? prose = null,
+        [Description("Planned, Outlined, Drafted, Revised or Final.")] string? status = null) =>
+        api.PostAsync($"/api/chapters/{chapterId}/scenes", new
+        {
+            title,
+            sortOrder,
+            summary,
+            goal,
+            conflict,
+            outcome,
+            povCharacterId,
+            location,
+            prose,
+            status = status ?? "Planned"
+        }, ct);
+
+    [McpServerTool(Name = "update_scene")]
+    [Description("Revise a scene. Supplying 'prose' writes or replaces the scene's draft text and "
+                 + "recomputes its word count.")]
+    public static Task<CallToolResult> UpdateScene(
+        NovelApiClient api,
+        [Description("The scene's id.")] Guid sceneId,
+        CancellationToken ct,
+        [Description("New title.")] string? title = null,
+        [Description("Position within the chapter.")] int? sortOrder = null,
+        [Description("What happens in the scene.")] string? summary = null,
+        [Description("What the POV character is trying to achieve.")] string? goal = null,
+        [Description("What stands in the way.")] string? conflict = null,
+        [Description("How it lands, and what it costs.")] string? outcome = null,
+        [Description("Id of the point-of-view character.")] Guid? povCharacterId = null,
+        [Description("Where the scene takes place.")] string? location = null,
+        [Description("Drafted prose for the scene.")] string? prose = null,
+        [Description("Planned, Outlined, Drafted, Revised or Final.")] string? status = null) =>
+        api.PatchAsync($"/api/scenes/{sceneId}", new
+        {
+            title,
+            sortOrder,
+            summary,
+            goal,
+            conflict,
+            outcome,
+            povCharacterId,
+            location,
+            prose,
+            status
+        }, ct);
+}
@@ -0,0 +1,53 @@
+using System.ComponentModel;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+
+namespace Novelly.Mcp.Tools;
+
+[McpServerToolType]
+public static class ProjectTools
+{
+    [McpServerTool(Name = "list_projects")]
+    [Description("List every novel project, with counts of characters, chapters and drafted words. "
+                 + "Start here to find the project id everything else needs.")]
+    public static Task<CallToolResult> ListProjects(NovelApiClient api, CancellationToken ct) =>
+        api.GetAsync("/api/projects", ct);
+
+    [McpServerTool(Name = "get_project_brief")]
+    [Description("Read a project's title, author, genre, logline, synopsis, notes and word-count target.")]
+    public static Task<CallToolResult> GetProject(
+        NovelApiClient api,
+        [Description("The project's id.")] Guid projectId,
+        CancellationToken ct) =>
+        api.GetAsync($"/api/projects/{projectId}", ct);
+
+    [McpServerTool(Name = "create_project")]
+    [Description("Create a new novel project.")]
+    public static Task<CallToolResult> CreateProject(
+        NovelApiClient api,
+        [Description("Working title.")] string title,
+        CancellationToken ct,
+        [Description("Author name.")] string? author = null,
+        [Description("Genre or category.")] string? genre = null,
+        [Description("One-sentence pitch.")] string? logline = null,
+        [Description("Paragraph-length summary of the whole book.")] string? synopsis = null,
+        [Description("Target manuscript length in words.")] int? targetWordCount = null) =>
+        api.PostAsync("/api/projects", new { title, author, genre, logline, synopsis, targetWordCount }, ct);
+
+    [McpServerTool(Name = "update_project_brief")]
+    [Description("Revise a project's top-level fields. Only the fields you supply change; "
+                 + "pass an empty string to clear one.")]
+    public static Task<CallToolResult> UpdateProject(
+        NovelApiClient api,
+        [Description("The project's id.")] Guid projectId,
+        CancellationToken ct,
+        [Description("New title.")] string? title = null,
+        [Description("Author name.")] string? author = null,
+        [Description("Genre or category.")] string? genre = null,
+        [Description("One-sentence pitch.")] string? logline = null,
+        [Description("Paragraph-length summary of the whole book.")] string? synopsis = null,
+        [Description("Free-form notes on theme, tone, comparable titles.")] string? notes = null,
+        [Description("Target manuscript length in words.")] int? targetWordCount = null) =>
+        api.PatchAsync($"/api/projects/{projectId}",
+            new { title, author, genre, logline, synopsis, notes, targetWordCount }, ct);
+}
@@ -0,0 +1,56 @@
+using System.ComponentModel;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+
+namespace Novelly.Mcp.Tools;
+
+[McpServerToolType]
+public static class TagTools
+{
+    [McpServerTool(Name = "list_tags")]
+    [Description("List a project's tags with how many characters, chapters and beats carry each. "
+                 + "Read this before inventing a new tag so you reuse the writer's vocabulary.")]
+    public static Task<CallToolResult> ListTags(
+        NovelApiClient api,
+        [Description("The project's id.")] Guid projectId,
+        CancellationToken ct) =>
+        api.GetAsync($"/api/projects/{projectId}/tags", ct);
+
+    [McpServerTool(Name = "get_tag_references")]
+    [Description("Cross-reference a tag: every character, chapter and beat carrying it. Use this "
+                 + "to trace a motif, a thread, or a piece of setup through the book.")]
+    public static Task<CallToolResult> GetTagReferences(
+        NovelApiClient api,
+        [Description("The tag's id.")] Guid tagId,
+        CancellationToken ct) =>
+        api.GetAsync($"/api/tags/{tagId}/references", ct);
+
+    [McpServerTool(Name = "create_tag")]
+    [Description("Create a tag explicitly. Applying an unknown tag by name to a character, "
+                 + "chapter or beat also creates it, so this is only needed to set a colour up front.")]
+    public static Task<CallToolResult> CreateTag(
+        NovelApiClient api,
+        [Description("The project's id.")] Guid projectId,
+        [Description("The tag's name. Unique within the project, matched case-insensitively.")] string name,
+        CancellationToken ct,
+        [Description("Optional hex colour for the UI, e.g. \"#9a4a2f\".")] string? color = null) =>
+        api.PostAsync($"/api/projects/{projectId}/tags", new { name, color }, ct);
+
+    [McpServerTool(Name = "update_tag")]
+    [Description("Rename or recolour a tag. Renaming updates it everywhere it is applied.")]
+    public static Task<CallToolResult> UpdateTag(
+        NovelApiClient api,
+        [Description("The tag's id.")] Guid tagId,
+        CancellationToken ct,
+        [Description("New name.")] string? name = null,
+        [Description("Hex colour, e.g. \"#9a4a2f\".")] string? color = null) =>
+        api.PatchAsync($"/api/tags/{tagId}", new { name, color }, ct);
+
+    [McpServerTool(Name = "delete_tag")]
+    [Description("Delete a tag. Whatever carried it is left alone — only the label goes.")]
+    public static Task<CallToolResult> DeleteTag(
+        NovelApiClient api,
+        [Description("The tag's id.")] Guid tagId,
+        CancellationToken ct) =>
+        api.DeleteAsync($"/api/tags/{tagId}", ct);
+}