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.
- package/README.md +298 -123
- 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 +1821 -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 +9 -3
package/README.md
CHANGED
|
@@ -6,84 +6,25 @@
|
|
|
6
6
|
[](https://nodejs.org/)
|
|
7
7
|
[](https://www.typescriptlang.org/)
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
**
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
-
|
|
130
|
-
- Options: `DEBUG`, `INFO`, `WARN`, `ERROR`
|
|
131
|
-
- Default: `INFO`
|
|
88
|
+
### Supported AI Models
|
|
132
89
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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
|
-
|
|
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
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
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
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
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
|
-
|
|
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:
|
|
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:
|
|
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
|
|
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
|
-
"
|
|
504
|
-
"
|
|
505
|
-
"
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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"}
|