This is page 1 of 18. Use http://codebase.md/minipuft/claude-prompts-mcp?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .actrc
├── .gitattributes
├── .github
│ └── workflows
│ ├── ci.yml
│ ├── mcp-compliance.yml
│ └── pr-validation.yml
├── .gitignore
├── agent.md
├── assets
│ └── logo.png
├── CLAUDE.md
├── config
│ └── framework-state.json
├── docs
│ ├── architecture.md
│ ├── chain-modification-examples.md
│ ├── contributing.md
│ ├── enhanced-gate-system.md
│ ├── execution-architecture-guide.md
│ ├── installation-guide.md
│ ├── mcp-tool-usage-guide.md
│ ├── mcp-tools-reference.md
│ ├── prompt-format-guide.md
│ ├── prompt-management.md
│ ├── prompt-vs-template-guide.md
│ ├── README.md
│ ├── template-development-guide.md
│ ├── TODO.md
│ ├── troubleshooting.md
│ └── version-history.md
├── LICENSE
├── local-test.sh
├── plans
│ ├── nunjucks-dynamic-chain-orchestration.md
│ ├── outputschema-realtime-progress-and-validation.md
│ ├── parallel-conditional-execution-analysis.md
│ ├── sqlite-storage-migration.md
│ └── symbolic-command-language-implementation.md
├── README.md
├── scripts
│ ├── setup-windows-testing.sh
│ ├── test_server.js
│ ├── test-all-platforms.sh
│ └── windows-tests
│ ├── test-windows-paths.js
│ ├── test-windows-startup.sh
│ └── windows-env.sh
└── server
├── config
│ ├── framework-state.json
│ └── tool-descriptions.json
├── config.json
├── jest.config.cjs
├── LICENSE
├── package-lock.json
├── package.json
├── prompts
│ ├── analysis
│ │ ├── advanced_analysis_engine.md
│ │ ├── content_analysis.md
│ │ ├── deep_analysis.md
│ │ ├── deep_research.md
│ │ ├── markdown_notebook.md
│ │ ├── note_integration.md
│ │ ├── note_refinement.md
│ │ ├── notes.md
│ │ ├── progressive_research.md
│ │ ├── prompts.json
│ │ ├── query_refinement.md
│ │ └── review.md
│ ├── architecture
│ │ ├── prompts.json
│ │ └── strategic-system-alignment.md
│ ├── content_processing
│ │ ├── format_enhancement.md
│ │ ├── noteIntegration.md
│ │ ├── obsidian_metadata_optimizer.md
│ │ ├── prompts.json
│ │ ├── vault_related_notes_finder.md
│ │ └── video_notes_enhanced.md
│ ├── debugging
│ │ ├── analyze_logs.md
│ │ └── prompts.json
│ ├── development
│ │ ├── analyze_code_structure.md
│ │ ├── analyze_file_structure.md
│ │ ├── code_review_optimization_chain.md
│ │ ├── component_flow_analysis.md
│ │ ├── create_modularization_plan.md
│ │ ├── detect_code_issues.md
│ │ ├── detect_project_commands.md
│ │ ├── expert_code_implementation.md
│ │ ├── generate_comprehensive_claude_md.md
│ │ ├── prompts.json
│ │ ├── strategicImplement.md
│ │ ├── suggest_code_improvements.md
│ │ └── transform_code_to_modules.md
│ ├── documentation
│ │ ├── create_docs_chain.md
│ │ ├── docs-content-creation.md
│ │ ├── docs-content-planning.md
│ │ ├── docs-final-assembly.md
│ │ ├── docs-project-analysis.md
│ │ ├── docs-review-refinement.md
│ │ └── prompts.json
│ ├── education
│ │ ├── prompts.json
│ │ └── vault_integrated_notes.md
│ ├── general
│ │ ├── diagnose.md
│ │ └── prompts.json
│ ├── promptsConfig.json
│ └── testing
│ ├── final_verification_test.md
│ └── prompts.json
├── README.md
├── scripts
│ └── validate-dependencies.js
├── src
│ ├── api
│ │ └── index.ts
│ ├── chain-session
│ │ └── manager.ts
│ ├── config
│ │ └── index.ts
│ ├── Dockerfile
│ ├── execution
│ │ ├── context
│ │ │ ├── context-resolver.ts
│ │ │ ├── framework-injector.ts
│ │ │ └── index.ts
│ │ ├── index.ts
│ │ ├── parsers
│ │ │ ├── argument-parser.ts
│ │ │ ├── index.ts
│ │ │ └── unified-command-parser.ts
│ │ └── types.ts
│ ├── frameworks
│ │ ├── framework-manager.ts
│ │ ├── framework-state-manager.ts
│ │ ├── index.ts
│ │ ├── integration
│ │ │ ├── framework-semantic-integration.ts
│ │ │ └── index.ts
│ │ ├── methodology
│ │ │ ├── guides
│ │ │ │ ├── 5w1h-guide.ts
│ │ │ │ ├── cageerf-guide.ts
│ │ │ │ ├── react-guide.ts
│ │ │ │ └── scamper-guide.ts
│ │ │ ├── index.ts
│ │ │ ├── interfaces.ts
│ │ │ └── registry.ts
│ │ ├── prompt-guidance
│ │ │ ├── index.ts
│ │ │ ├── methodology-tracker.ts
│ │ │ ├── service.ts
│ │ │ ├── system-prompt-injector.ts
│ │ │ └── template-enhancer.ts
│ │ └── types
│ │ ├── index.ts
│ │ ├── integration-types.ts
│ │ ├── methodology-types.ts
│ │ └── prompt-guidance-types.ts
│ ├── gates
│ │ ├── constants.ts
│ │ ├── core
│ │ │ ├── gate-definitions.ts
│ │ │ ├── gate-loader.ts
│ │ │ ├── gate-validator.ts
│ │ │ ├── index.ts
│ │ │ └── temporary-gate-registry.ts
│ │ ├── definitions
│ │ │ ├── code-quality.json
│ │ │ ├── content-structure.json
│ │ │ ├── educational-clarity.json
│ │ │ ├── framework-compliance.json
│ │ │ ├── research-quality.json
│ │ │ ├── security-awareness.json
│ │ │ └── technical-accuracy.json
│ │ ├── gate-state-manager.ts
│ │ ├── guidance
│ │ │ ├── FrameworkGuidanceFilter.ts
│ │ │ └── GateGuidanceRenderer.ts
│ │ ├── index.ts
│ │ ├── intelligence
│ │ │ ├── GatePerformanceAnalyzer.ts
│ │ │ └── GateSelectionEngine.ts
│ │ ├── templates
│ │ │ ├── code_quality_validation.md
│ │ │ ├── educational_clarity_validation.md
│ │ │ ├── framework_compliance_validation.md
│ │ │ ├── research_self_validation.md
│ │ │ ├── security_validation.md
│ │ │ ├── structure_validation.md
│ │ │ └── technical_accuracy_validation.md
│ │ └── types.ts
│ ├── index.ts
│ ├── logging
│ │ └── index.ts
│ ├── mcp-tools
│ │ ├── config-utils.ts
│ │ ├── constants.ts
│ │ ├── index.ts
│ │ ├── prompt-engine
│ │ │ ├── core
│ │ │ │ ├── engine.ts
│ │ │ │ ├── executor.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── types.ts
│ │ │ ├── index.ts
│ │ │ ├── processors
│ │ │ │ ├── response-formatter.ts
│ │ │ │ └── template-processor.ts
│ │ │ └── utils
│ │ │ ├── category-extractor.ts
│ │ │ ├── classification.ts
│ │ │ ├── context-builder.ts
│ │ │ └── validation.ts
│ │ ├── prompt-manager
│ │ │ ├── analysis
│ │ │ │ ├── comparison-engine.ts
│ │ │ │ ├── gate-analyzer.ts
│ │ │ │ └── prompt-analyzer.ts
│ │ │ ├── core
│ │ │ │ ├── index.ts
│ │ │ │ ├── manager.ts
│ │ │ │ └── types.ts
│ │ │ ├── index.ts
│ │ │ ├── operations
│ │ │ │ └── file-operations.ts
│ │ │ ├── search
│ │ │ │ ├── filter-parser.ts
│ │ │ │ └── prompt-matcher.ts
│ │ │ └── utils
│ │ │ ├── category-manager.ts
│ │ │ └── validation.ts
│ │ ├── shared
│ │ │ └── structured-response-builder.ts
│ │ ├── system-control.ts
│ │ ├── tool-description-manager.ts
│ │ └── types
│ │ └── shared-types.ts
│ ├── metrics
│ │ ├── analytics-service.ts
│ │ ├── index.ts
│ │ └── types.ts
│ ├── performance
│ │ ├── index.ts
│ │ └── monitor.ts
│ ├── prompts
│ │ ├── category-manager.ts
│ │ ├── converter.ts
│ │ ├── file-observer.ts
│ │ ├── hot-reload-manager.ts
│ │ ├── index.ts
│ │ ├── loader.ts
│ │ ├── promptUtils.ts
│ │ ├── registry.ts
│ │ └── types.ts
│ ├── runtime
│ │ ├── application.ts
│ │ └── startup.ts
│ ├── semantic
│ │ ├── configurable-semantic-analyzer.ts
│ │ └── integrations
│ │ ├── index.ts
│ │ └── llm-clients.ts
│ ├── server
│ │ ├── index.ts
│ │ └── transport
│ │ └── index.ts
│ ├── smithery.yaml
│ ├── text-references
│ │ ├── conversation.ts
│ │ └── index.ts
│ ├── types
│ │ └── index.ts
│ ├── types.ts
│ └── utils
│ ├── chainUtils.ts
│ ├── errorHandling.ts
│ ├── global-resource-tracker.ts
│ ├── index.ts
│ └── jsonUtils.ts
├── tests
│ ├── ci-startup-validation.js
│ ├── enhanced-validation
│ │ ├── contract-validation
│ │ │ ├── contract-test-suite.js
│ │ │ ├── interface-contracts.js
│ │ │ └── interface-contracts.ts
│ │ ├── environment-validation
│ │ │ ├── environment-parity-checker.js
│ │ │ └── environment-test-suite.js
│ │ ├── lifecycle-validation
│ │ │ ├── lifecycle-test-suite.js
│ │ │ └── process-lifecycle-validator.js
│ │ └── validation-orchestrator.js
│ ├── helpers
│ │ └── test-helpers.js
│ ├── integration
│ │ ├── mcp-tools.test.ts
│ │ ├── server-startup.test.ts
│ │ └── unified-parsing-integration.test.ts
│ ├── performance
│ │ ├── parsing-system-benchmark.test.ts
│ │ └── server-performance.test.ts
│ ├── scripts
│ │ ├── consolidated-tools.js
│ │ ├── establish-performance-baselines.js
│ │ ├── functional-mcp-validation.js
│ │ ├── integration-mcp-tools.js
│ │ ├── integration-routing-system.js
│ │ ├── integration-server-startup.js
│ │ ├── integration-unified-parsing.js
│ │ ├── methodology-guides.js
│ │ ├── performance-memory.js
│ │ ├── runtime-integration.js
│ │ ├── unit-conversation-manager.js
│ │ ├── unit-semantic-analyzer.js
│ │ └── unit-unified-parsing.js
│ ├── setup.ts
│ ├── test-enhanced-parsing.js
│ └── unit
│ ├── conversation-manager.test.ts
│ ├── semantic-analyzer-three-tier.test.ts
│ └── unified-parsing-system.test.ts
├── tsconfig.json
└── tsconfig.test.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Dependencies and Package Management
2 | server/node_modules/
3 | server/package-lock.json
4 | .npm/
5 | .yarn/
6 | .pnp.*
7 | yarn.lock
8 |
9 | # Build Output and TypeScript
10 | server/dist/
11 | build/
12 | out/
13 | *.tsbuildinfo
14 | .tsbuildinfo
15 |
16 | # Environment Variables
17 | server/.env*
18 | .env*
19 |
20 | # Logs and Debug Files
21 | #server/logs/
22 | logs/
23 | *.log
24 | npm-debug.log*
25 | yarn-debug.log*
26 | yarn-error.log*
27 |
28 | # Test Coverage and Reports
29 | coverage/
30 | nyc_output/
31 | .coverage/
32 | junit.xml
33 | test-results/
34 | *.lcov
35 |
36 | # Editor and IDE Files
37 | .vscode/
38 | .cursor/
39 |
40 | # Operating System Files
41 | .DS_Store
42 | .DS_Store?
43 | ._*
44 | .Spotlight-V100
45 | .Trashes
46 | ehthumbs.db
47 | Thumbs.db
48 | *:Zone.Identifier
49 | *.Zone.Identifier
50 |
51 | # Runtime and Cache Files
52 | .cache/
53 | tmp/
54 | temp/
55 | pids/
56 | *.pid
57 | *.seed
58 | *.pid.lock
59 |
60 | # MCP Server Specific
61 | admin-ui/
62 |
63 | # Runtime State Files
64 | # server/config/framework-state.json
65 | # .framework-state.json
66 |
67 | # Runtime State (generated during server execution)
68 | runtime-state/
69 | server/runtime-state/
70 |
71 | # Crash Dumps and Diagnostics
72 | *.dmp
73 | report.*.json
74 | *.diagraw
75 | heapdump-*
76 |
77 | # Claude-Code setup
78 | plans/archive/
79 | CLAUDE.md
80 | .codex/
81 | AGENTS.md
82 | .claude/
83 | server/.claude/
```
--------------------------------------------------------------------------------
/.actrc:
--------------------------------------------------------------------------------
```
1 | # Act Configuration for Claude Prompts MCP
2 | # Optimized for local CI testing with comprehensive platform support and performance enhancements
3 |
4 | # Primary platform mappings - Ubuntu versions
5 | -P ubuntu-latest=catthehacker/ubuntu:act-22.04
6 | -P ubuntu-20.04=catthehacker/ubuntu:act-20.04
7 | -P ubuntu-18.04=catthehacker/ubuntu:act-18.04
8 |
9 | # Windows platform mappings
10 | # Note: True Windows containers require Windows Docker mode; using Ubuntu for cross-platform compatibility
11 | -P windows-latest=catthehacker/ubuntu:act-22.04
12 | -P windows-2022=catthehacker/ubuntu:act-22.04
13 | -P windows-2019=catthehacker/ubuntu:act-22.04
14 |
15 | # macOS platform mappings
16 | # Note: ACT runs Linux containers; macOS simulation through Ubuntu
17 | -P macos-latest=catthehacker/ubuntu:act-22.04
18 | -P macos-13=catthehacker/ubuntu:act-22.04
19 | -P macos-12=catthehacker/ubuntu:act-22.04
20 |
21 | # Environment variables for proper CI simulation
22 | --env ACT=true
23 | --env CI=true
24 | --env NODE_ENV=test
25 |
26 | # Container configuration for better performance
27 | --container-architecture linux/amd64
28 |
29 | # Artifact server configuration
30 | --artifact-server-path /tmp/artifacts
31 |
32 | # Resource limits to prevent container issues
33 | --container-cap-add SYS_PTRACE
34 |
35 | # Networking and Docker integration
36 | --container-daemon-socket /var/run/docker.sock
37 |
38 | # Verbose output for debugging
39 | --verbose
```
--------------------------------------------------------------------------------
/.gitattributes:
--------------------------------------------------------------------------------
```
1 | # Cross-Platform Line Ending Configuration for MCP Claude Prompts Server
2 | # Ensures consistent behavior across Windows, macOS, and Linux development environments
3 |
4 | # Default behavior: normalize line endings to LF on checkin, convert to native on checkout
5 | * text=auto
6 |
7 | # Explicitly declare text files and line ending handling
8 | *.md text
9 | *.json text
10 | *.js text
11 | *.ts text
12 | *.mjs text
13 | *.yml text
14 | *.yaml text
15 | *.txt text
16 | *.html text
17 | *.css text
18 | *.scss text
19 | *.xml text
20 | *.config text
21 | *.gitignore text
22 | *.gitattributes text
23 |
24 | # Shell scripts should always use LF (for cross-platform compatibility)
25 | *.sh text eol=lf
26 | *.bash text eol=lf
27 |
28 | # Windows batch files should use CRLF
29 | *.bat text eol=crlf
30 | *.cmd text eol=crlf
31 |
32 | # Binary files (declare as binary to prevent line ending conversion)
33 | *.png binary
34 | *.jpg binary
35 | *.jpeg binary
36 | *.gif binary
37 | *.ico binary
38 | *.pdf binary
39 | *.zip binary
40 | *.tar binary
41 | *.gz binary
42 | *.7z binary
43 | *.exe binary
44 | *.dll binary
45 | *.so binary
46 | *.dylib binary
47 |
48 | # Node.js specific files
49 | package.json text
50 | package-lock.json text
51 | .nvmrc text
52 | .node-version text
53 |
54 | # Git files
55 | .gitignore text
56 | .gitattributes text
57 | .gitkeep text
58 |
59 | # GitHub and CI/CD files
60 | .github/** text
61 |
62 | # MCP Server specific files
63 | promptsConfig.json text
64 | config.json text
65 | *.mcp text
66 |
67 | # Ensure consistent handling of sensitive files
68 | *.env text
69 | *.key binary
70 | *.pem binary
71 | *.p12 binary
72 | *.pfx binary
73 |
74 | # Documentation files
75 | README* text
76 | LICENSE* text
77 | CHANGELOG* text
78 | CONTRIBUTING* text
79 | *.md text
80 |
81 | # TypeScript and JavaScript configuration
82 | tsconfig.json text
83 | jsconfig.json text
84 | .eslintrc* text
85 | .prettierrc* text
86 | *.config.js text
87 | *.config.ts text
88 |
89 | # Line ending overrides for specific problematic files
90 | # (These patterns help prevent Windows-specific issues)
91 | server/dist/** binary
92 | node_modules/** binary
93 | coverage/** binary
94 | logs/** binary
95 |
96 | # Special handling for files that might cause Windows issues
97 | # Exclude problematic characters and ensure proper encoding
98 | *.log text
99 | *.tmp binary
100 | *.cache binary
101 |
102 | # AI and prompt specific files (ensure proper text handling)
103 | server/prompts/**/*.md text
104 | server/prompts/**/*.json text
```
--------------------------------------------------------------------------------
/docs/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Claude Prompts MCP - Documentation
2 |
3 | ## 🚀 Getting Started
4 |
5 | - [Installation Guide](installation-guide.md) - Setup and configuration instructions
6 | - [Quick Start: Execution Modes](prompt-vs-template-guide.md) - Choose the right execution mode for your needs
7 | - [Troubleshooting](troubleshooting.md) - Common issues and solutions
8 |
9 | ## 📋 Core Concepts
10 |
11 | - [System Architecture](architecture.md) - Overall system design and components
12 | - [Three-Tier Execution System](execution-architecture-guide.md) - **Comprehensive guide** to prompt → template → chain execution model
13 | - [Chain System Analysis](chain-system-analysis.md) - Current chain capabilities, limitations, and future roadmap
14 |
15 | ## 🛠️ Development Guides
16 |
17 | - [Prompt Format Guide](prompt-format-guide.md) - How to create and format custom prompt templates
18 | - [Template Development Guide](template-development-guide.md) - Creating framework-aware templates with methodology integration
19 | - [Prompt Management](prompt-management.md) - Managing prompts and categories in the distributed configuration system
20 | - [Enhanced Gate System](enhanced-gate-system.md) - Quality validation system for templates and chains
21 |
22 | ## 📚 Technical Reference
23 |
24 | - [MCP Tools Reference](mcp-tools-reference.md) - Complete reference for the server's MCP tools
25 | - [Version History](version-history.md) - Complete version history and release notes
26 |
27 | ## 🤝 Contributing
28 |
29 | - [Contributing Guide](contributing.md) - Development and contribution guidelines
30 | - [TODO](TODO.md) - Current development tasks and roadmap
31 |
```
--------------------------------------------------------------------------------
/server/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Prompts Server
2 |
3 | A comprehensive Model Context Protocol (MCP) server that provides AI prompt management with hot-reloading capabilities, workflow orchestration, and enterprise-grade features.
4 |
5 | ## Overview
6 |
7 | The MCP Prompts Server implements a modernized execution architecture with three-tier processing that handles different types of prompt execution:
8 |
9 | - **Direct Prompt Processing**: Lightning-fast variable substitution via UnifiedPromptProcessor (90% of cases)
10 | - **LLM-Driven Chain Execution**: Multi-step workflows orchestrated by ConsolidatedPromptEngine (10% of cases)
11 | - **Framework Integration**: Methodology enhancement (CAGEERF/ReACT/5W1H/SCAMPER) applied contextually
12 |
13 | ## Architecture
14 |
15 | ### ExecutionCoordinator System
16 |
17 | The server uses ExecutionCoordinator as a thin orchestration layer that delegates all execution to ConsolidatedPromptEngine:
18 |
19 | ```typescript
20 | // Phase 3: Delegation-based execution routing
21 | const result = await executionCoordinator.executePrompt(
22 | promptId,
23 | args,
24 | options
25 | );
26 | // All execution delegated to ConsolidatedPromptEngine
27 | ```
28 |
29 | #### Core Components
30 |
31 | 1. **ExecutionCoordinator**: Thin orchestration layer with delegation pattern
32 | 2. **UnifiedPromptProcessor**: Handles 90% of prompt processing with fast variable substitution
33 | 3. **ConsolidatedPromptEngine**: Handles 10% of cases with LLM-driven chain execution and intelligent analysis
34 |
35 | ### Simplified Execution Architecture
36 |
37 | The system supports intelligent routing with three primary execution tiers:
38 |
39 | | Execution Tier | Framework Integration | Processing | Speed | Best For |
40 | | -------------- | ----------------------- | ------------------------ | -------------- | ------------------------------------- |
41 | | **Prompt** | ❌ Bypassed for speed | UnifiedPromptProcessor | Lightning Fast | Basic variable substitution |
42 | | **Template** | ✅ Methodology-aware | ConsolidatedPromptEngine | Smart | Framework-enhanced content generation |
43 | | **Chain** | ✅ Per-step enhancement | ConsolidatedPromptEngine | LLM-Driven | Multi-step workflows |
44 |
45 | #### Execution Flow
46 |
47 | - **Prompt Execution**: Fast path with direct variable substitution via UnifiedPromptProcessor, **bypasses framework injection** for maximum speed
48 | - **Template Execution**: Framework-enhanced processing with **automatic methodology injection** via ConsolidatedPromptEngine based on active framework
49 | - **Chain Execution**: LLM-driven iterative workflows with **per-step framework injection** and state management via ConsolidatedPromptEngine
50 | - **Framework Selection**: Rule-based framework selection using FrameworkManager based on execution type, complexity, and user preference
51 | - **Active Framework Management**: FrameworkStateManager maintains current active framework (default: CAGEERF) with runtime switching capabilities
52 |
53 | For detailed information about choosing the right execution type, see the [Execution Types Guide](../docs/execution-types-guide.md).
54 |
55 | ### Key Components
56 |
57 | - **Application Orchestrator**: Multi-phase startup with comprehensive health monitoring
58 | - **ConsolidatedPromptEngine**: Three-tier execution system with intelligent analysis and LLM-driven chains
59 | - **Template System**: Nunjucks-powered template processing with framework injection
60 | - **Gate System**: Quality validation with framework-aware evaluation
61 | - **Hot-Reload System**: Dynamic prompt updates without server restart
62 |
63 | ### Three-Tier Quality Assurance System
64 |
65 | The server implements an intelligent quality assurance model that adapts to execution type:
66 |
67 | #### Prompt Execution (No Framework, No Gates)
68 |
69 | - **Lightning Fast**: Direct Nunjucks variable substitution
70 | - **Zero Overhead**: Bypasses framework injection and quality gates
71 | - **Best For**: Simple formatting, variable replacement, basic templates
72 |
73 | #### Template Execution (Framework-Enhanced)
74 |
75 | - **Smart Processing**: Rule-based framework selection with conditional injection
76 | - **Methodology Integration**: CAGEERF, ReACT, 5W1H, or SCAMPER framework enhancement based on active framework
77 | - **Quality Validation**: Content validation and framework compliance
78 | - **Best For**: Analysis, reasoning, complex content generation
79 |
80 | #### Chain Execution (LLM-Driven Workflows)
81 |
82 | - **Iterative Processing**: LLM-guided step-by-step execution with intelligent coordination
83 | - **Context Management**: Conversation state and inter-step data flow management
84 | - **Quality Gate Integration**: Framework-aware validation and methodology compliance
85 | - **Best For**: Multi-step processes requiring sequential reasoning and state management
86 |
87 | For detailed gate configuration, see the [Enhanced Gate System Guide](../docs/enhanced-gate-system.md).
88 |
89 | ### Framework System Architecture
90 |
91 | The server implements a sophisticated framework system with systematic methodology application:
92 |
93 | #### Framework Components
94 |
95 | 1. **FrameworkManager** (Stateless): Loads methodology guides and generates framework definitions dynamically
96 | 2. **FrameworkStateManager** (Stateful): Tracks active framework and handles runtime switching with performance monitoring
97 | 3. **FrameworkInjector**: Conditionally injects framework-specific system prompts based on execution tier
98 | 4. **Methodology Guides**: CAGEERF, ReACT, 5W1H, SCAMPER guides providing framework-specific behavior
99 |
100 | #### Framework Selection Process
101 |
102 | ```typescript
103 | // Rule-based framework selection based on criteria
104 | const framework = frameworkManager.selectFramework({
105 | executionType: "template",
106 | complexity: "high",
107 | userPreference: "CAGEERF", // User preference is primary selection factor
108 | });
109 |
110 | // Runtime framework switching
111 | await frameworkStateManager.switchFramework({
112 | targetFramework: "ReACT",
113 | reason: "User preference change",
114 | });
115 | ```
116 |
117 | #### Conditional Framework Injection
118 |
119 | - **Prompt Tier**: Framework injection **bypassed** for maximum execution speed
120 | - **Template Tier**: **Automatic injection** of active framework's system prompt and methodology guidance
121 | - **Chain Tier**: **Per-step injection** allowing different frameworks per chain step
122 |
123 | #### Available Methodologies
124 |
125 | - **CAGEERF**: Comprehensive structured approach (Context, Analysis, Goals, Execution, Evaluation, Refinement, Framework)
126 | - **ReACT**: Reasoning and Acting pattern for systematic problem-solving
127 | - **5W1H**: Who, What, When, Where, Why, How systematic analysis
128 | - **SCAMPER**: Creative problem-solving (Substitute, Combine, Adapt, Modify, Put to other uses, Eliminate, Reverse)
129 |
130 | ## Quick Start
131 |
132 | ### Installation
133 |
134 | ```bash
135 | # Clone or navigate to the project
136 | cd /path/to/claude-prompts-mcp/server
137 |
138 | # Install dependencies
139 | npm install
140 |
141 | # Build TypeScript
142 | npm run build
143 | ```
144 |
145 | ### Claude Desktop Integration (Recommended)
146 |
147 | 1. **Add to Claude Desktop configuration** (typically `~/.claude_desktop_config.json`):
148 |
149 | ```json
150 | {
151 | "mcpServers": {
152 | "claude-prompts-mcp": {
153 | "command": "node",
154 | "args": ["/absolute/path/to/claude-prompts-mcp/server/dist/index.js"]
155 | }
156 | }
157 | }
158 | ```
159 |
160 | 2. **Restart Claude Desktop** - The server will start automatically when Claude Desktop connects.
161 |
162 | ### Manual Testing & Development
163 |
164 | ```bash
165 | # Development mode with hot-reloading
166 | npm run dev
167 |
168 | # Type checking only
169 | npm run typecheck
170 |
171 | # Run tests
172 | npm test
173 |
174 | # Manual STDIO mode (for testing without Claude Desktop)
175 | npm run start:stdio
176 |
177 | # Web/SSE mode (for web clients)
178 | npm run start:sse
179 | ```
180 |
181 | ## Configuration
182 |
183 | ### Main Configuration (`config.json`)
184 |
185 | ```json
186 | {
187 | "server": {
188 | "name": "claude-prompts-mcp",
189 | "version": "1.0.0"
190 | },
191 | "transports": {
192 | "stdio": { "enabled": true },
193 | "sse": { "enabled": true, "port": 3000 }
194 | },
195 | "logging": {
196 | "directory": "./logs",
197 | "level": "INFO"
198 | },
199 | "prompts": "./prompts/promptsConfig.json"
200 | }
201 | ```
202 |
203 | ### Prompts Configuration (`prompts/promptsConfig.json`)
204 |
205 | ```json
206 | {
207 | "categories": [
208 | {
209 | "name": "analysis",
210 | "displayName": "Analysis & Research",
211 | "description": "Data analysis and research prompts",
212 | "promptsFile": "./prompts/analysis/prompts.json"
213 | }
214 | ],
215 | "registrationMode": "NAME"
216 | }
217 | ```
218 |
219 | ## Prompt and Template Development
220 |
221 | ### Basic Prompt Structure (Fast Variable Substitution)
222 |
223 | ````markdown
224 | # Quick Code Formatter
225 |
226 | ## System Message
227 |
228 | Format code cleanly and consistently.
229 |
230 | ## User Message Template
231 |
232 | Please format this {{language}} code using {{style}} style:
233 |
234 | ```{{language}}
235 | {{code}}
236 | ```
237 | ````
238 |
239 | ## Arguments
240 |
241 | - language: Programming language (required)
242 | - style: Formatting style (required)
243 | - code: Code to format (required)
244 |
245 | ````
246 |
247 | ### Framework-Aware Template Structure (Methodology Enhanced)
248 |
249 | ```markdown
250 | # Code Security Analyzer
251 |
252 | ## System Message
253 | You are a security expert specialized in code analysis.
254 |
255 | ## User Message Template
256 | Analyze this {{language}} code for security vulnerabilities:
257 |
258 | ```{{language}}
259 | {{code}}
260 | ````
261 |
262 | Provide comprehensive analysis including:
263 |
264 | - Vulnerability assessment
265 | - Risk prioritization
266 | - Remediation recommendations
267 |
268 | ## Arguments
269 |
270 | - language: Programming language (required)
271 | - code: Code to analyze (required)
272 |
273 | ````
274 |
275 | ### Chain Execution
276 |
277 | ```json
278 | {
279 | "id": "analysis-chain",
280 | "name": "Analysis Chain",
281 | "chainSteps": [
282 | {
283 | "promptId": "data-extraction",
284 | "stepName": "Extract Data",
285 | "inputMapping": { "source": "input" },
286 | "outputMapping": { "extracted_data": "output" }
287 | },
288 | {
289 | "promptId": "data-analysis",
290 | "stepName": "Analyze Data",
291 | "inputMapping": { "data": "extracted_data" },
292 | "outputMapping": { "analysis_result": "output" }
293 | }
294 | ]
295 | }
296 | ````
297 |
298 | ### Enhanced Chain Configuration
299 |
300 | ```json
301 | {
302 | "id": "analysis-chain",
303 | "name": "Enhanced Analysis Chain",
304 | "executionMode": "chain",
305 | "chainSteps": [
306 | {
307 | "promptId": "data-validation",
308 | "stepName": "Validate Input Data",
309 | "inputMapping": { "source": "input" },
310 | "outputMapping": { "validated_data": "output" }
311 | },
312 | {
313 | "promptId": "advanced-analysis",
314 | "stepName": "Perform Analysis",
315 | "inputMapping": { "data": "validated_data" },
316 | "outputMapping": { "analysis_result": "output" }
317 | }
318 | ],
319 | "gates": [
320 | {
321 | "type": "validation",
322 | "requirements": [{ "type": "content_length", "criteria": { "min": 50 } }]
323 | }
324 | ]
325 | }
326 | ```
327 |
328 | ## Performance Features
329 |
330 | ### Caching and Optimization
331 |
332 | - **Three-Tier Execution Caching**: Optimized routing between prompt/template/chain execution
333 | - **Memory Management**: Automatic cleanup and size limits
334 | - **Performance Monitoring**: Real-time metrics and diagnostics
335 | - **Consolidated Tool Architecture**: 87.5% reduction in tool complexity
336 |
337 | ### Monitoring
338 |
339 | ```typescript
340 | // Get execution statistics from coordinator
341 | const stats = executionCoordinator.getExecutionStats();
342 |
343 | // Get framework state and analytics
344 | const analytics = frameworkStateManager.getAnalytics();
345 |
346 | // System health monitoring
347 | const health = applicationOrchestrator.getHealthStatus();
348 | ```
349 |
350 | ## Development Commands
351 |
352 | ### Essential Commands
353 |
354 | ```bash
355 | # Build TypeScript
356 | npm run build
357 |
358 | # Type checking
359 | npm run typecheck
360 |
361 | # Development mode
362 | npm run dev
363 |
364 | # Run tests
365 | npm test
366 |
367 | # Start production server
368 | npm start
369 | ```
370 |
371 | ### Transport-Specific
372 |
373 | ```bash
374 | # STDIO transport (Claude Desktop)
375 | npm run start:stdio
376 |
377 | # SSE transport (web clients)
378 | npm run start:sse
379 |
380 | # Development with verbose logging
381 | npm run start:verbose
382 | ```
383 |
384 | ### Environment Variables (Optional)
385 |
386 | ```bash
387 | # Optional: Optimize server root detection (streamlined detection system)
388 | export MCP_SERVER_ROOT=/path/to/claude-prompts-mcp/server
389 |
390 | # Optional: Direct path to prompts config (automatic detection available)
391 | export MCP_PROMPTS_CONFIG_PATH=/path/to/claude-prompts-mcp/server/prompts/promptsConfig.json
392 | ```
393 |
394 | **Detection Strategy:** The server uses streamlined detection with 3 core strategies:
395 |
396 | 1. **Script path analysis** (most reliable - works in 99% of cases)
397 | 2. **Module path detection** (reliable fallback for edge cases)
398 | 3. **Common directory patterns** (covers remaining scenarios)
399 |
400 | Environment variables provide **guaranteed detection** but are not required for normal operation.
401 |
402 | ## Troubleshooting
403 |
404 | ### Common Installation Issues
405 |
406 | 1. **"Cannot find module" errors**
407 |
408 | ```bash
409 | # Ensure you're in the server directory
410 | cd /path/to/claude-prompts-mcp/server
411 |
412 | # Clean install
413 | rm -rf node_modules package-lock.json
414 | npm install
415 | npm run build
416 | ```
417 |
418 | 2. **Claude Desktop not connecting**
419 |
420 | - Verify absolute paths in configuration (no relative paths like `./` or `~/`)
421 | - Ensure the `dist/index.js` file exists after running `npm run build`
422 | - Check Claude Desktop logs for connection errors
423 | - Restart Claude Desktop after configuration changes
424 |
425 | 3. **Permission errors**
426 |
427 | ```bash
428 | # Fix file permissions
429 | chmod +x dist/index.js
430 | ```
431 |
432 | 4. **TypeScript compilation errors**
433 |
434 | ```bash
435 | # Check for syntax errors
436 | npm run typecheck
437 |
438 | # Clean build
439 | npm run build
440 | ```
441 |
442 | ### Verifying Installation
443 |
444 | ```bash
445 | # Test the server manually
446 | node dist/index.js --help
447 |
448 | # Run the test suite
449 | npm test
450 |
451 | # Check if MCP tools are working
452 | # After connecting to Claude Desktop, try: /mcp
453 | ```
454 |
455 | ## Testing
456 |
457 | ### Test Structure
458 |
459 | - **Unit Tests**: Individual component testing
460 | - **Integration Tests**: Full system testing with ConsolidatedPromptEngine
461 | - **Performance Tests**: Three-tier execution benchmarking
462 | - **Framework Tests**: CAGEERF, ReACT, 5W1H, SCAMPER validation
463 |
464 | ### Running Tests
465 |
466 | ```bash
467 | # Run all tests
468 | npm test
469 |
470 | # Run specific test suites
471 | npm test -- --testNamePattern="ConsolidatedPromptEngine"
472 |
473 | # Run framework tests
474 | npm run test:cageerf-framework
475 |
476 | # Run MCP tools tests
477 | npm run test:mcp-tools
478 | ```
479 |
480 | ## Advanced Integration
481 |
482 | ### Web Clients (Alternative to Claude Desktop)
483 |
484 | For web-based integrations, use SSE transport:
485 |
486 | ```bash
487 | # Start SSE server
488 | npm run start:sse
489 | ```
490 |
491 | ```javascript
492 | // Connect to SSE endpoint
493 | const eventSource = new EventSource("http://localhost:3000/events");
494 | eventSource.onmessage = function (event) {
495 | const data = JSON.parse(event.data);
496 | // Handle MCP messages
497 | };
498 | ```
499 |
500 | ### Custom MCP Clients
501 |
502 | For custom integrations, the server supports both STDIO and SSE transports. See the [MCP Protocol Documentation](https://modelcontextprotocol.io) for implementation details.
503 |
504 | ## Error Handling
505 |
506 | ### Graceful Degradation
507 |
508 | - **Startup Failures**: Rollback mechanisms for partial initialization
509 | - **Execution Errors**: Comprehensive error boundaries
510 | - **Template Errors**: Detailed error reporting with context
511 | - **Performance Issues**: Automatic optimization and cleanup
512 |
513 | ### Logging
514 |
515 | - **Structured Logging**: JSON-formatted logs with context
516 | - **Log Levels**: DEBUG, INFO, WARN, ERROR
517 | - **Transport-Aware**: Prevents STDIO interference
518 | - **Performance Tracking**: Execution timing and metrics
519 |
520 | ## API Reference
521 |
522 | ### Consolidated MCP Tools (87.5% Reduction: 24+ → 3 Tools)
523 |
524 | - **prompt_engine**: Universal execution with intelligent analysis, semantic detection, and LLM-driven chain coordination
525 | - **prompt_manager**: Complete lifecycle management with smart filtering, type analysis, and configurable semantic analysis
526 | - **system_control**: Framework management, analytics, health monitoring, and comprehensive system administration
527 |
528 | ### ExecutionCoordinator Methods (Phase 3)
529 |
530 | ```typescript
531 | // Execute with delegation to ConsolidatedPromptEngine
532 | await executionCoordinator.executePrompt(promptId, args, options);
533 |
534 | // Get execution statistics (three-tier model)
535 | const stats = executionCoordinator.getExecutionStats();
536 | // Returns: { promptExecutions, templateExecutions, chainExecutions, failedExecutions }
537 |
538 | // Set consolidated engine for delegation
539 | executionCoordinator.setConsolidatedEngine(consolidatedPromptEngine);
540 | ```
541 |
542 | ### ConsolidatedPromptEngine Methods
543 |
544 | ```typescript
545 | // Universal execution with intelligent type detection
546 | const result = await consolidatedPromptEngine.executePrompt(command, options);
547 |
548 | // Semantic analysis with configurable analyzer
549 | const analysis = semanticAnalyzer.analyze(promptData);
550 | // Returns: { executionType: 'prompt'|'template'|'chain', requiresFramework: boolean }
551 | ```
552 |
553 | ### Framework System Methods
554 |
555 | ```typescript
556 | // Framework selection and management
557 | const framework = frameworkManager.selectFramework({
558 | executionType: "template",
559 | complexity: "high",
560 | });
561 |
562 | // Runtime framework switching
563 | await frameworkStateManager.switchFramework({
564 | targetFramework: "CAGEERF",
565 | reason: "Complexity requires structured approach",
566 | });
567 |
568 | // Framework injection (conditional based on execution tier)
569 | const injectionResult = await frameworkInjector.injectFrameworkContext(
570 | prompt,
571 | semanticAnalysis
572 | );
573 |
574 | // Get current framework state and health
575 | const state = frameworkStateManager.getCurrentState();
576 | const health = frameworkStateManager.getSystemHealth();
577 | ```
578 |
579 | ## Contributing
580 |
581 | 1. Follow TypeScript best practices
582 | 2. Include comprehensive tests
583 | 3. Update documentation
584 | 4. Ensure hot-reloading compatibility
585 | 5. Validate MCP protocol compliance
586 |
587 | ### Architecture Guidelines
588 |
589 | - **Delegation Pattern**: ExecutionCoordinator delegates all execution to ConsolidatedPromptEngine for simplified coordination
590 | - **Three-Tier Architecture**: Optimized routing between prompt (fast), template (framework-enhanced), and chain (LLM-driven) execution
591 | - **Conditional Framework Integration**: Framework injection applied selectively based on execution tier requirements
592 | - **Intelligent Routing**: Implement command routing with built-in detection and multi-strategy parsing
593 | - **Comprehensive Error Boundaries**: Implement error handling at all orchestration levels
594 | - **Backward Compatibility**: Maintain compatibility through ExecutionCoordinator interface while leveraging modern delegation architecture
595 |
596 | ## License
597 |
598 | MIT License - see LICENSE file for details.
599 |
600 | ## Support
601 |
602 | For issues and questions:
603 |
604 | - GitHub Issues: Report bugs and feature requests
605 | - Documentation: See `/docs` for detailed guides
606 | - Examples: Check `/examples` for usage patterns
607 |
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Claude Prompts MCP Server
2 |
3 | <div align="center">
4 |
5 | 
6 |
7 | [](https://www.npmjs.com/package/claude-prompts-server)
8 | [](https://opensource.org/licenses/MIT)
9 | [](https://modelcontextprotocol.io)
10 | [](https://nodejs.org)
11 |
12 | **A Universal Model Context Protocol Server for Advanced Prompt Management**
13 |
14 | Production-ready MCP server with intelligent prompt orchestration, hot-reload capabilities, and framework-driven AI workflows. Compatible with Claude Desktop, Cursor Windsurf, and any MCP client.
15 |
16 | [Quick Start](#quick-start) • [Features](#core-features) • [Documentation](#documentation) • [Configuration](#configuration)
17 |
18 | ---
19 |
20 | </div>
21 |
22 | ## Core Features
23 |
24 | **Three-Tier Execution Architecture**
25 |
26 | - **Prompt Execution**: Lightning-fast single prompt execution with variable substitution
27 | - **Template Processing**: Framework-enhanced templates with Nunjucks templating engine
28 | - **Chain Workflows**: Multi-step LLM-driven workflows with state management
29 |
30 | **Intelligent System Components**
31 |
32 | - **Structural Analysis**: Automatic execution type detection based on file structure
33 | - **Hot-Reload System**: Update prompts instantly without server restarts
34 | - **Quality Gates**: Framework-aware validation with conditional logic
35 | - **Performance Monitoring**: Comprehensive startup orchestration and health monitoring
36 |
37 | **Universal MCP Compatibility**
38 |
39 | - **Transport Support**: STDIO for desktop clients, SSE for web applications
40 | - **Client Integration**: Native support for Claude Desktop, Cursor Windsurf, and custom MCP clients
41 | - **Protocol Compliance**: Full Model Context Protocol implementation with tool registration
42 |
43 | ## Interactive Prompt Management
44 |
45 | Manage AI capabilities directly within conversations through three consolidated MCP tools:
46 |
47 | ```bash
48 | # Universal prompt execution with intelligent type detection
49 | prompt_engine >>code_formatter language="Python" style="PEP8"
50 |
51 | # Create and manage prompts with intelligent analysis
52 | prompt_manager create name="code_reviewer" type="template" \
53 | content="Analyze {{code}} for security, performance, and maintainability"
54 |
55 | # Analyze existing prompts for execution optimization
56 | prompt_manager analyze_type prompt_id="my_prompt"
57 |
58 | # System control and framework management
59 | system_control switch_framework framework="ReACT" reason="Problem-solving focus"
60 |
61 | # Execute complex multi-step LLM-driven chains
62 | prompt_engine >>code_review_optimization_chain target_code="..." language_framework="TypeScript"
63 | ```
64 |
65 | **Key Benefits:**
66 |
67 | - **Structural Intelligence**: Automatic execution routing based on file structure analysis
68 | - **Dynamic Capability Building**: Extend AI assistant capabilities through conversational management
69 | - **Minimal Configuration**: Execution type detection requires no manual setup
70 | - **Systematic Workflow**: Integrated creation, routing, and framework application
71 | - **Intelligent Command Routing**: Built-in command detection with multi-strategy parsing
72 | - **Methodology Integration**: Four thinking frameworks (CAGEERF, ReACT, 5W1H, SCAMPER) with conditional application
73 |
74 | ## Framework System
75 |
76 | The server implements a sophisticated methodology system that applies structured thinking frameworks to AI interactions:
77 |
78 | ### Available Methodologies
79 |
80 | - **CAGEERF**: Comprehensive structured approach (Context, Analysis, Goals, Execution, Evaluation, Refinement, Framework)
81 | - **ReACT**: Reasoning and Acting pattern for systematic problem-solving
82 | - **5W1H**: Who, What, When, Where, Why, How systematic analysis
83 | - **SCAMPER**: Creative problem-solving (Substitute, Combine, Adapt, Modify, Put to other uses, Eliminate, Reverse)
84 |
85 | ### Framework Features
86 |
87 | - **Manual Selection**: Choose optimal methodology based on specific needs
88 | - **Runtime Switching**: Change active framework with performance monitoring
89 | - **Conditional Application**: Framework enhancement applied when beneficial
90 | - **Performance Monitoring**: Track framework switching mechanics and usage
91 |
92 | ```bash
93 | # Switch methodology for different approaches
94 | system_control switch_framework framework="ReACT" reason="Problem-solving focus"
95 |
96 | # Monitor framework performance and usage
97 | system_control analytics show_details=true
98 |
99 | # Get current framework status
100 | system_control status
101 | ```
102 |
103 | **Result**: Structured, systematic AI conversations through proven thinking methodologies.
104 |
105 | ### Analysis System Capabilities
106 |
107 | **Core Analysis Functions:**
108 |
109 | - **Structural Analysis**: Detects execution type by examining template variables (`{{variable}}`), chain steps, and file structure
110 | - **Framework Application**: Applies selected framework methodology based on execution tier
111 | - **Routing Logic**: Routes to appropriate execution tier (prompt/template/chain) based on structural characteristics
112 |
113 | **Optional Semantic Enhancement:**
114 |
115 | - **LLM Integration**: When enabled, provides semantic understanding of prompt content
116 | - **Advanced Analysis**: Methodology recommendations and complexity assessment
117 | - **Default Mode**: Structural analysis only (no LLM dependency)
118 |
119 | **Framework Control:**
120 |
121 | ```bash
122 | # Manual framework selection
123 | system_control switch_framework framework="ReACT" reason="Problem-solving focus"
124 | ```
125 |
126 | ## Architecture & Reliability
127 |
128 | ### Developer Experience
129 |
130 | - **One-Command Installation**: Complete setup in under 60 seconds
131 | - **Hot-Reload System**: Update prompts, configs, and templates without restart
132 | - **Rich Template Engine**: Nunjucks with conditionals, loops, and data injection
133 | - **Universal MCP Integration**: Works with Claude Desktop, Cursor Windsurf, and any MCP client
134 | - **Multi-Transport Support**: STDIO for desktop + SSE/REST for web
135 | - **Dynamic Management**: Update, delete, and reload prompts on-the-fly
136 |
137 | ### Enterprise Architecture
138 |
139 | - **Orchestrated Startup**: Phased initialization with dependency management
140 | - **Error Handling**: Graceful degradation with comprehensive logging
141 | - **Health Monitoring**: Real-time module status, performance metrics, diagnostics
142 | - **Environment Detection**: Automatic adaptation for development and production
143 | - **Modular Design**: Extensible architecture for custom workflows
144 | - **Security**: Input validation, sanitization, and error boundaries
145 |
146 | ### Consolidated MCP Tools (3 Tools)
147 |
148 | - **prompt_engine**: Universal execution with intelligent analysis and chain coordination
149 | - **prompt_manager**: Complete lifecycle management with smart filtering and gate management
150 | - **system_control**: Framework management, analytics, and system administration
151 |
152 | ### Intelligent Features
153 |
154 | - **Structural Type Detection**: Automatic routing between prompt/template/chain execution
155 | - **Framework Integration**: Four methodologies with manual selection and conditional injection
156 | - **LLM-Driven Chains**: Step-by-step workflow coordination with state management
157 | - **Performance Analytics**: Three-tier execution monitoring with framework switching tracking
158 | - **Smart Argument Parsing**: JSON objects, single arguments, or conversational context
159 |
160 | ## Quick Start
161 |
162 | Get the server running in under a minute:
163 |
164 | ```bash
165 | # Clone, install, build, and start
166 | git clone https://github.com/minipuft/claude-prompts-mcp.git
167 | cd claude-prompts-mcp/server && npm install && npm run build && npm start
168 | ```
169 |
170 | ### MCP Client Integration
171 |
172 | #### Claude Desktop
173 |
174 | Drop this into your `claude_desktop_config.json`:
175 |
176 | ```json
177 | {
178 | "mcpServers": {
179 | "claude-prompts-mcp": {
180 | "command": "node",
181 | "args": ["E:\\path\\to\\claude-prompts-mcp\\server\\dist\\index.js"],
182 | "env": {
183 | "MCP_PROMPTS_CONFIG_PATH": "E:\\path\\to\\claude-prompts-mcp\\server\\prompts\\promptsConfig.json"
184 | }
185 | }
186 | }
187 | }
188 | ```
189 |
190 | #### Cursor Windsurf & Other MCP Clients
191 |
192 | Configure your MCP client to connect via STDIO transport:
193 |
194 | - **Command**: `node`
195 | - **Args**: `["path/to/claude-prompts-mcp/server/dist/index.js"]`
196 | - **Environment** (Optional): `MCP_PROMPTS_CONFIG_PATH=path/to/prompts/promptsConfig.json`
197 |
198 | #### Claude Code CLI Installation
199 |
200 | For Claude Code CLI users:
201 |
202 | ```bash
203 | claude mcp add-json claude-prompts-mcp '{"type":"stdio","command":"node","args":["path/to/claude-prompts-mcp/server/dist/index.js"],"env":{}}'
204 | ```
205 |
206 | ### Usage Examples
207 |
208 | Start using the server immediately:
209 |
210 | ```bash
211 | # Discover prompts with intelligent filtering
212 | prompt_manager list filter="category:analysis"
213 |
214 | # Execute prompts with automatic type detection
215 | prompt_engine >>friendly_greeting name="Developer"
216 |
217 | # Analyze content with framework enhancement
218 | prompt_engine >>content_analysis input="research data"
219 |
220 | # Run multi-step LLM-driven chains
221 | prompt_engine >>code_review_optimization_chain target_code="..." language_framework="TypeScript"
222 |
223 | # Monitor system performance
224 | system_control analytics include_history=true
225 |
226 | # Create new prompts conversationally
227 | "Create a prompt called 'bug_analyzer' that finds and explains code issues"
228 |
229 | # Refine existing prompts
230 | "Make the bug_analyzer prompt also suggest performance improvements"
231 |
232 | # Reference existing chain prompts
233 | # Example chains available: code_review_optimization_chain, create_docs_chain, video_notes_enhanced
234 |
235 | # Manual control when needed
236 | prompt_engine >>content_analysis input="sensitive data" step_confirmation=true gate_validation=true
237 | ```
238 |
239 | The system provides a structured approach to prompt management through systematic methodology application.
240 |
241 | ## Key Features
242 |
243 | ### Lightning-Fast Hot-Reload
244 |
245 | The orchestration engine monitors files and reloads everything seamlessly:
246 |
247 | ```bash
248 | # Edit any prompt file → Server detects → Reloads automatically → Zero downtime
249 | ```
250 |
251 | - **Instant Updates**: Change templates, arguments, descriptions in real-time
252 | - **Zero Restart Required**: Advanced hot-reload system keeps everything running
253 | - **Smart Dependency Tracking**: Only reloads what actually changed
254 | - **Graceful Error Recovery**: Invalid changes don't crash the server
255 |
256 | ### Advanced Template Engine
257 |
258 | Nunjucks-powered dynamic prompts with full templating capabilities:
259 |
260 | ```nunjucks
261 | Analyze {{content}} for {% if focus_area %}{{focus_area}}{% else %}general{% endif %} insights.
262 |
263 | {% for requirement in requirements %}
264 | - Consider: {{requirement}}
265 | {% endfor %}
266 |
267 | {% if previous_context %}
268 | Build upon: {{previous_context}}
269 | {% endif %}
270 | ```
271 |
272 | - **Conditional Logic**: Smart prompts that adapt based on input
273 | - **Loops & Iteration**: Handle arrays and complex data structures
274 | - **Template Inheritance**: Reuse and extend prompt patterns
275 | - **Real-Time Processing**: Templates render with live data injection
276 |
277 | ### Performance Forward Orchestration
278 |
279 | Multi-phase startup with comprehensive health monitoring:
280 |
281 | ```typescript
282 | Phase 1: Foundation → Config, logging, core services
283 | Phase 2: Data Loading → Prompts, categories, validation
284 | Phase 3: Module Init → Tools, executors, managers
285 | Phase 4: Server Launch → Transport, API, diagnostics
286 | ```
287 |
288 | - **Dependency Management**: Modules start in correct order with validation
289 | - **Health Monitoring**: Real-time status of all components
290 | - **Performance Metrics**: Memory usage, uptime, connection tracking
291 | - **Diagnostic Tools**: Built-in troubleshooting and debugging
292 |
293 | ### Intelligent Prompt Chains
294 |
295 | Multi-step workflows implemented as LLM-driven instruction sequences embedded in markdown templates:
296 |
297 | #### LLM-Driven Chain Format (Primary Method)
298 |
299 | Chains are defined directly in markdown files using step headers that guide Claude through a systematic process:
300 |
301 | ```markdown
302 | # Comprehensive Code Review
303 |
304 | ## User Message Template
305 |
306 | **Target Code**: {{target_code}}
307 | **Language/Framework**: {{language_framework}}
308 |
309 | This chain performs a systematic 6-step code review:
310 |
311 | ## Step 1: Structure & Organization Analysis
312 | Analyze code architecture, organization, patterns, naming conventions...
313 |
314 | **Output Required**: Structural assessment with identified patterns.
315 |
316 | ---
317 |
318 | ## Step 2: Functionality & Logic Review
319 | Examine business logic correctness, edge cases, error handling...
320 |
321 | **Output Required**: Logic validation with edge case analysis.
322 |
323 | ---
324 |
325 | ## Step 3: Security & Best Practices Audit
326 | Review for security vulnerabilities: input validation, authentication...
327 |
328 | **Output Required**: Security assessment with vulnerability identification.
329 | ```
330 |
331 | **Key Features:**
332 | - **LLM-Driven Execution**: Claude follows step-by-step instructions embedded in the template
333 | - **Context Preservation**: Each step builds on previous outputs naturally
334 | - **Flexible Structure**: Steps can include conditional logic and branching
335 | - **Framework Integration**: Automatically enhanced with active methodology (CAGEERF/ReACT)
336 |
337 | #### Modular Chain Format (Alternative)
338 |
339 | For chains that orchestrate multiple reusable prompts, use the markdown-embedded format:
340 |
341 | ```markdown
342 | ## Chain Steps
343 |
344 | 1. promptId: extract_key_points
345 | stepName: Extract Key Points
346 | inputMapping:
347 | content: original_content
348 | outputMapping:
349 | key_points: extracted_points
350 |
351 | 2. promptId: sentiment_analysis
352 | stepName: Analyze Sentiment
353 | inputMapping:
354 | text: extracted_points
355 | outputMapping:
356 | sentiment: analysis_result
357 | ```
358 |
359 | **Capabilities:**
360 | - **Prompt Reuse**: Chain together existing prompts
361 | - **Data Flow Mapping**: Explicit input/output variable mapping
362 | - **Gate Integration**: Apply quality gates at each step
363 | - **Error Recovery**: Graceful handling of failed steps
364 |
365 | **Real Examples**: See working chain implementations:
366 | - `server/prompts/development/code_review_optimization_chain.md` - 6-step code review workflow
367 | - `server/prompts/documentation/create_docs_chain.md` - Documentation generation chain
368 | - `server/prompts/content_processing/video_notes_enhanced.md` - Video analysis workflow
369 |
370 | ## System Architecture
371 |
372 | ```mermaid
373 | graph TB
374 | A[Claude Desktop] -->|MCP Protocol| B[Transport Layer]
375 | B --> C[🧠 Orchestration Engine]
376 | C --> D[📝 Prompt Manager]
377 | C --> E[🛠️ MCP Tools Manager]
378 | C --> F[⚙️ Config Manager]
379 | D --> G[🎨 Template Engine]
380 | E --> H[🔧 Management Tools]
381 | F --> I[🔥 Hot Reload System]
382 |
383 | style C fill:#ff6b35
384 | style D fill:#00ff88
385 | style E fill:#0066cc
386 | ```
387 |
388 | ## MCP Client Compatibility
389 |
390 | This server implements the Model Context Protocol (MCP) standard and works with any compatible client:
391 |
392 | ### Tested & Verified Clients
393 |
394 | - **Claude Desktop**: Full integration support
395 | - **Cursor Windsurf**: Native MCP compatibility
396 | - **Claude Code**: Full native support
397 |
398 | ### Transport Support
399 |
400 | - **STDIO**: Primary transport for desktop clients
401 | - **Server-Sent Events (SSE)**: Web-based clients and integrations
402 | - **HTTP Endpoints**: Basic endpoints for health checks and data queries
403 |
404 | ### Integration Features
405 |
406 | - **Auto-Discovery**: Clients detect tools automatically
407 | - **Tool Registration**: Dynamic capability announcement
408 | - **Hot Reload**: Changes appear instantly in clients
409 | - **Error Handling**: Graceful degradation across clients
410 |
411 | **Note**: As MCP adoption grows, this server will work with any new MCP-compatible AI assistant or development environment without modification.
412 |
413 | ## Configuration
414 |
415 | ### Server Configuration (`config.json`)
416 |
417 | Fine-tune your server's behavior:
418 |
419 | ```json
420 | {
421 | "server": {
422 | "name": "Claude Custom Prompts MCP Server",
423 | "version": "1.0.0",
424 | "port": 9090
425 | },
426 | "prompts": {
427 | "file": "promptsConfig.json",
428 | "registrationMode": "name"
429 | },
430 | "transports": {
431 | "default": "stdio",
432 | "sse": { "enabled": false },
433 | "stdio": { "enabled": true }
434 | }
435 | }
436 | ```
437 |
438 | ### Prompt Organization (`promptsConfig.json`)
439 |
440 | Structure your AI command library:
441 |
442 | ```json
443 | {
444 | "categories": [
445 | {
446 | "id": "development",
447 | "name": "🔧 Development",
448 | "description": "Code review, debugging, and development workflows"
449 | },
450 | {
451 | "id": "analysis",
452 | "name": "📊 Analysis",
453 | "description": "Content analysis and research prompts"
454 | },
455 | {
456 | "id": "creative",
457 | "name": "🎨 Creative",
458 | "description": "Content creation and creative writing"
459 | }
460 | ],
461 | "imports": [
462 | "prompts/development/prompts.json",
463 | "prompts/analysis/prompts.json",
464 | "prompts/creative/prompts.json"
465 | ]
466 | }
467 | ```
468 |
469 | ## Advanced Features
470 |
471 | ### Multi-Step Prompt Chains
472 |
473 | Build sophisticated AI workflows using two complementary approaches:
474 |
475 | #### LLM-Driven Chains (Recommended)
476 |
477 | The primary method uses step-by-step instructions embedded directly in markdown templates. Claude executes each step systematically while maintaining context:
478 |
479 | ```markdown
480 | # Research Analysis Chain
481 |
482 | ## User Message Template
483 |
484 | Research {{topic}} and provide {{analysis_type}} analysis.
485 |
486 | ## Step 1: Initial Research
487 | Gather comprehensive information about {{topic}} from available sources.
488 | Focus on {{analysis_type}} perspectives.
489 |
490 | **Output Required**: Research summary with key findings.
491 |
492 | ---
493 |
494 | ## Step 2: Extract Key Insights
495 | From the research findings, identify the most relevant insights.
496 | Organize by importance and relevance to {{analysis_type}} analysis.
497 |
498 | **Output Required**: Prioritized list of insights with supporting evidence.
499 |
500 | ---
501 |
502 | ## Step 3: Analyze Patterns
503 | Examine the extracted insights for patterns, trends, and relationships.
504 | Consider multiple analytical frameworks.
505 |
506 | **Output Required**: Pattern analysis with framework comparisons.
507 |
508 | ---
509 |
510 | ## Step 4: Synthesize Report
511 | Create comprehensive report combining all findings.
512 |
513 | **Output Required**: Structured report with executive summary.
514 | ```
515 |
516 | **Benefits:**
517 | - **Natural Flow**: Claude maintains context automatically across steps
518 | - **Flexible Logic**: Steps can include conditional branching and decision points
519 | - **Framework Enhanced**: Automatically augmented with active methodology (CAGEERF/ReACT)
520 | - **Clear Outputs**: Each step specifies required deliverables
521 |
522 | #### Modular Prompt Chains (Alternative)
523 |
524 | For orchestrating multiple reusable prompts with explicit data flow:
525 |
526 | ```markdown
527 | ## Chain Steps
528 |
529 | 1. promptId: research_topic
530 | stepName: Initial Research
531 | inputMapping:
532 | query: topic
533 | outputMapping:
534 | findings: research_data
535 |
536 | 2. promptId: extract_insights
537 | stepName: Extract Key Insights
538 | inputMapping:
539 | content: research_data
540 | outputMapping:
541 | insights: key_findings
542 |
543 | 3. promptId: analyze_patterns
544 | stepName: Analyze Patterns
545 | inputMapping:
546 | data: key_findings
547 | outputMapping:
548 | analysis: pattern_results
549 |
550 | 4. promptId: generate_report
551 | stepName: Synthesize Report
552 | inputMapping:
553 | insights: key_findings
554 | patterns: pattern_results
555 | outputMapping:
556 | report: final_output
557 | ```
558 |
559 | **Capabilities:**
560 |
561 | - **Prompt Reuse**: Leverage existing prompts as chain building blocks
562 | - **Explicit Data Flow**: Clear input/output mapping between steps
563 | - **Error Recovery**: Graceful handling of failed steps with retry logic
564 | - **Gate Validation**: Apply quality gates at each step for validation
565 |
566 | **Real Examples**: View production chain implementations:
567 | - `server/prompts/content_processing/noteIntegration.md` - Note processing with modular steps
568 | - Review the `## Chain Steps` section in any chain prompt for complete syntax
569 |
570 | ### Advanced Template Features
571 |
572 | Leverage the full power of Nunjucks templating:
573 |
574 | ```nunjucks
575 | # {{ title | title }} Analysis
576 |
577 | ## Context
578 | {% if previous_analysis %}
579 | Building upon previous analysis: {{ previous_analysis | summary }}
580 | {% endif %}
581 |
582 | ## Requirements
583 | {% for req in requirements %}
584 | {{loop.index}}. **{{req.priority | upper}}**: {{req.description}}
585 | {% if req.examples %}
586 | Examples: {% for ex in req.examples %}{{ex}}{% if not loop.last %}, {% endif %}{% endfor %}
587 | {% endif %}
588 | {% endfor %}
589 |
590 | ## Focus Areas
591 | {% set focus_areas = focus.split(',') %}
592 | {% for area in focus_areas %}
593 | - {{ area | trim | title }}
594 | {% endfor %}
595 | ```
596 |
597 | **Template Features:**
598 |
599 | - **Filters & Functions**: Transform data on-the-fly
600 | - **Conditional Logic**: Smart branching based on input
601 | - **Loops & Iteration**: Handle complex data structures
602 | - **Template Inheritance**: Build reusable prompt components
603 |
604 | ### Real-Time Management Tools
605 |
606 | Manage your prompts dynamically while the server runs:
607 |
608 | ```bash
609 | # Update prompts with intelligent re-analysis
610 | prompt_manager update id="analysis_prompt" content="new template"
611 |
612 | # Modify specific sections with validation
613 | prompt_manager modify id="research" section="examples" content="new examples"
614 |
615 | # Hot-reload with comprehensive validation
616 | system_control reload reason="updated templates"
617 | ```
618 |
619 | **Management Capabilities:**
620 |
621 | - **Live Updates**: Change prompts without server restart
622 | - **Section Editing**: Modify specific parts of prompts
623 | - **Bulk Operations**: Update multiple prompts at once
624 | - **Rollback Support**: Undo changes when things go wrong
625 |
626 | ### Production Monitoring
627 |
628 | Enterprise-grade observability:
629 |
630 | Built-in monitoring and diagnostics for production environments:
631 |
632 | ```typescript
633 | // Health Check Response
634 | {
635 | healthy: true,
636 | modules: {
637 | foundation: true,
638 | dataLoaded: true,
639 | modulesInitialized: true,
640 | serverRunning: true
641 | },
642 | performance: {
643 | uptime: 86400,
644 | memoryUsage: { rss: 45.2, heapUsed: 23.1 },
645 | promptsLoaded: 127,
646 | categoriesLoaded: 8
647 | }
648 | }
649 | ```
650 |
651 | **Monitoring Features:**
652 |
653 | - **Real-Time Health Checks**: All modules continuously monitored
654 | - **Performance Metrics**: Memory, uptime, connection tracking
655 | - **Diagnostic Tools**: Comprehensive troubleshooting information
656 | - **Error Tracking**: Graceful error handling with detailed logging
657 |
658 | ## Documentation
659 |
660 | | Guide | Description |
661 | | ------------------------------------------------------ | --------------------------------------------------------------- |
662 | | [Installation Guide](docs/installation-guide.md) | Complete setup walkthrough with troubleshooting |
663 | | [Troubleshooting Guide](docs/troubleshooting.md) | Common issues, diagnostic tools, and solutions |
664 | | [Architecture Overview](docs/architecture.md) | Deep dive into the orchestration engine, modules, and data flow |
665 | | [Prompt Format Guide](docs/prompt-format-guide.md) | Master prompt creation including chain workflows |
666 | | [Prompt Management](docs/prompt-management.md) | Dynamic management and hot-reload features |
667 | | [MCP Tools Reference](docs/mcp-tools-reference.md) | Complete MCP tools documentation |
668 | | [Roadmap & TODO](docs/TODO.md) | Planned features and development roadmap |
669 | | [Contributing](docs/contributing.md) | Join our development community |
670 |
671 | ## Contributing
672 |
673 | Join our development community:
674 |
675 | - **Found a bug?** [Open an issue](https://github.com/minipuft/claude-prompts-mcp/issues)
676 | - **Have an idea?** [Start a discussion](https://github.com/minipuft/claude-prompts-mcp/discussions)
677 | - **Want to contribute?** Check our [Contributing Guide](docs/contributing.md)
678 | - **Need help?** Visit our [Documentation](docs/README.md)
679 |
680 | ## License
681 |
682 | Released under the [MIT License](LICENSE) - see the file for details.
683 |
684 | ---
685 |
686 | <div align="center">
687 |
688 | **Star this repo if it's improving your AI workflow**
689 |
690 | [Report Bug](https://github.com/minipuft/claude-prompts-mcp/issues) • [Request Feature](https://github.com/minipuft/claude-prompts-mcp/issues) • [View Docs](docs/README.md)
691 |
692 | _Built for the AI development community_
693 |
694 | </div>
695 |
```
--------------------------------------------------------------------------------
/agent.md:
--------------------------------------------------------------------------------
```markdown
1 | # Agent Rules · Claude Prompts MCP
2 |
3 | Read this file at session start. Treat every rule as mandatory unless the user explicitly overrides it.
4 |
5 | ## Mission & Scope
6 | - **Role**: Automation/code-editing agent for the Claude Prompts MCP server repository (`claude-prompts-mcp`).
7 | - **Objective**: Deliver safe, reversible changes that respect MCP protocol guardrails and documented workflows.
8 | - **Hierarchy**: This file embeds global principles, domain conventions, and project-specific rules. No other rule files are loaded.
9 |
10 | ## Operating Principles (Global Layer)
11 | - **Plan-first mindset** → Outline intent, affected areas, and validation before implementing changes; keep the plan updated as work progresses.
12 | - **Protocol alignment** → Honor Model Context Protocol workflows and documented abstractions; prefer official tools/scripts over ad-hoc commands.
13 | - **Transparent reasoning** → Surface assumptions, blockers, and risks early; record skipped validations with justification.
14 | - **Reversibility** → Make small, reviewable diffs; avoid destructive operations without explicit user approval.
15 | - **Constraint awareness** → Respect sandbox/approval requirements, escalate instead of bypassing safeguards.
16 |
17 | ## Domain Guidance (Node.js + TypeScript MCP Stack)
18 | - Use Node.js 16+ and TypeScript in strict mode; maintain ES module syntax.
19 | - Keep code hot-reload friendly: prefer pure functions, dependency injection, and descriptive interfaces.
20 | - Follow Jest testing patterns; ensure new modules are testable and covered when practical.
21 | - Maintain compatibility with the multi-platform CI matrix (Ubuntu, macOS, Windows) and Node 16/18/20.
22 | - Avoid introducing unmanaged global state or side effects that could break STDIO/SSE transports.
23 |
24 | ## Project-Specific Guardrails
25 | - **MCP Tool Usage**: NEVER edit prompt/template/chain files directly. Interact via `prompt_manager`, `prompt_engine`, or `system_control` MCP tools. If direct modification is unavoidable, call it out and justify thoroughly.
26 | - **Hot-Reload Integrity**: Preserve registry synchronization; do not bypass the hot-reload manager or caches unless documented.
27 | - **Enhanced Gate System**: Respect five-level precedence (temporary → template → category → framework → fallback). Keep JSON definitions and TypeScript schemas synchronized.
28 | - **Framework Methodologies**: Document rationale when switching between CAGEERF, ReACT, 5W1H, and SCAMPER. Runtime selections persist in `server/runtime-state/framework-state.json`.
29 | - **Transport Parity**: Ensure changes remain compatible with both STDIO and SSE transports; run targeted smoke checks when touching transport logic.
30 |
31 | ## Task Workflow (Repeatable Loop)
32 | 1. **Discover**: Clarify scope with the user; inspect relevant sources (`CLAUDE.md`, `docs/*.md`, code modules) before editing.
33 | 2. **Design**: Outline approach, list affected files, and determine required validation commands or MCP tool operations.
34 | 3. **Implement**: Apply minimal, focused edits; keep formatting, linting, and typing consistent; update documentation if behavior changes.
35 | 4. **Validate**: Run appropriate scripts (`npm run typecheck`, `npm test`, `npm run validate:all`, targeted diagnostics). If skipped, explain why and assess risk.
36 | 5. **Document**: Summarize changes, highlight risks/gaps, suggest next steps, and note validations performed or skipped.
37 |
38 | ## Code Editing Playbooks
39 | - **TypeScript Modules**: Maintain strict typing; avoid ambient state; prefer descriptive interfaces and enums for shared contracts.
40 | - **Prompt & Chain Logic**: Route adjustments through MCP tools; confirm schema updates in `server/src/mcp-tools` and related validators.
41 | - **Gate System Changes**: Update definitions under `server/src/gates/` and supporting JSON; ensure precedence logic in `temporary-gate-registry`, `gate-state-manager`, and `category-extractor` stays coherent.
42 | - **Transport / Runtime**: Touching `server/src/runtime` or transport layers requires smoke tests via `npm run start:stdio` and `npm run start:sse`; avoid noisy logs in production paths.
43 | - **Configuration**: When editing `config/*.json` or `server/config*.json`, validate with `npm run validate:all` and confirm default values stay backwards compatible.
44 |
45 | ## Tooling & Command Reference
46 | - Build: `npm run build`
47 | - Type Check: `npm run typecheck`
48 | - Tests: `npm test`
49 | - CI parity: `npm run test:ci`, `npm run validate:all`
50 | - Dev watch: `npm run dev`
51 | - Diagnostics: `npm run start:verbose`, `npm run start:debug`
52 | - Transports: `npm run start:stdio`, `npm run start:sse`, `npm run start:production`
53 |
54 | ## Validation Expectations
55 | - Run type checks and relevant tests when altering execution paths, schemas, or TypeScript types.
56 | - Use targeted diagnostics for MCP tools, gate logic, and framework behavior when affected.
57 | - Document skipped validations with impact assessment and recommended follow-up.
58 |
59 | ## Safety & Escalation Checklist
60 | - Confirm with the user before scope jumps or potentially breaking changes.
61 | - Seek approval before destructive git or filesystem operations not explicitly requested.
62 | - Stop immediately and ask for guidance if unexpected repo changes appear or sandbox constraints block required workflows.
63 | - Keep track of lingering risks, TODOs, or follow-up items; store context in `plans/` when long-running work is needed.
64 |
65 | ## Documentation Map (Reference Only)
66 | - `CLAUDE.md` (historical global rules and context)
67 | - `docs/mcp-tool-usage-guide.md`
68 | - `docs/mcp-tools-reference.md`
69 | - `docs/architecture.md`
70 | - `docs/prompt-management.md`
71 | - `docs/enhanced-gate-system.md`
72 | - `docs/troubleshooting.md`
73 | - `docs/version-history.md`
74 |
75 | ## Session Closeout
76 | - Ensure working tree cleanliness or clearly communicate outstanding diffs.
77 | - Provide concise final response: change summary, validations run/skipped, risks, and recommended next steps.
78 | - Default to suggesting verification commands when you cannot run them yourself.
79 |
```
--------------------------------------------------------------------------------
/docs/contributing.md:
--------------------------------------------------------------------------------
```markdown
1 | # Contributing Guidelines
2 |
3 | Thank you for your interest in contributing to the Claude Prompts MCP Server! This document provides guidelines and instructions for contributing to this powerful Model Context Protocol server.
4 |
5 | ## Code of Conduct
6 |
7 | Please be respectful and considerate of others when contributing to this project. We aim to foster an inclusive and welcoming community for developers working with AI prompt engineering and MCP servers.
8 |
9 | ## Getting Started
10 |
11 | 1. Fork the repository on GitHub
12 | 2. Clone your fork locally
13 | 3. Set up the development environment as described below
14 | 4. Create a new branch for your changes
15 |
16 | ## Development Process
17 |
18 | ### Setting Up the Development Environment
19 |
20 | ```bash
21 | # Clone your fork
22 | git clone https://github.com/your-username/claude-prompts-mcp.git
23 | cd claude-prompts-mcp
24 |
25 | # Install server dependencies
26 | cd server
27 | npm install
28 |
29 | # Build the server
30 | npm run build
31 |
32 | # Start in development mode with hot-reload
33 | npm run dev
34 | ```
35 |
36 | ### Project Structure
37 |
38 | ```
39 | claude-prompts-mcp/
40 | ├── server/ # Main MCP server
41 | │ ├── src/ # TypeScript source code
42 | │ │ ├── orchestration/ # Application orchestration and startup
43 | │ │ ├── mcp-tools/ # MCP tool implementations
44 | │ │ ├── prompts/ # Prompt management system
45 | │ │ ├── api/ # REST API endpoints (SSE transport)
46 | │ │ ├── config/ # Configuration management
47 | │ │ ├── logging/ # Logging system
48 | │ │ ├── transport/ # Transport layer (STDIO/SSE)
49 | │ │ ├── types/ # TypeScript type definitions
50 | │ │ └── utils/ # Utility functions
51 | │ ├── prompts/ # Distributed prompt configuration
52 | │ │ └── examples/ # Example prompts
53 | │ ├── dist/ # Compiled JavaScript output
54 | │ ├── config.json # Server configuration
55 | │ ├── promptsConfig.json # Main prompts configuration
56 | │ └── package.json # Node.js dependencies
57 | ├── docs/ # Documentation
58 | └── README.md # Project overview
59 | ```
60 |
61 | ## Making Changes
62 |
63 | ### Server Development
64 |
65 | The server is built with Node.js, Express, and TypeScript, using a sophisticated orchestration system. Key areas for contribution:
66 |
67 | **Core Systems:**
68 |
69 | - `src/orchestration/index.ts` - Application orchestration and lifecycle management
70 | - `src/mcp-tools/index.ts` - MCP tool registration and implementation
71 | - `src/prompts/index.ts` - Prompt management and template processing
72 | - `src/api/index.ts` - REST API for SSE transport mode
73 |
74 | **Configuration System:**
75 |
76 | - `config.json` - Server configuration
77 | - `promptsConfig.json` - Main prompts configuration with category imports
78 | - `prompts/*/prompts.json` - Category-specific prompt definitions
79 |
80 | When making changes to the server:
81 |
82 | 1. **Follow TypeScript Best Practices**: Use proper type definitions and interfaces
83 | 2. **Maintain the Orchestration Pattern**: Respect the phased startup sequence
84 | 3. **Add Comprehensive Error Handling**: Use the existing error handling patterns
85 | 4. **Update Tests**: Add or update tests for new functionality
86 | 5. **Document Changes**: Update relevant documentation
87 |
88 | ### Prompt Development
89 |
90 | The server uses a distributed prompt configuration system:
91 |
92 | **Adding New Prompts:**
93 |
94 | 1. Choose or create a category in `prompts/`
95 | 2. Add your prompt markdown file to the category directory
96 | 3. Register the prompt in the category's `prompts.json` file
97 | 4. Test the prompt using the MCP tools
98 |
99 | **Creating New Categories:**
100 |
101 | 1. Create a new directory under `prompts/`
102 | 2. Create a `prompts.json` file in the directory
103 | 3. Add the category to `promptsConfig.json`
104 | 4. Add the import path to the imports array
105 |
106 | **Prompt Format Guidelines:**
107 |
108 | - Use clear, descriptive markdown format
109 | - Define all arguments with proper descriptions
110 | - Include system messages when appropriate
111 | - Test with various input scenarios
112 |
113 | ### Documentation Updates
114 |
115 | Documentation is written in Markdown and stored in the `docs/` directory. When updating documentation:
116 |
117 | 1. **Keep It Accurate**: Ensure all examples and references match the actual codebase
118 | 2. **Use Clear Examples**: Provide practical, working examples
119 | 3. **Update Cross-References**: Check for broken internal links
120 | 4. **Follow the Style Guide**: Maintain consistency with existing documentation
121 |
122 | ## Testing
123 |
124 | ### Server Tests
125 |
126 | ```bash
127 | cd server
128 | npm test
129 | ```
130 |
131 | ### Manual Testing with Claude Desktop
132 |
133 | 1. Build the server: `npm run build`
134 | 2. Update your `claude_desktop_config.json` to point to your development build
135 | 3. Restart Claude Desktop
136 | 4. Test your changes using the `>>` or `/` command syntax
137 |
138 | ### Prompt Testing
139 |
140 | Test prompts using the built-in MCP tools:
141 |
142 | ```bash
143 | # List all available prompts
144 | >>listprompts
145 |
146 | # Test a specific prompt
147 | >>your_prompt_id argument="test value"
148 |
149 | # Test with JSON arguments
150 | >>complex_prompt {"arg1": "value1", "arg2": "value2"}
151 | ```
152 |
153 | ## Pull Request Process
154 |
155 | 1. **Create a Feature Branch**: Create a descriptive branch name
156 | 2. **Make Focused Changes**: Keep PRs focused on a single feature or bug fix
157 | 3. **Write Clear Commit Messages**: Use descriptive commit messages
158 | 4. **Test Thoroughly**: Ensure all tests pass and manual testing is complete
159 | 5. **Update Documentation**: Update relevant documentation
160 | 6. **Submit the PR**: Include a clear description of changes and their purpose
161 |
162 | ### Pull Request Guidelines
163 |
164 | - **Clear Descriptions**: Explain what the PR does and why
165 | - **Link Related Issues**: Reference any related GitHub issues
166 | - **Include Examples**: Show how new features work
167 | - **Breaking Changes**: Clearly mark any breaking changes
168 | - **Performance Impact**: Note any performance implications
169 |
170 | ## Code Style and Standards
171 |
172 | ### TypeScript Standards
173 |
174 | - **Strict Type Checking**: Use TypeScript's strict mode
175 | - **Interface Definitions**: Create interfaces for complex data structures
176 | - **Proper Error Handling**: Use typed error handling patterns
177 | - **Documentation**: Add JSDoc comments for public APIs
178 |
179 | ### Code Organization
180 |
181 | - **Modular Architecture**: Follow the existing module structure
182 | - **Separation of Concerns**: Keep different functionalities in separate modules
183 | - **Dependency Injection**: Use the orchestration pattern for module dependencies
184 | - **Configuration-Driven**: Make features configurable when appropriate
185 |
186 | ### Naming Conventions
187 |
188 | - **Files**: Use kebab-case for file names (`prompt-manager.ts`)
189 | - **Classes**: Use PascalCase (`ApplicationOrchestrator`)
190 | - **Functions**: Use camelCase (`loadAndConvertPrompts`)
191 | - **Constants**: Use UPPER_SNAKE_CASE (`CONFIG_FILE`)
192 |
193 | ## Architecture Guidelines
194 |
195 | ### MCP Server Development
196 |
197 | When extending the MCP server:
198 |
199 | 1. **Use the Orchestration System**: Register new modules through the orchestrator
200 | 2. **Implement Health Checks**: Add health monitoring for new components
201 | 3. **Support Hot-Reload**: Ensure new features work with the hot-reload system
202 | 4. **Handle Multiple Transports**: Consider both STDIO and SSE transport modes
203 |
204 | ### Prompt System Development
205 |
206 | When extending the prompt system:
207 |
208 | 1. **Maintain Backward Compatibility**: Don't break existing prompt formats
209 | 2. **Use Nunjucks Templates**: Leverage the advanced templating features
210 | 3. **Support Text References**: Handle long content through the reference system
211 | 4. **Validate Input**: Use Zod or similar for input validation
212 |
213 | ## Performance Considerations
214 |
215 | - **Memory Usage**: Be mindful of memory consumption in long-running processes
216 | - **Hot-Reload Efficiency**: Ensure changes don't unnecessarily reload the entire system
217 | - **Template Processing**: Optimize template rendering for frequently-used prompts
218 | - **Error Recovery**: Implement graceful error recovery for robust operation
219 |
220 | ## Security Guidelines
221 |
222 | - **Input Validation**: Validate all user inputs using proper schemas
223 | - **Path Traversal**: Prevent directory traversal attacks in file operations
224 | - **Error Information**: Don't leak sensitive information in error messages
225 | - **Configuration Security**: Handle sensitive configuration data appropriately
226 |
227 | ## Versioning
228 |
229 | We use [Semantic Versioning](https://semver.org/):
230 |
231 | - **MAJOR**: Incompatible API changes or breaking prompt format changes
232 | - **MINOR**: New functionality in a backward-compatible manner
233 | - **PATCH**: Backward-compatible bug fixes
234 |
235 | ## Release Process
236 |
237 | 1. Update version numbers in `package.json`
238 | 2. Update the changelog
239 | 3. Create a release branch
240 | 4. Test the release thoroughly
241 | 5. Create a GitHub release with proper release notes
242 |
243 | ## Reporting Issues
244 |
245 | When reporting issues, please include:
246 |
247 | 1. **Clear Description**: Describe the issue clearly and concisely
248 | 2. **Reproduction Steps**: Provide step-by-step reproduction instructions
249 | 3. **Expected vs Actual**: Clearly state expected and actual behavior
250 | 4. **Environment Details**: Include OS, Node.js version, and Claude Desktop version
251 | 5. **Logs and Screenshots**: Attach relevant logs or screenshots
252 | 6. **Minimal Example**: Provide a minimal example that reproduces the issue
253 |
254 | ## Feature Requests
255 |
256 | Feature requests should include:
257 |
258 | 1. **Use Case Description**: Explain the real-world problem being solved
259 | 2. **Proposed Solution**: Describe your proposed approach
260 | 3. **Alternatives Considered**: Mention alternative solutions you've considered
261 | 4. **Implementation Ideas**: Share any implementation thoughts
262 |
263 | ## Community
264 |
265 | - **GitHub Issues**: For bug reports and feature requests
266 | - **GitHub Discussions**: For general questions and community discussion
267 | - **Pull Requests**: For code contributions and improvements
268 |
269 | ## Getting Help
270 |
271 | If you need help while contributing:
272 |
273 | 1. Check the documentation in the `docs/` directory
274 | 2. Look for similar issues or PRs in the GitHub repository
275 | 3. Ask questions in GitHub Discussions
276 | 4. Review the codebase for patterns and examples
277 |
278 | ## Recognition
279 |
280 | We appreciate all contributions to the project! Contributors will be:
281 |
282 | - Listed in the project contributors
283 | - Acknowledged in release notes for significant contributions
284 | - Invited to help shape the project's future direction
285 |
286 | ## License
287 |
288 | By contributing to this project, you agree that your contributions will be licensed under the project's MIT License.
289 |
290 | ---
291 |
292 | Thank you for contributing to the Claude Prompts MCP Server! Your contributions help make AI prompt engineering more powerful and accessible for developers worldwide. 🚀
293 |
```
--------------------------------------------------------------------------------
/CLAUDE.md:
--------------------------------------------------------------------------------
```markdown
1 | # Claude Prompts MCP - Global Rules Integration
2 |
3 | ## 🔗 Global Rules System Integration
4 |
5 | @include ~/.claude/CLAUDE.md#Rule_Loading_Hierarchy
6 |
7 | **Detected Context**: Node.js TypeScript MCP Server Project
8 | **Active Domain Rules**: JAVASCRIPT.md (ES modules, TypeScript strict mode, Jest testing, Node.js patterns)
9 |
10 | **Project-Specific Rule Overrides**:
11 |
12 | - **MCP tool usage** → NEVER use direct file operations, ALWAYS use MCP tools
13 | - **Framework switching** → Use methodology guides as single source of truth
14 | - **Hot-reload compatibility** → Maintain registry synchronization
15 |
16 | This file provides guidance to Claude Code (claude.ai/code) when working with this Model Context Protocol (MCP) server repository.
17 |
18 | ## Build and Development Commands
19 |
20 | ### Essential Commands
21 |
22 | - **Build**: `npm run build` - Compiles TypeScript to JavaScript in `dist/`
23 | - **Type Check**: `npm run typecheck` - Validates TypeScript types without compilation
24 | - **Start**: `npm start` - Runs the compiled server from `dist/index.js`
25 | - **Development**: `npm run dev` - Watches TypeScript files and restarts on changes
26 | - **Test**: `npm test` - Runs the test server using `../test_server.js`
27 |
28 | ### Transport-Specific Commands
29 |
30 | - **STDIO Transport**: `npm run start:stdio` - For MCP clients like Claude Desktop
31 | - **SSE Transport**: `npm run start:sse` - For web-based clients
32 | - **Production**: `npm run start:production` - Quiet mode with STDIO transport
33 | - **Development**: `npm run start:development` - Verbose mode with SSE transport
34 |
35 | ### Debugging Commands
36 |
37 | - **Verbose Mode**: `npm run start:verbose` - Detailed diagnostics and strategy information
38 | - **Debug Startup**: `npm run start:debug` - Extra debugging information
39 | - **Quiet Mode**: `npm run start:quiet` - Minimal output for production
40 | - **Help**: `npm run help` - Show command line options and environment variables
41 |
42 | ## ⚠️ CRITICAL: MCP Tool Usage Requirements
43 |
44 | **NEVER use direct file manipulation when working with this MCP server.** The server provides structured MCP tools that MUST be used instead.
45 |
46 | ### ❌ FORBIDDEN Operations
47 |
48 | - `Update()`, `Edit()`, `MultiEdit()`, `Write()` - Direct file operations
49 | - Direct modification of JSON files in `/prompts/` directories
50 | - Creating new prompt files manually
51 | - Bash commands that modify prompt files
52 |
53 | ### ✅ REQUIRED: Use MCP Tools
54 |
55 | - **prompt_manager** - All prompt/chain creation, modification, deletion
56 | - **system_control** - Server management, framework switching, analytics
57 | - **prompt_engine** - Prompt execution, chain operations, scaffolding
58 |
59 | **References**:
60 |
61 | - [MCP Tool Usage Guide](./docs/mcp-tool-usage-guide.md) - Complete tool documentation
62 | - [Chain Modification Examples](./docs/chain-modification-examples.md) - Step-by-step workflows
63 |
64 | **Example of CORRECT usage**:
65 |
66 | ```bash
67 | # Wrong: Update(~/prompts/chain.json)
68 | # Right: prompt_manager(action: "update", id: "chain_name", ...)
69 |
70 | # Wrong: Write(~/prompts/new_prompt.md)
71 | # Right: prompt_manager(action: "create", id: "new_prompt", ...)
72 | ```
73 |
74 | **Why this matters**: Direct file operations bypass MCP protocol compliance, break hot-reloading, cause registry desynchronization, and lead to "no structured content provided" errors.
75 |
76 | ## CI/CD Pipeline
77 |
78 | ### GitHub Actions Workflows
79 |
80 | The project uses GitHub Actions for automated testing and validation:
81 |
82 | #### Main CI Pipeline (`.github/workflows/ci.yml`)
83 |
84 | - **Triggers**: Push to `main`/`develop` branches, Pull Requests to `main`
85 | - **Matrix Testing**: Node.js versions 16, 18, 20 across Ubuntu, Windows, macOS
86 | - **Validation Steps**: TypeScript checking, build validation, test execution, server startup
87 | - **CAGEERF Integration**: Validates all CAGEERF framework modules compile and load
88 | - **Artifacts**: Uploads build artifacts for successful Ubuntu + Node 18 builds
89 |
90 | #### PR Validation (`.github/workflows/pr-validation.yml`)
91 |
92 | - **Triggers**: Pull request events (opened, synchronized, reopened)
93 | - **Quality Gates**: TypeScript, build, tests, CAGEERF validation, MCP tools validation
94 | - **Feedback**: Automated PR comments with validation results and changed files analysis
95 | - **Compatibility**: Checks for breaking changes when targeting main branch
96 |
97 | ### Quality Gates
98 |
99 | - **Mandatory**: TypeScript compilation, build success, test passing, server startup
100 | - **CAGEERF Validation**: All analyzer modules, template tools, and MCP integrations
101 | - **Code Quality**: No sensitive files, proper TypeScript structure, dependency consistency
102 |
103 | ## Nunjucks Dynamic Chain Orchestration Strategy
104 |
105 | ### Strategic Architecture Decision
106 |
107 | **Decision**: Keep Nunjucks template engine for dynamic chain orchestration capabilities.
108 |
109 | **Critical Discovery**: Nunjucks templates render on EACH chain step with access to previous step results, enabling powerful result-based conditional logic and adaptive prompt instructions.
110 |
111 | ### Chain Step Variable Access
112 |
113 | **How It Works**:
114 |
115 | ```
116 | Step 1: analysis
117 | → Renders template with input variables
118 | → Outputs: {analysis: "...", confidence: 0.85}
119 |
120 | Step 2: validation
121 | → Renders template with: {analysis: "...", confidence: 0.85, threshold: 0.8}
122 | → Outputs: {score: 0.6, issues: [...]}
123 |
124 | Step 3: refinement
125 | → Renders template with: ALL previous outputs + new variables
126 | → Can use {% if score < 0.7 %} conditionals!
127 | ```
128 |
129 | ### Capabilities Enabled
130 |
131 | **Result-Based Conditionals**:
132 |
133 | ```nunjucks
134 | {% if validation_score < 0.7 %}
135 | ⚠️ CRITICAL QUALITY ISSUES
136 | Apply aggressive refinement with citations...
137 | {% elif validation_score < 0.9 %}
138 | Moderate improvements needed...
139 | {% else %}
140 | Excellent quality - polish only...
141 | {% endif %}
142 | ```
143 |
144 | **Quality-Driven Adaptation**:
145 |
146 | - Adjust instruction depth based on previous step quality
147 | - Customize approach based on validation results
148 | - Adapt error recovery based on failure types
149 | - Modify format based on content characteristics
150 |
151 | **Complexity-Based Branching**:
152 |
153 | ```nunjucks
154 | {% set complexity = sources|length + topics|length %}
155 | {% if complexity > 20 %}
156 | 🔥 MAXIMUM COMPLEXITY - Apply systematic framework...
157 | {% elif complexity > 10 %}
158 | ⚡ HIGH COMPLEXITY - Structured analysis...
159 | {% else %}
160 | 📊 STANDARD - Focus on key insights...
161 | {% endif %}
162 | ```
163 |
164 | ### Implementation Guidelines
165 |
166 | **Best Practices**:
167 |
168 | 1. **Progressive Instruction Clarity**: More specific instructions as quality decreases
169 | 2. **Error Context Preservation**: Carry error context through recovery steps
170 | 3. **Metric-Driven Branching**: Use multiple quality metrics for nuanced decisions
171 | 4. **Accumulated State Tracking**: Reference outputs from multiple previous steps
172 | 5. **Self-Documenting Templates**: Make conditional logic clear and maintainable
173 |
174 | **Performance Considerations**:
175 |
176 | - Template rendering: <50ms per step
177 | - Variable substitution: ~1ms per 100 variables
178 | - Conditionals: ~0.5ms per condition
179 | - Templates cached in production (configured in jsonUtils.ts)
180 |
181 | **What Nunjucks CANNOT Do** (requires execution engine):
182 |
183 | - ❌ Change which prompt executes next (static chain definition)
184 | - ❌ Loop the same step (no recursive execution)
185 | - ❌ Dynamically select from prompt library (no runtime routing)
186 |
187 | ### Future Enhancements
188 |
189 | **Execution Engine Extensions** (beyond Nunjucks):
190 |
191 | - Dynamic step selection based on quality scores
192 | - Recursive step execution with quality thresholds
193 | - LLM-driven chain orchestration
194 | - Automatic quality gate enforcement
195 |
196 | **Reference**: See `/plans/nunjucks-dynamic-chain-orchestration.md` for comprehensive implementation strategy, patterns, and examples.
197 |
198 | ## Project Architecture
199 |
200 | ### Core System Structure
201 |
202 | This is a **Model Context Protocol (MCP) server** that provides AI prompt management with hot-reloading capabilities. The architecture follows a multi-phase orchestration pattern:
203 |
204 | 1. **Foundation Phase**: Configuration loading, logging setup, core services
205 | 2. **Data Loading Phase**: Prompt loading, category parsing, validation
206 | 3. **Module Initialization Phase**: Tools, executors, conversation managers
207 | 4. **Server Launch Phase**: Transport layer, API endpoints, health monitoring
208 |
209 | ### Key Components
210 |
211 | #### `/server/src/runtime/`
212 |
213 | - **Application Runtime** (`application.ts`) - Main entry point with comprehensive health monitoring and graceful shutdown
214 | - **Multi-phase startup** with dependency management and error recovery (Foundation → Data Loading → Module Initialization → Server Launch)
215 | - **Performance monitoring** with memory usage tracking and uptime metrics
216 | - **Startup orchestration** with strategy-based server detection
217 |
218 | #### `/server/src/frameworks/`
219 |
220 | - **Framework Manager** (`framework-manager.ts`) - Stateless framework orchestration, loads methodology guides and generates framework definitions
221 | - **Framework State Manager** (`framework-state-manager.ts`) - Stateful framework management, tracks active framework and handles switching
222 | - **Methodology Guides** (`adapters/`) - CAGEERF, ReACT, 5W1H, SCAMPER guides providing framework-specific guidance
223 | - **Framework Integration** (`integration/`) - Integration between frameworks and semantic analysis
224 | - **Framework Interfaces** (`interfaces/`) - Type definitions and contracts for framework system
225 |
226 | #### `/server/src/execution/`
227 |
228 | - **Execution Index** (`index.ts`) - Main execution orchestration and entry point
229 | - **Context Management** (`context/`) - Context resolution and framework injection
230 | - **Command Routing** (`routing/`) - Lightweight command routing optimized for LLM interactions
231 | - `command-router.ts` (149 lines) - Simple format detection and prompt resolution
232 | - `builtin-commands.ts` (52 lines) - Built-in command registry (listprompts, help, status, etc.)
233 | - Replaced legacy parsing system (1,354 lines) with 84% code reduction
234 | - **Execution Context** (`execution-context.ts`) - Type definitions for execution context
235 | - **Legacy Parsers** (`parsers/index.ts`) - Backwards compatibility exports (deprecated)
236 | - **Execution Types** (`types.ts`) - TypeScript interfaces for execution system
237 |
238 | #### `/server/src/gates/`
239 |
240 | - **Gate Definitions** (`definitions/`) - Gate definition templates and configurations
241 | - **Core Gates** (`core/`) - Core gate validation implementations and processors
242 | - **Gate Templates** (`templates/`) - Reusable gate template structures
243 | - **Main Index** (`index.ts`) - Gate system entry point and orchestration
244 |
245 | #### `/server/src/semantic/`
246 |
247 | - **Semantic Analysis Engine** - Automatic prompt type detection and analysis capabilities
248 | - **Integration Layer** (`integrations/`) - Framework and analysis system integration
249 | - **Analysis Types** - Type definitions for semantic analysis operations
250 |
251 | #### `/server/src/prompts/`
252 |
253 | - **Template processor** using Nunjucks with advanced features (conditionals, loops, macros)
254 | - **Prompt registry** for dynamic loading and hot-reloading
255 | - **Converter system** for format transformation and validation
256 | - **Hot-reload manager** - Supports dynamic prompt reloading without server restart
257 | - **Category manager** - Manages prompt organization and categorization
258 |
259 | #### `/server/src/mcp-tools/`
260 |
261 | - **Prompt Engine** (`prompt-engine.ts`) - Unified execution with intelligent analysis and semantic detection
262 | - **Prompt Manager** (`prompt-manager.ts`) - Complete lifecycle management with smart filtering and analysis
263 | - **System Control** (`system-control.ts`) - Framework management, analytics, and comprehensive system control
264 | - **Configuration & Error Handling** (`config-utils.ts`, `error-handler.ts`) - Centralized configuration and error management
265 | - **Advanced Filtering** (`filters/`) - Intelligent search and discovery capabilities
266 | - **Response Formatting** (`formatters/`) - Consistent MCP response formatting
267 | - **Validation System** (`validators/`) - Comprehensive input validation and schema checking
268 | - **Type Definitions** (`types/`) - TypeScript interfaces for MCP tool system
269 |
270 | #### `/server/src/performance/`
271 |
272 | - **Performance Monitor** (`monitor.ts`) - System performance tracking and metrics collection
273 | - **Memory Usage** - Memory monitoring and garbage collection optimization
274 | - **Startup Optimization** - Server startup time optimization and health monitoring
275 |
276 | #### `/server/src/metrics/`
277 |
278 | - **Usage Analytics** - Prompt usage patterns and execution metrics
279 | - **Performance Metrics** - System performance indicators and benchmarks
280 | - **Health Monitoring** - Server health status and diagnostic collection
281 |
282 | #### `/server/src/server/transport/`
283 |
284 | - **STDIO transport** for Claude Desktop integration
285 | - **SSE transport** for web-based clients
286 | - **Transport-aware logging** to avoid interference with STDIO protocol
287 | - **HTTP request processing and routing** for web-based clients
288 | - **WebSocket handlers** for real-time communication management
289 |
290 | ### Configuration System
291 |
292 | #### Main Configuration (`server/config.json`)
293 |
294 | - Server settings (name, version, port)
295 | - Transport configuration (STDIO/SSE)
296 | - Logging configuration (directory, level)
297 | - Prompts file reference pointing to `prompts/promptsConfig.json`
298 |
299 | #### Prompts Configuration (`server/prompts/promptsConfig.json`)
300 |
301 | - **Category organization** with logical grouping (18 categories including analysis, development, research, content_processing)
302 | - **Modular import system** using category-specific `prompts.json` files in `prompts/[category]/` directories
303 | - **Registration modes** (ID, NAME, or BOTH) with default NAME registration
304 | - **Dynamic imports** - categories are loaded from individual JSON files in subdirectories
305 |
306 | ### Prompt Organization
307 |
308 | #### File Structure
309 |
310 | ```
311 | server/prompts/
312 | ├── category-name/
313 | │ ├── prompts.json # Category prompt registry
314 | │ ├── prompt-name.md # Individual prompt files
315 | │ └── ...
316 | └── promptsConfig.json # Main configuration
317 | ```
318 |
319 | #### Prompt Format
320 |
321 | - **Markdown files** with structured sections
322 | - **Nunjucks templating** with `{{variable}}` syntax
323 | - **Argument definitions** with type information and validation
324 | - **Category association** for organization
325 |
326 | ### TypeScript Architecture
327 |
328 | #### Core Types (`src/types.ts`)
329 |
330 | - **Config interfaces** for application configuration
331 | - **PromptData** for prompt metadata and structure
332 | - **Message types** for conversation handling
333 | - **Transport types** for protocol abstraction
334 |
335 | #### Key Interfaces
336 |
337 | - `PromptData`: Complete prompt structure with metadata, arguments, and configuration
338 | - `PromptArgument`: Typed argument definitions with validation
339 | - `Category`: Prompt organization and categorization
340 | - `MessageContent`: Extensible content type system
341 |
342 | ### Framework System Architecture
343 |
344 | #### Methodology-Driven Design
345 |
346 | The core architecture is built around **methodology guides** that provide systematic approaches to prompt creation, processing, and execution. This replaces hard-coded framework logic with flexible, guideline-based behavior.
347 |
348 | #### Framework Components
349 |
350 | ##### Framework Manager (Stateless Orchestration)
351 |
352 | - **Location**: `/server/src/frameworks/framework-manager.ts`
353 | - **Purpose**: Loads methodology guides and dynamically generates framework definitions
354 | - **Key Functions**:
355 | - Initializes methodology guides (e.g CAGEERF, ReACT, 5W1H, SCAMPER)
356 | - Generates framework definitions from guide metadata
357 | - Creates execution contexts with framework-specific system prompts
358 | - Provides framework selection based on criteria
359 |
360 | ##### Framework State Manager (Stateful Management)
361 |
362 | - **Location**: `/server/src/frameworks/framework-state-manager.ts`
363 | - **Purpose**: Tracks active framework state and handles switching
364 | - **Key Functions**:
365 | - Maintains current active framework (default: CAGEERF)
366 | - Manages framework switching with validation and history
367 | - Provides health monitoring and performance metrics
368 | - Emits framework change events for system coordination
369 |
370 | ##### Methodology Guides
371 |
372 | - **Location**: `/server/src/frameworks/adapters/`
373 | - **Purpose**: Single source of truth for framework behavior
374 | -
375 |
376 | #### Framework Guide Interface
377 |
378 | Each methodology guide implements `IMethodologyGuide` with these capabilities:
379 |
380 | - **Prompt Creation Guidance**: Structure suggestions, argument recommendations, quality guidance
381 | - **Template Processing**: Framework-specific processing steps and enhancements
382 | - **Execution Steps**: Step-by-step guidance for applying the methodology
383 | - **Methodology Enhancement**: Quality gates and validation criteria
384 | - **Compliance Validation**: Checks prompt compliance with methodology principles
385 |
386 | #### Framework Selection & Switching
387 |
388 | - **Dynamic Selection**: Frameworks can be selected based on prompt complexity, execution type, and user preference
389 | - **Runtime Switching**: Active framework can be changed via MCP tools (`switch_framework`)
390 | - **State Persistence**: Framework state maintained across sessions with history tracking
391 | - **Performance Monitoring**: Tracks framework switching success rates and response times
392 |
393 | #### Integration Points
394 |
395 | ##### Semantic Analysis Integration
396 |
397 | - **Location**: `/server/src/frameworks/integration/framework-semantic-integration.ts`
398 | - **Purpose**: Coordinates semantic analysis results with framework selection
399 | - **Key Features**:
400 | - Uses semantic analysis to inform framework selection
401 | - Provides framework-specific execution contexts
402 | - Maintains separation between analysis (WHAT) and methodology (HOW)
403 |
404 | ##### Framework-Aware Gates
405 |
406 | - **Location**: `/server/src/gates/integration/framework-aware-gates.ts`
407 | - **Purpose**: Gate validation that adapts to active framework
408 | - **Key Features**:
409 | - Framework-specific validation criteria
410 | - Methodology-aware quality gates
411 | - Adaptive gate evaluation based on framework context
412 |
413 | ##### Framework Injection
414 |
415 | - **Location**: `/server/src/execution/processor/framework-injector.ts`
416 | - **Purpose**: Injects framework-specific guidance into execution context
417 | - **Key Features**:
418 | - Dynamic system prompt generation from methodology guides
419 | - Framework-enhanced template processing
420 | - Execution context augmentation with methodology guidance
421 |
422 | ### Execution Strategy Architecture
423 |
424 | #### Strategy Pattern Implementation
425 |
426 | The system uses the strategy pattern to handle different types of prompt execution:
427 |
428 | ##### Execution Engine
429 |
430 | - **Location**: `/server/src/execution/engine.ts`
431 | - **Purpose**: Orchestrates execution using appropriate strategy
432 | - **Key Functions**:
433 | - Strategy selection based on execution mode (prompt/chain/workflow)
434 | - Context management across execution phases
435 | - Error handling and recovery
436 | - Performance monitoring and logging
437 |
438 | ##### Execution Strategies
439 |
440 | - **Location**: `/server/src/execution/strategies/`
441 | - **Available Strategies**:
442 | - **Prompt Strategy**: Single prompt execution with framework injection
443 | - **Chain Strategy**: Sequential multi-step prompt execution with state management
444 | - **Workflow Strategy**: Complex workflow execution with gate validation and branching logic
445 |
446 | #### Template Processing Pipeline
447 |
448 | 1. **Template Loading**: Nunjucks template loaded from prompt definition
449 | 2. **Framework Injection**: Active methodology guide provides system prompt enhancements
450 | 3. **Variable Substitution**: User arguments processed through template
451 | 4. **Context Enhancement**: Framework-specific context added to execution
452 | 5. **Execution**: Strategy-appropriate execution with monitoring
453 |
454 | #### Conversation Management
455 |
456 | - **Location**: `/server/src/execution/conversation.ts`
457 | - **Purpose**: Manages conversation state across execution strategies
458 | - **Key Features**:
459 | - Message history tracking
460 | - Context preservation between steps
461 | - Framework-aware conversation enhancement
462 | - State persistence for long-running workflows
463 |
464 | ### Development Patterns
465 |
466 | #### Hot-Reloading System
467 |
468 | - **File watching** for prompt changes
469 | - **Registry updates** without server restart
470 | - **Template recompilation** on modification
471 | - **MCP client notification** of changes
472 |
473 | #### Error Handling
474 |
475 | - **Comprehensive error boundaries** at all levels
476 | - **Graceful degradation** for partial failures
477 | - **Health monitoring** with periodic validation
478 | - **Rollback mechanisms** for startup failures
479 |
480 | #### Template Processing
481 |
482 | - **Nunjucks engine** with full feature support
483 | - **Dynamic variable substitution** from arguments
484 | - **Conditional logic** and loops in templates
485 | - **Macro system** for reusable components
486 |
487 | ### MCP Integration
488 |
489 | #### Protocol Implementation
490 |
491 | - **Model Context Protocol SDK** integration
492 | - **Tool registration** for prompt management
493 | - **Conversation management** with state tracking
494 | - **Transport abstraction** for multiple client types
495 |
496 | #### Available MCP Tools (User Interface)
497 |
498 | The server exposes 3 consolidated MCP tools that users interact with:
499 |
500 | - **`prompt_engine`** - Execute prompts with intelligent analysis and semantic detection
501 | - **`prompt_manager`** - Create, update, delete, and manage prompts with smart filtering
502 | - **`system_control`** - Framework switching, analytics, health monitoring, and system management
503 |
504 | ### Performance Considerations
505 |
506 | #### Startup Optimization
507 |
508 | - **Strategy-based server detection** with early termination
509 | - **Environment variable bypass** for instant path detection
510 | - **Conditional logging** based on verbosity level
511 | - **Dependency management** with proper initialization order
512 |
513 | #### Runtime Performance
514 |
515 | - **Memory usage monitoring** with periodic reporting
516 | - **Health check validation** every 30 seconds
517 | - **Diagnostic collection** for troubleshooting
518 | - **Graceful shutdown** with resource cleanup
519 |
520 | ### Enhanced Systems
521 |
522 | #### Framework System Integration
523 |
524 | - **Methodology-driven architecture** with CAGEERF, ReACT, 5W1H, SCAMPER framework guides
525 | - **Dynamic framework switching** with runtime state management and performance monitoring
526 | - **Framework-aware quality gates** that adapt validation criteria based on active methodology
527 | - **Semantic analysis integration** for intelligent framework selection
528 | - **Framework injection system** for methodology-specific system prompt enhancement
529 |
530 | #### Execution Strategy System
531 |
532 | - **Strategy pattern implementation** with prompt, chain, and workflow execution strategies
533 | - **Execution engine orchestration** with context management and error recovery
534 | - **Template processing pipeline** with framework injection and Nunjucks template processing
535 | - **Conversation state management** with framework-aware conversation enhancement
536 |
537 | #### Gate Validation System
538 |
539 | - **Gate Registry** manages validation rules and quality gates with framework awareness
540 | - **Enhanced Gate Evaluators** with intelligent workflow validation and methodology-specific criteria
541 | - **Framework-aware gates** that adapt validation based on active framework context
542 | - **Multi-level validation** supporting validation, approval, condition, and quality gate types
543 |
544 | #### Advanced Analysis System
545 |
546 | - **Semantic Analyzer** for automatic prompt type detection and execution strategy recommendation
547 | - **Framework-semantic integration** coordinating analysis results with methodology selection
548 | - **Execution type detection** (prompt/chain/workflow) with framework-appropriate handling
549 | - **Quality assessment** with framework-specific validation criteria
550 |
551 | ### Key Development Guidelines
552 |
553 | - **Each functional area MUST have exactly ONE primary implementation**
554 | - **NEVER add new systems without explicit deprecation of old ones**
555 |
556 | ##### Dependency Direction Enforcement
557 |
558 | - **Establish clear architectural hierarchy** - lower layers cannot import from higher layers
559 | - **Bidirectional imports are STRICTLY FORBIDDEN**
560 | - **Example Fix Required**: `execution-coordinator.ts` ↔ `strategies/index.ts` circular import must be broken
561 | - **Use dependency injection or event patterns** instead of circular imports
562 |
563 | ##### Consolidation Over Addition Policy
564 |
565 | - **Strong preference for enhancing existing systems vs creating new ones**
566 | - **Question before coding**: "Can this functionality be added to an existing system?"
567 | - **Require architectural justification** for creating parallel systems
568 | - **Code reviews must verify no duplicate functionality is being introduced**
569 |
570 | #### Framework Development Rules
571 |
572 | ##### Methodology Guides as Single Source of Truth
573 |
574 | - **Never hard-code framework behavior** - All framework logic must come from methodology guides
575 | - **Methodology guides define framework identity** - `frameworkId`, `frameworkName`, `methodology` in guides
576 | - **Dynamic framework generation** - Framework definitions generated from guide metadata, not static configuration
577 | - **Guide-driven enhancements** - All framework-specific behavior (system prompts, quality gates, validation) comes from guide methods
578 |
579 | ##### Domain Cohesion Principles
580 |
581 | - **Framework logic belongs in `/frameworks`** - Keep all framework-related logic centralized
582 | - **Separate stateless from stateful** - Framework manager (stateless orchestration) separate from state manager (stateful tracking)
583 | - **Clear separation of concerns** - Analysis (WHAT the prompt needs) separate from methodology (HOW to approach it)
584 | - **Integration points are explicit** - Framework integration clearly defined in `/integration` directory
585 |
586 | ##### Methodology Guide Development
587 |
588 | - **Implement `IMethodologyGuide` interface** - All guides must follow the established contract
589 | - **Provide comprehensive guidance** - Implement all required methods: `guidePromptCreation`, `guideTemplateProcessing`, `guideExecutionSteps`, `enhanceWithMethodology`, `validateMethodologyCompliance`
590 | - **Framework-specific quality gates** - Each guide defines its own validation criteria and quality gates
591 | - **Template enhancement suggestions** - Guides provide specific suggestions for improving prompts
592 | - **Methodology validation** - Guides can validate prompt compliance with their methodology principles
593 |
594 | ##### Framework Integration Standards
595 |
596 | - **No direct framework coupling** - Other systems integrate through framework manager, not directly with guides
597 | - **Event-driven communication** - Framework state changes communicated through events
598 | - **Semantic analysis coordination** - Framework selection informed by, but not dependent on, semantic analysis
599 | - **Gate system integration** - Gates adapt to active framework but remain framework-agnostic in core logic
600 |
601 | #### Configuration Management
602 |
603 | - Use environment variables for path overrides (`MCP_SERVER_ROOT`, `MCP_PROMPTS_CONFIG_PATH`)
604 | - Maintain separation between server config and prompts config
605 | - Follow modular import patterns for prompt organization
606 | - Configure absolute paths for reliable Claude Desktop integration
607 | -
608 |
609 | #### Error Handling
610 |
611 | - Implement comprehensive error boundaries at all orchestration levels
612 | - Use structured logging with appropriate levels (supports both verbose and quiet modes)
613 | - Provide meaningful error messages with diagnostic information
614 | - Include rollback mechanisms for startup failures
615 |
616 | #### Testing
617 |
618 | - Test transport layer compatibility (STDIO and SSE)
619 | - Validate prompt template rendering with Nunjucks engine
620 | - Check hot-reloading functionality and workflow engine integration
621 | - Verify MCP protocol compliance and framework system validation
622 | - Test framework switching functionality and state persistence
623 |
624 | ### Environment Setup
625 |
626 | #### Required Environment Variables
627 |
628 | - `MCP_SERVER_ROOT`: Override server root directory detection (recommended for Claude Desktop)
629 | - `MCP_PROMPTS_CONFIG_PATH`: Direct path to prompts configuration file (bypasses server root detection)
630 |
631 | ## Project-Specific Development Integration
632 |
633 | ### MCP-Specific Development Standards
634 |
635 | **Project-Specific Requirements:**
636 |
637 | - **System Architecture Analysis**: Understand MCP server structure, framework system, and execution strategies
638 | - **Integration Point Mapping**: Components affected by changes (frameworks/, execution/, mcp-tools/, etc.)
639 | - **Performance Impact Assessment**: Baseline metrics and performance-sensitive areas for MCP protocol
640 | - **Client Compatibility Check**: Maintain Claude Desktop, web client, and MCP protocol compatibility
641 |
642 | **MCP Development Focus Areas:**
643 |
644 | - **Framework System**: Changes must work with all methodology guides
645 | - **Hot-Reload Compatibility**: File watching and registry updates for prompt management
646 | - **Multi-Transport Support**: Validate STDIO and SSE transport compatibility
647 | - **Command Routing System**: Lightweight routing optimized for LLM interactions (see Command Format Specification below)
648 |
649 | ### Command Format Specification
650 |
651 | The system uses a simplified CommandRouter (149 lines) optimized for LLM interactions, replacing the legacy parsing system (1,354 lines) with 84% code reduction.
652 |
653 | #### Supported Command Formats
654 |
655 | **1. Simple Format** (Most Common):
656 | ```
657 | >>prompt_name arguments
658 | ```
659 |
660 | **Examples**:
661 | ```
662 | >>listprompts
663 | >>analyze_code function foo() { return bar; }
664 | >>code_review target_code="./src/app.ts" language_framework="TypeScript/React"
665 | ```
666 |
667 | **2. JSON Format** (Structured Data):
668 | ```json
669 | {
670 | "command": ">>prompt_name",
671 | "args": { "key": "value", "key2": "value2" }
672 | }
673 | ```
674 |
675 | **Examples**:
676 | ```json
677 | {
678 | "command": ">>analyze_code",
679 | "args": {
680 | "code": "function foo() { return bar; }",
681 | "language": "javascript"
682 | }
683 | }
684 | ```
685 |
686 | #### Built-in Commands
687 |
688 | The following commands are handled specially by the system:
689 |
690 | - `listprompts`, `list_prompts`, `listprompt` - List all available prompts
691 | - `help`, `commands` - Show command help
692 | - `status`, `health` - Server status and health diagnostics
693 | - `analytics`, `metrics` - Usage analytics and performance metrics
694 |
695 | #### Command Resolution
696 |
697 | - **Case-Insensitive**: `>>ANALYZE_CODE` and `>>analyze_code` both work
698 | - **Name or ID**: Match by prompt ID or prompt name
699 | - **No Typo Correction**: LLMs send exact command names (no Levenshtein distance)
700 | - **Clear Error Messages**: Unknown prompts suggest using `>>listprompts`
701 |
702 | #### Argument Processing
703 |
704 | **Automatic Format Detection**:
705 |
706 | 1. **JSON args**: Parsed directly (LLMs send correct types)
707 | 2. **Single argument prompts**: Text mapped to first parameter
708 | 3. **Key=value format**: `key1="value1" key2="value2"`
709 | 4. **Simple text**: Passed as-is to first argument or `input` parameter
710 |
711 | **Type Handling**:
712 | - LLMs send correct types (no coercion needed)
713 | - Zod schema validation at MCP tool level
714 | - Optional: Use `z.coerce.number()` if type coercion needed
715 |
716 | #### Template Context Variables
717 |
718 | Special variables available in templates:
719 |
720 | - `{{previous_message}}` - Resolved from conversation history
721 | - `{{arg_name}}` - Any prompt argument
722 | - Framework-specific context injected automatically
723 |
724 | #### Migration from Legacy System
725 |
726 | **Removed Features** (No longer needed for LLM usage):
727 | - Typo correction (Levenshtein distance)
728 | - Type coercion (LLMs send correct types)
729 | - Smart content mapping (LLMs use schema descriptions)
730 | - Content-aware inference (over-engineered)
731 | - Environment variable defaults (rarely used)
732 |
733 | **See Also**:
734 | - Migration Guide: `docs/parser-migration-guide.md`
735 | - Refactoring Plan: `plans/parser-simplification-refactor.md`
736 | - CommandRouter Source: `server/src/execution/routing/command-router.ts`
737 |
738 | ## Coding Guidelines and Development Rules
739 |
740 | ### Enhanced Search System Implementation
741 |
742 | The system now includes advanced search capabilities implemented in `consolidated-prompt-manager.ts`:
743 |
744 | #### Search Filter Syntax
745 |
746 | - **Category Filtering**: `category:code`, `category:analysis`, `category:research`
747 | - **Intent-Based Discovery**: `intent:debugging`, `intent:analysis`, `intent:research`
748 | - **Execution Type Filtering**: `type:prompt`, `type:template`, `type:chain`, `type:workflow`
749 | - **Confidence-Based Filtering**: `confidence:>80`, `confidence:<100`, `confidence:70-90`
750 | - **Quality Gate Filtering**: `gates:yes`, `gates:no`
751 | - **Execution Requirements**: `execution:required`, `execution:optional`
752 | - **Text Search**: Supports fuzzy matching and partial word matching
753 | - **Combined Filters**: Multiple filters can be combined: `category:code type:workflow confidence:>80`
754 |
755 | #### Search Implementation Rules
756 |
757 | - **Fuzzy Text Matching**: Searches support partial word matching and multiple search terms
758 | - **Intent-Based Matching**: Maps user intents to relevant prompts using semantic analysis
759 | - **Category-Aware Results**: Results are organized by category with proper filtering
760 | - **LLM-Optimized Output**: Results include usage examples, confidence indicators, and actionable descriptions
761 |
762 | ### TypeScript Development Standards
763 |
764 | #### Type Safety Requirements
765 |
766 | - **Strict TypeScript**: All code must compile with strict TypeScript settings
767 | - **Explicit Typing**: Avoid `any` types - use proper interfaces and generic types
768 | - **Parameter Typing**: Always provide explicit types for function parameters, especially in callbacks and array methods
769 | - **Interface Implementation**: All framework guides must implement `IMethodologyGuide` interface completely
770 |
771 | #### ES Module Standards
772 |
773 | - **ES Module Syntax**: Use `import`/`export` syntax, not CommonJS `require()`
774 | - **File Extensions**: Import paths must include `.js` extension (TypeScript compiles to `.js`)
775 | - **Module Resolution**: Follow the moduleNameMapper in jest.config.cjs for consistent resolution
776 |
777 | ### Testing Standards
778 |
779 | #### Testing & Validation Commands
780 |
781 | **Essential Commands:**
782 |
783 | - `npm run test:ci` - Complete test suite (unit + integration + performance)
784 | - `npm run test:all-enhanced` - Enhanced framework and MCP validation
785 | - `npm run validate:all` - Core validation (dependencies + circular)
786 | - `npm run test:ci-startup` - Server startup validation
787 |
788 | **Quality Standards:**
789 |
790 | - **Jest Configuration**: ES modules, 30s timeout, single worker, `tests/setup.ts`
791 | - **Validation Integration**: Global Rules quality gates with evidence-based criteria
792 | - **Architecture Compliance**: Single source of truth principle enforcement
793 |
794 | ### Code Quality Standards
795 |
796 | #### Consolidated Tool Development Rules
797 |
798 | - **Single Responsibility**: Each consolidated tool handles one major functional area (execution, management, system control)
799 | - **Intelligent Filtering**: Support advanced filter syntax in prompt manager for discovery and organization
800 | - **Response Consistency**: All tools return standardized `ToolResponse` interface with consistent error handling
801 | - **Backwards Compatibility**: Maintain API compatibility when adding new features or filter types
802 |
803 | #### Framework Development Rules
804 |
805 | - **Methodology Guides**: All framework behavior must come from methodology guides, never hard-coded
806 | - **Interface Compliance**: New methodology guides must implement all required `IMethodologyGuide` methods
807 | - **Domain Separation**: Framework logic stays in `/frameworks`, semantic analysis in `/analysis`
808 | - **Integration Points**: Framework integration must be explicit and documented in `/integration` directory
809 |
810 | #### MCP Tool Development
811 |
812 | - **Tool Registration**: All MCP tools must be registered with proper Zod schema validation
813 | - **Error Handling**: Use the utility `handleError()` function for consistent error responses
814 | - **Response Format**: All tool responses must use the standardized `ToolResponse` interface
815 | - **Argument Validation**: Validate all required fields using `validateRequiredFields()` helper
816 |
817 | ### Development Workflow Standards
818 |
819 | #### Pre-Development Checklist (MANDATORY)
820 |
821 | Before starting any feature or system:
822 |
823 | 1. **System Overlap Check**: Run `npm run validate:all` to detect existing systems
824 | 2. **Architecture Review**: Can this be added to an existing system instead of creating new one?
825 | 3. **Dependency Check**: Will this create circular dependencies? Use `npm run validate:circular`
826 | 4. **Single Source Verification**: Does this violate "one system per function" rule?
827 |
828 | #### Code Changes
829 |
830 | - **System Validation First**: Run `npm run validate:all` before committing
831 | - **Type Check**: Always run `npm run typecheck` before committing
832 | - **Build Verification**: Run `npm run build` to ensure compilation succeeds
833 | - **Test Validation**: Run relevant test suites for changed components
834 | - **Hot-Reload Testing**: Verify changes work with `npm run dev` and hot-reloading
835 |
836 | #### Consolidated Tool Changes
837 |
838 | When modifying the consolidated MCP tools:
839 |
840 | 1. **Tool Schema Updates**: Update Zod schema validation for new parameters or options
841 | 2. **Response Format**: Maintain consistent `ToolResponse` interface across all tools
842 | 3. **Error Handling**: Use standardized `handleError()` function for consistent error responses
843 | 4. **Filter Support**: Add new filter types to intelligent filtering system in prompt manager
844 | 5. **Test Coverage**: Verify changes work with relevant test suites (`npm run test:mcp-tools`)
845 |
846 | #### Framework System Changes
847 |
848 | When modifying framework components:
849 |
850 | 1. **Methodology guides are single source of truth** - never bypass guide methods
851 | 2. **Test framework switching** using MCP tools after changes
852 | 3. **Validate guide interface compliance** with all required methods
853 | 4. **Ensure integration points remain decoupled** from direct guide access
854 |
855 | ## 🚀 Enhanced Development Standards Integration
856 |
857 | ### Evidence-Based Development Protocol
858 |
859 | **Required Language Standards** (from Global Rules):
860 |
861 | - **Prohibited**: "best|optimal|faster|secure|better|improved|enhanced|always|never|guaranteed"
862 | - **Required**: "may|could|potentially|typically|often|sometimes|measured|documented"
863 | - **Evidence**: "testing confirms|metrics show|benchmarks prove|data indicates|documentation states"
864 |
865 | **Research & Validation Standards**:
866 |
867 | - **Citations**: Official documentation required | Version compatibility verified | Sources documented
868 | - **Context7 Integration**: External libraries and documentation lookup for MCP protocol compliance
869 | - **WebSearch**: Official sources and current information for TypeScript/Node.js patterns
870 | - **Evidence before implementation**: Research → validate → implement (Global Rules workflow)
871 | - **Protocol Compliance**: All changes must maintain MCP SDK compatibility
872 |
873 | ### Environment & Deployment
874 |
875 | **Development Setup**: Node.js 16+ | TypeScript strict mode | Environment variables: `MCP_SERVER_ROOT`, `MCP_PROMPTS_CONFIG_PATH`
876 | **Transport Testing**: `npm run start:stdio` (Claude Desktop) | `npm run start:sse` (web clients)
877 | **CI/CD**: Cross-platform testing (Ubuntu/Windows/macOS, Node 16/18/20) | Quality gates with evidence-based validation
878 |
879 | #### Performance Budgets
880 |
881 | - Server startup: <3s | Tool response: <500ms | Framework switching: <100ms | Memory: <128MB
882 |
883 | ---
884 |
885 | **Integration**: @include ~/.claude/CLAUDE.md + MCP Protocol Compliance
886 |
```
--------------------------------------------------------------------------------
/server/prompts/documentation/prompts.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "prompts": []
3 | }
```
--------------------------------------------------------------------------------
/server/src/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
1 | version: 1
2 | start:
3 | command: ["node", "dist/index.js", "--transport=stdio", "--quiet"]
4 |
```
--------------------------------------------------------------------------------
/server/src/frameworks/integration/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Framework Integration Components
3 | * Semantic-framework integration layer
4 | */
5 |
6 | export * from './framework-semantic-integration.js';
```
--------------------------------------------------------------------------------
/server/prompts/testing/final_verification_test.md:
--------------------------------------------------------------------------------
```markdown
1 | # Final Verification Test
2 |
3 | ## Description
4 | Final verification of all isLLMEnabled() refactoring
5 |
6 | ## User Message Template
7 | This is the final test: {{input}}
8 |
```
--------------------------------------------------------------------------------
/config/framework-state.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "version": "1.0.0",
3 | "frameworkSystemEnabled": false,
4 | "activeFramework": "CAGEERF",
5 | "lastSwitchedAt": "2025-10-14T10:55:24.202Z",
6 | "switchReason": "Initial framework selection"
7 | }
```
--------------------------------------------------------------------------------
/server/tsconfig.test.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "extends": "./tsconfig.json",
3 | "compilerOptions": {
4 | "types": ["node", "jest"],
5 | "noEmit": true
6 | },
7 | "include": ["src/**/*", "tests/**/*"],
8 | "exclude": ["node_modules", "dist"]
9 | }
```
--------------------------------------------------------------------------------
/server/config/framework-state.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "version": "1.0.0",
3 | "frameworkSystemEnabled": true,
4 | "activeFramework": "CAGEERF",
5 | "lastSwitchedAt": "2025-10-14T10:55:00.754Z",
6 | "switchReason": "User request to enable CAGEERF framework."
7 | }
```
--------------------------------------------------------------------------------
/server/src/gates/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Gate System - Core Implementation
3 | *
4 | * The gate system provides validation and guidance capabilities for prompt execution.
5 | * This is the main gate system implementation.
6 | */
7 |
8 | // Export core gate system as primary interface
9 | export * from './core/index.js';
```
--------------------------------------------------------------------------------
/server/src/execution/context/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Context System Export Module
3 | *
4 | * Centralizes all context resolution infrastructure exports
5 | */
6 |
7 | export {
8 | ContextResolver,
9 | createContextResolver,
10 | type ContextResolution,
11 | type ContextProvider,
12 | type ContextSource,
13 | type ContextAggregationOptions
14 | } from './context-resolver.js';
```
--------------------------------------------------------------------------------
/server/src/performance/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Performance Monitoring Module
3 | *
4 | * Exports performance monitoring and optimization functionality
5 | * for the MCP server system.
6 | */
7 |
8 | export {
9 | PerformanceMonitor,
10 | createPerformanceMonitor,
11 | type PerformanceMetrics,
12 | type PerformanceThresholds,
13 | type PerformanceAlert
14 | } from "./monitor.js";
```
--------------------------------------------------------------------------------
/server/src/mcp-tools/prompt-manager/core/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Prompt Manager Core Module Exports
3 | *
4 | * This index file provides unified access to all core prompt manager functionality
5 | * to resolve module resolution issues in CI/CD environments.
6 | */
7 |
8 | // Re-export the consolidated prompt manager
9 | export * from './manager.js';
10 |
11 | // Re-export all core types and interfaces
12 | export * from './types.js';
```
--------------------------------------------------------------------------------
/server/prompts/testing/prompts.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "prompts": [
3 | {
4 | "id": "final_verification_test",
5 | "name": "Final Verification Test",
6 | "category": "testing",
7 | "description": "Final verification of all isLLMEnabled() refactoring",
8 | "file": "final_verification_test.md",
9 | "arguments": [
10 | {
11 | "name": "input",
12 | "type": "string",
13 | "description": "Test input"
14 | }
15 | ]
16 | }
17 | ]
18 | }
```
--------------------------------------------------------------------------------
/scripts/windows-tests/test-windows-startup.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | # Test Windows-like startup scenarios
3 |
4 | echo "Testing Windows-compatible startup..."
5 |
6 | # Simulate Windows environment
7 | export RUNNER_OS=Windows
8 | export PATH="/c/Windows/System32:$PATH"
9 |
10 | # Test Node.js startup
11 | cd server
12 | echo "Testing Node.js startup in Windows-like environment..."
13 | node --version
14 | npm --version
15 |
16 | # Test our application
17 | echo "Testing MCP server startup..."
18 | npm run help
19 |
20 | echo "✅ Windows startup test completed"
21 |
```
--------------------------------------------------------------------------------
/scripts/windows-tests/windows-env.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | # Windows environment simulation - no sensitive files
3 | export RUNNER_OS=Windows
4 | export PATH="/c/Windows/System32:/c/Windows:/c/Windows/System32/Wbem:$PATH"
5 | export USERPROFILE=/c/Users/runneradmin
6 | export TEMP=/c/Users/runneradmin/AppData/Local/Temp
7 | export TMP=/c/Users/runneradmin/AppData/Local/Temp
8 | export HOMEDRIVE=C:
9 | export HOMEPATH=/Users/runneradmin
10 | export PATHEXT=.COM:.EXE:.BAT:.CMD:.VBS:.VBE:.JS:.JSE:.WSF:.WSH:.MSC
11 | echo "Windows environment variables set"
12 |
```
--------------------------------------------------------------------------------
/server/prompts/education/prompts.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "prompts": [
3 | {
4 | "id": "vault_integrated_notes",
5 | "name": "Vault-Integrated Notes Creator",
6 | "category": "education",
7 | "description": "Create comprehensive notes that search the vault for real related notes instead of generating fictional ones",
8 | "file": "vault_integrated_notes.md",
9 | "arguments": [
10 | {
11 | "name": "topic",
12 | "description": "The topic to create comprehensive vault-integrated notes about",
13 | "required": true
14 | }
15 | ]
16 | }
17 | ]
18 | }
```
--------------------------------------------------------------------------------
/server/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "compilerOptions": {
3 | "target": "ES2020",
4 | "lib": ["ES2020"],
5 | "module": "NodeNext",
6 | "moduleResolution": "NodeNext",
7 | "types": ["node"],
8 | "esModuleInterop": true,
9 | "allowSyntheticDefaultImports": true,
10 | "forceConsistentCasingInFileNames": true,
11 | "strict": true,
12 | "skipLibCheck": true,
13 | "isolatedModules": true,
14 | "outDir": "dist",
15 | "sourceMap": true,
16 | "declaration": true,
17 | "resolveJsonModule": true
18 | },
19 | "include": ["src/**/*"],
20 | "exclude": ["node_modules", "dist", "tests"]
21 | }
```
--------------------------------------------------------------------------------
/server/src/metrics/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Metrics Module Exports
3 | *
4 | * Centralized exports for the metrics collector and related types.
5 | * Provides event-driven metrics collection separated from execution logic.
6 | */
7 |
8 | // Metrics collector
9 | export {
10 | MetricsCollector,
11 | createMetricsCollector
12 | } from './analytics-service.js';
13 |
14 | // Types
15 | export type {
16 | ExecutionData,
17 | GateValidationData,
18 | FrameworkSwitchData,
19 | ExecutionStats,
20 | SystemMetrics,
21 | FrameworkUsage,
22 | AnalyticsEvent,
23 | AnalyticsQueryOptions,
24 | AnalyticsSummary,
25 | PerformanceTrend
26 | } from './types.js';
```
--------------------------------------------------------------------------------
/server/src/mcp-tools/prompt-engine/core/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Prompt Engine Core Module Exports
3 | *
4 | * This index file provides unified access to all core prompt engine functionality
5 | * to resolve module resolution issues in CI/CD environments.
6 | */
7 |
8 | // Re-export the main execution engine (excluding conflicting types)
9 | export {
10 | ConsolidatedPromptEngine,
11 | createConsolidatedPromptEngine
12 | } from './engine.js';
13 |
14 | // Re-export the prompt executor
15 | export * from './executor.js';
16 |
17 | // Re-export all core types and interfaces (primary source for PromptClassification)
18 | export * from './types.js';
```
--------------------------------------------------------------------------------
/server/src/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
1 | FROM node:20-alpine
2 |
3 | # Set working directory
4 | WORKDIR /app
5 |
6 | # Copy package files first for better layer caching
7 | COPY package*.json ./
8 |
9 | # Install all dependencies
10 | RUN npm ci
11 |
12 | # Copy source code
13 | COPY . .
14 |
15 | # Build the TypeScript project
16 | RUN npm run build
17 |
18 | # Remove dev dependencies to reduce image size
19 | RUN npm ci --only=production && npm cache clean --force
20 |
21 | # Set environment variables
22 | ENV NODE_ENV=production
23 | ENV MCP_SERVER_ROOT=/app
24 |
25 | # Expose port
26 | EXPOSE 8000
27 |
28 | # Start the server
29 | CMD ["node", "dist/index.js", "--transport=stdio", "--quiet"]
```
--------------------------------------------------------------------------------
/scripts/windows-tests/test-windows-paths.js:
--------------------------------------------------------------------------------
```javascript
1 | // Test Windows path handling
2 | const path = require('path');
3 | const os = require('os');
4 |
5 | console.log('Testing Windows-compatible path handling...');
6 | console.log('Platform:', os.platform());
7 | console.log('Path separator:', path.sep);
8 | console.log('Path delimiter:', path.delimiter);
9 |
10 | // Test path operations that should work cross-platform
11 | const testPath = path.join('server', 'src', 'index.ts');
12 | console.log('Cross-platform path:', testPath);
13 |
14 | // Test environment variables
15 | console.log('NODE_ENV:', process.env.NODE_ENV);
16 | console.log('RUNNER_OS:', process.env.RUNNER_OS);
17 |
18 | console.log('✅ Windows compatibility test passed');
19 |
```
--------------------------------------------------------------------------------
/server/config.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "server": {
3 | "name": "claude-prompts-mcp",
4 | "version": "1.3.0",
5 | "port": 9090
6 | },
7 | "prompts": {
8 | "file": "prompts/promptsConfig.json"
9 | },
10 | "analysis": {
11 | "semanticAnalysis": {
12 | "enabled": false,
13 | "llmIntegration": {
14 | "enabled": false,
15 | "apiKey": null,
16 | "endpoint": null,
17 | "model": "gpt-4",
18 | "maxTokens": 1000,
19 | "temperature": 0.1
20 | }
21 | }
22 | },
23 | "gates": {
24 | "definitionsDirectory": "src/gates/definitions",
25 | "templatesDirectory": "src/gates/templates"
26 | },
27 | "transports": {
28 | "default": "stdio"
29 | },
30 | "logging": {
31 | "directory": "./logs",
32 | "level": "debug"
33 | }
34 | }
35 |
```
--------------------------------------------------------------------------------
/server/prompts/development/analyze_code_structure.md:
--------------------------------------------------------------------------------
```markdown
1 | # Analyze Code Structure
2 |
3 | ## Description
4 | Analyzes the structure and patterns of provided code.
5 |
6 | ## System Message
7 | You are a code structure analyst who provides clear, objective observations about code organization and architecture.
8 |
9 | ## User Message Template
10 | Please analyze the structure of the following {{language}} code:
11 |
12 | ```{{language}}
13 | {{code}}
14 | ```
15 |
16 | Provide a detailed analysis including:
17 | 1. Overall architecture and code organization
18 | 2. Function/method structure and relationships
19 | 3. Data flow patterns
20 | 4. Key design patterns used
21 | 5. Code complexity assessment
22 |
23 | Keep your analysis descriptive rather than prescriptive - focus on what the code does, not what should be changed.
```
--------------------------------------------------------------------------------
/server/prompts/debugging/prompts.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "prompts": [
3 | {
4 | "id": "analyze_logs",
5 | "name": "Advanced Log Analysis & Debugging",
6 | "category": "debugging",
7 | "description": "Comprehensive log analysis template incorporating advanced debugging strategies used by senior developers and SREs for systematic root cause analysis",
8 | "file": "analyze_logs.md",
9 | "arguments": [
10 | {
11 | "name": "logs",
12 | "description": "The complete log entries to analyze",
13 | "required": true
14 | },
15 | {
16 | "name": "context",
17 | "description": "Additional context: system state, recent changes, user reports, etc.",
18 | "required": false
19 | }
20 | ]
21 | }
22 | ]
23 | }
```
--------------------------------------------------------------------------------
/server/src/gates/constants.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Gate System Constants
3 | *
4 | * Centralized behavioral settings for the gate system.
5 | * These were previously configurable but are now set as sensible defaults.
6 | */
7 |
8 | /**
9 | * Default retry limit for failed validations
10 | */
11 | export const DEFAULT_RETRY_LIMIT = 3;
12 |
13 | /**
14 | * Whether to inject gate guidance into prompts by default
15 | */
16 | export const ENABLE_GUIDANCE_INJECTION = true;
17 |
18 | /**
19 | * Whether to perform gate validation by default
20 | */
21 | export const ENABLE_VALIDATION = true;
22 |
23 | /**
24 | * Default gate system behavioral configuration
25 | */
26 | export const GATE_SYSTEM_DEFAULTS = {
27 | defaultRetryLimit: DEFAULT_RETRY_LIMIT,
28 | enableGuidanceInjection: ENABLE_GUIDANCE_INJECTION,
29 | enableValidation: ENABLE_VALIDATION,
30 | } as const;
```
--------------------------------------------------------------------------------
/server/src/frameworks/methodology/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Methodology System Index - Phase 2 Implementation
3 | *
4 | * Centralized exports for the reorganized methodology system.
5 | * Provides clean imports for methodology guides, registry, and interfaces.
6 | */
7 |
8 | // Export methodology registry
9 | export { MethodologyRegistry, createMethodologyRegistry } from "./registry.js";
10 | export type { MethodologyRegistryConfig, MethodologyGuideEntry } from "./registry.js";
11 |
12 | // Export methodology interfaces
13 | export * from "./interfaces.js";
14 |
15 | // Export methodology guides from new location
16 | export { CAGEERFMethodologyGuide } from "./guides/cageerf-guide.js";
17 | export { ReACTMethodologyGuide } from "./guides/react-guide.js";
18 | export { FiveW1HMethodologyGuide } from "./guides/5w1h-guide.js";
19 | export { SCAMPERMethodologyGuide } from "./guides/scamper-guide.js";
```
--------------------------------------------------------------------------------
/server/src/frameworks/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Framework System (Phase 2: Methodology System Reorganization)
3 | * Streamlined framework system with consolidated type definitions,
4 | * organized methodology system, and framework behavior guidance
5 | */
6 |
7 | // Consolidated type definitions (Phase 1: NEW)
8 | export * from './types/index.js';
9 |
10 | // Methodology system (Phase 2: NEW)
11 | export * from './methodology/index.js';
12 |
13 | // Framework managers (stateless orchestration and stateful management)
14 | export * from './framework-manager.js';
15 | export * from './framework-state-manager.js';
16 |
17 | // Framework system components (stateful methodology switching)
18 | export * from './integration/index.js';
19 |
20 | // Prompt guidance system (Phase 3: NEW)
21 | export * from './prompt-guidance/index.js';
22 |
23 | // Methodology guides exported from ./methodology/ (single source of truth)
24 | // Legacy adapters directory removed - no duplication
```
--------------------------------------------------------------------------------
/server/prompts/development/detect_code_issues.md:
--------------------------------------------------------------------------------
```markdown
1 | # Detect Code Issues
2 |
3 | ## Description
4 | Identifies potential bugs, performance issues, and code smells in the provided code.
5 |
6 | ## System Message
7 | You are a code quality expert who specializes in identifying potential issues, bugs, and areas for improvement in code.
8 |
9 | ## User Message Template
10 | Based on the following code and its structural analysis, please identify potential issues:
11 |
12 | Code:
13 | ```{{language}}
14 | {{code}}
15 | ```
16 |
17 | Previous Analysis:
18 | {{analysis}}
19 |
20 | Identify and list potential issues in these categories:
21 | 1. Bugs and logical errors
22 | 2. Performance concerns
23 | 3. Security vulnerabilities
24 | 4. Maintainability problems
25 | 5. Edge cases not properly handled
26 |
27 | For each issue, provide:
28 | - A clear description of the problem
29 | - The specific location in the code (line or function)
30 | - The potential impact of the issue
31 | - The level of severity (Critical, High, Medium, Low)
```
--------------------------------------------------------------------------------
/server/src/frameworks/methodology/interfaces.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Methodology Interfaces - Phase 2 Implementation
3 | *
4 | * Consolidated interfaces for methodology guides and registry management.
5 | * This file centralizes all methodology-related interfaces that were
6 | * previously distributed across multiple files.
7 | */
8 |
9 | // Re-export all methodology interfaces from the consolidated types
10 | export type {
11 | IMethodologyGuide,
12 | PromptCreationGuidance,
13 | ProcessingGuidance,
14 | StepGuidance,
15 | MethodologyEnhancement,
16 | ArgumentGuidance,
17 | ProcessingStep,
18 | ExecutionStep,
19 | QualityGate,
20 | TemplateEnhancement,
21 | MethodologyToolDescription,
22 | MethodologyToolDescriptions,
23 | MethodologyValidation
24 | } from "../types/methodology-types.js";
25 |
26 | export {
27 | BaseMethodologyGuide
28 | } from "../types/methodology-types.js";
29 |
30 | // Registry-specific interfaces
31 | export type {
32 | MethodologyRegistryConfig,
33 | MethodologyGuideEntry
34 | } from "./registry.js";
```
--------------------------------------------------------------------------------
/server/prompts/general/prompts.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "prompts": [
3 | {
4 | "id": "diagnose",
5 | "name": "Codebase Diagnostics",
6 | "category": "general",
7 | "description": "Systematically diagnose issues in codebases including bugs, performance problems, security vulnerabilities, architecture issues, and technical debt",
8 | "file": "diagnose.md",
9 | "arguments": [
10 | {
11 | "name": "scope",
12 | "description": "Specific files, directories, or areas to analyze (e.g., 'src/auth/**', 'performance issues', 'security')"
13 | },
14 | {
15 | "name": "focus",
16 | "description": "Specific diagnostic focus (e.g., 'security', 'performance', 'architecture', 'type errors')"
17 | },
18 | {
19 | "name": "symptoms",
20 | "description": "Reported symptoms or problems (e.g., 'slow build times', 'memory leaks', 'failing tests')"
21 | }
22 | ]
23 | }
24 | ]
25 | }
```
--------------------------------------------------------------------------------
/server/src/mcp-tools/prompt-manager/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Prompt Manager - Modular Architecture Entry Point
3 | *
4 | * This module maintains 100% backwards compatibility while providing
5 | * a modular internal architecture for improved maintainability.
6 | */
7 |
8 | // Export the main class and factory function with exact same API
9 | export { ConsolidatedPromptManager } from "./core/manager.js";
10 | export { createConsolidatedPromptManager } from "./core/manager.js";
11 |
12 | // Export types for external use
13 | export type {
14 | PromptClassification,
15 | AnalysisResult,
16 | SmartFilters
17 | } from "./core/types.js";
18 |
19 | // Backwards compatibility exports
20 | export type { PromptManagerDependencies } from "./core/types.js";
21 |
22 | /**
23 | * Re-export all original interfaces to maintain API compatibility
24 | */
25 | export type {
26 | PromptManagerModule,
27 | PromptManagerData,
28 | OperationResult,
29 | CategoryResult,
30 | FileOperationResult,
31 | DependencyAnalysis,
32 | MigrationResult,
33 | ValidationContext
34 | } from "./core/types.js";
```
--------------------------------------------------------------------------------
/server/prompts/development/suggest_code_improvements.md:
--------------------------------------------------------------------------------
```markdown
1 | # Suggest Code Improvements
2 |
3 | ## Description
4 | Suggests specific improvements to address identified issues and enhance code quality.
5 |
6 | ## System Message
7 | You are a code improvement specialist who provides actionable, targeted suggestions to enhance code quality, readability, and performance.
8 |
9 | ## User Message Template
10 | Based on the code analysis and identified issues, please suggest specific improvements:
11 |
12 | Code:
13 | ```{{language}}
14 | {{code}}
15 | ```
16 |
17 | Analysis:
18 | {{analysis}}
19 |
20 | Identified Issues:
21 | {{issues}}
22 |
23 | Provide improvement recommendations in these areas:
24 | 1. Bug fixes and logical error corrections
25 | 2. Performance optimizations
26 | 3. Security enhancements
27 | 4. Maintainability improvements
28 | 5. Code organization and structure
29 |
30 | For each recommendation:
31 | - Provide a clear explanation of the improvement
32 | - Include code examples where appropriate
33 | - Explain the benefits of implementing the change
34 | - Prioritize recommendations (Critical, High, Medium, Low)
35 |
36 | Focus on practical, implementable changes that maintain the original code's intent and functionality.
```
--------------------------------------------------------------------------------
/server/prompts/architecture/prompts.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "prompts": [
3 | {
4 | "id": "strategic-system-alignment",
5 | "name": "Strategic System Alignment",
6 | "category": "architecture",
7 | "description": "Strategically align systems and code towards architectural rules and goals with systematic implementation planning and progress tracking in /plans markdown notes",
8 | "file": "strategic-system-alignment.md",
9 | "arguments": [
10 | {
11 | "name": "task_description",
12 | "type": "string",
13 | "description": "System/component to align and alignment goals"
14 | },
15 | {
16 | "name": "context_files",
17 | "type": "string",
18 | "description": "Optional: Relevant file paths"
19 | },
20 | {
21 | "name": "architectural_rules",
22 | "type": "string",
23 | "description": "Optional: Rules to align with"
24 | },
25 | {
26 | "name": "goals",
27 | "type": "string",
28 | "description": "Optional: Goals to achieve"
29 | },
30 | {
31 | "name": "constraints",
32 | "type": "string",
33 | "description": "Optional: Constraints to respect"
34 | }
35 | ]
36 | }
37 | ]
38 | }
```
--------------------------------------------------------------------------------
/server/jest.config.cjs:
--------------------------------------------------------------------------------
```
1 | /** @type {import('jest').Config} */
2 | module.exports = {
3 | preset: 'ts-jest/presets/default-esm',
4 | extensionsToTreatAsEsm: ['.ts'],
5 | testEnvironment: 'node',
6 | roots: ['<rootDir>/tests'],
7 | testMatch: [
8 | '<rootDir>/tests/**/*.test.ts'
9 | ],
10 | setupFilesAfterEnv: ['<rootDir>/tests/setup.ts'], // Re-enabled with working ES module support
11 | transform: {
12 | '^.+\\.ts$': ['ts-jest', {
13 | useESM: true,
14 | tsconfig: {
15 | module: 'esnext',
16 | target: 'es2020',
17 | moduleResolution: 'node',
18 | allowSyntheticDefaultImports: true,
19 | esModuleInterop: true
20 | }
21 | }]
22 | },
23 | collectCoverageFrom: [
24 | 'dist/**/*.js',
25 | '!dist/**/*.d.ts',
26 | '!dist/tests/**'
27 | ],
28 | coverageDirectory: 'coverage',
29 | coverageReporters: ['text', 'lcov'],
30 | testTimeout: 30000,
31 | verbose: true,
32 | maxWorkers: 1,
33 | // Essential for ES modules with Jest
34 | moduleFileExtensions: ['ts', 'js', 'mjs'],
35 | // Handle ES module imports properly - map .js imports to TypeScript files and preserve ES modules
36 | moduleNameMapper: {
37 | '^(\\.{1,2}/.*)\\.js$': '$1'
38 | },
39 | // Transform ES modules from node_modules if needed
40 | transformIgnorePatterns: [
41 | 'node_modules/(?!(@modelcontextprotocol)/)'
42 | ],
43 | // Support for dynamic imports and ES modules
44 | testPathIgnorePatterns: [
45 | '/node_modules/'
46 | ]
47 | };
```
--------------------------------------------------------------------------------
/server/prompts/development/expert_code_implementation.md:
--------------------------------------------------------------------------------
```markdown
1 | # Expert Code Implementation
2 |
3 | ## Description
4 | Expert implementation of refined coding requirements with comprehensive explanation and best practices.
5 |
6 | ## System Message
7 | You are an expert software developer with extensive experience across multiple domains. Your task is to implement high-quality, professional-grade code based on refined requirements. You write elegant, efficient, and well-documented code that follows best practices and industry standards.
8 |
9 | ## User Message Template
10 | Please implement the following coding request:
11 |
12 | **Request:** {{refined_query}}
13 | **Language:** {{language}}
14 | **Requirements:**
15 | {{requirements}}
16 | **Constraints:**
17 | {{constraints}}
18 |
19 | {% if gate_guidance %}
20 | ## Quality Guidelines
21 | {{gate_guidance}}
22 | {% endif %}
23 |
24 | For your implementation:
25 | 1. Design a robust solution that addresses all requirements
26 | 2. Write clean, efficient, well-structured code
27 | 3. Include comprehensive comments explaining complex sections
28 | 4. Implement proper error handling and edge case management
29 | 5. Follow language-specific best practices and conventions
30 | 6. Consider performance, security, and maintainability
31 | 7. Provide usage examples that demonstrate the code's functionality
32 |
33 | Your solution should be production-ready and include:
34 | - Complete, runnable code
35 | - Explanation of your implementation approach and design decisions
36 | - Any important technical considerations or limitations
37 | - Example usage showing how to properly use the code
38 |
```
--------------------------------------------------------------------------------
/server/src/gates/definitions/content-structure.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "id": "content-structure",
3 | "name": "Content Structure Guidelines",
4 | "type": "validation",
5 | "description": "Ensures well-organized, readable content with clear structure",
6 | "guidance": "**Content Structure Guidelines:**\n- Use clear headings and subheadings (## and ###)\n- Organize content in logical sections\n- Include bullet points or numbered lists for clarity\n- Provide examples when explaining concepts\n- Maintain consistent tone and style\n- Ensure smooth transitions between sections\n- Include a summary or conclusion when appropriate",
7 | "pass_criteria": [
8 | {
9 | "type": "content_check",
10 | "min_length": 200,
11 | "required_patterns": [
12 | "##",
13 | "-",
14 | "example"
15 | ]
16 | },
17 | {
18 | "type": "pattern_check",
19 | "keyword_count": {
20 | "##": 2
21 | },
22 | "regex_patterns": [
23 | "^##\\s+.+$",
24 | "^\\s*[-*]\\s+.+"
25 | ]
26 | }
27 | ],
28 | "_comment_llm_validation": "LLM self-check removed until API integration complete. Will be re-added when config.analysis.semanticAnalysis.llmIntegration is fully implemented.",
29 | "retry_config": {
30 | "max_attempts": 2,
31 | "improvement_hints": true,
32 | "preserve_context": true
33 | },
34 | "activation": {
35 | "prompt_categories": ["documentation", "content_processing", "education"],
36 | "explicit_request": false
37 | },
38 | "_comment": "Category gate - activates based on category only. Framework gates control methodology separately."
39 | }
```
--------------------------------------------------------------------------------
/server/src/gates/definitions/research-quality.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "id": "research-quality",
3 | "name": "Research Quality Guidelines",
4 | "type": "validation",
5 | "description": "Ensures thorough research with proper citations and credible sources",
6 | "guidance": "**Research Quality Guidelines:**\n- Cite at least 3 credible sources when making factual claims\n- Include publication dates for time-sensitive information\n- Distinguish between primary and secondary sources\n- Cross-reference facts across multiple sources\n- Provide context for statistical claims\n- Use authoritative sources (academic journals, government data, established news outlets)",
7 | "pass_criteria": [
8 | {
9 | "type": "content_check",
10 | "min_length": 300,
11 | "required_patterns": [
12 | "according to",
13 | "source",
14 | "published",
15 | "research",
16 | "study"
17 | ]
18 | },
19 | {
20 | "type": "pattern_check",
21 | "keyword_count": {
22 | "according to": 1,
23 | "source": 2
24 | }
25 | }
26 | ],
27 | "_comment_llm_validation": "LLM self-check removed until API integration complete. Will be re-added when config.analysis.semanticAnalysis.llmIntegration is fully implemented.",
28 | "retry_config": {
29 | "max_attempts": 3,
30 | "improvement_hints": true,
31 | "preserve_context": true
32 | },
33 | "activation": {
34 | "prompt_categories": ["research", "analysis"],
35 | "explicit_request": true
36 | },
37 | "_comment": "Category gate - activates based on category only. Framework gates control methodology separately."
38 | }
```
--------------------------------------------------------------------------------
/server/prompts/promptsConfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "categories": [
3 | {
4 | "id": "analysis",
5 | "name": "Analysis",
6 | "description": "Prompts for analyzing content and data"
7 | },
8 | {
9 | "id": "education",
10 | "name": "Education",
11 | "description": "Prompts for learning and teaching concepts"
12 | },
13 | {
14 | "id": "development",
15 | "name": "Development",
16 | "description": "Prompts for software development and code quality"
17 | },
18 | {
19 | "id": "documentation",
20 | "name": "Documentation",
21 | "description": "Prompts related to Documentation"
22 | },
23 | {
24 | "id": "debugging",
25 | "name": "debugging",
26 | "description": "Prompts related to debugging"
27 | },
28 | {
29 | "id": "content_processing",
30 | "name": "content_processing",
31 | "description": "Prompts related to content_processing"
32 | },
33 | {
34 | "id": "architecture",
35 | "name": "architecture",
36 | "description": "Prompts related to architecture"
37 | },
38 | {
39 | "id": "general",
40 | "name": "general",
41 | "description": "Prompts related to general"
42 | },
43 | {
44 | "id": "testing",
45 | "name": "testing",
46 | "description": "Prompts related to testing"
47 | }
48 | ],
49 | "prompts": [],
50 | "imports": [
51 | "analysis/prompts.json",
52 | "education/prompts.json",
53 | "development/prompts.json",
54 | "documentation/prompts.json",
55 | "debugging/prompts.json",
56 | "content_processing/prompts.json",
57 | "architecture/prompts.json",
58 | "general/prompts.json",
59 | "testing/prompts.json"
60 | ]
61 | }
```
--------------------------------------------------------------------------------
/server/prompts/analysis/query_refinement.md:
--------------------------------------------------------------------------------
```markdown
1 | # Query Refinement
2 |
3 | ## Description
4 | A systematic process to analyze and refine ambiguous coding requests into clear, actionable specifications.
5 |
6 | ## System Message
7 | You are an expert requirements analyst specializing in software development. Your task is to transform vague or ambiguous coding requests into clear, structured specifications. When presented with a query, you'll systematically analyze it, identify any technical ambiguities or missing information, and transform it into detailed requirements.
8 |
9 | ## User Message Template
10 | I need to refine this coding request: {{query}}
11 |
12 | Please follow these steps:
13 | 1. Parse the request to identify the core programming task
14 | 2. Determine the likely programming language(s) needed (specify if ambiguous)
15 | 3. Identify any technical ambiguities, unclear terms, or missing context
16 | 4. List key functional requirements that can be inferred from the request
17 | 5. Specify any performance, security, or quality constraints that should be considered
18 | 6. Propose any clarifying technical questions that would help resolve ambiguities
19 | 7. Provide a refined version of the request with clear specifications
20 |
21 | Output your analysis in this format:
22 | - **Language:** [Determined programming language]
23 | - **Refined Query:** [Clear, specific version of the request]
24 | - **Requirements:** [Bullet list of functional requirements]
25 | - **Constraints:** [Any performance/security/quality considerations]
26 | - **Clarifying Questions:** [Questions to further refine requirements]
27 |
```
--------------------------------------------------------------------------------
/server/src/mcp-tools/prompt-engine/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Prompt Engine - Unified Execution System
3 | *
4 | * Consolidated prompt engine providing systematic prompt execution with:
5 | * - Framework integration (CAGEERF, ReACT, 5W1H, SCAMPER)
6 | * - Chain execution with progress tracking
7 | * - Semantic analysis and intelligent execution mode detection
8 | * - Gate validation and retry logic
9 | *
10 | * This module maintains API compatibility while providing improved organization.
11 | */
12 |
13 | // Core engine exports
14 | export {
15 | ConsolidatedPromptEngine,
16 | createConsolidatedPromptEngine,
17 | } from "./core/engine.js";
18 |
19 | // Chain execution exports
20 | export {
21 | ChainExecutor,
22 | } from "./core/executor.js";
23 |
24 | // Type definitions
25 | export type {
26 | ChainExecutionContext,
27 | ChainExecutionOptions,
28 | ChainManagementCommand,
29 | ChainGateInfo,
30 | ChainValidationResult,
31 | ChainStepData,
32 | StepArgumentsContext,
33 | FormatterExecutionContext,
34 | SimpleResponseFormatter,
35 | PromptClassification,
36 | ChainExecutionStrategy,
37 | ChainState,
38 | } from "./core/types.js";
39 |
40 | // Processing utilities (internal use)
41 | export {
42 | TemplateProcessor,
43 | } from "./processors/template-processor.js";
44 |
45 | export {
46 | ResponseFormatter,
47 | } from "./processors/response-formatter.js";
48 |
49 | // Utility functions (internal use)
50 | export {
51 | PromptClassifier,
52 | } from "./utils/classification.js";
53 |
54 | export {
55 | EngineValidator,
56 | } from "./utils/validation.js";
57 |
58 | export {
59 | ContextBuilder,
60 | } from "./utils/context-builder.js";
61 |
62 | // Re-export shared utilities for backwards compatibility
63 | export {
64 | createExecutionResponse,
65 | } from "../shared/structured-response-builder.js";
```
--------------------------------------------------------------------------------
/server/prompts/documentation/docs-project-analysis.md:
--------------------------------------------------------------------------------
```markdown
1 | # Project Analysis (Step 1 of 5)
2 |
3 | ## Description
4 | Analyze a project to identify what needs to be documented and how
5 |
6 | ## System Message
7 | [System Info: You are a documentation specialist who excels at analyzing projects to determine documentation needs. Your goal is to identify key components, features, and concepts that require documentation while understanding the project's overall purpose and structure.]
8 |
9 | ## User Message Template
10 | I need to create technical documentation for the following project:
11 |
12 | {{project_info}}
13 |
14 | The documentation type I need is: {{doc_type}}
15 | The target audience is: {{audience}}
16 | {% if depth_level %}The desired depth level is: {{depth_level}}{% endif %}
17 |
18 | Please analyze this project to help plan the documentation by:
19 |
20 | 1. Identifying the key components, features, and concepts that need to be documented
21 | 2. Determining the most important aspects to cover based on the target audience
22 | 3. Analyzing the project's structure and how it should be reflected in the documentation
23 | 4. Identifying any technical prerequisites or background knowledge the audience might need
24 | 5. Recognizing potential pain points or complex areas that will need extra documentation attention
25 | 6. Suggesting appropriate documentation formats and styles for this specific project
26 | 7. Noting which sections would benefit from examples, diagrams, or code snippets
27 |
28 | Please organize your analysis with clear sections and provide a comprehensive overview of what the documentation should address and how it should be structured to best serve its purpose.
29 |
```
--------------------------------------------------------------------------------
/server/prompts/development/create_modularization_plan.md:
--------------------------------------------------------------------------------
```markdown
1 | # Create Modularization Plan
2 |
3 | ## Description
4 | Creates a detailed plan for splitting a file into smaller, more maintainable modules based on analysis of its structure and dependencies.
5 |
6 | ## System Message
7 | You are an expert software architect specializing in code organization and modular design. Your task is to create a detailed plan for splitting a file into smaller, more maintainable modules based on analysis of its structure and dependencies.
8 |
9 | ## User Message Template
10 | Based on the analysis of this {{language}} file located at {{file_path}}, please create a detailed modularization plan:
11 |
12 | **File Analysis Results:**
13 | {{analysis_results}}
14 |
15 | Create a comprehensive modularization plan that includes:
16 |
17 | ## 1. Module Breakdown Strategy
18 | - Identified modules with clear responsibilities
19 | - Module naming conventions and organization
20 | - Dependency relationships between modules
21 | - Interface design and public APIs
22 |
23 | ## 2. Implementation Roadmap
24 | - Step-by-step refactoring sequence
25 | - Risk mitigation strategies
26 | - Testing approach for each module
27 | - Rollback procedures if needed
28 |
29 | ## 3. Technical Specifications
30 | - File structure and directory organization
31 | - Import/export patterns for {{language}}
32 | - Configuration and setup requirements
33 | - Documentation standards
34 |
35 | ## 4. Quality Assurance Plan
36 | - Code review checkpoints
37 | - Testing strategies for each module
38 | - Performance validation approaches
39 | - Backwards compatibility considerations
40 |
41 | Provide a detailed, actionable plan that ensures successful modularization while maintaining code quality and functionality.
42 |
```
--------------------------------------------------------------------------------
/server/src/gates/definitions/code-quality.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "id": "code-quality",
3 | "name": "Code Quality Standards",
4 | "type": "validation",
5 | "description": "Ensures generated code follows best practices and quality standards",
6 | "guidance": "**Code Quality Standards:**\n- Include error handling and input validation\n- Add inline comments for complex logic\n- Follow consistent naming conventions\n- Consider edge cases and boundary conditions\n- Optimize for readability over cleverness\n- Include basic documentation/docstrings\n- Follow security best practices (input sanitization, avoid hardcoded secrets)",
7 | "pass_criteria": [
8 | {
9 | "type": "content_check",
10 | "min_length": 100,
11 | "required_patterns": [
12 | "try",
13 | "catch",
14 | "//",
15 | "*",
16 | "function",
17 | "const"
18 | ],
19 | "forbidden_patterns": [
20 | "TODO",
21 | "FIXME",
22 | "hack",
23 | "password123"
24 | ]
25 | },
26 | {
27 | "type": "pattern_check",
28 | "regex_patterns": [
29 | "function\\s+\\w+\\s*\\(",
30 | "\\/\\/.*\\w+",
31 | "try\\s*\\{"
32 | ]
33 | }
34 | ],
35 | "_comment_llm_validation": "LLM self-check removed until API integration complete. Will be re-added when config.analysis.semanticAnalysis.llmIntegration is fully implemented.",
36 | "retry_config": {
37 | "max_attempts": 2,
38 | "improvement_hints": true,
39 | "preserve_context": true
40 | },
41 | "activation": {
42 | "prompt_categories": ["code", "development"],
43 | "explicit_request": false
44 | },
45 | "_comment": "Category gate - activates based on category only. Framework gates control methodology separately."
46 | }
```
--------------------------------------------------------------------------------
/scripts/test-all-platforms.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 |
3 | # Comprehensive multi-platform testing script
4 |
5 | set -e
6 |
7 | RED='\033[0;31m'
8 | GREEN='\033[0;32m'
9 | YELLOW='\033[1;33m'
10 | BLUE='\033[0;34m'
11 | NC='\033[0m'
12 |
13 | print_test() {
14 | echo -e "${BLUE}[TEST]${NC} $1"
15 | }
16 |
17 | print_pass() {
18 | echo -e "${GREEN}[PASS]${NC} $1"
19 | }
20 |
21 | print_fail() {
22 | echo -e "${RED}[FAIL]${NC} $1"
23 | }
24 |
25 | # Test 1: Ubuntu (Linux) - Primary platform
26 | print_test "Testing Ubuntu/Linux platform..."
27 | if ./local-test.sh dry-run code-quality >/dev/null 2>&1; then
28 | print_pass "Ubuntu/Linux testing works"
29 | else
30 | print_fail "Ubuntu/Linux testing failed"
31 | fi
32 |
33 | # Test 2: Windows simulation with Node.js
34 | print_test "Testing Windows simulation (Node.js)..."
35 | if docker run --rm -v "$PWD":/workspace -w /workspace/server node:18-alpine npm --version >/dev/null 2>&1; then
36 | print_pass "Windows simulation (Node.js) works"
37 | else
38 | print_fail "Windows simulation (Node.js) failed"
39 | fi
40 |
41 | # Test 3: Cross-platform Node.js compatibility
42 | print_test "Testing cross-platform Node.js compatibility..."
43 | if node scripts/windows-tests/test-windows-paths.js >/dev/null 2>&1; then
44 | print_pass "Cross-platform compatibility works"
45 | else
46 | print_fail "Cross-platform compatibility failed"
47 | fi
48 |
49 | # Test 4: Windows environment simulation
50 | print_test "Testing Windows environment simulation..."
51 | if [ -f "scripts/windows-tests/windows-env.sh" ] && source scripts/windows-tests/windows-env.sh >/dev/null 2>&1; then
52 | print_pass "Windows environment simulation works"
53 | else
54 | print_fail "Windows environment simulation failed"
55 | fi
56 |
57 | echo ""
58 | echo "Multi-platform testing summary completed!"
59 |
```
--------------------------------------------------------------------------------
/server/prompts/analysis/markdown_notebook.md:
--------------------------------------------------------------------------------
```markdown
1 | # Markdown Notebook Creation
2 |
3 | This prompt transforms deep analysis content into a well-structured markdown notebook with headers, bullet points, and emphasized content, mermaid graphs, graphs, italics, quotes, block quotes, LATEX etc...
4 |
5 | ## System Message
6 |
7 | You are an expert at organizing complex information into clear, well-structured markdown notebooks. Your task is to take detailed analysis and transform it into an organized set of notes that are easy to read and navigate.
8 |
9 | ## User Message Template
10 |
11 | Please create a markdown notebook based on the following deep analysis of the topic "{{topic}}":
12 |
13 | ```
14 | {{analysis}}
15 | ```
16 |
17 | Create a comprehensive markdown notebook with:
18 | 1. A clear title and introduction
19 | 2. Well-organized sections with appropriate headings (H1, H2, H3)
20 | 3. Bullet points for key concepts
21 | 4. Code blocks, tables, or other formatting as appropriate
22 | 5. Emphasis on important insights using bold or italics
23 |
24 | Focus on organization, clarity, and knowledge structure. Include all important insights from the analysis.
25 |
26 | ## Arguments
27 |
28 | - topic: The topic or subject of the analysis
29 | - analysis: The detailed analysis to organize into a markdown notebook
30 |
31 | ## Output Format
32 |
33 | A well-structured markdown notebook that follows markdown conventions, with:
34 |
35 | ```markdown
36 | # [Title]
37 |
38 | ## Introduction
39 | [Brief overview]
40 |
41 | ## [Main Section 1]
42 | ### [Subsection 1.1]
43 | - Key point
44 | - Key point
45 |
46 | ### [Subsection 1.2]
47 | [Content]
48 |
49 | ## [Main Section 2]
50 | ...
51 | ```
52 |
53 | The notebook should be comprehensive yet clear, maintaining the depth of the original analysis while improving its organization and accessibility.
```
--------------------------------------------------------------------------------
/server/src/execution/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Modernized Execution System Export Module (Phase 3)
3 | *
4 | * Simplified execution system with ConsolidatedPromptEngine delegation:
5 | *
6 | * Key exports:
7 | * - ExecutionCoordinator: Thin orchestration layer that delegates to ConsolidatedPromptEngine
8 | * - All complex execution handled through ConsolidatedPromptEngine
9 | */
10 |
11 | // REMOVED: ExecutionCoordinator - modular chain system removed
12 | // All execution now handled directly by ConsolidatedPromptEngine
13 |
14 | // Execution conversation management integrated with text-references/conversation.ts
15 | // No separate execution conversation manager needed
16 |
17 | // UnifiedPromptProcessor removed - functionality consolidated into ExecutionCoordinator
18 |
19 | // Phase 3: Chain strategies removed - all execution delegated to ConsolidatedPromptEngine
20 | // Legacy strategy patterns deprecated in favor of ConsolidatedPromptEngine
21 |
22 | // Re-export types needed by strategies
23 | export type {
24 | ChainExecutionResult,
25 | ConvertedPrompt,
26 | // WorkflowExecutionResult removed in Phase 2 - use ChainExecutionResult
27 | // Workflow type removed in Phase 2 - use enhanced ChainStep configurations
28 | // RuntimeTarget removed in Phase 2 - workflow foundation types eliminated
29 | } from "../types/index.js";
30 |
31 | // REMOVED: All execution coordinator imports - modular chain system removed
32 |
33 | // REMOVED: createFullyConfiguredExecutionCoordinator - modular chain system removed
34 | // All execution now handled directly by ConsolidatedPromptEngine in mcp-tools/prompt-engine.ts
35 |
36 | // Legacy factory function removed - createFullyConfiguredExecutionEngine
37 | // Use createFullyConfiguredExecutionCoordinator instead
38 |
```
--------------------------------------------------------------------------------
/server/prompts/development/transform_code_to_modules.md:
--------------------------------------------------------------------------------
```markdown
1 | # Transform Code to Modules
2 |
3 | ## Description
4 | Transforms a large file into multiple smaller module files according to a modularization plan, ensuring proper imports/exports and maintaining functionality.
5 |
6 | ## System Message
7 | You are an expert software engineer specializing in code refactoring and modular design. Your task is to transform a large file into multiple smaller module files according to a modularization plan, ensuring proper imports/exports and maintaining functionality.
8 |
9 | ## User Message Template
10 | Based on the modularization plan, please transform this {{language}} file located at {{file_path}} into multiple smaller modules:
11 |
12 | **Original Code:**
13 | ```{{language}}
14 | {{original_code}}
15 | ```
16 |
17 | **Modularization Plan:**
18 | {{modularization_plan}}
19 |
20 | Please create the modular implementation with:
21 |
22 | ## 1. Module Files
23 | - Generate each module file with appropriate content
24 | - Implement proper imports/exports for {{language}}
25 | - Ensure clean separation of responsibilities
26 | - Maintain existing functionality
27 |
28 | ## 2. Interface Design
29 | - Clear public APIs for each module
30 | - Proper abstraction and encapsulation
31 | - Consistent naming conventions
32 | - Documentation for each module
33 |
34 | ## 3. Integration Code
35 | - Updated main file that imports new modules
36 | - Proper dependency management
37 | - Configuration and setup code
38 | - Error handling preservation
39 |
40 | ## 4. Implementation Notes
41 | - Changes made and rationale
42 | - Testing recommendations
43 | - Migration guide for users
44 | - Performance impact analysis
45 |
46 | Provide complete, working code for each module that maintains the original functionality while improving organization and maintainability.
47 |
```
--------------------------------------------------------------------------------
/server/src/frameworks/prompt-guidance/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Prompt Guidance System Index - Phase 3 Implementation
3 | *
4 | * Central exports for the prompt guidance system that provides intelligent
5 | * methodology integration for MCP prompts.
6 | *
7 | * The prompt guidance system consists of three core components:
8 | * - SystemPromptInjector: Injects methodology guidance into system prompts
9 | * - MethodologyTracker: Tracks active methodology state and handles switching
10 | * - TemplateEnhancer: Enhances user templates with methodology-specific guidance
11 | */
12 |
13 | // Core prompt guidance components
14 | export {
15 | SystemPromptInjector,
16 | createSystemPromptInjector,
17 | type SystemPromptInjectorConfig
18 | } from './system-prompt-injector.js';
19 |
20 | export {
21 | MethodologyTracker,
22 | createMethodologyTracker,
23 | type MethodologyTrackerConfig,
24 | type MethodologyTrackerEvents
25 | } from './methodology-tracker.js';
26 |
27 | export {
28 | TemplateEnhancer,
29 | createTemplateEnhancer,
30 | type TemplateEnhancerConfig,
31 | type TemplateEnhancementContext
32 | } from './template-enhancer.js';
33 |
34 | // Unified prompt guidance service
35 | export {
36 | PromptGuidanceService,
37 | createPromptGuidanceService,
38 | type PromptGuidanceServiceConfig
39 | } from './service.js';
40 |
41 | // Service-specific types (to avoid conflicts with types/index.js)
42 | export type { PromptGuidanceResult as ServicePromptGuidanceResult } from './service.js';
43 |
44 | // Re-export relevant types from the types system
45 | export type {
46 | SystemPromptInjectionResult,
47 | TemplateEnhancementResult,
48 | MethodologyState,
49 | MethodologySwitchRequest,
50 | MethodologyHealth,
51 | PersistedMethodologyState,
52 | TemplateProcessingGuidance,
53 | PromptGuidanceConfig,
54 | PromptGuidanceResult
55 | } from '../types/index.js';
```
--------------------------------------------------------------------------------
/server/prompts/education/vault_integrated_notes.md:
--------------------------------------------------------------------------------
```markdown
1 | # Vault-Integrated Notes Creator
2 |
3 | ## Description
4 | Create comprehensive notes that search the vault for real related notes instead of generating fictional ones
5 |
6 | ## System Message
7 | You are an expert note-taker with access to a comprehensive Obsidian vault. You excel at creating detailed, well-structured notes that integrate with existing knowledge through real vault searches and authentic cross-references.
8 |
9 | ## User Message Template
10 | I need to create comprehensive notes about: {{topic}}
11 |
12 | CRITICAL REQUIREMENTS:
13 | 1. **Real Vault Integration**: Before creating the Related Notes section, you MUST search the vault for actual related content using available search tools
14 | 2. **Authentic Cross-References**: Only include [[WikiLinks]] to notes that actually exist in the vault
15 | 3. **Strategic Linking**: Follow the S.P.A.R.C. methodology with 3-8 meaningful connections per note
16 | 4. **Vault Standards**: Follow all formatting standards from the vault's CLAUDE.md and workbench protocols
17 |
18 | PROCESS:
19 | 1. First, use search tools (Grep, Glob) to find related content in the vault
20 | 2. Identify actual existing notes that relate to the topic
21 | 3. Create comprehensive notes with real vault connections
22 | 4. Use enhanced frontmatter with relevant tags found in the vault
23 | 5. Include actual [[WikiLinks]] to discovered related notes
24 |
25 | SEARCH STRATEGY:
26 | - Search for key terms related to {{topic}}
27 | - Look for notes in relevant domain folders (Art/, Computer Science/, etc.)
28 | - Identify MOCs (Maps of Content) that should link to this note
29 | - Find case studies, techniques, or concepts that relate
30 |
31 | Create detailed, professional notes that authentically integrate with the existing vault knowledge structure.
32 |
```
--------------------------------------------------------------------------------
/server/src/gates/definitions/security-awareness.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "id": "security-awareness",
3 | "name": "Security Best Practices",
4 | "type": "validation",
5 | "description": "Ensures security-conscious development practices and prevents common vulnerabilities",
6 | "guidance": "**Security Best Practices:**\n- Never include hardcoded secrets, passwords, or API keys in code\n- Validate and sanitize all user inputs\n- Use parameterized queries to prevent SQL injection\n- Implement proper authentication and authorization\n- Follow OWASP Top 10 security guidelines\n- Use HTTPS and secure communication protocols\n- Implement rate limiting for APIs\n- Log security events but never log sensitive data\n- Keep dependencies updated and scan for vulnerabilities",
7 | "pass_criteria": [
8 | {
9 | "type": "content_check",
10 | "forbidden_patterns": [
11 | "password=\"",
12 | "api_key=\"",
13 | "secret=\"",
14 | "token=\"",
15 | "password123",
16 | "admin123",
17 | "root:root",
18 | "SELECT * FROM"
19 | ]
20 | },
21 | {
22 | "type": "pattern_check",
23 | "regex_patterns": [
24 | "validate|sanitize|escape",
25 | "parameterized|prepared",
26 | "authentication|authorization",
27 | "https://|ssl|tls"
28 | ]
29 | }
30 | ],
31 | "_comment_llm_validation": "LLM self-check removed until API integration complete. Will be re-added when config.analysis.semanticAnalysis.llmIntegration is fully implemented.",
32 | "retry_config": {
33 | "max_attempts": 2,
34 | "improvement_hints": true,
35 | "preserve_context": true
36 | },
37 | "activation": {
38 | "prompt_categories": ["code", "development"],
39 | "explicit_request": false
40 | },
41 | "_comment": "Category gate - activates based on category only. Framework gates control methodology separately."
42 | }
```
--------------------------------------------------------------------------------
/server/src/gates/templates/research_self_validation.md:
--------------------------------------------------------------------------------
```markdown
1 | # Research Quality Self-Check Template
2 |
3 | ## Instructions
4 | Please evaluate your response against the following research quality criteria. Be honest and objective in your assessment.
5 |
6 | ## Research Quality Criteria
7 |
8 | ### Citation Requirements
9 | - [ ] **Credible Sources**: Used at least 3 credible, authoritative sources
10 | - [ ] **Publication Dates**: Included publication dates for time-sensitive information
11 | - [ ] **Source Types**: Distinguished between primary and secondary sources
12 | - [ ] **Citation Format**: Used proper citation format (mentioned source names/types)
13 |
14 | ### Content Quality
15 | - [ ] **Cross-Referencing**: Cross-referenced facts across multiple sources
16 | - [ ] **Context**: Provided appropriate context for claims and statistics
17 | - [ ] **Objectivity**: Avoided speculation and maintained objectivity
18 | - [ ] **Authority**: Used authoritative sources (academic, government, established media)
19 |
20 | ### Research Depth
21 | - [ ] **Comprehensive**: Addressed the topic thoroughly
22 | - [ ] **Current**: Used recent and relevant information when appropriate
23 | - [ ] **Balanced**: Presented multiple perspectives where applicable
24 | - [ ] **Evidence-Based**: Supported claims with concrete evidence
25 |
26 | ## Self-Assessment
27 |
28 | **Overall Research Quality Score (0.0-1.0): ___**
29 |
30 | **Reasoning for Score:**
31 | [Explain your assessment. What research standards were met? What could be improved?]
32 |
33 | **Areas for Improvement:**
34 | [If score is below 0.75, list specific areas that need enhancement]
35 |
36 | ## Validation Response
37 |
38 | Based on your self-assessment:
39 | - **PASS** if score ≥ 0.75 and all critical citation requirements are met
40 | - **NEEDS_IMPROVEMENT** if score < 0.75 or missing critical elements
41 |
42 | **Final Assessment: [PASS/NEEDS_IMPROVEMENT]**
```
--------------------------------------------------------------------------------
/server/tests/setup.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Jest Test Setup
3 | * Global configuration and utilities for all tests
4 | */
5 |
6 | // Set test environment
7 | process.env.NODE_ENV = 'test';
8 |
9 | // Global test timeout - commented out as it's set in jest.config.cjs
10 | // jest.setTimeout(30000);
11 |
12 | // Mock console methods in tests if needed
13 | const originalConsoleError = console.error;
14 | const originalConsoleWarn = console.warn;
15 |
16 | // These jest globals are setup in individual test files since ES modules handle setup differently
17 | // beforeEach(() => {
18 | // // Reset mocks before each test
19 | // jest.clearAllMocks();
20 | // });
21 |
22 | // afterEach(() => {
23 | // // Cleanup after each test
24 | // jest.restoreAllMocks();
25 | // });
26 |
27 | // Global test utilities - simplified for ES modules
28 | global.testUtils = {
29 | // Suppress console output during tests
30 | suppressConsole: () => {
31 | console.error = () => {};
32 | console.warn = () => {};
33 | },
34 |
35 | // Restore console output
36 | restoreConsole: () => {
37 | console.error = originalConsoleError;
38 | console.warn = originalConsoleWarn;
39 | },
40 |
41 | // Wait for async operations
42 | waitFor: (ms: number) => new Promise(resolve => setTimeout(resolve, ms)),
43 |
44 | // Create mock logger - implementation will use jest mocks in individual tests
45 | createMockLogger: () => ({
46 | info: () => {},
47 | warn: () => {},
48 | error: () => {},
49 | debug: () => {}
50 | })
51 | };
52 |
53 | // Extend Jest matchers if needed
54 | declare global {
55 | namespace jest {
56 | interface Matchers<R> {
57 | // Add custom matchers here if needed
58 | }
59 | }
60 |
61 | var testUtils: {
62 | suppressConsole: () => void;
63 | restoreConsole: () => void;
64 | waitFor: (ms: number) => Promise<void>;
65 | createMockLogger: () => any;
66 | };
67 | }
68 |
69 | // Export statement required for ES modules, but empty to avoid issues
70 | export {};
71 |
72 |
```
--------------------------------------------------------------------------------
/server/prompts/development/analyze_file_structure.md:
--------------------------------------------------------------------------------
```markdown
1 | # Analyze File Structure
2 |
3 | ## Description
4 | Analyzes a file's structure to identify potential modules, dependencies, and organization patterns for refactoring.
5 |
6 | ## System Message
7 | You are an expert code analyst specializing in code organization and architecture. Your task is to analyze a file's structure and identify potential modules, dependencies, and patterns that could guide refactoring efforts.
8 |
9 | ## User Message Template
10 | Please analyze the structure of this {{language}} file located at {{file_path}}:
11 |
12 | ```{{language}}
13 | {{code}}
14 | ```
15 |
16 | Provide a comprehensive structural analysis including:
17 |
18 | ## 1. Code Organization Overview
19 | - File size and complexity metrics
20 | - Main components and their purposes
21 | - Current architectural patterns used
22 | - Overall organization quality assessment
23 |
24 | ## 2. Functional Areas Identification
25 | - Core business logic sections
26 | - Utility functions and helpers
27 | - Configuration and setup code
28 | - External integrations and dependencies
29 |
30 | ## 3. Dependency Analysis
31 | - Import/require statements analysis
32 | - Internal dependencies between functions/classes
33 | - External library dependencies
34 | - Circular dependency risks
35 |
36 | ## 4. Modularization Opportunities
37 | - Logical groupings for potential modules
38 | - Cohesive functional areas
39 | - Reusable components identification
40 | - Interface boundary recommendations
41 |
42 | ## 5. Code Quality Assessment
43 | - Code smells and anti-patterns
44 | - Maintainability concerns
45 | - Performance considerations
46 | - {{language}}-specific best practices compliance
47 |
48 | ## 6. Refactoring Recommendations
49 | - Priority modules for extraction
50 | - Suggested module names and responsibilities
51 | - Interface design recommendations
52 | - Step-by-step refactoring approach
53 |
54 | Focus on practical, actionable insights that will guide effective refactoring decisions.
55 |
```
--------------------------------------------------------------------------------
/server/src/gates/definitions/technical-accuracy.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "id": "technical-accuracy",
3 | "name": "Technical Accuracy Standards",
4 | "type": "validation",
5 | "description": "Ensures technical correctness, fact-checking, and precision in technical content",
6 | "guidance": "**Technical Accuracy Standards:**\n- Verify technical facts and specifications before stating them\n- Use precise technical terminology correctly\n- Include version numbers and compatibility information where relevant\n- Distinguish between stable and experimental features\n- Provide context for technical decisions and trade-offs\n- Reference official documentation when available\n- Avoid speculation about implementation details without evidence\n- Test code examples for syntax correctness\n- Include error handling and edge cases in technical discussions",
7 | "pass_criteria": [
8 | {
9 | "type": "content_check",
10 | "min_length": 200,
11 | "required_patterns": [
12 | "version",
13 | "according to",
14 | "documentation",
15 | "specification"
16 | ]
17 | },
18 | {
19 | "type": "pattern_check",
20 | "keyword_count": {
21 | "accurate": 1,
22 | "precise": 1
23 | },
24 | "regex_patterns": [
25 | "v\\d+\\.\\d+",
26 | "RFC \\d+",
27 | "\\d{4}-\\d{2}-\\d{2}"
28 | ]
29 | }
30 | ],
31 | "_comment_llm_validation": "LLM self-check removed until API integration complete. Will be re-added when config.analysis.semanticAnalysis.llmIntegration is fully implemented.",
32 | "retry_config": {
33 | "max_attempts": 3,
34 | "improvement_hints": true,
35 | "preserve_context": true
36 | },
37 | "activation": {
38 | "prompt_categories": ["development", "analysis", "research"],
39 | "explicit_request": true
40 | },
41 | "_comment": "Category gate - activates based on category only. Framework gates control methodology separately."
42 | }
```
--------------------------------------------------------------------------------
/server/src/gates/definitions/educational-clarity.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "id": "educational-clarity",
3 | "name": "Educational Content Clarity",
4 | "type": "validation",
5 | "description": "Ensures educational content is clear, well-structured, and pedagogically sound",
6 | "guidance": "**Educational Clarity Guidelines:**\n- Start with clear learning objectives or goals\n- Use progressive complexity (simple to advanced)\n- Include concrete examples for abstract concepts\n- Provide step-by-step explanations for processes\n- Use analogies and metaphors to aid understanding\n- Include practice exercises or applications when appropriate\n- Anticipate and address common misconceptions\n- Use clear, jargon-free language with definitions for technical terms\n- Organize content with logical flow and transitions\n- Include summary or key takeaways",
7 | "pass_criteria": [
8 | {
9 | "type": "content_check",
10 | "min_length": 400,
11 | "required_patterns": [
12 | "example",
13 | "step",
14 | "understand",
15 | "learn"
16 | ]
17 | },
18 | {
19 | "type": "pattern_check",
20 | "keyword_count": {
21 | "example": 2,
22 | "for example": 1
23 | },
24 | "regex_patterns": [
25 | "^##\\s+.*$",
26 | "^\\d+\\.\\s+.*$",
27 | "^\\s*[-*]\\s+.*$"
28 | ]
29 | }
30 | ],
31 | "_comment_llm_validation": "LLM self-check removed until API integration complete. Will be re-added when config.analysis.semanticAnalysis.llmIntegration is fully implemented.",
32 | "retry_config": {
33 | "max_attempts": 2,
34 | "improvement_hints": true,
35 | "preserve_context": true
36 | },
37 | "activation": {
38 | "prompt_categories": ["education", "documentation", "content_processing", "development"],
39 | "explicit_request": false
40 | },
41 | "_comment": "Category gate - activates based on category only. Framework gates control methodology separately."
42 | }
```
--------------------------------------------------------------------------------
/server/src/gates/definitions/framework-compliance.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "id": "framework-compliance",
3 | "name": "Framework Methodology Compliance",
4 | "type": "validation",
5 | "gate_type": "framework",
6 | "description": "Ensures responses follow the active framework methodology (CAGEERF, ReACT, 5W1H, SCAMPER). This is a framework-level gate that applies universally across all categories when a framework is active.",
7 | "guidance": "**Framework Methodology Compliance:**\n- CAGEERF: Include Context, Analysis, Goals, Execution, Evaluation, Refinement, Framework considerations\n- ReACT: Show clear Reasoning and Acting phases with systematic problem-solving\n- 5W1H: Address Who, What, When, Where, Why, How in comprehensive analysis\n- SCAMPER: Apply creative thinking techniques (Substitute, Combine, Adapt, Modify, Put to other uses, Eliminate, Reverse)\n- Structure responses according to framework principles\n- Include systematic thinking and methodology awareness\n- Show iterative improvement and refinement processes",
8 | "pass_criteria": [
9 | {
10 | "type": "content_check",
11 | "min_length": 300,
12 | "required_patterns": [
13 | "context",
14 | "analysis",
15 | "systematic"
16 | ]
17 | },
18 | {
19 | "type": "pattern_check",
20 | "keyword_count": {
21 | "framework": 1,
22 | "methodology": 1
23 | }
24 | }
25 | ],
26 | "_comment_llm_validation": "LLM self-check removed until API integration complete. Will be re-added when config.analysis.semanticAnalysis.llmIntegration is fully implemented.",
27 | "retry_config": {
28 | "max_attempts": 2,
29 | "improvement_hints": true,
30 | "preserve_context": true
31 | },
32 | "activation": {
33 | "explicit_request": false,
34 | "framework_context": ["CAGEERF", "ReACT", "5W1H", "SCAMPER"]
35 | },
36 | "_comment": "Framework gates apply universally - no category restrictions. Activated by framework context only."
37 | }
```
--------------------------------------------------------------------------------
/server/src/gates/core/gate-definitions.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Gate System - Shared Definitions & Interfaces
3 | *
4 | * Centralized type definitions for all gate system components.
5 | * This enables clean dependencies and consistent interfaces.
6 | */
7 |
8 | /**
9 | * Gate type classification for precedence and activation logic
10 | */
11 | export type GateType = 'framework' | 'category' | 'quality' | 'security';
12 |
13 | /**
14 | * Gate definition structure loaded from JSON files
15 | */
16 | export interface GateDefinition {
17 | id: string;
18 | name: string;
19 | guidance: string;
20 | gate_type?: GateType; // Framework gates bypass category checks
21 | activation: {
22 | prompt_categories?: string[];
23 | framework_context?: string[];
24 | explicit_request?: boolean;
25 | };
26 | }
27 |
28 | /**
29 | * Context information for gate activation and rendering
30 | */
31 | export interface GateContext {
32 | framework?: string;
33 | category?: string;
34 | promptId?: string;
35 | }
36 |
37 | /**
38 | * Gate selection criteria for intelligent selection
39 | */
40 | export interface GateSelectionCriteria {
41 | framework?: string;
42 | category?: string;
43 | promptId?: string;
44 | executionMode?: 'prompt' | 'template' | 'chain';
45 | complexityLevel?: 'low' | 'medium' | 'high';
46 | }
47 |
48 | /**
49 | * Result of gate selection with reasoning
50 | */
51 | export interface GateSelectionResult {
52 | selectedGates: string[];
53 | reasoning: string[];
54 | confidence: number;
55 | estimatedExecutionTime: number;
56 | fallbackGates: string[];
57 | }
58 |
59 | /**
60 | * Performance metrics for individual gates
61 | */
62 | export interface GatePerformanceMetrics {
63 | gateId: string;
64 | avgExecutionTime: number;
65 | successRate: number;
66 | retryRate: number;
67 | lastUsed: Date;
68 | usageCount: number;
69 | }
70 |
71 | /**
72 | * Overall gate system analytics
73 | */
74 | export interface GateSystemAnalytics {
75 | totalGates: number;
76 | avgExecutionTime: number;
77 | overallSuccessRate: number;
78 | topPerformingGates: string[];
79 | underperformingGates: string[];
80 | recommendations: string[];
81 | }
```
--------------------------------------------------------------------------------
/server/prompts/documentation/docs-content-creation.md:
--------------------------------------------------------------------------------
```markdown
1 | # Content Creation (Step 3 of 5)
2 |
3 | ## Description
4 | Transform the content plan into well-crafted documentation
5 |
6 | ## System Message
7 | [System Info: You are a technical writer who excels at creating clear, concise, and comprehensive documentation. Your goal is to transform content plans into well-crafted documentation that effectively communicates technical information to the target audience.]
8 |
9 | ## User Message Template
10 | I need to create the content for {{doc_type}} documentation based on this content plan:
11 | {{previous_message}}
12 |
13 | For this project:
14 | {{project_info}}
15 |
16 | With this target audience:
17 | {{audience}}
18 |
19 | Please create the full documentation content following these technical writing best practices:
20 |
21 | 1. Write with clarity and precision
22 | - Use consistent terminology throughout
23 | - Define technical terms on first use
24 | - Maintain appropriate technical depth for the audience
25 | - Write in active voice with direct instructions
26 |
27 | 2. Structure content for readability
28 | - Use clear hierarchical headings (H1, H2, H3, etc.)
29 | - Keep paragraphs focused and concise
30 | - Use bullet points and numbered lists appropriately
31 | - Include informative code comments in examples
32 |
33 | 3. Follow documentation conventions
34 | - Use proper Markdown formatting
35 | - Create comprehensive code examples with proper syntax highlighting
36 | - Include descriptive captions for any tables or figures
37 | - Properly format command-line instructions, API endpoints, etc.
38 |
39 | 4. Ensure content completeness
40 | - Address all sections outlined in the content plan
41 | - Provide sufficient context and explanation for technical concepts
42 | - Include all necessary cross-references between related sections
43 | - Cover error cases and edge conditions where appropriate
44 |
45 | Please produce the complete documentation content organized according to the content plan, ready for final review and refinement.
46 |
```