mcp-adr-analysis-server 1.1.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/README.md +313 -69
  2. package/dist/src/config/ai-config.d.ts +81 -0
  3. package/dist/src/config/ai-config.d.ts.map +1 -0
  4. package/dist/src/config/ai-config.js +134 -0
  5. package/dist/src/config/ai-config.js.map +1 -0
  6. package/dist/src/index.d.ts +96 -1
  7. package/dist/src/index.d.ts.map +1 -1
  8. package/dist/src/index.js +1818 -199
  9. package/dist/src/index.js.map +1 -1
  10. package/dist/src/prompts/adr-suggestion-prompts.d.ts +2 -2
  11. package/dist/src/prompts/adr-suggestion-prompts.d.ts.map +1 -1
  12. package/dist/src/prompts/adr-suggestion-prompts.js +25 -17
  13. package/dist/src/prompts/adr-suggestion-prompts.js.map +1 -1
  14. package/dist/src/prompts/analysis-prompts.js +1 -1
  15. package/dist/src/prompts/analysis-prompts.js.map +1 -1
  16. package/dist/src/resources/index.d.ts +1 -1
  17. package/dist/src/resources/index.d.ts.map +1 -1
  18. package/dist/src/resources/index.js +52 -44
  19. package/dist/src/resources/index.js.map +1 -1
  20. package/dist/src/templates/domain-knowledge-templates.d.ts +36 -0
  21. package/dist/src/templates/domain-knowledge-templates.d.ts.map +1 -0
  22. package/dist/src/templates/domain-knowledge-templates.js +376 -0
  23. package/dist/src/templates/domain-knowledge-templates.js.map +1 -0
  24. package/dist/src/tools/adr-suggestion-tool.d.ts +8 -3
  25. package/dist/src/tools/adr-suggestion-tool.d.ts.map +1 -1
  26. package/dist/src/tools/adr-suggestion-tool.js +561 -172
  27. package/dist/src/tools/adr-suggestion-tool.js.map +1 -1
  28. package/dist/src/tools/content-masking-tool.d.ts.map +1 -1
  29. package/dist/src/tools/content-masking-tool.js +168 -22
  30. package/dist/src/tools/content-masking-tool.js.map +1 -1
  31. package/dist/src/tools/deployment-analysis-tool.d.ts.map +1 -1
  32. package/dist/src/tools/deployment-analysis-tool.js +64 -27
  33. package/dist/src/tools/deployment-analysis-tool.js.map +1 -1
  34. package/dist/src/tools/environment-analysis-tool.d.ts.map +1 -1
  35. package/dist/src/tools/environment-analysis-tool.js +65 -29
  36. package/dist/src/tools/environment-analysis-tool.js.map +1 -1
  37. package/dist/src/tools/research-question-tool.d.ts.map +1 -1
  38. package/dist/src/tools/research-question-tool.js +150 -49
  39. package/dist/src/tools/research-question-tool.js.map +1 -1
  40. package/dist/src/tools/rule-generation-tool.d.ts.map +1 -1
  41. package/dist/src/tools/rule-generation-tool.js +328 -143
  42. package/dist/src/tools/rule-generation-tool.js.map +1 -1
  43. package/dist/src/types/ape-framework.d.ts +566 -0
  44. package/dist/src/types/ape-framework.d.ts.map +1 -0
  45. package/dist/src/types/ape-framework.js +98 -0
  46. package/dist/src/types/ape-framework.js.map +1 -0
  47. package/dist/src/types/index.d.ts +96 -93
  48. package/dist/src/types/index.d.ts.map +1 -1
  49. package/dist/src/types/knowledge-generation.d.ts +671 -0
  50. package/dist/src/types/knowledge-generation.d.ts.map +1 -0
  51. package/dist/src/types/knowledge-generation.js +107 -0
  52. package/dist/src/types/knowledge-generation.js.map +1 -0
  53. package/dist/src/types/reflexion-framework.d.ts +652 -0
  54. package/dist/src/types/reflexion-framework.d.ts.map +1 -0
  55. package/dist/src/types/reflexion-framework.js +85 -0
  56. package/dist/src/types/reflexion-framework.js.map +1 -0
  57. package/dist/src/utils/adr-suggestions.d.ts +1 -1
  58. package/dist/src/utils/adr-suggestions.d.ts.map +1 -1
  59. package/dist/src/utils/adr-suggestions.js +8 -50
  60. package/dist/src/utils/adr-suggestions.js.map +1 -1
  61. package/dist/src/utils/ai-executor.d.ts +125 -0
  62. package/dist/src/utils/ai-executor.d.ts.map +1 -0
  63. package/dist/src/utils/ai-executor.js +292 -0
  64. package/dist/src/utils/ai-executor.js.map +1 -0
  65. package/dist/src/utils/automatic-prompt-engineering.d.ts +72 -0
  66. package/dist/src/utils/automatic-prompt-engineering.d.ts.map +1 -0
  67. package/dist/src/utils/automatic-prompt-engineering.js +820 -0
  68. package/dist/src/utils/automatic-prompt-engineering.js.map +1 -0
  69. package/dist/src/utils/cache.d.ts +54 -22
  70. package/dist/src/utils/cache.d.ts.map +1 -1
  71. package/dist/src/utils/cache.js +1234 -143
  72. package/dist/src/utils/cache.js.map +1 -1
  73. package/dist/src/utils/config.d.ts +2 -2
  74. package/dist/src/utils/config.js +3 -3
  75. package/dist/src/utils/config.js.map +1 -1
  76. package/dist/src/utils/deployment-analysis.d.ts.map +1 -1
  77. package/dist/src/utils/deployment-analysis.js +57 -38
  78. package/dist/src/utils/deployment-analysis.js.map +1 -1
  79. package/dist/src/utils/environment-analysis.d.ts.map +1 -1
  80. package/dist/src/utils/environment-analysis.js +113 -100
  81. package/dist/src/utils/environment-analysis.js.map +1 -1
  82. package/dist/src/utils/file-system.d.ts +42 -13
  83. package/dist/src/utils/file-system.d.ts.map +1 -1
  84. package/dist/src/utils/file-system.js +795 -89
  85. package/dist/src/utils/file-system.js.map +1 -1
  86. package/dist/src/utils/index.d.ts +9 -0
  87. package/dist/src/utils/index.d.ts.map +1 -0
  88. package/dist/src/utils/index.js +13 -0
  89. package/dist/src/utils/index.js.map +1 -0
  90. package/dist/src/utils/knowledge-generation.d.ts +79 -0
  91. package/dist/src/utils/knowledge-generation.d.ts.map +1 -0
  92. package/dist/src/utils/knowledge-generation.js +646 -0
  93. package/dist/src/utils/knowledge-generation.js.map +1 -0
  94. package/dist/src/utils/output-masking.d.ts.map +1 -1
  95. package/dist/src/utils/output-masking.js +2 -1
  96. package/dist/src/utils/output-masking.js.map +1 -1
  97. package/dist/src/utils/prompt-composition.d.ts +234 -0
  98. package/dist/src/utils/prompt-composition.d.ts.map +1 -0
  99. package/dist/src/utils/prompt-composition.js +379 -0
  100. package/dist/src/utils/prompt-composition.js.map +1 -0
  101. package/dist/src/utils/prompt-execution.d.ts +88 -0
  102. package/dist/src/utils/prompt-execution.d.ts.map +1 -0
  103. package/dist/src/utils/prompt-execution.js +227 -0
  104. package/dist/src/utils/prompt-execution.js.map +1 -0
  105. package/dist/src/utils/reflexion.d.ts +92 -0
  106. package/dist/src/utils/reflexion.d.ts.map +1 -0
  107. package/dist/src/utils/reflexion.js +1100 -0
  108. package/dist/src/utils/reflexion.js.map +1 -0
  109. package/dist/src/utils/research-integration.d.ts.map +1 -1
  110. package/dist/src/utils/research-integration.js +156 -100
  111. package/dist/src/utils/research-integration.js.map +1 -1
  112. package/dist/src/utils/research-questions.d.ts.map +1 -1
  113. package/dist/src/utils/research-questions.js +85 -24
  114. package/dist/src/utils/research-questions.js.map +1 -1
  115. package/dist/src/utils/rule-generation.d.ts.map +1 -1
  116. package/dist/src/utils/rule-generation.js +92 -108
  117. package/dist/src/utils/rule-generation.js.map +1 -1
  118. package/package.json +7 -1
package/README.md CHANGED
@@ -6,7 +6,7 @@
6
6
  [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
7
7
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue)](https://www.typescriptlang.org/)
8
8
 
9
- A comprehensive Model Context Protocol (MCP) server for AI-powered architectural decision analysis and management. This enterprise-ready solution provides intelligent analysis of Architectural Decision Records (ADRs), project ecosystems, and development workflows through 23 specialized MCP tools.
9
+ A comprehensive Model Context Protocol (MCP) server that provides **AI-powered architectural analysis** with **immediate, actionable results**. Unlike traditional MCP tools that return prompts, this server executes analysis internally using OpenRouter.ai and returns actual insights, ADR suggestions, and architectural recommendations.
10
10
 
11
11
  **Author**: [Tosin Akinosho](https://github.com/tosin2013)
12
12
  **Repository**: [https://github.com/tosin2013/mcp-adr-analysis-server.git](https://github.com/tosin2013/mcp-adr-analysis-server.git)
@@ -21,8 +21,14 @@ This MCP server enhances AI assistants with deep architectural analysis capabili
21
21
 
22
22
  ## ✨ Key Features
23
23
 
24
+ ### 🤖 **AI-Powered Execution (NEW)**
25
+ - **Immediate Results**: Get actual ADR suggestions, not prompts to submit elsewhere
26
+ - **OpenRouter.ai Integration**: Supports Claude, GPT-4, and cost-effective models
27
+ - **Smart Caching**: Intelligent response caching with configurable TTL
28
+ - **Graceful Fallback**: Automatic fallback to prompt-only mode when AI unavailable
29
+
24
30
  ### 🏗️ **Architectural Analysis & Intelligence**
25
- - **Technology Detection**: AI-powered identification of ANY technology stack (React, Python, Terraform, Kubernetes, etc.)
31
+ - **Technology Detection**: AI-powered identification of ANY technology stack
26
32
  - **Pattern Recognition**: Intelligent detection of architectural patterns and best practices
27
33
  - **Dependency Analysis**: Comprehensive project structure and dependency mapping
28
34
  - **Knowledge Graph Generation**: Create interconnected architectural knowledge representations
@@ -33,12 +39,6 @@ This MCP server enhances AI assistants with deep architectural analysis capabili
33
39
  - **ADR Lifecycle Management**: Complete ADR creation, analysis, and maintenance workflows
34
40
  - **Template Support**: Multiple ADR formats (Nygard, MADR, custom templates)
35
41
 
36
- ### 🔍 **Research & Documentation Intelligence**
37
- - **Research Integration**: Monitor and incorporate research findings into architectural decisions
38
- - **Context-Aware Research Questions**: Generate targeted research questions based on project context
39
- - **Documentation Analysis**: Extract insights from existing documentation and codebases
40
- - **Knowledge Synthesis**: Combine multiple information sources for comprehensive analysis
41
-
42
42
  ### 🛡️ **Enterprise Security & Compliance**
43
43
  - **Content Masking**: Automatic detection and masking of sensitive information
44
44
  - **Secret Prevention**: Proactive guidance to prevent secret exposure
@@ -51,39 +51,49 @@ This MCP server enhances AI assistants with deep architectural analysis capabili
51
51
  - **Environment Analysis**: Analyze and optimize deployment environments
52
52
  - **Rule Generation & Validation**: Extract and validate architectural rules from decisions
53
53
 
54
- ## 🛠️ Available MCP Tools
54
+ ## 🛠️ Available MCP Tools (25 Total)
55
55
 
56
- ### Core Analysis Tools
56
+ ### 🎯 **Workflow & Development Guidance** (AI-Powered ✅) **NEW!**
57
+ - **`get_workflow_guidance`** - Intelligent workflow advisor that recommends optimal tool sequences based on your goals and project context
58
+ - **`get_development_guidance`** - Comprehensive development guidance that translates architectural decisions into specific coding tasks and implementation roadmap
59
+
60
+ ### 🏗️ **Core Analysis Tools** (AI-Powered ✅)
57
61
  - **`analyze_project_ecosystem`** - Comprehensive technology and pattern detection
58
- - **`get_architectural_context`** - Generate intelligent architectural insights
62
+ - **`get_architectural_context`** - Generate intelligent architectural insights + automatic ADR setup
59
63
  - **`generate_adrs_from_prd`** - Convert requirements to structured ADRs
60
- - **`generate_adr_todo`** - Create actionable task lists from ADRs
64
+ - **`analyze_content_security`** - Detect sensitive information patterns
61
65
 
62
- ### Advanced Intelligence Tools
66
+ ### 📋 **ADR Management Tools** (AI-Powered ✅)
63
67
  - **`suggest_adrs`** - Auto-suggest ADRs from implicit decisions
64
68
  - **`generate_adr_from_decision`** - Create ADRs from specific decisions
65
69
  - **`discover_existing_adrs`** - Intelligent ADR discovery and analysis
66
- - **`incorporate_research`** - Integrate research findings into decisions
70
+ - **`generate_adr_todo`** - Create actionable task lists from ADRs
71
+
72
+ ### 🔍 **Research & Documentation Tools** (AI-Powered ✅)
67
73
  - **`generate_research_questions`** - Create context-aware research questions
74
+ - **`incorporate_research`** - Integrate research findings into decisions
75
+ - **`create_research_template`** - Generate research documentation templates
68
76
 
69
- ### Security & Compliance Tools
70
- - **`analyze_sensitive_content`** - Detect sensitive information patterns
71
- - **`mask_content`** - Intelligent content masking and protection
72
- - **`configure_masking`** - Customize security and masking settings
73
- - **`validate_content_security`** - Comprehensive security validation
74
- - **`apply_security_guidance`** - Proactive security recommendations
77
+ ### 🛡️ **Security & Compliance Tools** (AI-Powered ✅)
78
+ - **`generate_content_masking`** - Intelligent content masking and protection
79
+ - **`configure_custom_patterns`** - Customize security and masking settings
80
+ - **`apply_basic_content_masking`** - Basic content masking (fallback)
81
+ - **`validate_content_masking`** - Validate masking effectiveness
75
82
 
76
- ### Workflow & Management Tools
83
+ ### 🏗️ **Rule & Governance Tools** (AI-Powered ✅)
77
84
  - **`generate_rules`** - Extract architectural rules from ADRs
78
85
  - **`validate_rules`** - Validate code against architectural rules
79
86
  - **`create_rule_set`** - Create comprehensive rule management systems
87
+
88
+ ### 🚀 **Deployment & Environment Tools** (AI-Powered ✅)
80
89
  - **`analyze_environment`** - Environment analysis and optimization
81
90
  - **`analyze_deployment_progress`** - Deployment tracking and verification
82
91
 
83
- ### Utility & Integration Tools
84
- - **`clear_cache`** - Cache management and optimization
85
- - **`create_research_template`** - Generate research documentation templates
92
+ ### ⚙️ **Utility & Management Tools**
93
+ - **`manage_cache`** - Cache management and optimization
94
+ - **`configure_output_masking`** - Configure global output masking
86
95
  - **`request_action_confirmation`** - Interactive user confirmation workflows
96
+ - **`check_ai_execution_status`** - Diagnostic tool to troubleshoot AI execution configuration issues
87
97
 
88
98
  ## 📦 Installation
89
99
 
@@ -111,32 +121,51 @@ npm run build
111
121
  npm start
112
122
  ```
113
123
 
114
- ## ⚙️ Configuration
124
+ ## 🤖 AI Execution Configuration
125
+
126
+ The MCP server supports **AI-powered execution** that transforms tools from returning prompts to returning actual results. This solves the fundamental UX issue where AI agents receive prompts instead of actionable data.
127
+
128
+ ### Quick Setup
129
+
130
+ 1. **Get OpenRouter API Key**: Visit [https://openrouter.ai/keys](https://openrouter.ai/keys)
131
+ 2. **Set Environment Variables**:
132
+ ```bash
133
+ OPENROUTER_API_KEY=your_openrouter_api_key_here
134
+ EXECUTION_MODE=full
135
+ AI_MODEL=anthropic/claude-3-sonnet
136
+ ```
137
+ 3. **Restart MCP Server**: Tools now return actual results instead of prompts!
115
138
 
116
139
  ### Environment Variables
117
140
 
118
- The MCP server supports the following environment variables:
141
+ #### **AI Execution (Recommended)**
142
+ - **`OPENROUTER_API_KEY`** (Required for AI): OpenRouter API key from https://openrouter.ai/keys
143
+ - **`EXECUTION_MODE`** (Optional): `full` (AI execution) or `prompt-only` (legacy)
144
+ - **`AI_MODEL`** (Optional): AI model to use (see supported models below)
119
145
 
120
- - **`PROJECT_PATH`** (Required): Path to the project directory to analyze
121
- - Use `.` for current directory in project-specific configs
122
- - Use `${workspaceFolder}` in VS Code/Cline for workspace root
123
- - Use absolute paths for global configurations
146
+ #### **Performance Tuning (Optional)**
147
+ - **`AI_TEMPERATURE`** (Optional): Response consistency (0-1, default: 0.1)
148
+ - **`AI_MAX_TOKENS`** (Optional): Response length limit (default: 4000)
149
+ - **`AI_TIMEOUT`** (Optional): Request timeout in ms (default: 60000)
150
+ - **`AI_CACHE_ENABLED`** (Optional): Enable response caching (default: true)
124
151
 
125
- - **`ADR_DIRECTORY`** (Optional): Directory containing ADR files
126
- - Default: `docs/adrs`
127
- - Relative to PROJECT_PATH
152
+ #### **Project Configuration**
153
+ - **`PROJECT_PATH`** (Required): Path to the project directory to analyze
154
+ - **`ADR_DIRECTORY`** (Optional): Directory containing ADR files (default: `docs/adrs`)
155
+ - **`LOG_LEVEL`** (Optional): Logging level (DEBUG, INFO, WARN, ERROR)
128
156
 
129
- - **`LOG_LEVEL`** (Optional): Logging level
130
- - Options: `DEBUG`, `INFO`, `WARN`, `ERROR`
131
- - Default: `INFO`
157
+ ### Supported AI Models
132
158
 
133
- - **`CACHE_ENABLED`** (Optional): Enable/disable caching
134
- - Options: `true`, `false`
135
- - Default: `true`
159
+ | Model | Provider | Use Case | Input Cost | Output Cost |
160
+ |-------|----------|----------|------------|-------------|
161
+ | `anthropic/claude-3-sonnet` | Anthropic | Analysis, reasoning | $3.00/1K | $15.00/1K |
162
+ | `anthropic/claude-3-haiku` | Anthropic | Quick tasks | $0.25/1K | $1.25/1K |
163
+ | `openai/gpt-4o` | OpenAI | Versatile analysis | $5.00/1K | $15.00/1K |
164
+ | `openai/gpt-4o-mini` | OpenAI | Cost-effective | $0.15/1K | $0.60/1K |
136
165
 
137
- ### Client Configurations
166
+ ## ⚙️ Client Configuration
138
167
 
139
- ### Claude Desktop
168
+ ### Claude Desktop (Recommended Setup)
140
169
  Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
141
170
 
142
171
  ```json
@@ -146,6 +175,10 @@ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/
146
175
  "command": "mcp-adr-analysis-server",
147
176
  "env": {
148
177
  "PROJECT_PATH": "/path/to/your/project",
178
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
179
+ "EXECUTION_MODE": "full",
180
+ "AI_MODEL": "anthropic/claude-3-sonnet",
181
+ "EXECUTION_MODE": "full",
149
182
  "ADR_DIRECTORY": "docs/adrs",
150
183
  "LOG_LEVEL": "ERROR"
151
184
  }
@@ -428,30 +461,99 @@ npm run typecheck # Run TypeScript type checking
428
461
  - **Security**: Content masking and secret prevention
429
462
  - **MCP Compliance**: Strict adherence to Model Context Protocol specification
430
463
 
464
+
465
+
431
466
  ## 🚀 Getting Started
432
467
 
433
- ### Quick Start with Claude Desktop
434
- 1. Install the MCP server:
435
- ```bash
436
- npm install -g mcp-adr-analysis-server
437
- ```
468
+ ### Quick Start (3 Steps)
438
469
 
439
- 2. Add to your Claude Desktop configuration:
440
- ```json
441
- {
442
- "mcpServers": {
443
- "adr-analysis": {
444
- "command": "mcp-adr-analysis-server"
445
- }
446
- }
470
+ 1. **Install**: `npm install -g mcp-adr-analysis-server`
471
+ 2. **Get API Key**: Visit [https://openrouter.ai/keys](https://openrouter.ai/keys)
472
+ 3. **Configure Claude Desktop**: Add to your configuration:
473
+
474
+ ```json
475
+ {
476
+ "mcpServers": {
477
+ "adr-analysis": {
478
+ "command": "mcp-adr-analysis-server",
479
+ "env": {
480
+ "PROJECT_PATH": "/path/to/your/project",
481
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
482
+ "EXECUTION_MODE": "full",
483
+ "AI_MODEL": "anthropic/claude-3-sonnet"
484
+ }
485
+ }
486
+ }
447
487
  }
448
488
  ```
449
489
 
450
- 3. Restart Claude Desktop and start analyzing your projects!
490
+ 4. **Restart Claude Desktop** and start getting AI-powered architectural insights!
491
+
492
+ ### Example Usage
493
+
494
+ Once configured, you can ask Claude:
495
+
496
+ > "Analyze this React project's architecture and suggest ADRs for any implicit decisions"
497
+
498
+ > "Generate ADRs from the PRD.md file and create a todo.md with implementation tasks"
499
+
500
+ > "Check this codebase for security issues and provide masking recommendations"
501
+
502
+ The server will now return **actual analysis results** instead of prompts to submit elsewhere!
503
+
504
+ ## 🚀 Complete Development Lifecycle
505
+
506
+ The MCP server now provides a **complete development lifecycle assistant** with intelligent workflow guidance:
507
+
508
+ ### **🎯 Step 1: Get Workflow Guidance**
509
+ ```
510
+ get_workflow_guidance
511
+ ```
512
+ **Parameters:**
513
+ ```json
514
+ {
515
+ "goal": "analyze new project and set up architectural documentation",
516
+ "projectContext": "new_project",
517
+ "availableAssets": ["codebase"],
518
+ "timeframe": "thorough_review"
519
+ }
520
+ ```
521
+
522
+ **Result**: Intelligent tool sequence recommendations and workflow guidance.
523
+
524
+ ### **🏗️ Step 2: Get Development Guidance**
525
+ ```
526
+ get_development_guidance
527
+ ```
528
+ **Parameters:**
529
+ ```json
530
+ {
531
+ "developmentPhase": "implementation",
532
+ "adrsToImplement": ["ADR-001: API Design", "ADR-002: Database Schema"],
533
+ "technologyStack": ["TypeScript", "React", "Node.js"],
534
+ "teamContext": {"size": "small_team", "experienceLevel": "mixed"}
535
+ }
536
+ ```
537
+
538
+ **Result**: Specific coding tasks, implementation patterns, and development roadmap.
539
+
540
+ ### **📊 Step 3: Execute Recommended Tools**
541
+ Follow the workflow guidance to execute the recommended tool sequence for your specific goals.
542
+
543
+ ### **🔄 Complete Workflow Examples**
544
+
545
+ #### **New Project Setup**
546
+ 1. `get_workflow_guidance` → 2. `analyze_project_ecosystem` → 3. `get_architectural_context` → 4. `suggest_adrs` → 5. `get_development_guidance`
547
+
548
+ #### **Existing Project Analysis**
549
+ 1. `get_workflow_guidance` → 2. `discover_existing_adrs` → 3. `get_architectural_context` → 4. `generate_adr_todo` → 5. `get_development_guidance`
550
+
551
+ #### **Security Audit**
552
+ 1. `get_workflow_guidance` → 2. `analyze_content_security` → 3. `generate_content_masking` → 4. `validate_content_masking`
451
553
 
452
554
  ### Configuration Examples
453
555
 
454
- #### Example 1: Single Project Analysis
556
+ #### Example 1: AI-Powered Project Analysis
455
557
  ```json
456
558
  {
457
559
  "mcpServers": {
@@ -460,6 +562,45 @@ npm run typecheck # Run TypeScript type checking
460
562
  "env": {
461
563
  "PROJECT_PATH": "/Users/username/my-react-app",
462
564
  "ADR_DIRECTORY": "docs/decisions",
565
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
566
+ "EXECUTION_MODE": "full",
567
+ "AI_MODEL": "anthropic/claude-3-sonnet",
568
+ "AI_TEMPERATURE": "0.1",
569
+ "LOG_LEVEL": "INFO"
570
+ }
571
+ }
572
+ }
573
+ }
574
+ ```
575
+
576
+ #### Example 2: Cost-Effective Setup
577
+ ```json
578
+ {
579
+ "mcpServers": {
580
+ "adr-analysis": {
581
+ "command": "mcp-adr-analysis-server",
582
+ "env": {
583
+ "PROJECT_PATH": "/Users/username/my-project",
584
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
585
+ "EXECUTION_MODE": "full",
586
+ "AI_MODEL": "anthropic/claude-3-haiku",
587
+ "AI_MAX_TOKENS": "2000",
588
+ "AI_TEMPERATURE": "0.05"
589
+ }
590
+ }
591
+ }
592
+ }
593
+ ```
594
+
595
+ #### Example 3: Prompt-Only Mode (Legacy)
596
+ ```json
597
+ {
598
+ "mcpServers": {
599
+ "adr-analysis": {
600
+ "command": "mcp-adr-analysis-server",
601
+ "env": {
602
+ "PROJECT_PATH": "/Users/username/my-project",
603
+ "EXECUTION_MODE": "prompt-only",
463
604
  "LOG_LEVEL": "INFO"
464
605
  }
465
606
  }
@@ -467,7 +608,7 @@ npm run typecheck # Run TypeScript type checking
467
608
  }
468
609
  ```
469
610
 
470
- #### Example 2: Multi-Project Setup (Different configs for different projects)
611
+ #### Example 4: Multi-Project Setup
471
612
  ```json
472
613
  {
473
614
  "mcpServers": {
@@ -476,6 +617,9 @@ npm run typecheck # Run TypeScript type checking
476
617
  "env": {
477
618
  "PROJECT_PATH": "/Users/username/frontend-app",
478
619
  "ADR_DIRECTORY": "docs/adrs",
620
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
621
+ "EXECUTION_MODE": "full",
622
+ "AI_MODEL": "openai/gpt-4o-mini",
479
623
  "LOG_LEVEL": "ERROR"
480
624
  }
481
625
  },
@@ -484,6 +628,9 @@ npm run typecheck # Run TypeScript type checking
484
628
  "env": {
485
629
  "PROJECT_PATH": "/Users/username/backend-api",
486
630
  "ADR_DIRECTORY": "architecture/decisions",
631
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
632
+ "EXECUTION_MODE": "full",
633
+ "AI_MODEL": "anthropic/claude-3-sonnet",
487
634
  "LOG_LEVEL": "DEBUG"
488
635
  }
489
636
  }
@@ -491,7 +638,7 @@ npm run typecheck # Run TypeScript type checking
491
638
  }
492
639
  ```
493
640
 
494
- #### Example 3: Development vs Production
641
+ #### Example 5: Development Environment
495
642
  ```json
496
643
  {
497
644
  "mcpServers": {
@@ -500,33 +647,130 @@ npm run typecheck # Run TypeScript type checking
500
647
  "env": {
501
648
  "PROJECT_PATH": "${workspaceFolder}",
502
649
  "ADR_DIRECTORY": "docs/adrs",
503
- "LOG_LEVEL": "DEBUG",
504
- "CACHE_ENABLED": "true",
505
- "ANALYSIS_TIMEOUT": "60000"
650
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
651
+ "EXECUTION_MODE": "full",
652
+ "AI_MODEL": "anthropic/claude-3-haiku",
653
+ "AI_CACHE_ENABLED": "true",
654
+ "AI_CACHE_TTL": "1800",
655
+ "LOG_LEVEL": "DEBUG"
506
656
  }
507
657
  }
508
658
  }
509
659
  }
510
660
  ```
511
661
 
512
- ### Example Prompts for AI Assistants
513
662
 
514
- **Project Analysis:**
663
+
664
+ ## � Troubleshooting
665
+
666
+ ### ⚠️ **CRITICAL**: Tools Return Prompts Instead of Results
667
+
668
+ **Symptom**: When calling tools like `suggest_adrs`, you receive large detailed instructions and prompts instead of actual ADR suggestions.
669
+
670
+ **Root Cause**: AI execution is not properly configured. The tool is falling back to prompt-only mode.
671
+
672
+ **Solution**: Add these **required** environment variables to your MCP configuration:
673
+
674
+ ```json
675
+ {
676
+ "mcpServers": {
677
+ "adr-analysis": {
678
+ "command": "mcp-adr-analysis-server",
679
+ "env": {
680
+ "PROJECT_PATH": "/path/to/your/project",
681
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
682
+ "EXECUTION_MODE": "full",
683
+ "AI_MODEL": "anthropic/claude-3-sonnet"
684
+ }
685
+ }
686
+ }
687
+ }
688
+ ```
689
+
690
+ **Verification**: After adding these variables and restarting, tools should return actual results like:
691
+ - `suggest_adrs` → Actual ADR suggestions with titles and reasoning
692
+ - `analyze_project_ecosystem` → Real technology analysis and recommendations
693
+ - `generate_content_masking` → Actual masked content, not masking instructions
694
+
695
+ **Quick Diagnostic**: Use the built-in diagnostic tool:
515
696
  ```
516
- Using the MCP ADR Analysis Server, analyze this React TypeScript project and generate architectural insights focusing on scalability and security.
697
+ check_ai_execution_status
517
698
  ```
699
+ This will show exactly what's wrong with your configuration and provide step-by-step fix instructions.
700
+
701
+ ### Other AI Execution Issues
702
+
703
+ **Problem**: "AI execution not available" errors
704
+ ```bash
705
+ # Check execution mode
706
+ echo $EXECUTION_MODE
518
707
 
519
- **ADR Generation:**
708
+ # Verify API key is set
709
+ echo $OPENROUTER_API_KEY | head -c 10
710
+
711
+ # Test AI connectivity
712
+ curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
713
+ https://openrouter.ai/api/v1/models
520
714
  ```
521
- Using the ADR analysis tools, convert the PRD.md file into structured ADRs and create a todo.md with actionable tasks.
715
+
716
+ **Problem**: "AI execution not available" errors
717
+ - ✅ Verify `OPENROUTER_API_KEY` is set correctly
718
+ - ✅ Check `EXECUTION_MODE=full` in environment
719
+ - ✅ Ensure API key has sufficient credits
720
+ - ✅ Verify network connectivity to OpenRouter
721
+
722
+ **Problem**: Slow AI responses
723
+ ```bash
724
+ # Reduce token limits for faster responses
725
+ AI_MAX_TOKENS=2000
726
+ AI_TEMPERATURE=0.05
727
+
728
+ # Enable caching for repeated queries
729
+ AI_CACHE_ENABLED=true
730
+ AI_CACHE_TTL=3600
522
731
  ```
523
732
 
524
- **Security Analysis:**
733
+ **Problem**: High API costs
734
+ ```bash
735
+ # Use cost-effective models
736
+ AI_MODEL=anthropic/claude-3-haiku
737
+ # or
738
+ AI_MODEL=openai/gpt-4o-mini
739
+
740
+ # Reduce token usage
741
+ AI_MAX_TOKENS=2000
742
+ AI_TEMPERATURE=0.1
525
743
  ```
526
- Analyze this codebase for sensitive content and provide security recommendations using the content masking tools.
744
+
745
+ ### Environment Configuration
746
+
747
+ **Check current configuration:**
748
+ ```bash
749
+ # View AI execution status
750
+ node -e "
751
+ const { getAIExecutionStatus } = require('./dist/utils/prompt-execution.js');
752
+ console.log(JSON.stringify(getAIExecutionStatus(), null, 2));
753
+ "
527
754
  ```
528
755
 
529
- ## 🔒 Security Features
756
+ **Reset configuration:**
757
+ ```bash
758
+ # Clear cache and restart
759
+ rm -rf .mcp-adr-cache
760
+ npm run build
761
+ ```
762
+
763
+ ### Common Issues
764
+
765
+ | Issue | Solution |
766
+ |-------|----------|
767
+ | "Module not found" errors | Run `npm install && npm run build` |
768
+ | TypeScript compilation errors | Check Node.js version >= 18.0.0 |
769
+ | Permission denied | Check file permissions and project path |
770
+ | API rate limits | Reduce `AI_MAX_TOKENS` or increase `AI_TIMEOUT` |
771
+ | Cache issues | Clear cache with `rm -rf .mcp-adr-cache` |
772
+
773
+ ## �🔒 Security Features
530
774
 
531
775
  ### Content Protection
532
776
  - **Automatic Secret Detection**: Identifies API keys, passwords, and sensitive data
@@ -0,0 +1,81 @@
1
+ /**
2
+ * AI Configuration for OpenRouter.ai Integration
3
+ *
4
+ * This module handles configuration for AI execution capabilities,
5
+ * allowing the MCP server to execute prompts internally and return
6
+ * actual results instead of prompts.
7
+ */
8
+ export interface AIConfig {
9
+ /** OpenRouter API key for authentication */
10
+ apiKey: string;
11
+ /** Base URL for OpenRouter API */
12
+ baseURL: string;
13
+ /** Default AI model to use for prompt execution */
14
+ defaultModel: string;
15
+ /** Execution mode: 'full' executes prompts, 'prompt-only' returns prompts */
16
+ executionMode: 'full' | 'prompt-only';
17
+ /** Site URL for OpenRouter rankings (optional) */
18
+ siteUrl?: string;
19
+ /** Site name for OpenRouter rankings (optional) */
20
+ siteName?: string;
21
+ /** Request timeout in milliseconds */
22
+ timeout: number;
23
+ /** Maximum retries for failed requests */
24
+ maxRetries: number;
25
+ /** Temperature for AI responses (0-1) */
26
+ temperature: number;
27
+ /** Maximum tokens for AI responses */
28
+ maxTokens: number;
29
+ /** Enable response caching */
30
+ cacheEnabled: boolean;
31
+ /** Cache TTL in seconds */
32
+ cacheTTL: number;
33
+ }
34
+ export interface ModelConfig {
35
+ /** Model identifier for OpenRouter */
36
+ id: string;
37
+ /** Human-readable model name */
38
+ name: string;
39
+ /** Model provider (openai, anthropic, etc.) */
40
+ provider: string;
41
+ /** Cost per 1K tokens (input) */
42
+ inputCost: number;
43
+ /** Cost per 1K tokens (output) */
44
+ outputCost: number;
45
+ /** Maximum context length */
46
+ contextLength: number;
47
+ /** Recommended use cases */
48
+ useCases: string[];
49
+ }
50
+ /**
51
+ * Available AI models for different use cases
52
+ */
53
+ export declare const AVAILABLE_MODELS: Record<string, ModelConfig>;
54
+ /**
55
+ * Default AI configuration
56
+ */
57
+ export declare const DEFAULT_AI_CONFIG: Omit<AIConfig, 'siteUrl' | 'siteName'> & {
58
+ siteUrl: string;
59
+ siteName: string;
60
+ };
61
+ /**
62
+ * Load AI configuration from environment variables
63
+ */
64
+ export declare function loadAIConfig(): AIConfig;
65
+ /**
66
+ * Validate AI configuration
67
+ */
68
+ export declare function validateAIConfig(config: AIConfig): void;
69
+ /**
70
+ * Get model configuration by ID
71
+ */
72
+ export declare function getModelConfig(modelId: string): ModelConfig | undefined;
73
+ /**
74
+ * Check if AI execution is enabled
75
+ */
76
+ export declare function isAIExecutionEnabled(config: AIConfig): boolean;
77
+ /**
78
+ * Get recommended model for a specific use case
79
+ */
80
+ export declare function getRecommendedModel(useCase: string, costSensitive?: boolean): string;
81
+ //# sourceMappingURL=ai-config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ai-config.d.ts","sourceRoot":"","sources":["../../../src/config/ai-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,QAAQ;IACvB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,aAAa,EAAE,MAAM,GAAG,aAAa,CAAC;IACtC,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,YAAY,EAAE,OAAO,CAAC;IACtB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAqCxD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,GAAG,UAAU,CAAC,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAa3G,CAAC;AAEF;;GAEG;AACH,wBAAgB,YAAY,IAAI,QAAQ,CAiBvC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAoBvD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGvE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAE9D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,GAAE,OAAe,GAAG,MAAM,CAiB3F"}