Documentation Standards

This guide outlines the documentation requirements and standards for IoWarp MCP servers.

README Requirements

Each MCP server must include a comprehensive README.md file in its root directory.

Required Sections

1. Server Name and Description

   • Clear, concise description of the server's purpose
   • Key features and capabilities

2. Installation

   • Prerequisites (Python version, dependencies)
   • Installation instructions using uv
   • Any environment-specific setup requirements

3. Configuration

   • Required environment variables
   • Optional configuration parameters
   • Example configuration snippets

4. Available Tools

   • List of all tools provided by the server
   • Description of each tool's purpose
   • Input parameters and expected outputs
   • Usage examples

5. Usage Examples

   • Basic usage scenarios
   • Common workflows
   • Code snippets demonstrating tool usage

6. Testing

   • How to run tests
   • Test coverage information
   • Manual testing procedures

7. Development Status

   • Current development phase
   • Known limitations or issues
   • Future planned features

Code Documentation

Docstring Standards

Follow Google-style docstrings for all functions and classes:

def process_data(data: List[Dict], format_type: str = "json") -> str:
    """Process data and return formatted output.
    
    Args:
        data: List of dictionaries containing raw data
        format_type: Output format ("json", "csv", "xml")
        
    Returns:
        Formatted string representation of the data
        
    Raises:
        ValueError: If format_type is not supported
        TypeError: If data is not properly structured
    """

Type Hints

• Use type hints for all function parameters and return values
• Import types from typing module when needed
• Use Optional for nullable parameters

Comments

• Add inline comments for complex logic
• Explain non-obvious implementation decisions
• Document any workarounds or known issues

API Documentation

Tool Descriptions

Each tool must have:

• Clear, descriptive name
• Comprehensive description explaining its purpose
• Complete parameter documentation with types and constraints
• Return value documentation with examples

Schema Documentation

• Use JSON Schema for input validation
• Document all schema properties
• Include examples for complex schemas
• Specify required vs optional fields

Error Documentation

Error Messages

• Use clear, actionable error messages
• Include context about what went wrong
• Suggest potential solutions when possible
• Avoid technical jargon in user-facing messages

Error Handling

Document:

• Expected error conditions
• How errors are handled and reported
• Recovery strategies
• Logging behavior during errors

Version Documentation

Changelog

Maintain a CHANGELOG.md file with:

• Version numbers following semantic versioning
• Clear description of changes in each version
• Breaking changes highlighted prominently
• Migration guides for major version updates

Version Compatibility

Document:

• Minimum supported Python version
• Compatible MCP protocol versions
• Dependency version requirements
• Platform compatibility notes

Examples and Tutorials

Code Examples

• Provide working, tested examples
• Include complete context (imports, setup)
• Show both success and error cases
• Use realistic data in examples

Integration Examples

• Show how to integrate with Claude Desktop
• Provide configuration file examples
• Include troubleshooting common integration issues

Documentation Maintenance

Review Process

• Documentation updates required for all code changes
• Review documentation for accuracy during PR reviews
• Regular audits to ensure documentation stays current

Style Guidelines

• Use consistent formatting and terminology
• Write in clear, concise language
• Use active voice when possible
• Include visual aids (diagrams, screenshots) when helpful

Accessibility

• Use descriptive link text
• Provide alt text for images
• Ensure proper heading hierarchy
• Test with screen readers when possible