@locus-dev/mcp-server

@locus-dev/mcp-server

Give your AI coding assistant the product context it's missing.

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

stories.yaml belongs to you. 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

• 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

• Cursor
• OpenAI Codex CLI
• 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()

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

• 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:

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