/**
* Markdown Documentation Formatter
* Converts documentation objects to well-formatted markdown files
*/
import type {
ToolDocumentation,
CategoryDocumentation,
TypeDocumentation,
DocumentationOutput,
ExampleUsage,
ParameterDocumentation,
} from "./DocumentationGenerator.js";
export class MarkdownFormatter {
/**
* Generate main API overview documentation
*/
generateApiOverview(output: DocumentationOutput): string {
const { tools, categories, summary } = output;
return `# WordPress MCP Server - API Documentation
${this.generateBadges()}
## Overview
The WordPress MCP Server provides **${summary.totalTools} tools** across **${
summary.totalCategories
} categories** for comprehensive WordPress management through the Model Context Protocol.
**Last Updated:** ${new Date(summary.lastUpdated).toLocaleDateString()}
**Version:** ${summary.version}
**Coverage:** ${summary.coverage.toolsWithExamples}/${summary.totalTools} tools with examples
## Quick Start
### Basic Usage
\`\`\`bash
# List all posts
wp_list_posts
# Get specific post
wp_get_post --id=123
# Create new post
wp_create_post --title="My Post" --content="Post content"
\`\`\`
### Multi-Site Usage
\`\`\`bash
# Target specific site
wp_list_posts --site=site1
# Use with different authentication
wp_get_site_settings --site=production
\`\`\`
## Tool Categories
${this.generateCategoriesTable(categories)}
## Available Tools
${this.generateToolsTable(tools)}
## Authentication
All tools support multiple authentication methods:
- **Application Passwords** (recommended)
- **JWT Authentication**
- **Basic Authentication** (development only)
- **API Key Authentication**
## Error Handling
Standard error response format:
\`\`\`json
{
"error": "Error type",
"message": "Human-readable error message",
"code": "ERROR_CODE",
"details": {
"endpoint": "/wp-json/wp/v2/posts",
"method": "GET"
}
}
\`\`\`
## Configuration
### Multi-Site Configuration
\`\`\`json
{
"sites": [
{
"id": "site1",
"name": "My WordPress Site",
"config": {
"WORDPRESS_SITE_URL": "https://example.com",
"WORDPRESS_USERNAME": "username",
"WORDPRESS_APP_PASSWORD": "app_password"
}
}
]
}
\`\`\`
## Response Formats
All tools return responses in this format:
\`\`\`json
{
"success": true,
"data": {
// Tool-specific response data
},
"metadata": {
"timestamp": "2024-01-01T00:00:00.000Z",
"site": "site1",
"tool": "wp_list_posts"
}
}
\`\`\`
## Performance Monitoring
The server includes comprehensive performance monitoring:
- Real-time metrics collection
- Historical performance analysis
- Industry benchmark comparisons
- Automated optimization recommendations
See [Performance Monitoring Guide](./performance/README.md) for details.
## Additional Resources
- [Tool Reference](./tools/README.md) - Detailed tool documentation
- [Type Definitions](./types/README.md) - TypeScript type definitions
- [Examples](./examples/README.md) - Usage examples and workflows
- [OpenAPI Specification](./openapi.json) - Machine-readable API spec
## Support
- **Documentation:** [GitHub Repository](https://github.com/docdyhr/mcp-wordpress)
- **Issues:** [GitHub Issues](https://github.com/docdyhr/mcp-wordpress/issues)
- **Discussions:** [GitHub Discussions](https://github.com/docdyhr/mcp-wordpress/discussions)
`;
}
/**
* Generate tool documentation
*/
generateToolDocumentation(tool: ToolDocumentation): string {
return `# ${tool.name}
${this.generateToolBadge(tool.category)}
${tool.description}
## Parameters
${this.generateParametersTable(tool.parameters)}
## Examples
${this.generateExamples(tool.examples)}
${tool.wordpressEndpoint ? this.generateWordPressMapping(tool.wordpressEndpoint) : ""}
${tool.requiredPermissions ? this.generatePermissions(tool.requiredPermissions) : ""}
## Response Format
**Return Type:** \`${tool.returnType}\`
${this.generateResponseExample(tool)}
## Error Handling
${this.generateErrorDocumentation(tool.errorCodes)}
${tool.relatedTools.length > 0 ? this.generateRelatedTools(tool.relatedTools) : ""}
---
*Generated automatically from tool definitions - Do not edit manually*
`;
}
/**
* Generate category documentation
*/
generateCategoryDocumentation(category: CategoryDocumentation): string {
return `# ${category.name} Tools
${category.description}
**Tool Count:** ${category.toolCount}
## Available Tools
${category.tools.map((tool) => `- [\`${tool}\`](./tools/${tool}.md)`).join("\n")}
## Common Usage Patterns
${category.usagePatterns.map((pattern) => `- ${pattern}`).join("\n")}
## Examples
### Basic ${category.name} Workflow
\`\`\`bash
# List all ${category.name.toLowerCase()}
wp_list_${category.name.toLowerCase()}
# Get specific item
wp_get_${category.name.toLowerCase().slice(0, -1)} --id=123
# Create new item
wp_create_${category.name.toLowerCase().slice(0, -1)} --title="Example"
\`\`\`
### Multi-Site ${category.name} Management
\`\`\`bash
# Work with specific site
wp_list_${category.name.toLowerCase()} --site=production
# Bulk operations
wp_list_${category.name.toLowerCase()} --site=staging --limit=50
\`\`\`
`;
}
/**
* Generate type documentation
*/
generateTypeDocumentation(type: TypeDocumentation): string {
return `# ${type.name}
${type.description}
${type.wordpressSource ? `**WordPress Source:** \`${type.wordpressSource}\`` : ""}
## Properties
${this.generateTypePropertiesTable(type.properties)}
## Example
\`\`\`json
${JSON.stringify(type.examples[0] || {}, null, 2)}
\`\`\`
${type.examples.length > 1 ? this.generateAdditionalExamples(type.examples.slice(1)) : ""}
`;
}
/**
* Generate parameters table
*/
private generateParametersTable(parameters: ParameterDocumentation[]): string {
if (parameters.length === 0) {
return "*No parameters required.*";
}
const headers = "| Parameter | Type | Required | Description | Default | Examples |";
const separator = "|-----------|------|----------|-------------|---------|----------|";
const rows = parameters.map((param) => {
const examples = param.examples
.slice(0, 2)
.map((ex) => `\`${ex}\``)
.join(", ");
const defaultVal = param.defaultValue !== undefined ? `\`${param.defaultValue}\`` : "-";
const required = param.required ? "✅" : "❌";
return `| \`${param.name}\` | \`${param.type}\` | ${required} | ${param.description} | ${defaultVal} | ${
examples || "-"
} |`;
});
return [headers, separator, ...rows].join("\n");
}
/**
* Generate examples section
*/
private generateExamples(examples: ExampleUsage[]): string {
if (examples.length === 0) {
return "*No examples available.*";
}
return examples
.map(
(example) => `### ${example.title}
${example.description}
**Command:**
\`\`\`bash
${example.command} ${this.formatParameters(example.parameters)}
\`\`\`
**Response:**
\`\`\`json
${JSON.stringify(example.expectedResponse, null, 2)}
\`\`\`
${example.errorExample ? this.generateErrorExample(example.errorExample) : ""}
`,
)
.join("\n\n");
}
/**
* Generate error example
*/
private generateErrorExample(errorExample: { scenario: string; error: unknown }): string {
return `**Error Example (${errorExample.scenario}):**
\`\`\`json
${JSON.stringify(errorExample.error, null, 2)}
\`\`\``;
}
/**
* Generate WordPress mapping section
*/
private generateWordPressMapping(endpoint: string): string {
return `## WordPress REST API Mapping
**Endpoint:** \`${endpoint}\`
This tool directly interfaces with the WordPress REST API endpoint above. The response format and available parameters are determined by WordPress core functionality.
### WordPress Documentation
- [WordPress REST API Handbook](https://developer.wordpress.org/rest-api/)
- [Endpoint Reference](https://developer.wordpress.org/rest-api/reference/)
`;
}
/**
* Generate permissions section
*/
private generatePermissions(permissions: string[]): string {
return `## Required Permissions
This tool requires the following WordPress user capabilities:
${permissions.map((perm) => `- \`${perm}\``).join("\n")}
**Note:** The authenticated user must have these capabilities to successfully execute this tool.
`;
}
/**
* Generate response example
*/
private generateResponseExample(tool: ToolDocumentation): string {
return `\`\`\`json
{
"success": true,
"data": {
// ${tool.returnType} response data
},
"metadata": {
"timestamp": "2024-01-01T00:00:00.000Z",
"tool": "${tool.name}",
"site": "site1"
}
}
\`\`\``;
}
/**
* Generate error documentation
*/
private generateErrorDocumentation(errorCodes: unknown[]): string {
if (errorCodes.length === 0) {
return `### Common Errors
- **Authentication Error**: Invalid credentials or insufficient permissions
- **Validation Error**: Invalid or missing required parameters
- **Not Found Error**: Requested resource does not exist
- **Server Error**: Internal WordPress or network error
See [Error Handling Guide](../error-handling.md) for complete error reference.`;
}
return errorCodes
.map(
(error) => `### ${(error as Record<string, unknown>).code}
**Message:** ${(error as Record<string, unknown>).message}
**Description:** ${(error as Record<string, unknown>).description}
**Resolution:** ${(error as Record<string, unknown>).resolution}
`,
)
.join("\n\n");
}
/**
* Generate related tools section
*/
private generateRelatedTools(relatedTools: string[]): string {
return `## Related Tools
${relatedTools.map((tool) => `- [\`${tool}\`](./${tool}.md)`).join("\n")}
`;
}
/**
* Generate categories table
*/
private generateCategoriesTable(categories: CategoryDocumentation[]): string {
const headers = "| Category | Tools | Description |";
const separator = "|----------|-------|-------------|";
const rows = categories.map(
(cat) => `| [${cat.name}](./categories/${cat.name.toLowerCase()}.md) | ${cat.toolCount} | ${cat.description} |`,
);
return [headers, separator, ...rows].join("\n");
}
/**
* Generate tools table
*/
private generateToolsTable(tools: ToolDocumentation[]): string {
const headers = "| Tool | Category | Description |";
const separator = "|------|----------|-------------|";
const rows = tools.map(
(tool) => `| [\`${tool.name}\`](./tools/${tool.name}.md) | ${tool.category} | ${tool.description} |`,
);
return [headers, separator, ...rows].join("\n");
}
/**
* Generate type properties table
*/
private generateTypePropertiesTable(properties: unknown[]): string {
const headers = "| Property | Type | Required | Description |";
const separator = "|----------|------|----------|-------------|";
const rows = properties.map((prop) => {
const propObj = prop as Record<string, unknown>;
const required = propObj.required ? "✅" : "❌";
return `| \`${propObj.name}\` | \`${propObj.type}\` | ${required} | ${propObj.description} |`;
});
return [headers, separator, ...rows].join("\n");
}
/**
* Generate badges for overview
*/
private generateBadges(): string {
return `
`;
}
/**
* Generate tool category badge
*/
private generateToolBadge(category: string): string {
const colors = {
posts: "blue",
pages: "green",
media: "purple",
users: "orange",
comments: "red",
taxonomies: "yellow",
site: "lightblue",
auth: "darkblue",
cache: "grey",
performance: "brightgreen",
};
const color = colors[category.toLowerCase() as keyof typeof colors] || "lightgrey";
return ``;
}
/**
* Format parameters for command examples
*/
private formatParameters(params: Record<string, unknown>): string {
return Object.entries(params)
.map(([key, value]) => `--${key}="${value}"`)
.join(" ");
}
/**
* Generate additional examples
*/
private generateAdditionalExamples(examples: unknown[]): string {
return `## Additional Examples
${examples
.map(
(example, index) => `### Example ${index + 2}
\`\`\`json
${JSON.stringify(example, null, 2)}
\`\`\`
`,
)
.join("\n")}`;
}
}
