Only ready stories reach the sprint.

Jev scores each story, lists what is missing, and holds back the ones an AI coding agent could not build.

Open live board

$ claude mcp add story-board -- uv run --directory /abs/path/story-refinement story-board-mcp

The Story Board with six columns. Each card shows its readiness verdict and quality score, for example Ready 95%, Discuss 80% and Needs refinement 55%.

The Story Board in dark mode, with a readiness verdict and quality score on each card.

Works with your coding agent

Claude Code GitHub Copilot CLI OpenAI Codex CLI Any MCP client

A real backlog, assessed

A flower shop website that Claude Code and Copilot CLI worked through over MCP, and the example backlog that ships with the API. Both are on the live board.

The Flowershop Website board: fifteen stories in Done, each naming the agents that changed it, and a human-only story in Backlog. — **Agents on the card.** A card names each agent that changed the story, and shows the score before the last assessment.

The Flowershop Website board in dark mode. — **Agents on the card.** A card names each agent that changed the story, and shows the score before the last assessment.

A story marked Needs refinement at 55% quality, with six questions for its author and the AI-agent readiness checks. — **Questions for the author.** Each assessment says what is missing, so refinement starts from a list instead of a meeting.

The same assessment in dark mode. — **Questions for the author.** Each assessment says what is missing, so refinement starts from a list instead of a meeting.

A human-only go-live story. The AI-agent readiness checks are marked Skipped, human-only. — **Human-only work.** Its assessment skips the AI-agent checks, and agents can read it but not change it.

The human-only story in dark mode. — **Human-only work.** Its assessment skips the AI-agent checks, and agents can read it but not change it.

What teams use it for

The board and the MCP server enforce the same rules, so a story is held to the same bar whoever moves it.

Keep unready stories out of the sprint

Every story gets a verdict and a quality score. Discuss and Needs refinement stories stay in Backlog or Refinement until they are assessed again.

Ready 95% Discuss 88% Needs refinement 55% Not ready 7%

agent_no_open_decisions
No TBDs, open questions or alternatives left to choose.
agent_verifiable
Says how to check the work: tests, examples, a command.
agent_code_context
Names files, modules, endpoints or a pattern to follow.
agent_self_contained
Needs no production access, credentials or approvals.

Refine a story from your agent

The agent rewrites the text, assesses it again and logs a note saying why.

Tighten the acceptance criteria of ST-3, then assess it.

Some work stays with people

Accounts, servers, secrets, another team's API. Tag the story human-only and agents can still read it, but the store refuses their edits, moves and assessments.

Human-only

Done needs proof

Moving a story to Done asks for a test report, a screenshot or recording if the UI changed, and a commit. All of it lands in the story's activity.

Activity log: copilot-cli moved FW-5 to Done with pytest, vitest and Playwright reports and a screenshot of the cart page.

Waits on, blocks

A story can't enter In sprint or Done until every story it waits on is done. The board and the API both refuse cycles.

Waits on FLW-1, FLW-2Blocks FLW-3

Every change has a reason

Each agent write needs a note, logged under the agent's name and shown on the card. There are no delete tools.

Move ST-5 to Blocked, because we are waiting for the payment provider contract.

One store, two ways in

People use the board and agents use the MCP server. Both read and write the same SQLite file, so the board shows an agent's changes the next time it refetches.

Agents, over MCP

Your agent starts story-board-mcp over stdio. The API doesn't need to be running.

One story store

Boards, stories, assessment history, the activity log and evidence files. Assessments are scored by Jev from TypeSafe.

People, on the board

A React board on the FastAPI Story Readiness API, with every endpoint in the API docs.

Twelve MCP tools

board takes an id or a key prefix like FLW. story takes an id or a key like FLW-12.

Read

list_boardslist_storiesget_storyget_activity

Write, each with a note

create_boardupdate_boardcreate_storyupdate_storymove_storyadd_blockerremove_blockerassess_story

The board's rules apply to agents too. The 100-story limit, blocked reasons, evidence for Done and the column limits for unrefined stories.
Named changes. Set STORY_AGENT_NAME per client and the activity log says which agent did what.
Linear, if you want it. Add the ready-check label to a Linear issue and it is assessed automatically. Off unless LINEAR_ENABLED=true.
Split big stories. A split creates a child story that keeps its parent's tags, and the side panel links the two.

Connect your agent

The MCP server runs on your machine and keeps its own local database. The live board here is a shared sandbox for trying the UI.

uv and Python 3.12+Install uv. It installs the story-board-mcp command.
A TypeSafe API keySet TYPESAFE_API_KEY in .env. Only assess_story needs it; the other tools work without it.
An absolute pathReplace /path/to/story-refinement with the folder you cloned into. pwd inside it prints the path.

Get the server

git clone https://github.com/SushiTuna/ibm-hackathon-template story-refinement
cd story-refinement
uv sync
cp .env.example .env        # set TYPESAFE_API_KEY

Add it to Claude Code, for every project

claude mcp add --transport stdio --scope user story-board \
  -e STORY_AGENT_NAME=claude-code \
  -- uv run --directory /path/to/story-refinement story-board-mcp

Check it

claude mcp list              # story-board should be listed and connected

Get the server

git clone https://github.com/SushiTuna/ibm-hackathon-template story-refinement
cd story-refinement
uv sync
cp .env.example .env        # set TYPESAFE_API_KEY

Add it to Copilot CLI (saved in ~/.copilot/mcp-config.json)

copilot mcp add story-board \
  --env STORY_AGENT_NAME=copilot-cli \
  -- uv run --directory /path/to/story-refinement story-board-mcp

Check it

copilot mcp list               # every server, from every config source
copilot mcp get story-board    # this server's config

Get the server

git clone https://github.com/SushiTuna/ibm-hackathon-template story-refinement
cd story-refinement
uv sync
cp .env.example .env        # set TYPESAFE_API_KEY

Add it to Codex CLI

codex mcp add story-board \
  --env STORY_AGENT_NAME=codex \
  -- uv run --directory /path/to/story-refinement story-board-mcp

Or in ~/.codex/config.toml

[mcp_servers.story-board]
command = "uv"
args = ["run", "--directory", "/path/to/story-refinement", "story-board-mcp"]
env = { STORY_AGENT_NAME = "codex" }
# The first start may install dependencies; allow more than the 10-second default.
startup_timeout_sec = 30

Claude Code, built from GitHub by uvx. Pass the key and an absolute database path.

claude mcp add story-board \
  -e TYPESAFE_API_KEY=your-key \
  -e STORIES_DB_PATH=/abs/path/story-refinement/data/stories.db \
  -- uvx --from git+https://github.com/SushiTuna/ibm-hackathon-template story-board-mcp

Any other MCP client

{
  "mcpServers": {
    "story-board": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/SushiTuna/ibm-hackathon-template", "story-board-mcp"],
      "env": {
        "TYPESAFE_API_KEY": "your-key",
        "STORIES_DB_PATH": "/abs/path/story-refinement/data/stories.db"
      }
    }
  }
}

Try it

Ask your agent to "List the boards on the story board." Inside a session, /mcp shows the server's status and its tools.

Full guide

Project-scoped config, read-only tools for Copilot, the container setup and troubleshooting are in MCP_INSTALLATION.md.