mcp-adr-analysis-server 1.1.0 → 2.0.1

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 +298 -123
  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 +1821 -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 +9 -3
package/README.md CHANGED
@@ -6,84 +6,25 @@
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.
10
-
11
- **Author**: [Tosin Akinosho](https://github.com/tosin2013)
12
- **Repository**: [https://github.com/tosin2013/mcp-adr-analysis-server.git](https://github.com/tosin2013/mcp-adr-analysis-server.git)
13
-
14
- ## 🚀 What is the Model Context Protocol (MCP)?
15
-
16
- > The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.
17
- >
18
- > — [Model Context Protocol README](https://github.com/modelcontextprotocol#:~:text=The%20Model%20Context,context%20they%20need.)
19
-
20
- This MCP server enhances AI assistants with deep architectural analysis capabilities, enabling intelligent code generation, decision tracking, and development workflow automation.
21
-
22
- ## ✨ Key Features
23
-
24
- ### 🏗️ **Architectural Analysis & Intelligence**
25
- - **Technology Detection**: AI-powered identification of ANY technology stack (React, Python, Terraform, Kubernetes, etc.)
26
- - **Pattern Recognition**: Intelligent detection of architectural patterns and best practices
27
- - **Dependency Analysis**: Comprehensive project structure and dependency mapping
28
- - **Knowledge Graph Generation**: Create interconnected architectural knowledge representations
29
-
30
- ### 📋 **ADR Management & Generation**
31
- - **ADR Generation from PRD**: Convert Product Requirements Documents to structured ADRs
32
- - **Intelligent ADR Suggestions**: Auto-suggest ADRs from implicit code decisions
33
- - **ADR Lifecycle Management**: Complete ADR creation, analysis, and maintenance workflows
34
- - **Template Support**: Multiple ADR formats (Nygard, MADR, custom templates)
35
-
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
- ### 🛡️ **Enterprise Security & Compliance**
43
- - **Content Masking**: Automatic detection and masking of sensitive information
44
- - **Secret Prevention**: Proactive guidance to prevent secret exposure
45
- - **Security Hardening**: Built-in security best practices and validation
46
- - **Compliance Tracking**: Ensure architectural decisions meet enterprise standards
47
-
48
- ### 📊 **Development Workflow Automation**
49
- - **Todo Management**: Generate actionable task lists from ADRs and project analysis
50
- - **Deployment Tracking**: Monitor deployment progress and completion verification
51
- - **Environment Analysis**: Analyze and optimize deployment environments
52
- - **Rule Generation & Validation**: Extract and validate architectural rules from decisions
53
-
54
- ## 🛠️ Available MCP Tools
55
-
56
- ### Core Analysis Tools
57
- - **`analyze_project_ecosystem`** - Comprehensive technology and pattern detection
58
- - **`get_architectural_context`** - Generate intelligent architectural insights
59
- - **`generate_adrs_from_prd`** - Convert requirements to structured ADRs
60
- - **`generate_adr_todo`** - Create actionable task lists from ADRs
61
-
62
- ### Advanced Intelligence Tools
63
- - **`suggest_adrs`** - Auto-suggest ADRs from implicit decisions
64
- - **`generate_adr_from_decision`** - Create ADRs from specific decisions
65
- - **`discover_existing_adrs`** - Intelligent ADR discovery and analysis
66
- - **`incorporate_research`** - Integrate research findings into decisions
67
- - **`generate_research_questions`** - Create context-aware research questions
68
-
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
75
-
76
- ### Workflow & Management Tools
77
- - **`generate_rules`** - Extract architectural rules from ADRs
78
- - **`validate_rules`** - Validate code against architectural rules
79
- - **`create_rule_set`** - Create comprehensive rule management systems
80
- - **`analyze_environment`** - Environment analysis and optimization
81
- - **`analyze_deployment_progress`** - Deployment tracking and verification
82
-
83
- ### Utility & Integration Tools
84
- - **`clear_cache`** - Cache management and optimization
85
- - **`create_research_template`** - Generate research documentation templates
86
- - **`request_action_confirmation`** - Interactive user confirmation workflows
9
+ **AI-powered architectural analysis for intelligent development workflows.** This Model Context Protocol (MCP) server provides immediate, actionable architectural insights instead of prompts. Get real ADR suggestions, technology analysis, and security recommendations through OpenRouter.ai integration.
10
+
11
+ **Key Differentiator**: Returns actual analysis results, not prompts to submit elsewhere.
12
+
13
+ **Author**: [Tosin Akinosho](https://github.com/tosin2013) | **Repository**: [GitHub](https://github.com/tosin2013/mcp-adr-analysis-server.git)
14
+
15
+ ## What is MCP?
16
+
17
+ The Model Context Protocol enables seamless integration between AI assistants and external tools. This server enhances AI assistants with deep architectural analysis capabilities, enabling intelligent code generation, decision tracking, and development workflow automation.
18
+
19
+ ## ✨ Core Capabilities
20
+
21
+ 🤖 **AI-Powered Analysis** - Immediate architectural insights with OpenRouter.ai integration
22
+ 🏗️ **Technology Detection** - Identify any tech stack and architectural patterns
23
+ 📋 **ADR Management** - Generate, suggest, and maintain Architectural Decision Records
24
+ 🛡️ **Security & Compliance** - Detect and mask sensitive content automatically
25
+ 📊 **Workflow Automation** - Todo generation, deployment tracking, and rule validation
26
+
27
+
87
28
 
88
29
  ## 📦 Installation
89
30
 
@@ -111,32 +52,51 @@ npm run build
111
52
  npm start
112
53
  ```
113
54
 
114
- ## ⚙️ Configuration
55
+ ## 🤖 AI Execution Configuration
56
+
57
+ 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.
58
+
59
+ ### Quick Setup
60
+
61
+ 1. **Get OpenRouter API Key**: Visit [https://openrouter.ai/keys](https://openrouter.ai/keys)
62
+ 2. **Set Environment Variables**:
63
+ ```bash
64
+ OPENROUTER_API_KEY=your_openrouter_api_key_here
65
+ EXECUTION_MODE=full
66
+ AI_MODEL=anthropic/claude-3-sonnet
67
+ ```
68
+ 3. **Restart MCP Server**: Tools now return actual results instead of prompts!
115
69
 
116
70
  ### Environment Variables
117
71
 
118
- The MCP server supports the following environment variables:
72
+ #### **AI Execution (Recommended)**
73
+ - **`OPENROUTER_API_KEY`** (Required for AI): OpenRouter API key from https://openrouter.ai/keys
74
+ - **`EXECUTION_MODE`** (Optional): `full` (AI execution) or `prompt-only` (legacy)
75
+ - **`AI_MODEL`** (Optional): AI model to use (see supported models below)
119
76
 
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
77
+ #### **Performance Tuning (Optional)**
78
+ - **`AI_TEMPERATURE`** (Optional): Response consistency (0-1, default: 0.1)
79
+ - **`AI_MAX_TOKENS`** (Optional): Response length limit (default: 4000)
80
+ - **`AI_TIMEOUT`** (Optional): Request timeout in ms (default: 60000)
81
+ - **`AI_CACHE_ENABLED`** (Optional): Enable response caching (default: true)
124
82
 
125
- - **`ADR_DIRECTORY`** (Optional): Directory containing ADR files
126
- - Default: `docs/adrs`
127
- - Relative to PROJECT_PATH
83
+ #### **Project Configuration**
84
+ - **`PROJECT_PATH`** (Required): Path to the project directory to analyze
85
+ - **`ADR_DIRECTORY`** (Optional): Directory containing ADR files (default: `docs/adrs`)
86
+ - **`LOG_LEVEL`** (Optional): Logging level (DEBUG, INFO, WARN, ERROR)
128
87
 
129
- - **`LOG_LEVEL`** (Optional): Logging level
130
- - Options: `DEBUG`, `INFO`, `WARN`, `ERROR`
131
- - Default: `INFO`
88
+ ### Supported AI Models
132
89
 
133
- - **`CACHE_ENABLED`** (Optional): Enable/disable caching
134
- - Options: `true`, `false`
135
- - Default: `true`
90
+ | Model | Provider | Use Case | Input Cost | Output Cost |
91
+ |-------|----------|----------|------------|-------------|
92
+ | `anthropic/claude-3-sonnet` | Anthropic | Analysis, reasoning | $3.00/1K | $15.00/1K |
93
+ | `anthropic/claude-3-haiku` | Anthropic | Quick tasks | $0.25/1K | $1.25/1K |
94
+ | `openai/gpt-4o` | OpenAI | Versatile analysis | $5.00/1K | $15.00/1K |
95
+ | `openai/gpt-4o-mini` | OpenAI | Cost-effective | $0.15/1K | $0.60/1K |
136
96
 
137
- ### Client Configurations
97
+ ## ⚙️ Client Configuration
138
98
 
139
- ### Claude Desktop
99
+ ### Claude Desktop (Recommended Setup)
140
100
  Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
141
101
 
142
102
  ```json
@@ -146,6 +106,10 @@ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/
146
106
  "command": "mcp-adr-analysis-server",
147
107
  "env": {
148
108
  "PROJECT_PATH": "/path/to/your/project",
109
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
110
+ "EXECUTION_MODE": "full",
111
+ "AI_MODEL": "anthropic/claude-3-sonnet",
112
+ "EXECUTION_MODE": "full",
149
113
  "ADR_DIRECTORY": "docs/adrs",
150
114
  "LOG_LEVEL": "ERROR"
151
115
  }
@@ -428,30 +392,99 @@ npm run typecheck # Run TypeScript type checking
428
392
  - **Security**: Content masking and secret prevention
429
393
  - **MCP Compliance**: Strict adherence to Model Context Protocol specification
430
394
 
395
+
396
+
431
397
  ## 🚀 Getting Started
432
398
 
433
- ### Quick Start with Claude Desktop
434
- 1. Install the MCP server:
435
- ```bash
436
- npm install -g mcp-adr-analysis-server
437
- ```
399
+ ### Quick Start (3 Steps)
400
+
401
+ 1. **Install**: `npm install -g mcp-adr-analysis-server`
402
+ 2. **Get API Key**: Visit [https://openrouter.ai/keys](https://openrouter.ai/keys)
403
+ 3. **Configure Claude Desktop**: Add to your configuration:
438
404
 
439
- 2. Add to your Claude Desktop configuration:
440
- ```json
441
- {
442
- "mcpServers": {
443
- "adr-analysis": {
444
- "command": "mcp-adr-analysis-server"
445
- }
446
- }
405
+ ```json
406
+ {
407
+ "mcpServers": {
408
+ "adr-analysis": {
409
+ "command": "mcp-adr-analysis-server",
410
+ "env": {
411
+ "PROJECT_PATH": "/path/to/your/project",
412
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
413
+ "EXECUTION_MODE": "full",
414
+ "AI_MODEL": "anthropic/claude-3-sonnet"
415
+ }
416
+ }
417
+ }
447
418
  }
448
419
  ```
449
420
 
450
- 3. Restart Claude Desktop and start analyzing your projects!
421
+ 4. **Restart Claude Desktop** and start getting AI-powered architectural insights!
422
+
423
+ ### Example Usage
424
+
425
+ Once configured, you can ask Claude:
426
+
427
+ > "Analyze this React project's architecture and suggest ADRs for any implicit decisions"
428
+
429
+ > "Generate ADRs from the PRD.md file and create a todo.md with implementation tasks"
430
+
431
+ > "Check this codebase for security issues and provide masking recommendations"
432
+
433
+ The server will now return **actual analysis results** instead of prompts to submit elsewhere!
434
+
435
+ ## 🚀 Complete Development Lifecycle
436
+
437
+ The MCP server now provides a **complete development lifecycle assistant** with intelligent workflow guidance:
438
+
439
+ ### **🎯 Step 1: Get Workflow Guidance**
440
+ ```
441
+ get_workflow_guidance
442
+ ```
443
+ **Parameters:**
444
+ ```json
445
+ {
446
+ "goal": "analyze new project and set up architectural documentation",
447
+ "projectContext": "new_project",
448
+ "availableAssets": ["codebase"],
449
+ "timeframe": "thorough_review"
450
+ }
451
+ ```
452
+
453
+ **Result**: Intelligent tool sequence recommendations and workflow guidance.
454
+
455
+ ### **🏗️ Step 2: Get Development Guidance**
456
+ ```
457
+ get_development_guidance
458
+ ```
459
+ **Parameters:**
460
+ ```json
461
+ {
462
+ "developmentPhase": "implementation",
463
+ "adrsToImplement": ["ADR-001: API Design", "ADR-002: Database Schema"],
464
+ "technologyStack": ["TypeScript", "React", "Node.js"],
465
+ "teamContext": {"size": "small_team", "experienceLevel": "mixed"}
466
+ }
467
+ ```
468
+
469
+ **Result**: Specific coding tasks, implementation patterns, and development roadmap.
470
+
471
+ ### **📊 Step 3: Execute Recommended Tools**
472
+ Follow the workflow guidance to execute the recommended tool sequence for your specific goals.
473
+
474
+ ### **🔄 Complete Workflow Examples**
475
+
476
+ #### **New Project Setup**
477
+ 1. `get_workflow_guidance` → 2. `analyze_project_ecosystem` → 3. `get_architectural_context` → 4. `suggest_adrs` → 5. `get_development_guidance`
478
+
479
+ #### **Existing Project Analysis**
480
+ 1. `get_workflow_guidance` → 2. `discover_existing_adrs` → 3. `get_architectural_context` → 4. `generate_adr_todo` → 5. `get_development_guidance`
481
+
482
+ #### **Security Audit**
483
+ 1. `get_workflow_guidance` → 2. `analyze_content_security` → 3. `generate_content_masking` → 4. `validate_content_masking`
451
484
 
452
485
  ### Configuration Examples
453
486
 
454
- #### Example 1: Single Project Analysis
487
+ #### Example 1: AI-Powered Project Analysis
455
488
  ```json
456
489
  {
457
490
  "mcpServers": {
@@ -460,6 +493,10 @@ npm run typecheck # Run TypeScript type checking
460
493
  "env": {
461
494
  "PROJECT_PATH": "/Users/username/my-react-app",
462
495
  "ADR_DIRECTORY": "docs/decisions",
496
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
497
+ "EXECUTION_MODE": "full",
498
+ "AI_MODEL": "anthropic/claude-3-sonnet",
499
+ "AI_TEMPERATURE": "0.1",
463
500
  "LOG_LEVEL": "INFO"
464
501
  }
465
502
  }
@@ -467,7 +504,42 @@ npm run typecheck # Run TypeScript type checking
467
504
  }
468
505
  ```
469
506
 
470
- #### Example 2: Multi-Project Setup (Different configs for different projects)
507
+ #### Example 2: Cost-Effective Setup
508
+ ```json
509
+ {
510
+ "mcpServers": {
511
+ "adr-analysis": {
512
+ "command": "mcp-adr-analysis-server",
513
+ "env": {
514
+ "PROJECT_PATH": "/Users/username/my-project",
515
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
516
+ "EXECUTION_MODE": "full",
517
+ "AI_MODEL": "anthropic/claude-3-haiku",
518
+ "AI_MAX_TOKENS": "2000",
519
+ "AI_TEMPERATURE": "0.05"
520
+ }
521
+ }
522
+ }
523
+ }
524
+ ```
525
+
526
+ #### Example 3: Prompt-Only Mode (Legacy)
527
+ ```json
528
+ {
529
+ "mcpServers": {
530
+ "adr-analysis": {
531
+ "command": "mcp-adr-analysis-server",
532
+ "env": {
533
+ "PROJECT_PATH": "/Users/username/my-project",
534
+ "EXECUTION_MODE": "prompt-only",
535
+ "LOG_LEVEL": "INFO"
536
+ }
537
+ }
538
+ }
539
+ }
540
+ ```
541
+
542
+ #### Example 4: Multi-Project Setup
471
543
  ```json
472
544
  {
473
545
  "mcpServers": {
@@ -476,6 +548,9 @@ npm run typecheck # Run TypeScript type checking
476
548
  "env": {
477
549
  "PROJECT_PATH": "/Users/username/frontend-app",
478
550
  "ADR_DIRECTORY": "docs/adrs",
551
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
552
+ "EXECUTION_MODE": "full",
553
+ "AI_MODEL": "openai/gpt-4o-mini",
479
554
  "LOG_LEVEL": "ERROR"
480
555
  }
481
556
  },
@@ -484,6 +559,9 @@ npm run typecheck # Run TypeScript type checking
484
559
  "env": {
485
560
  "PROJECT_PATH": "/Users/username/backend-api",
486
561
  "ADR_DIRECTORY": "architecture/decisions",
562
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
563
+ "EXECUTION_MODE": "full",
564
+ "AI_MODEL": "anthropic/claude-3-sonnet",
487
565
  "LOG_LEVEL": "DEBUG"
488
566
  }
489
567
  }
@@ -491,7 +569,7 @@ npm run typecheck # Run TypeScript type checking
491
569
  }
492
570
  ```
493
571
 
494
- #### Example 3: Development vs Production
572
+ #### Example 5: Development Environment
495
573
  ```json
496
574
  {
497
575
  "mcpServers": {
@@ -500,33 +578,130 @@ npm run typecheck # Run TypeScript type checking
500
578
  "env": {
501
579
  "PROJECT_PATH": "${workspaceFolder}",
502
580
  "ADR_DIRECTORY": "docs/adrs",
503
- "LOG_LEVEL": "DEBUG",
504
- "CACHE_ENABLED": "true",
505
- "ANALYSIS_TIMEOUT": "60000"
581
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
582
+ "EXECUTION_MODE": "full",
583
+ "AI_MODEL": "anthropic/claude-3-haiku",
584
+ "AI_CACHE_ENABLED": "true",
585
+ "AI_CACHE_TTL": "1800",
586
+ "LOG_LEVEL": "DEBUG"
506
587
  }
507
588
  }
508
589
  }
509
590
  }
510
591
  ```
511
592
 
512
- ### Example Prompts for AI Assistants
513
593
 
514
- **Project Analysis:**
594
+
595
+ ## � Troubleshooting
596
+
597
+ ### ⚠️ **CRITICAL**: Tools Return Prompts Instead of Results
598
+
599
+ **Symptom**: When calling tools like `suggest_adrs`, you receive large detailed instructions and prompts instead of actual ADR suggestions.
600
+
601
+ **Root Cause**: AI execution is not properly configured. The tool is falling back to prompt-only mode.
602
+
603
+ **Solution**: Add these **required** environment variables to your MCP configuration:
604
+
605
+ ```json
606
+ {
607
+ "mcpServers": {
608
+ "adr-analysis": {
609
+ "command": "mcp-adr-analysis-server",
610
+ "env": {
611
+ "PROJECT_PATH": "/path/to/your/project",
612
+ "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
613
+ "EXECUTION_MODE": "full",
614
+ "AI_MODEL": "anthropic/claude-3-sonnet"
615
+ }
616
+ }
617
+ }
618
+ }
619
+ ```
620
+
621
+ **Verification**: After adding these variables and restarting, tools should return actual results like:
622
+ - `suggest_adrs` → Actual ADR suggestions with titles and reasoning
623
+ - `analyze_project_ecosystem` → Real technology analysis and recommendations
624
+ - `generate_content_masking` → Actual masked content, not masking instructions
625
+
626
+ **Quick Diagnostic**: Use the built-in diagnostic tool:
515
627
  ```
516
- Using the MCP ADR Analysis Server, analyze this React TypeScript project and generate architectural insights focusing on scalability and security.
628
+ check_ai_execution_status
629
+ ```
630
+ This will show exactly what's wrong with your configuration and provide step-by-step fix instructions.
631
+
632
+ ### Other AI Execution Issues
633
+
634
+ **Problem**: "AI execution not available" errors
635
+ ```bash
636
+ # Check execution mode
637
+ echo $EXECUTION_MODE
638
+
639
+ # Verify API key is set
640
+ echo $OPENROUTER_API_KEY | head -c 10
641
+
642
+ # Test AI connectivity
643
+ curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
644
+ https://openrouter.ai/api/v1/models
517
645
  ```
518
646
 
519
- **ADR Generation:**
647
+ **Problem**: "AI execution not available" errors
648
+ - ✅ Verify `OPENROUTER_API_KEY` is set correctly
649
+ - ✅ Check `EXECUTION_MODE=full` in environment
650
+ - ✅ Ensure API key has sufficient credits
651
+ - ✅ Verify network connectivity to OpenRouter
652
+
653
+ **Problem**: Slow AI responses
654
+ ```bash
655
+ # Reduce token limits for faster responses
656
+ AI_MAX_TOKENS=2000
657
+ AI_TEMPERATURE=0.05
658
+
659
+ # Enable caching for repeated queries
660
+ AI_CACHE_ENABLED=true
661
+ AI_CACHE_TTL=3600
520
662
  ```
521
- Using the ADR analysis tools, convert the PRD.md file into structured ADRs and create a todo.md with actionable tasks.
663
+
664
+ **Problem**: High API costs
665
+ ```bash
666
+ # Use cost-effective models
667
+ AI_MODEL=anthropic/claude-3-haiku
668
+ # or
669
+ AI_MODEL=openai/gpt-4o-mini
670
+
671
+ # Reduce token usage
672
+ AI_MAX_TOKENS=2000
673
+ AI_TEMPERATURE=0.1
522
674
  ```
523
675
 
524
- **Security Analysis:**
676
+ ### Environment Configuration
677
+
678
+ **Check current configuration:**
679
+ ```bash
680
+ # View AI execution status
681
+ node -e "
682
+ const { getAIExecutionStatus } = require('./dist/utils/prompt-execution.js');
683
+ console.log(JSON.stringify(getAIExecutionStatus(), null, 2));
684
+ "
525
685
  ```
526
- Analyze this codebase for sensitive content and provide security recommendations using the content masking tools.
686
+
687
+ **Reset configuration:**
688
+ ```bash
689
+ # Clear cache and restart
690
+ rm -rf .mcp-adr-cache
691
+ npm run build
527
692
  ```
528
693
 
529
- ## 🔒 Security Features
694
+ ### Common Issues
695
+
696
+ | Issue | Solution |
697
+ |-------|----------|
698
+ | "Module not found" errors | Run `npm install && npm run build` |
699
+ | TypeScript compilation errors | Check Node.js version >= 18.0.0 |
700
+ | Permission denied | Check file permissions and project path |
701
+ | API rate limits | Reduce `AI_MAX_TOKENS` or increase `AI_TIMEOUT` |
702
+ | Cache issues | Clear cache with `rm -rf .mcp-adr-cache` |
703
+
704
+ ## �🔒 Security Features
530
705
 
531
706
  ### Content Protection
532
707
  - **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"}