User Stories

Open Source — GitScrum MCP Server is open source under the MIT license. Available on npm and GitHub. Model Context Protocol server for GitScrum — Claude, GitHub Copilot, Cursor, and any MCP-compatible client full operational access to your project management stack.

The user_story tool provides 5 actions for managing user stories — the building blocks of agile requirements. User stories capture what your users need in a structured format ("As a [role], I want [capability], so that [benefit]"), and the MCP Server lets your AI assistant create, update, search, and organize them without leaving your IDE or AI client.

User stories in GitScrum serve as the bridge between high-level epics and actionable tasks. Each user story defines a requirement that can be broken down into one or more tasks on the Kanban board. Through the MCP Server, your AI assistant can build entire requirement hierarchies — from epics to user stories to tasks — in a single conversation.

Actions Overview

Listing User Stories

The list action returns all user stories within a specific project. Each user story in the response includes its uuid, title, description, priority, and linked task count. This gives your AI assistant the full picture of the project's requirements landscape.

Use this action to review the backlog, check requirement coverage, or identify stories that need further breakdown into tasks.

Required Parameters

Example Prompts

You:  "List all user stories in the Backend project"
AI:   Calls user_story action=list → returns all stories with titles, priorities, and task counts

You:  "Show me the requirements backlog"
AI:   Calls user_story action=list → returns the full user story list for the current project

You:  "How many user stories do we have in the Mobile project?"
AI:   Calls user_story action=list → counts and summarizes the results

Getting User Story Details

The get action returns the complete user story object, including description, acceptance criteria, priority, linked tasks, and all metadata. This is the action to call when you need the full context of a specific requirement.

Required Parameters

You:  "Show me the details of the password reset user story"
AI:   Finds the story via list/search → calls user_story action=get → returns full details

You:  "What are the acceptance criteria for the authentication story?"
AI:   Calls user_story action=get → extracts and presents acceptance criteria

Creating User Stories

The create action builds a new user story in a single call. You can set the title, description, priority, and acceptance criteria at creation time. The AI assistant can infer the user story format from your natural language — you don't need to follow the "As a... I want... So that..." template literally, though it's recommended for clarity.

Required Parameters

Optional Parameters

Example Prompts

You:  "Create a user story 'As a user, I want to reset my password so that
       I can regain access to my account'"
AI:   Calls user_story action=create with title, company_slug, project_slug

You:  "Create a high-priority story for two-factor authentication with acceptance
       criteria: must support TOTP and SMS"
AI:   Calls user_story action=create with title, priority="high",
      acceptance_criteria="- [ ] Support TOTP\n- [ ] Support SMS"

You:  "Add a user story for the Dashboard project: 'As a manager, I want to
       export reports as PDF so that I can share them with stakeholders'.
       Include description about supported formats."
AI:   Calls user_story action=create with title, description, company_slug, project_slug

You:  "Create a story about real-time notifications with detailed acceptance criteria"
AI:   Calls user_story action=create with title, acceptance_criteria containing
      specific conditions as a Markdown checklist

Updating User Stories

The update action modifies any field on an existing user story. Only the fields you specify are changed — all other fields remain untouched. This is useful for refining requirements as the team learns more, adjusting priorities during backlog grooming, or adding acceptance criteria after initial story creation.

Required Parameters

Optional Parameters

All optional parameters from create are available in update: title, description, priority, acceptance_criteria.

Example Prompts

You:  "Update the password reset story to high priority"
AI:   Finds the story → calls user_story action=update with priority="high"

You:  "Add acceptance criteria to the authentication story:
       must validate email format and enforce password complexity"
AI:   Calls user_story action=update with acceptance_criteria

You:  "Rename the notifications story to 'Real-time Push Notifications'"
AI:   Calls user_story action=update with title="Real-time Push Notifications"

You:  "Add more context to the export story description"
AI:   Gets current description → calls user_story action=update with expanded description

Searching User Stories

The search action finds user stories by keyword across title, description, and acceptance criteria. This is faster than listing all stories and filtering client-side — the search happens server-side and returns only matching results.

Required Parameters

Example Prompts

You:  "Search for user stories about authentication"
AI:   Calls user_story action=search with q="authentication" → returns matching stories

You:  "Find stories related to payment processing"
AI:   Calls user_story action=search with q="payment" → returns relevant stories

You:  "Are there any user stories mentioning API rate limiting?"
AI:   Calls user_story action=search with q="rate limiting" → returns results or empty set

Linking User Stories to Tasks

User stories gain their real power when linked to tasks on the Kanban board. When creating a task through the task tool, you can pass the userstoryslug parameter to associate the task with a specific user story. This creates a traceable chain from requirement to implementation.

Workflow: From Requirement to Implementation

You:  "Create a user story for user password reset"
AI:   Calls user_story action=create → returns the new story with its slug

You:  "Now break it down into tasks: validate email, send reset link,
       handle token expiration, update password"
AI:   Calls task action=create four times, each with user_story_slug
      pointing to the password reset story

You:  "Show me all tasks linked to the password reset story"
AI:   Calls task action=filter with user_story=[story slug]
      → returns all implementation tasks

This workflow ensures every task traces back to a business requirement, making sprint reviews and stakeholder reporting straightforward. The AI assistant handles the slug resolution — you reference stories by name, and the MCP server maps them to the correct identifiers.

Requirements Planning Workflow

For teams using MCP-driven requirements management, this workflow covers the full planning cycle:

1. Define user stories from stakeholder input

Translate business requirements into structured user stories.

You:  "We need password reset, two-factor auth, and session management.
       Create user stories for each."
AI:   Creates three user stories with appropriate titles and descriptions

2. Add acceptance criteria

Refine each story with specific, testable criteria.

You:  "Add acceptance criteria to all three stories"
AI:   Updates each story with detailed acceptance criteria checklists

3. Break down into tasks

Convert stories into implementable tasks on the Kanban board.

You:  "Break the password reset story into development tasks"
AI:   Creates tasks linked to the story via user_story_slug

4. Track coverage

Verify that all stories have implementation tasks.

You:  "Which user stories have no tasks yet?"
AI:   Lists stories → cross-references with task filter → identifies gaps

Next Steps

• Epics: Group user stories into strategic epics for high-level planning.
• Tasks: Create and manage the tasks that implement user stories.
• Sprints: Plan sprints around prioritized user stories.
• Quick Start: Set up the MCP server if you haven't already.