kgatilin/claude-workflow-example

AI Coding Agent Workflow for MCP Server Development

This project showcases a structured coding agent workflow using Claude to implement a Model Context Protocol (MCP) server for Jira issue retrieval. It demonstrates how to leverage AI agents to streamline development through standardized commands and task management.

What is an MCP Server?

The Model Context Protocol (MCP) is a system that allows AI agents to securely interact with tools and services, giving Claude "hands" to work with your local files, GitHub repositories, databases, and external APIs. An MCP server provides standardized access to specific functionality - in this case, retrieving Jira issue information.

MCP servers enable AI agents to:

• Access real-time data from external services
• Perform actions on behalf of users through standardized interfaces
• Integrate with existing tools and workflows securely
• Provide context-aware assistance based on live data

How to Install Claude

Installation

Claude Code CLI is the command-line interface that enables AI-powered development workflows.

Prerequisites:

• Node.js 18.0.0 or higher
• 4GB RAM minimum
• Active internet connection

Installation:

npm install -g @anthropic-ai/claude-code

Platform Support:

• macOS: Works natively on macOS 10.15+
• Linux: Ubuntu 20.04+/Debian 10+ supported
• Windows: Requires WSL2 (Windows Subsystem for Linux)

Windows WSL Setup:

# Enable WSL
wsl --install

# Or use PowerShell installer
irm https://claude.ai/install.ps1 | iex

Official Documentation: Claude Code Setup Guide

Authentication Options

After installing Claude Code CLI, you need to choose how to authenticate and access Claude models:

Option 1: Subscription (Recommended for Regular Use)

• Fixed monthly cost with higher usage limits
• Most economical for frequent Claude Code usage (Pro or Max plans)
• Automatic authentication through Anthropic account
• Setup: Sign up at claude.ai and run claude to authenticate

Option 2: Direct API Access (Pay-per-Use)

• Pay only for what you use
• Good for occasional usage or testing
• Setup:
  1. Visit Anthropic Console
  2. Sign up/login to your account
  3. Navigate to Settings → API Keys
  4. Click "Create Key" and claim free credits ($5 for 14 days)
  5. Configure your environment:

     export ANTHROPIC_API_KEY="your-api-key"
     

• Pricing:
  • Input: $3-15 per million tokens (depending on model)
  • Output: $15-75 per million tokens

Option 3: Enterprise Cloud Backends

Amazon Bedrock:

• Enterprise deployment with AWS infrastructure
• Claude Opus 4 and Sonnet 4 available
• Regions: US East/West, APAC, Europe
• Setup:

  export CLAUDE_CODE_USE_BEDROCK=1
  export AWS_REGION=us-east-1
  

• Documentation: Claude on Amazon Bedrock

Google Cloud Vertex AI:

• Enterprise deployment with GCP infrastructure
• Available through Vertex AI Model Garden
• Setup:

  gcloud config set project YOUR-PROJECT-ID
  gcloud services enable aiplatform.googleapis.com
  export CLAUDE_CODE_USE_VERTEX=1
  

• Setup Guide: Claude on Google Vertex AI
• Official GCP Documentation: Anthropic Claude models on Vertex AI
• Required IAM role: roles/aiplatform.user

Getting Started

First-time Setup: On first run, Claude Code will prompt for authentication:

claude
# Follow browser authentication flow for subscription/API
# Or ensure environment variables are set for cloud backends

Using Claude Code: Navigate to your project directory and launch Claude:

cd your-project-directory
claude

Claude Code provides an interactive terminal interface where you can:

• Ask questions about your codebase in natural language
• Request features to be built from descriptions
• Debug and fix issues by describing problems
• Navigate and understand complex codebases

Official Getting Started Guide: Claude Code Overview

How to Use the Workflow

This project implements a structured workflow with five main commands that guide you through implementing an MCP server from requirements to completion.

Command Sequence

This is a collaborative human-AI workflow, not automation. Each command must be manually invoked by you after reviewing the previous stage's output. The AI assistant accelerates development by 10x while you maintain complete control over when and how to proceed.

First, launch Claude Code in your project directory:

cd your-project-directory
claude

Then execute the workflow with human oversight at each stage:

# 1. Initialize task from backlog
/workflow:init_task @.agent/backlog/jira-get-issue-mcp.md

📋 Review & Decide: Examine the generated business requirements in 00_task.md. Validate acceptance criteria, modify requirements if needed. When satisfied, run the next command.

# 2. Create implementation plan
/workflow:plan

🏗️ Review & Decide: Examine the technical plan in 01_implementation_plan.md. Verify architecture decisions, assess complexity, adjust approach if needed. When the strategy looks good, proceed to implementation.

# 3. Implement the feature with TDD
/workflow:implement

⚡ Review & Decide: Test the implementation, run the code, verify functionality matches requirements. The AI builds fast, but you ensure it builds right. When ready, run the review.

# 4. Review implementation against requirements
/workflow:review [additional-focus-areas]

🔍 Review & Decide: Evaluate the comprehensive review findings in 03_review.md. If fixes are needed, run the fix command. If satisfied, you're done.

# 5. Fix any issues found in review (if needed)
/workflow:review_fix

✅ Review & Decide: Validate that fixes address the identified issues without introducing new problems. Repeat review cycle as needed.

Key Principles:

• Human judgment drives decisions - AI provides options, you choose the path
• Review every output - Fast generation requires careful validation
• Iterative improvement - Use feedback to refine results at each stage
• Quality gate enforcement - Don't proceed until each stage meets your standards

Command Descriptions

1. /workflow:init_task - Task Initialization

Purpose: Transform brief backlog items into comprehensive business requirements

What it does:

• Creates a feature branch for the task
• Sets up standardized task folder structure (/.agent/tasks/[task-name]/)
• Expands brief requirements into detailed user stories
• Researches external dependencies and current versions
• Creates comprehensive acceptance criteria
• Focuses exclusively on business requirements (what to build, not how)

Output: 00_task.md with complete business requirements

Supporting Scripts:

• .claude/scripts/init_task_setup.sh - Creates feature branches, task directories, and stage tracking

2. /workflow:plan - Implementation Planning

Purpose: Create detailed technical implementation plan with systems architecture approach

What it does:

• Analyzes task complexity (simple vs. complex)
• Designs system architecture with component relationships
• Creates mermaid diagrams for data/control flow
• Maps acceptance criteria to specific tests
• Defines implementation tasks in executable order
• Determines iteration strategy (single vs. multiple iterations)

Output: 01_implementation_plan.md with detailed technical plan

3. /workflow:implement - TDD Implementation

Purpose: Implement features using Test-Driven Development with minimal essential tests

What it does:

• Follows pragmatic TDD: test behavior, not implementation
• Writes one focused test per acceptance criteria
• Implements simplest code to pass tests
• Tracks progress with TodoWrite tool
• Creates working software incrementally
• Avoids over-engineering (YAGNI principle)

Output: Complete implementation with test coverage and 02_implementation_log.md

Supporting Scripts:

• .claude/scripts/get_current_task_context.sh - Extracts current task info from git branch and folder structure

4. /workflow:review [additional-review-focus] - Quality Review

Purpose: Review implementation against task requirements and planned architecture

Arguments:

• additional-review-focus (optional): Specific areas to focus on during review (e.g., "security", "performance", "error handling")

What it does:

• Launches 5 parallel specialized review agents:
  • Code Quality: maintainability, readability, idiomaticity
  • Test Quality: coverage, clarity, behavior focus
  • Architecture Alignment: compliance with planned design
  • Acceptance Criteria: requirement fulfillment verification
  • Security & Performance: vulnerability and bottleneck analysis
• Synthesizes findings into binary classification (Must Fix vs. Future Improvement)
• Verifies all acceptance criteria are met with corresponding tests
• Makes APPROVED/REQUIRES FIXES decision

Output: 03_review.md with comprehensive assessment and decision

Supporting Scripts:

• .claude/scripts/find_review_comments.sh - Identifies unresolved review comments across the codebase
• .claude/scripts/get_current_task_context.sh - Provides task context for review scope

5. /workflow:review_fix - Issue Resolution

Purpose: Address blocking issues identified in review before proceeding

What it does:

• Focuses only on "Must Fix" issues that block requirements
• Implements targeted fixes without scope creep
• Re-runs verification tests
• Updates implementation log with fixes applied

Output: Updated code and 04_fixes_applied.md

Supporting Utility Commands

In addition to the main workflow commands, several utility commands are available:

/utility:new_command - Create new custom slash commands

• Takes command name and purpose as arguments
• Follows Claude 4 prompt engineering best practices
• Automatically determines required tools and structure

/utility:improve_command - Enhance existing slash commands

• Accepts feedback to improve command functionality
• Maintains consistency with established patterns

/utility:update_project_rules - Update CLAUDE.md project guidelines

• Adds new rules or guidance while maintaining structure
• Ensures project-specific instructions are preserved

Slash Command Syntax

Slash commands use a frontmatter-based syntax with specific structure:

Frontmatter Format

---
allowed-tools: Read, Write, Bash, WebSearch
argument-hint: <command-name> <purpose>
description: Brief description of command purpose
model: claude-sonnet-4-0  # Specify model explicitly
---

Bash Command Integration

Commands can execute bash scripts using the ! prefix:

## Setup Context
!`.claude/scripts/init_task_setup.sh $ARGUMENTS`

File References

Reference documentation using the @ prefix:

Read @docs/mcp_app_guide.md for implementation patterns
Based on @.claude/snippets/agents-workflow.md

Argument Handling

Commands access arguments through variables:

- `$ARGUMENTS` - All arguments as single string
- `$1`, `$2`, etc. - Individual positional arguments

Command Organization

.claude/commands/
├── workflow/          # Task workflow commands
│   ├── init_task.md
│   ├── plan.md
│   ├── implement.md
│   ├── review.md
│   └── review_fix.md
└── utility/           # General utility commands
    ├── new_command.md
    ├── improve_command.md
    └── update_project_rules.md

Testing the MCP Server

Prerequisites

1. Environment Configuration Create a .env file in your project root:

   JIRA_BASE_URL=https://your-domain.atlassian.net
   JIRA_EMAIL=your-email@company.com
   JIRA_API_TOKEN=your-api-token
   

2. Jira API Token Setup

   • Go to Atlassian Account Settings
   • Click "Create API token"
   • Copy the token to your .env file

Testing Methods

Method 1: MCP Inspector (Recommended)

The MCP Inspector provides a visual testing interface for MCP servers:

1. Build your MCP server:

   npm run build
   

2. Start MCP Inspector:

   npx @modelcontextprotocol/inspector node dist/index.js .env
   

3. Test in browser:

   • Inspector runs on http://localhost:6274 (client) and http://localhost:6277 (proxy)
   • Click "▶︎Connect" to connect to your MCP server
   • Use the Tools tab to test get_jira_issue with valid issue keys (e.g., "PROJ-123")
   • Verify responses contain summary, description, status, and assignee fields
   • Test error handling with invalid issue keys

Features:

• Interactive testing of Resources, Prompts, and Tools
• Real-time connection status
• Visual schema validation
• Session tokens for security

Method 2: Claude Code MCP Configuration

Configure Claude Code to use your MCP server locally:

1. Build your MCP server:

   npm run build
   

2. Add MCP server to Claude Code:

   # Using CLI command (recommended)
   claude mcp add jira-server --scope local -- node dist/index.js .env
   
   # Or create .claude.json manually:
   {
     "mcpServers": {
       "jira": {
         "command": "node",
         "args": ["dist/index.js", ".env"]
       }
     }
   }
   

3. Restart Claude Code and test:

   claude
   # In conversation: "Get me details for Jira issue PROJ-123"
   

Configuration file locations:

• Primary: .claude.json in project directory (local scope)
• Alternative: ~/.claude.json (global scope)

Method 3: VS Code MCP Configuration

Configure VS Code with GitHub Copilot Chat extension:

1. Install GitHub Copilot Chat extension from VS Code marketplace

2. Add MCP server configuration:

   # Use Command Palette: "MCP: Add Server"
   # Or create .vscode/mcp.json manually:
   {
     "mcpServers": {
       "jira": {
         "command": "node",
         "args": ["dist/index.js", ".env"]
       }
     }
   }
   

3. Enable MCP in settings:

   • Open VS Code settings
   • Enable Chat > Mcp > Discovery
   • Enable Chat > Mcp

4. Test in VS Code:

   • Open Copilot Chat panel
   • Ask: "@jira get details for issue PROJ-123"

Configuration locations:

• Workspace: .vscode/mcp.json (project-specific)
• Global: Use "MCP: Open User Configuration" command

Required Environment Parameters

Verification Steps

1. Server starts successfully:

   node dist/index.js .env
   # Should output: "MCP server running on stdio"
   

   Note: The .env file path is required as the first argument.

2. Tool responds to valid input:

   • Issue key format: PROJ-123 (project key + hyphen + number)
   • Returns JSON with summary, description, status, assignee fields

3. Error handling works:

   • Invalid issue keys return appropriate error messages
   • Authentication failures provide clear feedback
   • Network issues are handled gracefully

4. Response time acceptable:

   • Requests complete within 5 seconds
   • No timeout errors under normal conditions

Project Structure

├── .agent/                             # Agent workflow system
│   ├── backlog/                        # Task backlog items (submitted)
│   ├── tasks/                          # Task execution logs (not submitted)
│   │   └── jira-get-issue-mcp/         # Example task documentation
│   │       ├── 00_task.md              # Business requirements
│   │       ├── 01_implementation_plan.md # Technical plan
│   │       ├── 02_implementation_log.md # Implementation details
│   │       ├── 03_review.md            # Quality review results
│   │       └── stage.yaml              # Workflow stage tracking
│   └── templates/                      # Task templates (submitted)
├── .claude/                            # Claude Code configuration
│   ├── commands/                       # Slash command definitions
│   │   ├── workflow/                   # Main workflow commands
│   │   └── utility/                    # Helper commands
│   ├── scripts/                        # Supporting bash scripts
│   ├── snippets/                       # Reusable code snippets
│   └── prompts/                        # Prompt templates
├── docs/                               # Documentation
├── CLAUDE.md                           # Claude Code instructions
├── package.json                        # Node.js dependencies
├── tsconfig.json                       # TypeScript configuration
├── .env                                # Environment variables (local)
└── README.md                           # This file

Note: This project showcases the workflow structure and commands. What gets submitted to the repository:

• .agent/backlog/ - Task definitions
• .claude/commands/ - Workflow commands
• .claude/scripts/ - Supporting scripts
• Documentation and configuration

What is generated during workflow execution (not submitted):

• .agent/tasks/ - Task execution logs
• src/ and tests/ - Actual implementation code

Getting Started

1. Clone this repository to see the complete workflow example
2. Install Claude using one of the methods above
3. Run the workflow on your own backlog item:

   # Create your backlog file
   echo "Build an MCP server for [your use case]" > .agent/backlog/my-task.md
   
   # Start the workflow
   /workflow:init_task @.agent/backlog/my-task.md
   

4. Follow the command sequence to implement your own MCP server
5. Test with MCP Inspector to verify functionality

This workflow demonstrates how AI coding agents can streamline development through structured processes, comprehensive planning, and quality assurance - all while maintaining focus on user requirements and business value.