# 📚 Documentation Navigation - Diataxis Framework
**Find exactly what you need based on your current goal.**
## 🏗️ Documentation Architecture
```mermaid
graph TB
subgraph "User Intent"
Learn[🎓 I want to LEARN]
Solve[🛠️ I want to SOLVE]
Lookup[📖 I want to LOOK UP]
Understand[💡 I want to UNDERSTAND]
end
subgraph "Documentation Sections"
Learn --> Tutorials[Tutorials<br/>Step-by-step learning]
Solve --> HowTo[How-To Guides<br/>Problem solving]
Lookup --> Reference[Reference<br/>Technical details]
Understand --> Explanation[Explanation<br/>Deep concepts]
end
subgraph "Content Types"
Tutorials --> T1[Getting Started]
Tutorials --> T2[Advanced Techniques]
HowTo --> H1[Troubleshooting]
HowTo --> H2[Workflows]
Reference --> R1[API Reference]
Reference --> R2[Configuration]
Explanation --> E1[Architecture]
Explanation --> E2[Design Philosophy]
end
```
---
## 🎯 What do you want to do right now?
### 🎓 **I want to LEARN** → [Tutorials](#tutorials)
_"Teach me how to use this step-by-step"_
**When to use**: You're new to MCP or architectural decision records, want to understand concepts through hands-on practice.
### 🛠️ **I want to SOLVE** → [How-To Guides](#how-to-guides)
_"Help me fix this specific problem"_
**When to use**: You have a specific issue, error, or task you need to accomplish right now.
### 📖 **I want to LOOK UP** → [Reference](#reference)
_"What are the exact parameters for this tool?"_
**When to use**: You know what tool you want to use but need exact syntax, parameters, or options.
### 💡 **I want to UNDERSTAND** → [Explanation](#explanation)
_"Why does this work this way?"_
**When to use**: You want to understand the deeper concepts, design decisions, and architectural principles.
---
## 🎓 Tutorials
_Learning-oriented • Step-by-step • Safe to experiment_
Start here if you're new to MCP ADR Analysis or want to build your skills systematically.
### **Getting Started Series**
- **[Your First MCP Analysis](./tutorials/01-first-steps.md)** ⭐
- _30 minutes • Beginner_
- Install server, run first analysis, create your first ADR
- **[Working with Existing Projects](./tutorials/02-existing-projects.md)**
- _45 minutes • Beginner_
- Analyze codebases with existing architecture, discover implicit decisions
- **[Advanced Analysis Techniques](./tutorials/03-advanced-analysis.md)**
- _60 minutes • Intermediate_
- Security scanning, deployment readiness, performance analysis
### **Specialized Learning Paths**
- **[Security-First Architecture](./tutorials/security-focused-workflow.md)**
- _90 minutes • Intermediate_
- End-to-end security analysis and ADR generation workflow
- **[Team Collaboration Workflows](./tutorials/team-collaboration.md)**
- _60 minutes • Advanced_
- Multi-developer ADR processes, review workflows, knowledge sharing
**👨🎓 New to architectural decision records?** Start with [Your First MCP Analysis](./tutorials/01-first-steps.md)
---
## 🛠️ How-To Guides
_Problem-solving • Goal-oriented • Real scenarios_
Use these when you need to solve a specific problem or accomplish a particular task.
### **Common Problems**
- **[Troubleshoot Common Issues](./how-to-guides/troubleshooting.md)** 🆘
- Fix installation problems, resolve errors, diagnose issues
- **[Handle Security Concerns](./how-to-guides/security-analysis.md)**
- Detect sensitive content, configure masking, secure deployments
- **[Prepare for Deployment](./how-to-guides/deployment-readiness.md)**
- Validate production readiness, run final checks, create deployment plans
### **Workflow Solutions**
- **[Migrate from Manual ADRs](./how-to-guides/migrate-existing-adrs.md)**
- Convert existing documentation, preserve history, establish new processes
- **[Integrate with CI/CD](./how-to-guides/cicd-integration.md)**
- Automate ADR validation, enforce architectural rules, track compliance
- **[Scale for Large Teams](./how-to-guides/large-team-scaling.md)**
- Multi-repository setups, federated decision tracking, governance workflows
### **Specific Tasks**
- **[Generate ADRs from Requirements](./how-to-guides/prd-to-adrs.md)**
- Convert PRD documents, structure decisions, maintain traceability
- **[Track Implementation Progress](./how-to-guides/progress-tracking.md)**
- Monitor ADR implementation, identify blockers, report status
- **[Create Custom Rules](./how-to-guides/custom-rules.md)**
- Define architectural constraints, validate compliance, enforce standards
- **[Setup Firecrawl Integration](./how-to-guides/firecrawl-setup.md)** 🔥
- Enable web research capabilities for enhanced analysis
- **[MCP Client Compatibility](./how-to-guides/mcp-client-compatibility.md)** 🔌
- Configure server for Claude Desktop, Cline, Cursor, Gemini, and more
**🚨 Having an issue right now?** Check [Troubleshooting](./how-to-guides/troubleshooting.md) first.
---
## 📖 Reference
_Information-oriented • Systematic • Comprehensive_
Complete documentation for when you need exact details about tools, parameters, and APIs.
### **Complete API Documentation**
- **[Complete API Reference](./reference/api-reference.md)** 📋
- All 37 tools with parameters, examples, and usage patterns
- Quick navigation and search functionality
- Common usage patterns and workflows
### **Tool Categories**
- **[Analysis Tools](./reference/analysis-tools.md)**
- Project analysis, context extraction, ecosystem understanding
- **[Generation Tools](./reference/generation-tools.md)**
- ADR creation, TODO generation, documentation synthesis
- **[Security Tools](./reference/security-tools.md)**
- Content scanning, masking, credential detection
- **[Validation Tools](./reference/validation-tools.md)**
- Progress tracking, rule validation, deployment readiness
### **Configuration Reference**
- **[Environment Variables](./reference/environment-config.md)**
- All configuration options, default values, environment setup
- **[MCP Client Configuration](./reference/mcp-client-config.md)**
- Claude Desktop, Cursor, other MCP clients setup
### **Schemas and Formats**
- **[ADR Templates](./reference/adr-templates.md)**
- Standard formats, MADR templates, Y-statements
- **[JSON Schemas](./reference/json-schemas.md)**
- Tool parameters, response formats, data structures
**🔍 Looking for a specific tool?** Use the [API Reference](./reference/api-reference.md) search.
---
## 💡 Explanation
_Understanding-oriented • Conceptual • Background_
Deep-dive into concepts, design decisions, and the "why" behind the architecture.
### **Core Concepts**
- **[Understanding MCP](./explanation/mcp-concepts.md)** 🧠
- What is Model Context Protocol, how it works, why it matters
- **[Architectural Decision Records](./explanation/adr-philosophy.md)**
- ADR principles, best practices, decision-making frameworks
- **[AI-Assisted Architecture](./explanation/ai-architecture-concepts.md)**
- How AI enhances architectural analysis, human-AI collaboration
### **Design Decisions**
- **[Server Architecture](./explanation/server-architecture.md)**
- Why we chose this design, tradeoffs, alternative approaches
- **[Tool Design Philosophy](./explanation/tool-design.md)**
- Principles behind tool organization, naming, parameter design
- **[Security Model](./explanation/security-philosophy.md)**
- Threat model, protection strategies, privacy considerations
### **Advanced Topics**
- **[Knowledge Graph Architecture](./explanation/knowledge-graph.md)**
- How we build and maintain project understanding over time
- **[Prompt Engineering Techniques](./explanation/prompt-engineering.md)**
- APE, Knowledge Generation, Reflexion frameworks explained
- **[Performance and Scalability](./explanation/performance-design.md)**
- How the server handles large projects, optimization strategies
**🤔 Want to understand the bigger picture?** Start with [Understanding MCP](./explanation/mcp-concepts.md).
---
## 🧭 Quick Navigation
### **By Experience Level**
- **New to MCP**: [First Steps Tutorial](./tutorials/01-first-steps.md) → [MCP Concepts](./explanation/mcp-concepts.md)
- **New to ADRs**: [ADR Philosophy](./explanation/adr-philosophy.md) → [Generate Your First ADR](./tutorials/01-first-steps.md)
- **Experienced User**: [API Reference](./reference/api-reference.md) → [Advanced Techniques](./tutorials/03-advanced-analysis.md)
### **By Use Case**
- **Personal Projects**: [First Steps](./tutorials/01-first-steps.md) → [Existing Projects](./tutorials/02-existing-projects.md)
- **Team Projects**: [Team Collaboration](./tutorials/team-collaboration.md) → [Large Team Scaling](./how-to-guides/large-team-scaling.md)
- **Enterprise**: [Security Workflow](./tutorials/security-focused-workflow.md) → [CI/CD Integration](./how-to-guides/cicd-integration.md)
### **By Problem Type**
- **Installation/Setup**: [Troubleshooting](./how-to-guides/troubleshooting.md)
- **Security Concerns**: [Security Analysis](./how-to-guides/security-analysis.md)
- **Performance Issues**: [Performance Design](./explanation/performance-design.md)
- **Integration Questions**: [CI/CD Integration](./how-to-guides/cicd-integration.md)
---
## 📊 Documentation Quality Metrics
This documentation follows the [Diataxis framework](https://diataxis.fr/) for maximum usability:
- **✅ Tutorials**: Learn by doing with safe, guided practice
- **✅ How-To Guides**: Solve real problems with proven solutions
- **✅ Reference**: Look up exact information quickly and reliably
- **✅ Explanation**: Understand concepts and design decisions deeply
### Quick Feedback
Found what you needed? Missing something important?
**[Improve this documentation](https://github.com/tosin2013/mcp-adr-analysis-server/issues)**
---
_Can't find what you need? [Search the complete API reference](./reference/api-reference.md) or [file an issue](https://github.com/tosin2013/mcp-adr-analysis-server/issues) to help us improve the documentation._