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.
- package/README.md +313 -69
- package/dist/src/config/ai-config.d.ts +81 -0
- package/dist/src/config/ai-config.d.ts.map +1 -0
- package/dist/src/config/ai-config.js +134 -0
- package/dist/src/config/ai-config.js.map +1 -0
- package/dist/src/index.d.ts +96 -1
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +1818 -199
- package/dist/src/index.js.map +1 -1
- package/dist/src/prompts/adr-suggestion-prompts.d.ts +2 -2
- package/dist/src/prompts/adr-suggestion-prompts.d.ts.map +1 -1
- package/dist/src/prompts/adr-suggestion-prompts.js +25 -17
- package/dist/src/prompts/adr-suggestion-prompts.js.map +1 -1
- package/dist/src/prompts/analysis-prompts.js +1 -1
- package/dist/src/prompts/analysis-prompts.js.map +1 -1
- package/dist/src/resources/index.d.ts +1 -1
- package/dist/src/resources/index.d.ts.map +1 -1
- package/dist/src/resources/index.js +52 -44
- package/dist/src/resources/index.js.map +1 -1
- package/dist/src/templates/domain-knowledge-templates.d.ts +36 -0
- package/dist/src/templates/domain-knowledge-templates.d.ts.map +1 -0
- package/dist/src/templates/domain-knowledge-templates.js +376 -0
- package/dist/src/templates/domain-knowledge-templates.js.map +1 -0
- package/dist/src/tools/adr-suggestion-tool.d.ts +8 -3
- package/dist/src/tools/adr-suggestion-tool.d.ts.map +1 -1
- package/dist/src/tools/adr-suggestion-tool.js +561 -172
- package/dist/src/tools/adr-suggestion-tool.js.map +1 -1
- package/dist/src/tools/content-masking-tool.d.ts.map +1 -1
- package/dist/src/tools/content-masking-tool.js +168 -22
- package/dist/src/tools/content-masking-tool.js.map +1 -1
- package/dist/src/tools/deployment-analysis-tool.d.ts.map +1 -1
- package/dist/src/tools/deployment-analysis-tool.js +64 -27
- package/dist/src/tools/deployment-analysis-tool.js.map +1 -1
- package/dist/src/tools/environment-analysis-tool.d.ts.map +1 -1
- package/dist/src/tools/environment-analysis-tool.js +65 -29
- package/dist/src/tools/environment-analysis-tool.js.map +1 -1
- package/dist/src/tools/research-question-tool.d.ts.map +1 -1
- package/dist/src/tools/research-question-tool.js +150 -49
- package/dist/src/tools/research-question-tool.js.map +1 -1
- package/dist/src/tools/rule-generation-tool.d.ts.map +1 -1
- package/dist/src/tools/rule-generation-tool.js +328 -143
- package/dist/src/tools/rule-generation-tool.js.map +1 -1
- package/dist/src/types/ape-framework.d.ts +566 -0
- package/dist/src/types/ape-framework.d.ts.map +1 -0
- package/dist/src/types/ape-framework.js +98 -0
- package/dist/src/types/ape-framework.js.map +1 -0
- package/dist/src/types/index.d.ts +96 -93
- package/dist/src/types/index.d.ts.map +1 -1
- package/dist/src/types/knowledge-generation.d.ts +671 -0
- package/dist/src/types/knowledge-generation.d.ts.map +1 -0
- package/dist/src/types/knowledge-generation.js +107 -0
- package/dist/src/types/knowledge-generation.js.map +1 -0
- package/dist/src/types/reflexion-framework.d.ts +652 -0
- package/dist/src/types/reflexion-framework.d.ts.map +1 -0
- package/dist/src/types/reflexion-framework.js +85 -0
- package/dist/src/types/reflexion-framework.js.map +1 -0
- package/dist/src/utils/adr-suggestions.d.ts +1 -1
- package/dist/src/utils/adr-suggestions.d.ts.map +1 -1
- package/dist/src/utils/adr-suggestions.js +8 -50
- package/dist/src/utils/adr-suggestions.js.map +1 -1
- package/dist/src/utils/ai-executor.d.ts +125 -0
- package/dist/src/utils/ai-executor.d.ts.map +1 -0
- package/dist/src/utils/ai-executor.js +292 -0
- package/dist/src/utils/ai-executor.js.map +1 -0
- package/dist/src/utils/automatic-prompt-engineering.d.ts +72 -0
- package/dist/src/utils/automatic-prompt-engineering.d.ts.map +1 -0
- package/dist/src/utils/automatic-prompt-engineering.js +820 -0
- package/dist/src/utils/automatic-prompt-engineering.js.map +1 -0
- package/dist/src/utils/cache.d.ts +54 -22
- package/dist/src/utils/cache.d.ts.map +1 -1
- package/dist/src/utils/cache.js +1234 -143
- package/dist/src/utils/cache.js.map +1 -1
- package/dist/src/utils/config.d.ts +2 -2
- package/dist/src/utils/config.js +3 -3
- package/dist/src/utils/config.js.map +1 -1
- package/dist/src/utils/deployment-analysis.d.ts.map +1 -1
- package/dist/src/utils/deployment-analysis.js +57 -38
- package/dist/src/utils/deployment-analysis.js.map +1 -1
- package/dist/src/utils/environment-analysis.d.ts.map +1 -1
- package/dist/src/utils/environment-analysis.js +113 -100
- package/dist/src/utils/environment-analysis.js.map +1 -1
- package/dist/src/utils/file-system.d.ts +42 -13
- package/dist/src/utils/file-system.d.ts.map +1 -1
- package/dist/src/utils/file-system.js +795 -89
- package/dist/src/utils/file-system.js.map +1 -1
- package/dist/src/utils/index.d.ts +9 -0
- package/dist/src/utils/index.d.ts.map +1 -0
- package/dist/src/utils/index.js +13 -0
- package/dist/src/utils/index.js.map +1 -0
- package/dist/src/utils/knowledge-generation.d.ts +79 -0
- package/dist/src/utils/knowledge-generation.d.ts.map +1 -0
- package/dist/src/utils/knowledge-generation.js +646 -0
- package/dist/src/utils/knowledge-generation.js.map +1 -0
- package/dist/src/utils/output-masking.d.ts.map +1 -1
- package/dist/src/utils/output-masking.js +2 -1
- package/dist/src/utils/output-masking.js.map +1 -1
- package/dist/src/utils/prompt-composition.d.ts +234 -0
- package/dist/src/utils/prompt-composition.d.ts.map +1 -0
- package/dist/src/utils/prompt-composition.js +379 -0
- package/dist/src/utils/prompt-composition.js.map +1 -0
- package/dist/src/utils/prompt-execution.d.ts +88 -0
- package/dist/src/utils/prompt-execution.d.ts.map +1 -0
- package/dist/src/utils/prompt-execution.js +227 -0
- package/dist/src/utils/prompt-execution.js.map +1 -0
- package/dist/src/utils/reflexion.d.ts +92 -0
- package/dist/src/utils/reflexion.d.ts.map +1 -0
- package/dist/src/utils/reflexion.js +1100 -0
- package/dist/src/utils/reflexion.js.map +1 -0
- package/dist/src/utils/research-integration.d.ts.map +1 -1
- package/dist/src/utils/research-integration.js +156 -100
- package/dist/src/utils/research-integration.js.map +1 -1
- package/dist/src/utils/research-questions.d.ts.map +1 -1
- package/dist/src/utils/research-questions.js +85 -24
- package/dist/src/utils/research-questions.js.map +1 -1
- package/dist/src/utils/rule-generation.d.ts.map +1 -1
- package/dist/src/utils/rule-generation.js +92 -108
- package/dist/src/utils/rule-generation.js.map +1 -1
- package/package.json +7 -1
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
[](https://nodejs.org/)
|
|
7
7
|
[](https://www.typescriptlang.org/)
|
|
8
8
|
|
|
9
|
-
A comprehensive Model Context Protocol (MCP) server
|
|
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
|
|
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
|
-
###
|
|
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
|
-
- **`
|
|
64
|
+
- **`analyze_content_security`** - Detect sensitive information patterns
|
|
61
65
|
|
|
62
|
-
###
|
|
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
|
-
- **`
|
|
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
|
-
- **`
|
|
71
|
-
- **`
|
|
72
|
-
- **`
|
|
73
|
-
- **`
|
|
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
|
-
###
|
|
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 &
|
|
84
|
-
- **`
|
|
85
|
-
- **`
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
-
|
|
130
|
-
- Options: `DEBUG`, `INFO`, `WARN`, `ERROR`
|
|
131
|
-
- Default: `INFO`
|
|
157
|
+
### Supported AI Models
|
|
132
158
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
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
|
-
|
|
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:
|
|
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
|
|
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
|
|
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
|
-
"
|
|
504
|
-
"
|
|
505
|
-
"
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
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"}
|