path: root/docs/superpowers/plans/2026-07-08-story-mcp-surface.md

# Story-Level Chatbot MCP Surface Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add `create_story`, `get_story`, `list_stories`, and `accept_story` to the chatbot-facing MCP server (`/chatbot/mcp`), so a chatbot can create and drive a Story the same way it already creates and drives a plain Task — closing the "MCP surface: story-level tools, additive to what exists" gap from the recursive-story-decomposition design spec.

**Architecture:** Both new tools and the existing REST endpoints (`internal/api/stories.go`) must share one service-layer implementation, mirroring how `internal/api/taskops.go`'s `acceptTask`/`rejectTask`/`cancelTask` already back both `internal/api/server.go`'s REST handlers and `internal/api/chatbotmcp.go`'s `accept_task`/`reject_task`/`cancel_task` tools — so the two surfaces cannot drift. `create_story`/`get_story`/`list_stories` are thin wrappers around the existing `storage.DB.CreateStory`/`GetStory`/`ListStories` (no new service-layer method needed, since there's no shared state-transition logic to protect — unlike accept, which does need one, exactly like `acceptTask`).

**Tech Stack:** Go, `github.com/modelcontextprotocol/go-sdk/mcp`, existing `internal/story`/`internal/storage` packages.

## Global Constraints

- Every new MCP tool must mirror an existing sibling tool's exact code shape in `internal/api/chatbotmcp.go` (input struct with `jsonschema` tags, `mcp.AddTool` registration, `mcpJSON`/`mcpText` for output) — this file has zero deviation from that shape today and this plan must not introduce any.
- `story.Story` has **no `repository_url` field** — only the loose-reference `ProjectID` (mirrors `tasks.project`, unenforced, no automatic resolution to a repo). The design spec's prose lists `create_story`'s inputs as "(name, spec, acceptance_criteria, repository_url → story_id)", but that field does not exist on the data model and nothing yet resolves a repo from a story (that requires the deferred root-task-spawning piece of the recursive-decomposition design). This plan's `create_story` accepts `project_id` instead — do not add a `repository_url` field to `story.Story` or to storage as part of this plan; that would be schema scope well beyond an additive MCP wrapper.
- Do not touch `internal/scheduler/story_orchestrator.go` or anything else in the recursive-decomposition design's larger, still-deferred pieces (per-node arbitrated review generalization, `builder` role system-prompt authoring). This plan is scoped to the MCP surface only.

---

## Task 1: Extract `acceptStory` service-layer helper

**Files:**
- Modify: `internal/api/stories.go` (add `errStoryNotFound`, add `acceptStory` method, refactor `handleAcceptStory` to call it)
- Modify: `internal/api/taskops.go` (map `errStoryNotFound` to 404 in `writeOpError`)
- Test: `internal/api/stories_test.go` (existing `TestServer_AcceptStory_*` tests must still pass unmodified — this task's own verification, no new tests needed)

**Interfaces:**
- Produces: `func (s *Server) acceptStory(id string, actor event.Actor) error` — Task 2 calls this directly from the new `accept_story` MCP tool.

- [ ] **Step 1: Add `errStoryNotFound` and the `acceptStory` helper**

In `internal/api/stories.go`, add `"errors"` to the import block (it currently imports `encoding/json`, `net/http`, `strconv`, `github.com/google/uuid`, `.../internal/event`, `.../internal/storage`, `.../internal/story`):

```go
import (
	"encoding/json"
	"errors"
	"net/http"
	"strconv"

	"github.com/google/uuid"
	"github.com/thepeterstone/claudomator/internal/event"
	"github.com/thepeterstone/claudomator/internal/storage"
	"github.com/thepeterstone/claudomator/internal/story"
)
```

Directly after the imports, add:

```go
// errStoryNotFound is returned when a story ID does not resolve. REST maps
// it to 404 (via writeOpError, mirroring errTaskNotFound in taskops.go); MCP
// surfaces it as a tool error.
var errStoryNotFound = errors.New("story not found")
```

Directly before `handleAcceptStory` (which you'll replace in Step 2), add this new method:

```go
// acceptStory is the shared service-layer accept-gate for a story: both
// handleAcceptStory (REST) and the accept_story chatbot MCP tool call this,
// mirroring taskops.go's shared task-operation pattern (see acceptTask) so
// the two surfaces cannot drift.
func (s *Server) acceptStory(id string, actor event.Actor) error {
	st, err := s.store.GetStory(id)
	if err != nil {
		return errStoryNotFound
	}
	if st.Status != "REVIEW_READY" {
		return conflictf("story cannot be accepted from status %s", st.Status)
	}

	from := st.Status
	st.Status = "DONE"
	if err := s.store.UpdateStory(st); err != nil {
		return err
	}

	payload, _ := json.Marshal(struct {
		StoryID string `json:"story_id"`
		From    string `json:"from"`
		To      string `json:"to"`
	}{StoryID: id, From: from, To: "DONE"})
	if err := s.store.CreateEvent(&event.Event{
		TaskID:  id,
		Kind:    event.KindHumanAccepted,
		Actor:   actor,
		Payload: payload,
	}); err != nil {
		s.logger.Error("failed to record human_accepted event", "storyID", id, "error", err)
	}
	return nil
}
```

- [ ] **Step 2: Refactor `handleAcceptStory` to call it**

Find the existing `handleAcceptStory` function (its whole body, including the doc comment above it):

```go
// handleAcceptStory is the human accept-gate for a story: it mirrors
// handleAcceptTask's pattern exactly (validate current state, transition,
// emit an event) but operates on story.Story, which (unlike task.Task) has
// no enforced state machine (story.UpdateStory is unvalidated pass-through —
// see internal/story's doc comments) — so the "only valid from REVIEW_READY"
// check is done here, not in the storage layer.
func (s *Server) handleAcceptStory(w http.ResponseWriter, r *http.Request) {
	id := r.PathValue("id")
	st, err := s.store.GetStory(id)
	if err != nil {
		writeJSON(w, http.StatusNotFound, map[string]string{"error": "story not found"})
		return
	}
	if st.Status != "REVIEW_READY" {
		writeJSON(w, http.StatusConflict, map[string]string{"error": "story cannot be accepted from status " + st.Status})
		return
	}

	from := st.Status
	st.Status = "DONE"
	if err := s.store.UpdateStory(st); err != nil {
		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
		return
	}

	payload, _ := json.Marshal(struct {
		StoryID string `json:"story_id"`
		From    string `json:"from"`
		To      string `json:"to"`
	}{StoryID: id, From: from, To: "DONE"})
	if err := s.store.CreateEvent(&event.Event{
		TaskID:  id,
		Kind:    event.KindHumanAccepted,
		Actor:   event.ActorUser,
		Payload: payload,
	}); err != nil {
		s.logger.Error("failed to record human_accepted event", "storyID", id, "error", err)
	}

	writeJSON(w, http.StatusOK, map[string]string{"message": "story accepted", "story_id": id})
}
```

Replace it with:

```go
// handleAcceptStory is the human accept-gate for a story: it mirrors
// handleAcceptTask's pattern exactly (validate current state, transition,
// emit an event), delegating to the shared acceptStory service-layer helper
// so the chatbot MCP accept_story tool cannot drift from this REST behavior.
func (s *Server) handleAcceptStory(w http.ResponseWriter, r *http.Request) {
	id := r.PathValue("id")
	if err := s.acceptStory(id, event.ActorUser); err != nil {
		writeOpError(w, err)
		return
	}
	writeJSON(w, http.StatusOK, map[string]string{"message": "story accepted", "story_id": id})
}
```

- [ ] **Step 3: Map `errStoryNotFound` to 404 in `writeOpError`**

In `internal/api/taskops.go`, find `writeOpError`:

```go
// writeOpError maps a service-layer error to the appropriate REST status.
func writeOpError(w http.ResponseWriter, err error) {
	switch {
	case errors.Is(err, errTaskNotFound):
		writeJSON(w, http.StatusNotFound, map[string]string{"error": "task not found"})
		return
	}
	var ce *conflictError
	if errors.As(err, &ce) {
		writeJSON(w, http.StatusConflict, map[string]string{"error": ce.Error()})
		return
	}
	var be *badRequestError
	if errors.As(err, &be) {
		writeJSON(w, http.StatusBadRequest, map[string]string{"error": be.Error()})
		return
	}
	writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
}
```

Replace the `switch` block with:

```go
	switch {
	case errors.Is(err, errTaskNotFound):
		writeJSON(w, http.StatusNotFound, map[string]string{"error": "task not found"})
		return
	case errors.Is(err, errStoryNotFound):
		writeJSON(w, http.StatusNotFound, map[string]string{"error": "story not found"})
		return
	}
```

- [ ] **Step 4: Run the existing story tests to confirm the refactor is behavior-preserving**

Run: `go test ./internal/api/ -run TestServer_AcceptStory -v`
Expected: `TestServer_AcceptStory_SucceedsFromReviewReady`, `TestServer_AcceptStory_FailsFromOtherStatuses`, and `TestServer_AcceptStory_NotFound` all PASS unmodified — this task is a pure refactor, so these pre-existing tests are the proof it preserves REST behavior exactly. No new tests are added in this task.

- [ ] **Step 5: Run the full package suite, then the full repo suite**

Run: `go test ./internal/api/...`
Expected: PASS for everything.

Then run: `go test ./...` (the entire repo). A prior unrelated plan in this repo (`docs/superpowers/plans/2026-07-08-subtask-ordering-and-verdict-reporting.md`, Task 4) found that task-scoped tests passing is not sufficient — a separate package's code can fail to compile due to a change here. This task doesn't change any shared interface, but verify the full suite anyway rather than assuming. Paste the actual output.

- [ ] **Step 6: Commit**

```bash
git add internal/api/stories.go internal/api/taskops.go
git commit -m "refactor(api): extract acceptStory service-layer helper, mirroring acceptTask"
```

---

## Task 2: Add `create_story`/`get_story`/`list_stories`/`accept_story` chatbot MCP tools

**Files:**
- Modify: `internal/api/chatbotmcp.go` (new input structs + 4 new `mcp.AddTool` registrations)
- Test: `internal/api/chatbotmcp_test.go` (append)

**Interfaces:**
- Consumes: `s.acceptStory` (Task 1), `s.store.CreateStory`/`GetStory`/`ListStories` (existing, `internal/storage/story.go`), `storage.StoryFilter{Status, EpicID}` (existing).
- Produces: nothing new for later work — this is the last piece of the story-level MCP surface described in the design spec.

- [ ] **Step 1: Add the new input structs and imports**

In `internal/api/chatbotmcp.go`, the import block currently reads:

```go
import (
	"context"
	"crypto/subtle"
	"encoding/json"
	"net/http"
	"strings"
	"time"

	"github.com/modelcontextprotocol/go-sdk/mcp"
	"github.com/thepeterstone/claudomator/internal/event"
	"github.com/thepeterstone/claudomator/internal/storage"
	"github.com/thepeterstone/claudomator/internal/task"
)
```

Replace it with (adding `github.com/google/uuid` and `.../internal/story`):

```go
import (
	"context"
	"crypto/subtle"
	"encoding/json"
	"net/http"
	"strings"
	"time"

	"github.com/google/uuid"
	"github.com/modelcontextprotocol/go-sdk/mcp"
	"github.com/thepeterstone/claudomator/internal/event"
	"github.com/thepeterstone/claudomator/internal/storage"
	"github.com/thepeterstone/claudomator/internal/story"
	"github.com/thepeterstone/claudomator/internal/task"
)
```

Directly after the existing `rejectTaskMCPInput` struct (find it — ends with its closing `}`, directly before `type compactTask struct`), add these three new input structs:

```go
type createStoryMCPInput struct {
	Name               string   `json:"name" jsonschema:"short human-readable story name"`
	Spec               string   `json:"spec,omitempty" jsonschema:"prose description of the intent -- what a human is asking for and why"`
	AcceptanceCriteria []string `json:"acceptance_criteria,omitempty" jsonschema:"optional list of concrete criteria the finished work must satisfy"`
	EpicID             string   `json:"epic_id,omitempty" jsonschema:"optional epic ID to group this story under"`
	ProjectID          string   `json:"project_id,omitempty" jsonschema:"optional loose-reference project ID; not yet used to automatically resolve a repository"`
	Priority           string   `json:"priority,omitempty" jsonschema:"optional priority, e.g. high, normal, low"`
}

type listStoriesMCPInput struct {
	Status string `json:"status,omitempty" jsonschema:"optional status filter, e.g. DISCOVERY, IN_PROGRESS, REVIEW_READY, DONE"`
	EpicID string `json:"epic_id,omitempty" jsonschema:"optional epic ID filter"`
}

type storyIDInput struct {
	StoryID string `json:"story_id" jsonschema:"the story ID"`
}
```

- [ ] **Step 2: Register the four new tools**

In the same file, find the `cancel_task` tool registration (the last `mcp.AddTool` call before `return srv`):

```go
	mcp.AddTool(srv, &mcp.Tool{
		Name:        "cancel_task",
		Description: "Cancel a RUNNING or QUEUED task.",
	}, func(_ context.Context, _ *mcp.CallToolRequest, in taskIDInput) (*mcp.CallToolResult, any, error) {
		msg, err := s.cancelTask(in.TaskID, event.ActorChatbot)
		if err != nil {
			return nil, nil, err
		}
		return mcpText(msg), nil, nil
	})

	return srv
```

Replace it with (adding the four new registrations directly after `cancel_task`, before `return srv`):

```go
	mcp.AddTool(srv, &mcp.Tool{
		Name:        "cancel_task",
		Description: "Cancel a RUNNING or QUEUED task.",
	}, func(_ context.Context, _ *mcp.CallToolRequest, in taskIDInput) (*mcp.CallToolResult, any, error) {
		msg, err := s.cancelTask(in.TaskID, event.ActorChatbot)
		if err != nil {
			return nil, nil, err
		}
		return mcpText(msg), nil, nil
	})

	mcp.AddTool(srv, &mcp.Tool{
		Name:        "create_story",
		Description: "Create a story representing a piece of user intent -- a shippable slice of work realized by a tree of tasks. Use this instead of submit_task when the ask needs to be broken down rather than run as a single step. Returns the new story.",
	}, func(_ context.Context, _ *mcp.CallToolRequest, in createStoryMCPInput) (*mcp.CallToolResult, any, error) {
		if strings.TrimSpace(in.Name) == "" {
			return nil, nil, badRequestf("name is required")
		}
		st := &story.Story{
			ID:                 uuid.New().String(),
			Name:               in.Name,
			Status:             "DISCOVERY",
			DiscoverySource:    "agent",
			Spec:               in.Spec,
			AcceptanceCriteria: in.AcceptanceCriteria,
			EpicID:             in.EpicID,
			ProjectID:          in.ProjectID,
			Priority:           in.Priority,
		}
		if st.AcceptanceCriteria == nil {
			st.AcceptanceCriteria = []string{}
		}
		if err := s.store.CreateStory(st); err != nil {
			return nil, nil, err
		}
		return mcpJSON(st)
	})

	mcp.AddTool(srv, &mcp.Tool{
		Name:        "get_story",
		Description: "Get one story by ID.",
	}, func(_ context.Context, _ *mcp.CallToolRequest, in storyIDInput) (*mcp.CallToolResult, any, error) {
		st, err := s.store.GetStory(in.StoryID)
		if err != nil {
			return nil, nil, errStoryNotFound
		}
		return mcpJSON(st)
	})

	mcp.AddTool(srv, &mcp.Tool{
		Name:        "list_stories",
		Description: "List stories, optionally filtered by status and/or epic_id.",
	}, func(_ context.Context, _ *mcp.CallToolRequest, in listStoriesMCPInput) (*mcp.CallToolResult, any, error) {
		stories, err := s.store.ListStories(storage.StoryFilter{Status: in.Status, EpicID: in.EpicID})
		if err != nil {
			return nil, nil, err
		}
		if stories == nil {
			stories = []*story.Story{}
		}
		return mcpJSON(stories)
	})

	mcp.AddTool(srv, &mcp.Tool{
		Name:        "accept_story",
		Description: "Accept a REVIEW_READY story, marking it DONE. This is the single human/chatbot touchpoint for a whole story's pipeline -- the underlying builder/evaluator/arbitration tasks are auto-accepted by the story orchestrator.",
	}, func(_ context.Context, _ *mcp.CallToolRequest, in storyIDInput) (*mcp.CallToolResult, any, error) {
		if err := s.acceptStory(in.StoryID, event.ActorChatbot); err != nil {
			return nil, nil, err
		}
		return mcpText("Story accepted."), nil, nil
	})

	return srv
```

- [ ] **Step 3: Write the failing tests**

First, update the import block at the top of `internal/api/chatbotmcp_test.go`. It currently reads:

```go
import (
	"context"
	"encoding/json"
	"net/http"
	"net/http/httptest"
	"testing"

	"github.com/modelcontextprotocol/go-sdk/mcp"
	"github.com/thepeterstone/claudomator/internal/storage"
	"github.com/thepeterstone/claudomator/internal/task"
)
```

Replace it with (adding `.../internal/event` and `.../internal/story`):

```go
import (
	"context"
	"encoding/json"
	"net/http"
	"net/http/httptest"
	"testing"

	"github.com/modelcontextprotocol/go-sdk/mcp"
	"github.com/thepeterstone/claudomator/internal/event"
	"github.com/thepeterstone/claudomator/internal/storage"
	"github.com/thepeterstone/claudomator/internal/story"
	"github.com/thepeterstone/claudomator/internal/task"
)
```

Then append the following tests to the end of the file:

```go
func TestChatbotMCP_CreateStory_AndGetStory(t *testing.T) {
	srv, _ := testServer(t)
	srv.SetAPIToken("s3cret")
	cs := chatbotClient(t, srv, "s3cret")

	out := callText(t, cs, "create_story", map[string]any{
		"name":                "Add login page",
		"spec":                "Users should be able to log in with email + password",
		"acceptance_criteria": []string{"User can log in", "Invalid credentials show an error"},
	})
	var created story.Story
	if err := json.Unmarshal([]byte(out), &created); err != nil {
		t.Fatalf("unmarshal create_story result %q: %v", out, err)
	}
	if created.ID == "" {
		t.Fatal("create_story returned empty story ID")
	}
	if created.Status != "DISCOVERY" {
		t.Errorf("Status: want DISCOVERY, got %q", created.Status)
	}

	out = callText(t, cs, "get_story", map[string]any{"story_id": created.ID})
	var got story.Story
	if err := json.Unmarshal([]byte(out), &got); err != nil {
		t.Fatalf("unmarshal get_story result %q: %v", out, err)
	}
	if got.Name != "Add login page" {
		t.Errorf("Name: want %q, got %q", "Add login page", got.Name)
	}
	if len(got.AcceptanceCriteria) != 2 {
		t.Errorf("AcceptanceCriteria: want 2 items, got %+v", got.AcceptanceCriteria)
	}
}

func TestChatbotMCP_CreateStory_MissingName_ReturnsToolError(t *testing.T) {
	srv, _ := testServer(t)
	srv.SetAPIToken("s3cret")
	cs := chatbotClient(t, srv, "s3cret")

	res, err := cs.CallTool(context.Background(), &mcp.CallToolParams{Name: "create_story", Arguments: map[string]any{}})
	if err != nil {
		t.Fatalf("CallTool transport error: %v", err)
	}
	if !res.IsError {
		t.Fatal("expected create_story with no name to return a tool error")
	}
}

func TestChatbotMCP_GetStory_NotFound_ReturnsToolError(t *testing.T) {
	srv, _ := testServer(t)
	srv.SetAPIToken("s3cret")
	cs := chatbotClient(t, srv, "s3cret")

	res, err := cs.CallTool(context.Background(), &mcp.CallToolParams{Name: "get_story", Arguments: map[string]any{"story_id": "nope"}})
	if err != nil {
		t.Fatalf("CallTool transport error: %v", err)
	}
	if !res.IsError {
		t.Fatal("expected get_story with unknown ID to return a tool error")
	}
}

func TestChatbotMCP_ListStories_FiltersByStatus(t *testing.T) {
	srv, store := testServer(t)
	srv.SetAPIToken("s3cret")
	cs := chatbotClient(t, srv, "s3cret")

	if err := store.CreateStory(&story.Story{ID: "s1", Name: "One", Status: "DISCOVERY", AcceptanceCriteria: []string{}}); err != nil {
		t.Fatalf("seed story 1: %v", err)
	}
	if err := store.CreateStory(&story.Story{ID: "s2", Name: "Two", Status: "DONE", AcceptanceCriteria: []string{}}); err != nil {
		t.Fatalf("seed story 2: %v", err)
	}

	out := callText(t, cs, "list_stories", map[string]any{"status": "DONE"})
	var got []story.Story
	if err := json.Unmarshal([]byte(out), &got); err != nil {
		t.Fatalf("unmarshal list_stories result %q: %v", out, err)
	}
	if len(got) != 1 || got[0].ID != "s2" {
		t.Errorf("expected only story s2, got %+v", got)
	}
}

func TestChatbotMCP_AcceptStory_SucceedsFromReviewReady(t *testing.T) {
	srv, store := testServer(t)
	srv.SetAPIToken("s3cret")
	cs := chatbotClient(t, srv, "s3cret")

	if err := store.CreateStory(&story.Story{ID: "s1", Name: "One", Status: "REVIEW_READY", AcceptanceCriteria: []string{}}); err != nil {
		t.Fatalf("seed story: %v", err)
	}

	callText(t, cs, "accept_story", map[string]any{"story_id": "s1"})

	got, err := store.GetStory("s1")
	if err != nil {
		t.Fatalf("get story after accept: %v", err)
	}
	if got.Status != "DONE" {
		t.Errorf("Status: want DONE, got %q", got.Status)
	}

	events, err := store.ListEvents("s1", 0)
	if err != nil {
		t.Fatalf("list events: %v", err)
	}
	found := false
	for _, e := range events {
		if e.Kind == event.KindHumanAccepted && e.Actor == event.ActorChatbot {
			found = true
		}
	}
	if !found {
		t.Error("expected a KindHumanAccepted event with ActorChatbot")
	}
}

func TestChatbotMCP_AcceptStory_FailsFromOtherStatus(t *testing.T) {
	srv, store := testServer(t)
	srv.SetAPIToken("s3cret")
	cs := chatbotClient(t, srv, "s3cret")

	if err := store.CreateStory(&story.Story{ID: "s1", Name: "One", Status: "IN_PROGRESS", AcceptanceCriteria: []string{}}); err != nil {
		t.Fatalf("seed story: %v", err)
	}

	res, err := cs.CallTool(context.Background(), &mcp.CallToolParams{Name: "accept_story", Arguments: map[string]any{"story_id": "s1"}})
	if err != nil {
		t.Fatalf("CallTool transport error: %v", err)
	}
	if !res.IsError {
		t.Fatal("expected accept_story from IN_PROGRESS to return a tool error")
	}
}
```

- [ ] **Step 4: Run tests to verify they fail**

Run: `go test ./internal/api/ -run 'TestChatbotMCP_(CreateStory|GetStory|ListStories|AcceptStory)' -v`

Expected: compile failure — `create_story`/`get_story`/`list_stories`/`accept_story` tools don't exist yet. Paste the actual output.

- [ ] **Step 5: Run tests to verify they pass**

Run the same command as Step 4.
Expected: PASS, all 6 new tests. Paste the actual output.

- [ ] **Step 6: Run the full package suite, then the full repo suite**

Run: `go test ./internal/api/...`
Expected: PASS for everything, including the pre-existing `TestChatbotMCP_*` and `TestServer_*Story*` tests.

Then run: `go test ./...` (the entire repo). This must also pass — paste the actual output.

- [ ] **Step 7: Commit**

```bash
git add internal/api/chatbotmcp.go internal/api/chatbotmcp_test.go
git commit -m "feat(api): add create_story/get_story/list_stories/accept_story to chatbot MCP"
```

---

## Final Verification

- [ ] Run `go build ./...` — passes.
- [ ] Run `go test ./...` — passes, full repo.
- [ ] Run `grep -rn "create_story\|get_story\|list_stories\|accept_story\|acceptStory\|errStoryNotFound" internal/` to visually confirm every file in both tasks' File Maps was actually touched.