Ryan Malloy
bea4a2e5d3
Community-driven testing excellence for the MCP ecosystem MCPTesta is a comprehensive testing framework for FastMCP servers that brings scientific rigor and enterprise-grade capabilities to MCP protocol testing. 🎯 Core Features: • Comprehensive FastMCP server testing with advanced protocol support • Parallel execution with intelligent dependency resolution • Flexible CLI and YAML configuration system • Rich reporting: console, HTML, JSON, and JUnit formats • Advanced MCP protocol features: notifications, cancellation, progress tracking • Production-ready Docker environment with caddy-docker-proxy integration 🧪 Advanced Testing Capabilities: • Multi-transport support (stdio, SSE, WebSocket) • Authentication testing (Bearer tokens, OAuth flows) • Stress testing and performance validation • Memory profiling and leak detection • CI/CD integration with comprehensive reporting 🎨 Professional Assets: • Complete logo package with lab experiment theme • Comprehensive documentation with Diátaxis framework • Community-focused branding and messaging • Multi-platform favicon and social media assets 📚 Documentation: • Getting started tutorials and comprehensive guides • Complete CLI and YAML reference documentation • Architecture explanations and testing strategies • Team collaboration and security compliance guides 🚀 Ready for: • Community contributions and external development • Enterprise deployment and production use • Integration with existing FastMCP workflows • Extension and customization for specific needs Built with modern Python practices using uv, FastMCP, and Starlight documentation. Designed for developers who demand scientific precision in their testing tools. Repository: https://git.supported.systems/mcp/mcptesta Documentation: https://mcptesta.l.supported.systems
233 lines
7.2 KiB
Markdown
233 lines
7.2 KiB
Markdown
# MCPTesta Documentation
|
|
|
|
This directory contains the comprehensive documentation for MCPTesta, built with [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/) following the [Diátaxis](https://diataxis.fr/) 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](/tutorials/first-test/)** - Write and run your first MCPTesta test
|
|
- **[Testing Walkthrough](/tutorials/testing-walkthrough/)** - Explore MCPTesta's testing capabilities
|
|
- **[YAML Configuration](/tutorials/yaml-configuration/)** - Master advanced configurations
|
|
- **[Parallel Testing](/tutorials/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](/how-to/test-production-servers/)** - Safe production testing strategies
|
|
- **[CI/CD Integration](/how-to/ci-cd-integration/)** - Automate testing in pipelines
|
|
- **[Troubleshooting](/how-to/troubleshooting/)** - Diagnose and resolve issues
|
|
|
|
#### 📖 Reference (Information-oriented)
|
|
*"What are the options for...?"*
|
|
|
|
Complete and accurate descriptions of the machinery:
|
|
|
|
- **[CLI Reference](/reference/cli/)** - Complete command-line interface documentation
|
|
- **[YAML Reference](/reference/yaml/)** - Comprehensive configuration format specification
|
|
- **[API Reference](/reference/api/)** - Full Python API documentation
|
|
|
|
#### 💡 Explanation (Understanding-oriented)
|
|
*"Why does this work this way?"*
|
|
|
|
Discussions that clarify and illuminate how and why:
|
|
|
|
- **[MCP Protocol Testing](/explanation/mcp-protocol/)** - Understanding MCP protocol testing concepts
|
|
- **[Architecture](/explanation/architecture/)** - MCPTesta's design and architectural decisions
|
|
- **[Testing Strategies](/explanation/testing-strategies/)** - Methodologies and approaches
|
|
|
|
## Development
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 18+
|
|
- npm or yarn
|
|
|
|
### Local Development
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Build the site
|
|
npm run build
|
|
|
|
# Deploy to hosting platform
|
|
# (specific commands depend on your hosting choice)
|
|
```
|
|
|
|
## Technology Stack
|
|
|
|
**[Astro](https://astro.build/)**: Static site generator with excellent performance
|
|
**[Starlight](https://starlight.astro.build/)**: Documentation theme optimized for technical content
|
|
**[Diátaxis](https://diataxis.fr/)**: 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.* |