Product Requirements Document: Unleash MCP Server

Overview

Product Name: Unleash MCP Server Version: 1.0.0 Status: Phase 3 Complete - Full Feature Set Last Updated: 2025-10-28

Vision

Enable LLM-powered coding assistants to act as purpose-driven coding buddies that keep risky changes safely gated behind Unleash feature flags. The MCP server provides a focused surface area for creating, evaluating, and wrapping code changes with feature flags while maintaining Unleash best practices.

Goals

Simplify feature flag creation - Reduce ceremony around creating flags via Admin API
Guide best practices - Surface Unleash recommendations at the right moments
Accelerate adoption - Generate code snippets that follow existing patterns
Maintain quality - Validate inputs, normalize errors, stream progress

Non-Goals

Generic API explorer for all Unleash endpoints
Full-featured Unleash UI replacement
Flag analytics or reporting dashboard
User management or permissions administration

Target Users

Primary: LLM coding assistants (Claude, GPT-4, etc.) via MCP protocol
Secondary: Developers using MCP-enabled tools who want programmatic flag management
Tertiary: Teams adopting feature flag workflows who need guided rollout strategies

Phase 1: Completed ✅

Scope

Build the foundation and implement the create_flag tool.

What Was Delivered

1. Project Infrastructure

Package Management: Yarn-based project with TypeScript
Build System: TypeScript compiler with strict mode, ES2022 target
Testing Framework: Vitest configured (no tests yet)
Development Tools:
- yarn dev - Development mode with tsx
- yarn build - Production build
- yarn lint - Type checking
- yarn test - Test runner

2. Configuration System (`src/config.ts`)

Features:

Environment variable loading via .env file
CLI flag support (--dry-run, --log-level)
Zod schema validation with helpful error messages
Optional default project/environment configuration

Environment Variables:

UNLEASH_BASE_URL (required) - Unleash instance URL
UNLEASH_PAT (required) - Personal Access Token
UNLEASH_DEFAULT_PROJECT (optional) - Default project for flag creation
UNLEASH_DEFAULT_ENVIRONMENT (optional) - Reserved for future use

CLI Flags:

--dry-run - Simulate operations without API calls
--log-level <level> - Set logging verbosity (debug|info|warn|error)

3. Unleash Admin API Client (`src/unleash/client.ts`)

Features:

Minimal client focused on flag creation endpoint only
Native fetch API (Node 18+) - no external HTTP dependencies
Dry-run mode support for safe testing
PAT authentication
Comprehensive error handling with detailed messages

Endpoints Implemented:

POST /api/admin/projects/{projectId}/features - Create feature flag

Types:

FeatureFlagType: release | experiment | operational | kill-switch | permission
CreateFeatureFlagRequest - Input payload
CreateFeatureFlagResponse - API response

4. Error Handling (`src/utils/errors.ts`)

Features:

Normalized error format: {code, message, hint}
Zod validation error translation
HTTP error parsing with status-specific hints
Custom error class for domain errors

Error Hints Include:

401: Check PAT token
403: Verify permissions
404: Check project ID
409: Flag name conflict
422: Invalid parameters
429: Rate limiting
5xx: Server errors

5. Streaming Utilities (`src/utils/streaming.ts`)

Features:

Progress notifications via MCP protocol
Resource link creation for created flags
Formatted success/error messages
Dry-run message formatting

6. Shared Context (`src/context.ts`)

Features:

Centralized runtime context for all tools
Logger with configurable levels
Helper functions:
- ensureProjectId() - Project ID resolution
- handleToolError() - Consistent error handling
- createLogger() - Level-based logging

7. Feature Flag Create Tool (`src/tools/featureFlagCreate.ts`)

Input Schema:

{
  projectId?: string,      // Optional if default set
  name: string,            // Required, unique per project
  type: FeatureFlagType,   // Required
  description: string,     // Required
  impressionData?: boolean // Optional, defaults to false
}

Features:

Zod input validation
Progress streaming (0% → 100%)
Default project ID resolution
Comprehensive tool description with best practices
Resource URI generation
Dry-run support

Output:

Success message with flag URL
Resource URI for programmatic access
Error messages with hints for recovery

8. MCP Server (`src/index.ts`)

Features:

MCP SDK integration
Stdio transport for communication
Tool registration and routing
Startup logging and configuration display
Graceful error handling

9. Documentation

README.md:

Installation and setup instructions
Environment variable reference
Usage examples
CLI flag documentation
Best practices from Unleash docs
Troubleshooting guide
Architecture overview
Roadmap for future phases

.env.example:

Template with all configuration options
Helpful comments for each variable
PAT generation instructions

Technical Achievements

✅ Full TypeScript with strict mode - zero type errors
✅ Comprehensive error handling with user-friendly hints
✅ Progress streaming for operation visibility
✅ Dry-run mode for safe testing
✅ Purpose-driven architecture - minimal dependencies
✅ Best practices embedded in tool descriptions
✅ Clean separation of concerns (config, client, tools, utils)

Quality Metrics

Type Safety: 100% - All code fully typed, strict mode enabled
Build Status: ✅ Passing - No compilation errors
Dependencies: Minimal - Only @modelcontextprotocol/sdk, zod, dotenv
Documentation: Comprehensive - README, inline comments, JSDoc

Phase 2: Evaluation Guidance (Planned)

Objective

Guide LLMs on when to create feature flags and what rollout strategy to use.

Scope

1. `evaluate_change` Prompt

Purpose: Analyze code changes and provide authoritative guidance on flag usage.

Inputs (Optional JSON):

{
  repository?: string,      // Repo context
  branch?: string,          // Current branch
  files?: string[],         // Modified files
  riskLevel?: string,       // User-assessed risk
  impact?: string,          // Expected impact area
  notes?: string           // Additional context
}

Output Guidance Should Include:

Flag Recommendation: Should a flag be created? (Yes/No/Maybe)
Flag Type Suggestion: Which type best fits this change?
Rollout Strategy: Suggested steps (dev enablement, percentage rollout, etc.)
Risk Assessment: Identified risks and mitigation strategies
Next Action: Which tool to call next (create_flag or wrap_change)
Best Practice References: Links to relevant Unleash documentation

Tone: Proactive, authoritative, aligned with Unleash best practices

Key Features:

Pattern matching for common risky changes (DB schema, auth, payments, etc.)
Rollout sequencing recommendations (dev → staging → production)
Flag lifecycle guidance (when to remove, how long to keep)
Ownership recommendations (who should manage this flag)

2. Best Practices Knowledge Base

File: src/docs/unleashBestPractices.ts or similar

Content:

Condensed guidance from https://docs.getunleash.io/topics/feature-flags/best-practices-using-feature-flags-at-scale
Flag lifecycle management
Cleanup strategies
Rollout sequencing patterns
Common anti-patterns to avoid

Purpose: Allow prompts/tools to reference best practices without re-fetching

TODO: Phase 2 Tasks

Phase 3: Completed ✅

Objective

Generate language-specific code snippets that wrap changes behind feature flags, following existing project conventions.

What Was Delivered

1. `wrap_change` Tool

Purpose: Return code snippets for guarding changes with feature flags.

Inputs:

{
  flagName: string,             // Required: Feature flag name
  language?: string,            // Optional: Programming language (auto-detected from fileName)
  fileName?: string,            // Optional: File name to help detect language
  codeContext?: string,         // Optional: Surrounding code for pattern detection
  frameworkHint?: string        // Optional: React, Express, Django, etc.
}

Features Implemented:

✅ Multi-language snippet templates (8 languages)
✅ Search instructions for finding existing patterns
✅ Pattern detection guidance (via LLM-driven search)
✅ Convention awareness (match imports, method names, wrapping styles)
✅ Framework-specific templates (React, Express, Django, Rails, etc.)
✅ Comprehensive wrapping guidance with examples

Output: Returns a comprehensive markdown document containing:

Quick start with recommended pattern
Search instructions for finding existing flag patterns
Wrapping instructions with placeholders
All available templates for the detected language
SDK documentation links
Best practices checklist

2. Language Detection Module (`src/templates/languages.ts`)

Implemented:

✅ Auto-detection from file extensions
✅ Manual language specification support
✅ Language metadata (SDK info, common methods, client names)
✅ 9 supported languages:
- TypeScript/JavaScript (Node, React, Vue, Angular)
- Python (FastAPI, Django, Flask)
- Go
- Ruby (Rails)
- PHP (Laravel)
- C# (.NET/ASP.NET)
- Java (Spring Boot)
- Rust (Actix/Rocket)

3. Wrapper Templates Module (`src/templates/wrapperTemplates.ts`)

Implemented Patterns per Language:

✅ If-block: Standard conditional execution
✅ Guard clause: Early return pattern
✅ Hook: React hooks with JSX conditional
✅ Ternary: Single-line conditional
✅ Decorator: Python/TypeScript decorator pattern
✅ Middleware: Express/Go/Rust middleware pattern

Template Coverage:

✅ TypeScript: 4 patterns (if-block, guard, hook, ternary)
✅ JavaScript: 4 patterns (if-block, guard, hook, ternary)
✅ Python: 3 patterns (if-block, guard, decorator)
✅ Go: 3 patterns (if-block, guard, middleware)
✅ Ruby: 2 patterns (if-block, guard)
✅ PHP: 2 patterns (if-block, guard)
✅ C#: 2 patterns (if-block, guard)
✅ Java: 2 patterns (if-block, guard)
✅ Rust: 2 patterns (if-block, guard)

4. Search Guidance Generator (`src/templates/searchGuidance.ts`)

Implemented:

✅ Step-by-step search instructions using Grep
✅ Language-specific regex patterns from flagDetectionPatterns.ts
✅ Pattern analysis guidance (imports, client names, methods, wrapping styles)
✅ Default fallbacks when no patterns found
✅ Full file reading instructions for context
✅ Pattern matching instructions

5. Integration & Registration

Completed:

✅ Tool registered in MCP server (src/index.ts)
✅ Integrated with server context
✅ Progress token support (optional)
✅ Comprehensive error handling
✅ Structured content output for programmatic use

Technical Achievements

✅ Full TypeScript with strict mode - zero type errors
✅ Language-agnostic design supporting 9 languages
✅ Prompt-based approach (LLM performs pattern detection)
✅ No network calls - pure template generation (fast)
✅ Reuses existing flagDetectionPatterns for consistency
✅ Framework-aware templates
✅ Comprehensive documentation in README

Quality Metrics

Type Safety: 100% - All code fully typed
Build Status: ✅ Passing - No compilation errors
Language Coverage: 9 languages with 20+ total templates
Documentation: Comprehensive - Tool description, README section, inline comments

Cross-Phase Tasks

Documentation

Create docs/architecture.md explaining purpose-driven design
Create docs/contributing.md with contribution guidelines
Add inline code comments where logic is complex
Create examples directory with sample MCP conversations

Testing

Write unit tests for config loading
Write unit tests for error normalization
Write unit tests for Unleash client
Write integration tests for create_flag
Add test coverage reporting
Set up CI/CD for automated testing

Quality & Maintenance

Developer Experience

Add debug mode with verbose logging
Create sample .env files for different scenarios
Add example MCP client configurations
Create troubleshooting runbook
Add telemetry (optional, opt-in)

Security & Compliance

Security audit of dependencies
Add dependency scanning (Dependabot)
Document security best practices
Add rate limiting considerations
Token rotation guidance

Success Metrics

Phase 1 (Completed ✅)

Zero TypeScript compilation errors
Successful build output
All required configuration options documented
Error handling covers all common cases
README provides clear setup instructions

Phase 2 (Planned)

Evaluation prompt provides actionable guidance in >90% of cases
Risk assessment matches developer intuition in manual review
Rollout recommendations align with Unleash best practices
Users can follow prompt guidance to successful flag creation

Phase 3 (Completed ✅)

Generated snippets compile/run without modification
Pattern detection guidance helps LLMs identify conventions
Support for 9 programming languages (exceeded goal)
Users can copy-paste snippets directly into their codebase
Framework-specific templates for major frameworks

Overall

LLM assistants can complete full flag workflow without human intervention
Average time to create and wrap a flag: <2 minutes
Error messages enable self-service recovery
Documentation comprehensiveness score: >8/10

Technical Debt & Known Limitations

Current Limitations

Single Endpoint: Only supports flag creation, not updates or deletion
No Validation: Project ID existence not validated before API call
No Tests: Framework configured but no tests written
No Strategies: Cannot configure rollout strategies during creation
No Variants: Cannot create variants during flag creation
No Tags: Cannot assign tags to flags
Stdio Only: Only supports stdio transport (no HTTP/SSE)

Planned Improvements

Expand API Coverage (Post-Phase 3):
- Update existing flags
- Delete/archive flags
- List existing flags
- Configure strategies and variants
Enhanced Validation:
- Pre-flight project existence check
- Flag name availability check
- Duplicate detection with suggestions
Richer Features:
- Tag assignment during creation
- Initial strategy configuration
- Variant creation
- Constraint configuration

Dependencies

Production Dependencies

@modelcontextprotocol/sdk (^1.0.4) - MCP protocol implementation
zod (^3.24.1) - Schema validation
dotenv (^16.4.7) - Environment variable loading

Development Dependencies

typescript (^5.7.2) - TypeScript compiler
@types/node (^22.10.2) - Node.js type definitions
tsx (^4.19.2) - TypeScript execution
vitest (^2.1.8) - Testing framework

Dependency Strategy

Minimize external dependencies
Use native Node.js APIs where possible (fetch vs axios)
Keep dependencies updated (Dependabot recommended)
Audit regularly for security vulnerabilities

Risk Assessment

Technical Risks

Risk	Probability	Impact	Mitigation
Unleash API changes break client	Low	High	Pin API version, add integration tests, monitor Unleash changelog
MCP protocol changes	Medium	High	Pin SDK version, follow MCP updates, test against new releases
PAT token security	Medium	Critical	Document secure storage, support token rotation, never log tokens
Rate limiting from Unleash	Low	Medium	Implement backoff, add rate limit handling, document limits
Large codebases crash pattern detection	Medium	Low	Add timeout, limit context size, graceful degradation

Product Risks

Risk	Probability	Impact	Mitigation
LLMs don't follow guidance	Medium	High	Iterative prompt improvement, clear action items, examples
Generated code doesn't match project style	Medium	Medium	Improve pattern detection, provide customization options
Users create too many flags (sprawl)	High	Medium	Evaluation prompt warns about reuse, tracks flag rationale
Flags not cleaned up after rollout	High	High	Lifecycle reminders in prompts, flag age tracking (future)

Open Questions

Phase 2

Should evaluate_change have access to git history to detect risky patterns?
How should we handle multi-service architectures in rollout recommendations?
Should we integrate with existing project management tools for flag tracking?

Phase 3

How do we handle frameworks/languages we don't have templates for?
Should we support custom template injection by users?
How granular should pattern detection be (file-level vs. project-level)?

General

Should we add telemetry to understand usage patterns? (Privacy concerns)
Do we need a local cache for created flags to prevent duplicates?
Should we support other MCP transports (HTTP, SSE) beyond stdio?

References

Version History

v0.1.1 (2025-11-18) - Support GitHub MCP registry
v0.1.0 (2025-11-17) - Beta release
- All core capabilities implemented: create_flag, detect_flag, evaluate_change, wrap_change
- 9 programming languages supported
- 20+ code templates across multiple frameworks
- Comprehensive pattern detection guidance
v0.0.4 (2025-11-05) - new tools (detect-flag, cleanup_flag, set_flag_rollout, etc.)
v0.0.3 (2025-10-30) - minor logging improvements
v0.0.2 (2025-10-30) - minor code improvements
v0.0.1 (2025-10-30) - Phase 1 complete: Foundation and create_flag tool

FilesExpand file tree

PRD.md

Latest commit

History

PRD.md

File metadata and controls

Product Requirements Document: Unleash MCP Server

Overview

Vision

Goals

Non-Goals

Target Users

Phase 1: Completed ✅

Scope

What Was Delivered

1. Project Infrastructure

2. Configuration System (src/config.ts)

3. Unleash Admin API Client (src/unleash/client.ts)

4. Error Handling (src/utils/errors.ts)

5. Streaming Utilities (src/utils/streaming.ts)

6. Shared Context (src/context.ts)

7. Feature Flag Create Tool (src/tools/featureFlagCreate.ts)

8. MCP Server (src/index.ts)

9. Documentation

Technical Achievements

Quality Metrics

Phase 2: Evaluation Guidance (Planned)

Objective

Scope

1. evaluate_change Prompt

2. Best Practices Knowledge Base

TODO: Phase 2 Tasks

Phase 3: Completed ✅

Objective

What Was Delivered

1. wrap_change Tool

2. Language Detection Module (src/templates/languages.ts)

3. Wrapper Templates Module (src/templates/wrapperTemplates.ts)

4. Search Guidance Generator (src/templates/searchGuidance.ts)

5. Integration & Registration

Technical Achievements

Quality Metrics

Cross-Phase Tasks

Documentation

Testing

Quality & Maintenance

Developer Experience

Security & Compliance

Success Metrics

Phase 1 (Completed ✅)

Phase 2 (Planned)

Phase 3 (Completed ✅)

Overall

Technical Debt & Known Limitations

Current Limitations

Planned Improvements

Dependencies

Production Dependencies

Development Dependencies

Dependency Strategy

Risk Assessment

Technical Risks

Product Risks

Open Questions

Phase 2

Phase 3

General

References

Version History

2. Configuration System (`src/config.ts`)

3. Unleash Admin API Client (`src/unleash/client.ts`)

4. Error Handling (`src/utils/errors.ts`)

5. Streaming Utilities (`src/utils/streaming.ts`)

6. Shared Context (`src/context.ts`)

7. Feature Flag Create Tool (`src/tools/featureFlagCreate.ts`)

8. MCP Server (`src/index.ts`)

1. `evaluate_change` Prompt

1. `wrap_change` Tool

2. Language Detection Module (`src/templates/languages.ts`)

3. Wrapper Templates Module (`src/templates/wrapperTemplates.ts`)

4. Search Guidance Generator (`src/templates/searchGuidance.ts`)