io.github.jonybur-oc/mcp-server

Official

by jonybur-oc · TypeScript

stories.yaml — an open specification for software requirements, enforced by CI.

Open specification for software requirements in YAML enforced through CI pipelines.

README.md11 KBView on GitHub

@locus-dev/mcp-server

Give your AI coding agent the spec it should be reading before writing code.

MCP server for Locus — exposes your stories.yaml as structured resources and tools for Claude Code, Cursor, Windsurf, Zed, OpenAI Codex, Continue.dev, GitHub Copilot, and any MCP-compatible client.

stories.yaml is the single source of truth for your product requirements. It lives in your repo. No account required.

Quick start — zero config

Add one entry to your Claude Code config (~/.config/claude/claude_desktop_config.json):

json

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@locus-dev/mcp-server"]
    }
  }
}

That's it. No API keys, no credentials, no account.

The server reads stories.yaml from your project directory automatically.

Compatible with Claude Code, Codex, Cursor, Continue.dev, GitHub Copilot, and any MCP-compatible coding agent.

stories.yaml belongs to you. It lives in your repo. Switch AI tools anytime — your spec stays intact.

How it works

Add a stories.yaml file to your project root (see schema docs)
Add the MCP server to your AI client config (above)
Your AI coding assistant now sees what needs to be built, what the acceptance criteria are, and what's already done

The server finds stories.yaml automatically:

LOCUS_STORIES_PATH env var if set
stories.yaml in the current directory
Walks up to find stories.yaml at the repo root (stops at .git)
Also accepts stories.yml and stories.json

Client setup guides

Cloud mode (optional)

If you use the Locus platform for team sync, set these environment variables to enable cloud mode:

Variable	Description
`PROTOTYPER_API_KEY`	Supabase user JWT (from Locus web app → Settings → API Keys)
`PROTOTYPER_SUPABASE_URL`	Your Supabase project URL
`PROTOTYPER_PROJECT_ID`	Default project UUID (optional — avoids passing `project_id` to every call)

Cloud mode config example:

json

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@locus-dev/mcp-server"],
      "env": {
        "PROTOTYPER_API_KEY": "your-jwt",
        "PROTOTYPER_SUPABASE_URL": "https://your-project.supabase.co",
        "PROTOTYPER_PROJECT_ID": "optional-project-uuid"
      }
    }
  }
}

If PROTOTYPER_API_KEY and PROTOTYPER_SUPABASE_URL are both set, cloud mode activates automatically. Otherwise, file mode is used.

Environment variables

Variable	Mode	Description
`LOCUS_STORIES_PATH`	File	Explicit path to `stories.yaml` (overrides auto-discovery)
`PROTOTYPER_API_KEY`	Cloud	Supabase user JWT
`PROTOTYPER_SUPABASE_URL`	Cloud	Supabase project URL
`PROTOTYPER_PROJECT_ID`	Cloud	Default project UUID

Tools

`list_stories`

List user stories with optional filters.

code

list_stories(status="not-implemented", section="Leave Management")

Parameters:

project_id (optional) — file mode: always local; cloud mode: defaults to PROTOTYPER_PROJECT_ID
status — not-implemented | partial | implemented | stale | deprecated | all (default: all)
section — case-insensitive partial match on story section

`get_story`

Get full detail for a single story.

code

get_story(story_id="US-04")

Parameters:

story_id (required) — e.g. US-01, AUTH-03
project_id (optional)

Returns: Full story YAML including description and acceptance criteria.

`get_active_story`

Get the story currently being implemented — partial status first, then first not-implemented.

Used by Story Guard to check whether an agent action is in scope.

code

get_active_story()

`mark_story_status`

Update the implementation status of a story.

In file mode, writes directly to stories.yaml. In cloud mode, syncs to the Locus platform.

code

mark_story_status(story_id="US-01", status="implemented", notes="PR #47 — LeaveRequestForm")

Parameters:

story_id (required)
status (required) — not-implemented | partial | implemented | stale | deprecated
notes (optional) — PR number, component name, known limitations

`find_stories`

Full-text search across titles, descriptions, and acceptance criteria.

code

find_stories(query="authentication")

`get_coverage`

Implementation coverage summary — total stories, counts by status, overall percentage.

code

get_coverage()

`create_story`

Add a new story to stories.yaml. Use when you discover behaviour in the codebase with no story covering it, or when specifying a new feature before implementation begins.

In file mode, writes directly to stories.yaml with validation. Auto-generates a unique story ID if one is not provided.

code

create_story(
  title="User can export transactions as CSV",
  description="Users can download their transaction history as a CSV file for external reporting.",
  section="Transactions",
  acceptance_criteria=[
    "Export button visible on /transactions page",
    "CSV includes date, amount, and description columns",
    "File downloads as transactions-YYYY-MM-DD.csv"
  ]
)

Parameters:

title (required) — verb-first: "User can X"
description (required) — what the user can do and why
section (required) — feature area; if omitted, existing sections are listed to guide your choice
id (optional) — e.g. US-07; auto-generated from existing prefix if omitted
status (optional) — not-implemented | partial | implemented (default: not-implemented)
acceptance_criteria (optional) — list of testable conditions; at least 2 recommended
depends_on (optional) — story IDs that must be implemented first; validated against existing IDs

Validation:

Duplicate ID prevention with next-available-ID suggestion
ID format enforced: PREFIX-NUMBER (e.g. US-01, BT-12)
depends_on cross-reference check — errors if referenced IDs don't exist
Advisory warning if fewer than 2 acceptance criteria are provided

`suggest_stories`

Analyse a git diff or a set of source files and suggest user stories that are missing from stories.yaml. Use before implementing a feature, when reviewing a PR, or when auditing coverage.

code

suggest_stories(
  diff="git diff HEAD~1..HEAD -- src/auth/",
  context="This diff adds OAuth2 login via Google"
)

code

suggest_stories(
  files=["src/payments/checkout.ts", "src/payments/invoice.ts"]
)

Parameters:

diff (optional) — a git diff string to analyse
files (optional) — list of source file paths to read and analyse
context (optional) — additional context to guide story generation
project_id (optional)

Returns: 3–5 draft stories with titles, descriptions, sections, and acceptance criteria in YAML. Pass each suggestion directly to create_story to add them to stories.yaml.

`link_pr`

Associate a pull request with the stories it implements or references. Writes pr_refs to each story in stories.yaml, creating an audit trail between PRs and stories.

Call this when opening or merging a PR with story_ids set to all stories the PR contributes to.

code

link_pr(
  pr_url="https://github.com/org/repo/pull/142",
  pr_number=142,
  pr_title="feat: broadcast pre-peg-in transaction",
  story_ids=["BT-07", "BT-08"],
  link_type="implements",
  state="merged"
)

Parameters:

pr_url (required) — full GitHub PR URL
pr_number (required) — PR number
story_ids (required) — array of story IDs this PR implements or references
pr_title (optional) — PR title
link_type (optional) — implements | partial | refs (default: implements)
state (optional) — open | merged | closed (default: open)
merged_at (optional) — ISO 8601 timestamp
repo (optional) — owner/repo; auto-extracted from pr_url if omitted

Result in stories.yaml:

yaml

stories:
  - id: BT-07
    title: Broadcast pre-peg-in transaction
    # ...
    pr_refs:
      - pr_url: https://github.com/org/repo/pull/142
        pr_number: 142
        pr_title: 'feat: broadcast pre-peg-in transaction'
        link_type: implements
        state: merged

Re-running with the same pr_url updates the existing entry rather than duplicating it.

Story Guard

Story Guard fires after every agent action to check whether the action is within the active story's acceptance criteria.

Setup

Create .claude/settings.json in your project root:

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "mcp_tool",
            "tool": "locus/get_active_story",
            "description": "Story Guard: check action scope against active story acceptance criteria"
          }
        ]
      }
    ]
  }
}

This fires get_active_story() after every tool call — file writes, bash commands, and external API calls. The agent sees the active story's acceptance criteria and can determine whether its last action was in scope.

Why it matters

In April 2026, a Cursor AI coding agent deleted a production database and all its backups in 9 seconds — because it had no story contract to check its own actions against. Story Guard is the structural answer: the intent contract lives upstream, before execution, where the agent can reason about its own scope.

Typical session flow

Developer starts a Claude Code session with Locus MCP connected
Developer says: "Implement the Leave Management stories"
Claude calls list_stories(status="not-implemented", section="Leave Management") — sees the specs from stories.yaml
Claude implements each story, calls get_story for detail when needed
When done, calls mark_story_status(story_id="US-03", status="implemented", notes="PR #52") — writes back to stories.yaml
The spec and its status are now both in the repo

Story schema

Stories follow the Locus open schema (YAML, v1.1).

Minimal stories.yaml:

yaml

version: "1.1"
project:
  id: my-project
  name: My Project
stories:
  - id: US-01
    title: User can sign up
    description: New users can create an account with email and password
    section: Authentication
    status: not-implemented
    acceptance_criteria:
      - Email field validates format before submission
      - Password must be at least 8 characters
      - Successful signup redirects to /dashboard

License

Install

Configuration

Environment variables

PROTOTYPER_API_KEYsecret

Optional: Locus API key for cloud team sync. Prefix ptmcp_. Not required for local stories.yaml mode.

PROTOTYPER_PROJECT_ID

Optional: Locus project UUID for cloud team sync.

LOCUS_STORIES_PATH

Optional: Explicit path to stories.yaml. Defaults to auto-discovery from project root.

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@locus-dev/mcp-server@0.6.1"
      ],
      "env": {
        "PROTOTYPER_API_KEY": "<YOUR_PROTOTYPER_API_KEY>",
        "PROTOTYPER_PROJECT_ID": "<YOUR_PROTOTYPER_PROJECT_ID>",
        "LOCUS_STORIES_PATH": "<YOUR_LOCUS_STORIES_PATH>"
      }
    }
  }
}