SoloFlow MCP Server

A Model Context Protocol (MCP) server for project document management with 32 comprehensive prompts covering the complete software development lifecycle.

English | 中文

Features

• 🚀 MCP Protocol Support: Complete Model Context Protocol implementation
• 📁 Document Management: Automatically manage project documents in .soloflow/ directory
• 🔧 Four Core Operations: list, read, update, init
• 🎯 32 Comprehensive Prompts: Built-in prompts covering the entire software development lifecycle
• 🛡️ Security Isolation: Path isolation based on projectRoot
• 📝 Markdown Support: Complete Markdown document format support
• 🎯 Cursor Integration: Perfect support for Cursor IDE integration
• ⚡ Lightweight: Only stdio transport support, no HTTP dependencies

Quick Start

1. Configure Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "soloflow-mcp": {
      "command": "npx",
      "args": ["@benyue1978/soloflow-mcp"]
    }
  }
}

2. Initialize Project

# Run in project root directory
npx @benyue1978/soloflow-mcp init /path/to/your/project

3. Start Using

In Cursor, AI assistants can now:

• List project documents: list operation
• Read document content: read operation
• Update document content: update operation
• Initialize project configuration: init operation
• Use 32 comprehensive prompts for software development lifecycle

Comprehensive Prompt System

SoloFlow MCP provides 32 prompts organized into 8 categories, covering the complete software development lifecycle:

📊 Prompt Categories Overview

Category	Count	Description
Core	4	Essential project management functions
Role	5	Specialized functions for different development roles
Task	6	Advanced task management and breakdown functions
Requirements	3	Requirements analysis and management functions
Design	5	Comprehensive design functions
Development	4	Code implementation and development functions
Testing	5	Testing and quality assurance functions
Release	5	Complete release and deployment lifecycle management

🎯 Scenario-Based Usage Guide

Scenario 1: New Project Setup

Goal: Initialize a new project with proper documentation and workspace setup

Prompt Sequence:

1. /soloflow-mcp/core/init-project - Initialize project documentation structure
2. /soloflow-mcp/core/setup-workspace - Set up development environment with technology stack
3. /soloflow-mcp/requirements/analyze-requirements - Analyze and document requirements
4. /soloflow-mcp/requirements/prioritize-requirements - Prioritize requirements using MoSCoW method
5. /soloflow-mcp/task/breakdown-requirements - Break down requirements into manageable tasks

Example Usage:

# In Cursor chat, type:
/soloflow-mcp/core/init-project
/soloflow-mcp/core/setup-workspace --frontend React --backend Node.js --testing Jest --deployment Docker --database PostgreSQL
/soloflow-mcp/requirements/analyze-requirements --domain e-commerce --scope full-system

Scenario 2: Requirements Analysis Phase

Goal: Comprehensive requirements gathering and analysis

Prompt Sequence:

1. /soloflow-mcp/role/analyst-mode - Switch to analyst mode for requirements focus
2. /soloflow-mcp/requirements/analyze-requirements - Comprehensive requirements analysis
3. /soloflow-mcp/requirements/validate-requirements - Validate requirements completeness
4. /soloflow-mcp/requirements/prioritize-requirements - Prioritize using value-complexity matrix
5. /soloflow-mcp/task/create-epic - Create high-level epics from requirements

Example Usage:

# In Cursor chat, type:
/soloflow-mcp/role/analyst-mode
/soloflow-mcp/requirements/analyze-requirements --domain finance --scope full-system
/soloflow-mcp/requirements/validate-requirements --validationType comprehensive

Scenario 3: System Design Phase

Goal: Design system architecture, UI, and data models

Prompt Sequence:

1. /soloflow-mcp/role/architect-mode - Switch to architect mode for design focus
2. /soloflow-mcp/design/system-architecture - Design overall system architecture
3. /soloflow-mcp/design/api-interface - Design API interfaces and contracts
4. /soloflow-mcp/design/database-schema - Design database schema and data models
5. /soloflow-mcp/design/create-ui - Design user interface and user experience
6. /soloflow-mcp/design/review-design - Review and validate design decisions

Example Usage:

# In Cursor chat, type:
/soloflow-mcp/role/architect-mode
/soloflow-mcp/design/system-architecture --architectureType microservices
/soloflow-mcp/design/api-interface --apiType REST
/soloflow-mcp/design/database-schema --dbType PostgreSQL

Scenario 4: Development Phase

Goal: Implement features with proper code quality and testing

Prompt Sequence:

1. /soloflow-mcp/role/developer-mode - Switch to developer mode for implementation focus
2. /soloflow-mcp/task/breakdown-architecture - Break down architecture into implementation tasks
3. /soloflow-mcp/development/write-code - Implement features with best practices
4. /soloflow-mcp/development/code-review-checklist - Use code review checklist
5. /soloflow-mcp/testing/write-unit-tests - Write comprehensive unit tests
6. /soloflow-mcp/development/fix-bug - Debug and fix issues as they arise

Example Usage:

# In Cursor chat, type:
/soloflow-mcp/role/developer-mode
/soloflow-mcp/development/write-code --feature user-authentication --language TypeScript --framework Express
/soloflow-mcp/testing/write-unit-tests --component auth-service --language TypeScript --framework Jest
/soloflow-mcp/development/code-review-checklist --codeLanguage TypeScript

Scenario 5: Testing Phase

Goal: Comprehensive testing strategy and execution

Prompt Sequence:

1. /soloflow-mcp/role/tester-mode - Switch to tester mode for quality focus
2. /soloflow-mcp/testing/create-test-plan - Create comprehensive test plan
3. /soloflow-mcp/testing/write-unit-tests - Write unit tests for all components
4. /soloflow-mcp/testing/run-tests - Execute tests and analyze results
5. /soloflow-mcp/testing/test-report - Generate detailed test reports
6. /soloflow-mcp/testing/performance-test - Conduct performance testing

Example Usage:

# In Cursor chat, type:
/soloflow-mcp/role/tester-mode
/soloflow-mcp/testing/create-test-plan --feature payment-system --testType comprehensive
/soloflow-mcp/testing/run-tests --testType all --environment staging
/soloflow-mcp/testing/performance-test --component api-gateway --loadType stress

Scenario 6: Release Management

Goal: Safe and reliable deployment with monitoring

Prompt Sequence:

1. /soloflow-mcp/role/project-manager-mode - Switch to project manager mode for coordination
2. /soloflow-mcp/release/commit-changes - Commit changes with proper conventions
3. /soloflow-mcp/release/create-release - Create software release with versioning
4. /soloflow-mcp/release/deployment-checklist - Use deployment checklist
5. /soloflow-mcp/release/monitor-deployment - Monitor deployment status
6. /soloflow-mcp/release/rollback-plan - Prepare rollback plan if needed

Example Usage:

# In Cursor chat, type:
/soloflow-mcp/role/project-manager-mode
/soloflow-mcp/release/commit-changes --commitType feat --scope user-authentication
/soloflow-mcp/release/create-release --version 1.2.0 --releaseType minor
/soloflow-mcp/release/deployment-checklist --environment production

Scenario 7: Bug Fixing and Maintenance

Goal: Efficient bug fixing and code maintenance

Prompt Sequence:

1. /soloflow-mcp/development/fix-bug - Analyze and fix bugs
2. /soloflow-mcp/development/refactor-code - Refactor code for better maintainability
3. /soloflow-mcp/testing/run-tests - Run tests to ensure fixes work
4. /soloflow-mcp/release/commit-changes - Commit fixes with proper messages
5. /soloflow-mcp/core/generate-docs - Update documentation for changes

Example Usage:

# In Cursor chat, type:
/soloflow-mcp/development/fix-bug --bugDescription "User login fails with 500 error" --severity high
/soloflow-mcp/development/refactor-code --component auth-service --reason "Improve error handling"
/soloflow-mcp/core/generate-docs --docType api --component authentication

Scenario 8: Project Management and Coordination

Goal: Effective project management and team coordination

Prompt Sequence:

1. /soloflow-mcp/role/project-manager-mode - Switch to project manager mode
2. /soloflow-mcp/task/add-task - Add new tasks to project
3. /soloflow-mcp/task/estimate-tasks - Estimate time and effort for tasks
4. /soloflow-mcp/task/create-story - Create detailed user stories
5. /soloflow-mcp/core/check-project-status - Check overall project status
6. /soloflow-mcp/task/create-epic - Organize tasks into epics

Example Usage:

# In Cursor chat, type:
/soloflow-mcp/role/project-manager-mode
/soloflow-mcp/task/add-task --taskTitle "Implement OAuth integration" --priority high --category backend --estimatedTime 3d
/soloflow-mcp/task/estimate-tasks
/soloflow-mcp/core/check-project-status

📋 Complete Prompt Reference

Core Functions (4 prompts)

• /soloflow-mcp/core/init-project - Initialize project documentation structure
• /soloflow-mcp/core/check-project-status - Check project status and documentation completeness
• /soloflow-mcp/core/generate-docs - Generate comprehensive documentation for current implementation
• /soloflow-mcp/core/setup-workspace - Set up project workspace with technology stack

Role-based Functions (5 prompts)

• /soloflow-mcp/role/analyst-mode - Switch to analyst mode for requirements analysis
• /soloflow-mcp/role/architect-mode - Switch to architect mode for system design
• /soloflow-mcp/role/developer-mode - Switch to developer mode for implementation
• /soloflow-mcp/role/tester-mode - Switch to tester mode for quality assurance
• /soloflow-mcp/role/project-manager-mode - Switch to project manager mode for coordination

Task Management (6 prompts)

• /soloflow-mcp/task/add-task - Add new tasks to project
• /soloflow-mcp/task/breakdown-requirements - Break down requirements into tasks
• /soloflow-mcp/task/breakdown-architecture - Break down architecture into implementation tasks
• /soloflow-mcp/task/create-epic - Create large-scale feature epics
• /soloflow-mcp/task/create-story - Create detailed user stories
• /soloflow-mcp/task/estimate-tasks - Estimate time and effort for tasks

Requirements Analysis (3 prompts)

• /soloflow-mcp/requirements/analyze-requirements - Comprehensive requirements analysis
• /soloflow-mcp/requirements/validate-requirements - Validate requirements completeness
• /soloflow-mcp/requirements/prioritize-requirements - Prioritize requirements using various methods

Design Functions (5 prompts)

• /soloflow-mcp/design/create-ui - Design user interface and user experience
• /soloflow-mcp/design/system-architecture - Design overall system architecture
• /soloflow-mcp/design/api-interface - Design API interfaces and contracts
• /soloflow-mcp/design/database-schema - Design database schema and data models
• /soloflow-mcp/design/review-design - Review and validate design decisions

Development Functions (4 prompts)

• /soloflow-mcp/development/write-code - Implement features with best practices
• /soloflow-mcp/development/fix-bug - Debug and fix code issues
• /soloflow-mcp/development/refactor-code - Refactor code for better maintainability
• /soloflow-mcp/development/code-review-checklist - Use comprehensive code review checklist

Testing Functions (5 prompts)

• /soloflow-mcp/testing/create-test-plan - Create comprehensive test plans
• /soloflow-mcp/testing/write-unit-tests - Write unit tests for components
• /soloflow-mcp/testing/run-tests - Execute tests and analyze results
• /soloflow-mcp/testing/test-report - Generate detailed test reports
• /soloflow-mcp/testing/performance-test - Conduct performance testing

Release Management (5 prompts)

• /soloflow-mcp/release/commit-changes - Commit changes with proper conventions
• /soloflow-mcp/release/create-release - Create software releases with versioning
• /soloflow-mcp/release/deployment-checklist - Use deployment preparation checklist
• /soloflow-mcp/release/rollback-plan - Prepare rollback plans
• /soloflow-mcp/release/monitor-deployment - Monitor deployment status

Supported Document Types

Document Type	Filename	Purpose
overview	overview.md	Project overview and summary
requirements	requirements.md	Functional and non-functional requirements
system_architecture	system_architecture.md	Technical architecture design
test_strategy	test_strategy.md	Testing strategy and plans
tasks	tasks.md	Project task lists and progress
ui_design	ui_design.md	UI/UX design specifications
deployment	deployment.md	Deployment and infrastructure docs
notes	notes.md	Project notes and observations

MCP Operations

Core Operations

list - List Documents

List all documents in the .soloflow/ directory:

{
  "name": "list",
  "description": "List all documents in the .soloflow directory",
  "inputSchema": {
    "projectRoot": "string - Absolute path to project root"
  }
}

Response Example:

[
  {
    "type": "requirements",
    "title": "Project Requirements",
    "filename": "requirements.md"
  },
  {
    "type": "tasks", 
    "title": "Project Tasks",
    "filename": "tasks.md"
  }
]

read - Read Document

Read content of a specific document type:

{
  "name": "read",
  "description": "Read document content by type",
  "inputSchema": {
    "projectRoot": "string - Absolute path to project root",
    "type": "string - Document type (overview, requirements, etc.)"
  }
}

Response Example:

{
  "raw": "# Project Requirements\n\n## Functional Requirements\n1. User management\n2. Data storage"
}

update - Update Document

Create or update document content:

{
  "name": "update",
  "description": "Create or update document content",
  "inputSchema": {
    "projectRoot": "string - Absolute path to project root",
    "type": "string - Document type (overview, requirements, etc.)",
    "content": "string - Document content in Markdown format"
  }
}

Response Example:

{
  "ok": true,
  "message": "Document updated successfully"
}

init - Initialize Project

Initialize project configuration, create .cursor/rules/soloflow.mdc file:

{
  "name": "init",
  "description": "Initialize project configuration",
  "inputSchema": {
    "projectRoot": "string - Absolute path to project root"
  }
}

Response Example:

{
  "message": "Project initialized successfully. Created .cursor/rules/soloflow.mdc"
}

Security Features

Path Isolation

• All operations require projectRoot parameter
• Strict absolute path validation
• Protection against path traversal attacks
• Project root directory must exist

Document Type Validation

• Predefined document type whitelist
• Strict type validation
• Prevention of arbitrary file access

Error Handling

• Detailed error messages
• Graceful failure handling
• Secure default behavior

Development

Local Development

# Clone repository
git clone https://github.com/benyue1978/solo-flow-mcp.git
cd solo-flow-mcp

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Start development server
npm start

Project Structure

├── src/
│   ├── index.ts              # Service startup entry
│   ├── context.ts            # Path validation and utility functions
│   ├── tools/                # MCP operation handlers
│   │   ├── list.ts          # List documents
│   │   ├── read.ts          # Read documents
│   │   ├── update.ts        # Update documents
│   │   └── init.ts          # Initialize project
│   ├── prompts/              # Comprehensive prompt system
│   │   ├── core-prompts.ts  # Core project management prompts
│   │   ├── role-prompts.ts  # Role-based prompts
│   │   ├── task-prompts.ts  # Task management prompts
│   │   ├── requirements-prompts.ts # Requirements analysis prompts
│   │   ├── design-prompts.ts # Design and architecture prompts
│   │   ├── development-prompts.ts # Development and coding prompts
│   │   ├── testing-prompts.ts # Testing and QA prompts
│   │   ├── release-prompts.ts # Release and deployment prompts
│   │   ├── docs-prompts.ts  # Documentation prompts
│   │   ├── workspace-prompts.ts # Workspace setup prompts
│   │   ├── categories.ts    # Prompt categories
│   │   ├── mapping.ts       # Path mapping system
│   │   └── index.ts         # Prompt registry
│   ├── types/
│   │   └── docTypes.ts      # Document type definitions
│   └── resources/
│       └── soloflow-content.ts # Resource file content
├── tests/                    # Test files
│   ├── unit/                # Unit tests
│   ├── integration/         # Integration tests
│   └── utils/               # Test utilities
└── .soloflow/               # Project documentation

Testing

Run All Tests

npm test

Run Specific Tests

# Unit tests
npm run test:unit

# Integration tests
npm run test:integration

# Coverage tests
npm run test:coverage

Test Coverage

• Unit tests: 50 test cases
• Integration tests: mcp-inspector integration
• Coverage target: > 85%

Usage Examples

Example 1: Initialize Project

# In project root directory
npx @benyue1978/soloflow-mcp init /Users/username/my-project

Example 2: Create Requirements Document

# Create requirements document via MCP operation
npx @benyue1978/soloflow-mcp update \
  --projectRoot /Users/username/my-project \
  --type requirements \
  --content "# Project Requirements\n\n## Functional Requirements\n1. User authentication\n2. Data persistence"

Example 3: Using in Cursor

1. Configure Cursor settings
2. Initialize project
3. In Cursor, AI assistants can:
   • List project documents
   • Read document content
   • Update document content
   • Manage project configuration
   • Use 32 comprehensive prompts for software development lifecycle

Example 4: Using Prompts in Cursor

1. Configure Cursor settings (as shown above)

2. In Cursor's chat dialog, type any of the 32 prompts:

   • /soloflow-mcp/core/init-project - Initialize project documentation
   • /soloflow-mcp/requirements/analyze-requirements - Analyze requirements
   • /soloflow-mcp/design/system-architecture - Design system architecture
   • /soloflow-mcp/development/write-code - Write code with best practices
   • /soloflow-mcp/testing/create-test-plan - Create test plans
   • /soloflow-mcp/release/commit-changes - Commit changes properly

3. The AI will automatically execute the prompt and update your project documentation

Troubleshooting

Common Issues

Q: Why do we need absolute paths? A: For security isolation, ensuring the MCP service can only access the specified project directory.

Q: How to reset project configuration? A: Delete the .cursor/rules/soloflow.mdc file, then run the init operation again.

Q: What document formats are supported? A: Currently supports Markdown format, other formats may be supported in the future.

Q: How to handle concurrent writes? A: Current version uses simple file system operations, it's recommended to avoid concurrent writes to the same document.

Q: How to use prompts effectively? A: Use prompts in sequence following the software development lifecycle. Start with core functions, then move to specific phases like requirements, design, development, testing, and release.

Error Codes

Error	Cause	Solution
Project root directory does not exist	Project root directory doesn't exist	Ensure path is correct and directory exists
Invalid document type	Document type not in whitelist	Use predefined document types
Document content cannot be empty	Document content is empty	Provide valid document content

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the project
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License - see LICENSE file for details

Changelog

v1.1.0

• Major version bump with enhanced project documentation management
• Update all internal project documents to reflect v1.0.6 features and v1.1.0 status
• Improve package.json with better description and metadata
• Enhance project structure with comprehensive documentation updates
• Add detailed technical specifications and architecture documentation
• Update deployment and test strategy documentation
• Improve project notes with comprehensive development history
• Ensure all 8 core documents are synchronized with latest project status
• Maintain 50 test cases with 100% pass rate
• Complete bilingual documentation support (English and Chinese)

v1.0.6

• Add comprehensive bilingual documentation support with Chinese README
• Add language selection links between English and Chinese README files
• Add 32 comprehensive prompts covering entire software development lifecycle
• Add scenario-based usage guide with 8 common development scenarios
• Add role-based prompts for different development roles
• Add requirements analysis, design, development, testing, and release management prompts
• Add git_commit.mdc rule file for standardized Git commit messages
• Create git-commit-content.ts with embedded git commit guidelines
• Update init tool to automatically create git_commit.mdc during project initialization
• Enhance project setup with Git commit message conventions
• Follow consistent pattern for rule file creation and management

v1.0.5

• Add comprehensive prompt system with 32 prompts covering entire software development lifecycle
• Add scenario-based usage guide with 8 common development scenarios
• Add role-based prompts for different development roles
• Add requirements analysis, design, development, testing, and release management prompts
• Add git_commit.mdc rule file for standardized Git commit messages
• Create git-commit-content.ts with embedded git commit guidelines
• Update init tool to automatically create git_commit.mdc during project initialization
• Enhance project setup with Git commit message conventions
• Follow consistent pattern for rule file creation and management

v1.0.4

• Update soloflow.mdc content with latest MCP Prompts and Read Before Update rules
• Sync soloflow-content.ts with latest documentation guidelines
• Improve ordered list formatting for MD029 compliance
• Enhance documentation structure and best practices

v1.0.2

• Add comprehensive project documentation (overview, ui_design, deployment, notes)
• Update README.md with detailed prompts usage guide
• Add Cursor integration examples for direct prompt usage
• Improve documentation structure and user experience

v1.0.1

• Add six core prompts for software engineering best practices
• Add test coverage
• Add Cursor integration support
• Add NPM package release

v1.0.0

• Initial version release
• Support for list, read, update, init operations
• Complete test suite
• Cursor integration support
• NPM package release

Contact

• Author: SongYue yuesong@gmail.com
• Project URL: https://github.com/benyue1978/solo-flow-mcp
• NPM Package: https://www.npmjs.com/package/@benyue1978/soloflow-mcp