mcptesta/docs

MCPTesta Documentation

This directory contains the comprehensive documentation for MCPTesta, built with Astro and Starlight following the Diátaxis documentation framework.

Documentation Structure

The documentation is organized according to Diátaxis principles, with four distinct types of content serving different user needs:

📚 Diátaxis Organization

🎓 Tutorials (Learning-oriented)

"Can you teach me to...?"

Step-by-step lessons that take the reader by the hand through a series of steps to complete a project:

• Your First Test - Write and run your first MCPTesta test
• Testing Walkthrough - Explore MCPTesta's testing capabilities
• YAML Configuration - Master advanced configurations
• Parallel Testing - Optimize test execution performance

🔧 How-to Guides (Problem-oriented)

"How do I...?"

Practical guides that show how to solve specific problems:

• Test Production Servers - Safe production testing strategies
• CI/CD Integration - Automate testing in pipelines
• Troubleshooting - Diagnose and resolve issues

📖 Reference (Information-oriented)

"What are the options for...?"

Complete and accurate descriptions of the machinery:

• CLI Reference - Complete command-line interface documentation
• YAML Reference - Comprehensive configuration format specification
• API Reference - Full Python API documentation

💡 Explanation (Understanding-oriented)

"Why does this work this way?"

Discussions that clarify and illuminate how and why:

• MCP Protocol Testing - Understanding MCP protocol testing concepts
• Architecture - MCPTesta's design and architectural decisions
• Testing Strategies - Methodologies and approaches

Development

Prerequisites

• Node.js 18+
• npm or yarn

Local Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Content Structure

docs/
├── src/
│   ├── content/
│   │   └── docs/
│   │       ├── introduction.md
│   │       ├── installation.md
│   │       ├── tutorials/
│   │       ├── how-to/
│   │       ├── reference/
│   │       ├── explanation/
│   │       └── community/
│   ├── styles/
│   │   └── custom.css
│   └── assets/
├── astro.config.mjs
├── package.json
└── README.md

Writing Guidelines

Diátaxis Principles

When contributing to the documentation, ensure content follows Diátaxis principles:

Tutorials:

• Use "we" language and hands-on approach
• Provide reliable, tested step-by-step instructions
• Focus on learning, not teaching
• Build confidence through visible results
• Minimize explanation

How-to Guides:

• Start with the user's problem
• Provide a series of steps to solve it
• Focus on practical usability over completeness
• Handle real-world complexity
• Write from the user's perspective

Reference:

• Be neutral and authoritative
• Mirror the product's structure
• Avoid instruction or explanation
• Provide complete, accurate information
• Optimize for consultation

Explanation:

• Make connections between concepts
• Provide higher perspective
• Be readable "in the bath"
• Answer "Can you tell me about...?" questions
• Offer informed opinions and context

Content Guidelines

Clarity: Write for developers of all skill levels Completeness: Cover the full scope of each topic Currency: Keep examples and information up to date Consistency: Use consistent terminology and formatting Accessibility: Ensure content is accessible to all users

Code Examples

Working Examples: All code examples should be tested and functional Context: Provide sufficient context for examples to be understood Comments: Include helpful comments in complex examples Error Handling: Show both success and error scenarios

File Naming

Use kebab-case for all files:

• testing-walkthrough.md
• ci-cd-integration.md
• mcp-protocol.md

Contributing

Content Contributions

1. Identify the content type using Diátaxis principles
2. Check existing content to avoid duplication
3. Follow the appropriate style for the content type
4. Include working examples and test them
5. Submit a pull request with clear description

Documentation Issues

If you find issues with the documentation:

1. Check existing issues to avoid duplicates
2. Provide specific details about the problem
3. Suggest improvements when possible
4. Include context about your use case

Style and Formatting

Markdown: Use standard Markdown syntax Headers: Use sentence case for headers Links: Use descriptive link text Images: Include alt text for accessibility Code: Use syntax highlighting with language specification

Deployment

The documentation is automatically built and deployed on:

• Main branch: Production deployment
• Pull requests: Preview deployments for review

Manual Deployment

# Build the site
npm run build

# Deploy to hosting platform
# (specific commands depend on your hosting choice)

Technology Stack

Astro: Static site generator with excellent performance Starlight: Documentation theme optimized for technical content Diátaxis: Documentation methodology for user-centered organization

Why These Choices?

Astro: Fast, modern static site generation with excellent SEO and performance Starlight: Purpose-built for technical documentation with excellent navigation and search Diátaxis: Proven methodology that serves different user mental states effectively

Maintenance

Regular Updates

• Content Review: Quarterly review of all content for accuracy
• Link Checking: Automated checking for broken links
• Example Testing: Regular validation of code examples
• User Feedback: Incorporate feedback from the community

Analytics and Monitoring

• Usage Tracking: Monitor which content is most valuable
• Search Analytics: Understand what users are looking for
• Performance Monitoring: Ensure fast loading times
• User Feedback: Collect and respond to user input

Support

For documentation-specific questions:

• GitHub Issues: Report bugs or request new content
• GitHub Discussions: Ask questions about the documentation
• Pull Requests: Contribute improvements directly

For MCPTesta usage questions, see the main project documentation and support channels.

---

This documentation is built with ❤️ by the MCPTesta community following Diátaxis principles to serve all FastMCP developers effectively.