@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):

{
  "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

1. Add a stories.yaml file to your project root (see schema docs)
2. Add the MCP server to your AI client config (above)
3. 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:

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

---

Client setup guides

• Claude Code
• Cursor
• OpenAI Codex CLI
• Windsurf
• Zed
• Continue.dev
• GitHub Copilot (VS Code)

---

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:

{
  "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.

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.

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.

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.

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.

find_stories(query="authentication")

---

get_coverage

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

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.

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.

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

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.

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:

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:

{
  "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

1. Developer starts a Claude Code session with Locus MCP connected
2. Developer says: "Implement the Leave Management stories"
3. Claude calls list_stories(status="not-implemented", section="Leave Management") — sees the specs from stories.yaml
4. Claude implements each story, calls get_story for detail when needed
5. When done, calls mark_story_status(story_id="US-03", status="implemented", notes="PR #52") — writes back to stories.yaml
6. 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:

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

MIT © Jony Bursztyn