Skip to main content

LLM-MCP Documentation Standards

This document defines the standards and guidelines for all LLM-MCP documentation. Following these standards ensures consistency, clarity, and usability across the documentation.

Table of Contents​

Document Structure​

Standard Document Structure​

Every document should follow this structure:

  1. Title (H1): Clear, descriptive title using a single # heading
  2. Overview: Brief introduction to the topic (1-3 paragraphs)
  3. Table of Contents: For documents longer than 3 sections
  4. Main Content: Organized with appropriate headings
  5. Examples: Practical examples where applicable
  6. Related Resources: Links to related documentation
  7. See Also: Cross-references to related topics

Heading Hierarchy​

Use heading levels consistently:

  • H1 (#): Document title (only one per document)
  • H2 (##): Major sections
  • H3 (###): Subsections
  • H4 (####): Sub-subsections
  • H5 (#####): Avoid if possible, but use for deep nesting if needed

Formatting Guidelines​

Markdown Elements​

Use these Markdown elements consistently:

Lists​

  • Use unordered lists (-) for items without sequence
  • Use ordered lists (1.) for sequential steps
  • Maintain consistent indentation for nested lists
- First-level item
  - Second-level item
    - Third-level item

Code Blocks​

  • Always specify the language for syntax highlighting
  • Use triple backticks (```) for code blocks
  • Use single backticks (`) for inline code
```typescript
// TypeScript code example
function example(): string {
  return "This is a code example";
}

#### Tables

- Use tables for structured data
- Align columns for better readability
- Include header row with column names

```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Value 1  | Value 2  | Value 3  |
| Value 4  | Value 5  | Value 6  |

Blockquotes​

  • Use blockquotes for important notes, warnings, or tips
  • Prefix with appropriate label (Note, Warning, Tip)
> **Note:** This is an important note to remember.

> **Warning:** This action cannot be undone.

> **Tip:** Here's a helpful tip to make things easier.

File Naming Conventions​

  • Use kebab-case for file names (e.g., getting-started.md)
  • Keep file names short but descriptive
  • Avoid special characters and spaces

Writing Style​

General Guidelines​

  • Write in clear, concise language
  • Use active voice rather than passive voice
  • Keep sentences and paragraphs short
  • Target a technical audience but avoid unnecessary jargon
  • Define acronyms on first use

Tone​

  • Professional but approachable
  • Instructional and helpful
  • Confident but not authoritative
  • Neutral and objective

Grammar and Spelling​

  • Use US English spelling
  • Check for spelling and grammar errors
  • Maintain consistent tense (preferably present tense)
  • Use Oxford commas in lists

Code Examples​

Code Style​

  • Follow project coding standards
  • Include comments for complex sections
  • Use meaningful variable and function names
  • Format code consistently

Code Example Structure​

### Example: [Brief Description]

This example demonstrates [what the example does].

```typescript
// Complete code example with comments
import [McpClient] from '@llm-mcp/client';

// Initialize client
const client = new McpClient({
  url: 'http://localhost:3001',
  apiKey: 'your-api-key'
});

// Execute a tool
async function executeTool() {
  const result = await client.executeTool('example-tool', {
    param1: 'value1',
    param2: 'value2'
  });
  
  console.log('Tool execution result:', result);
}

Key points about this example:

  • Uses the McpClient to connect to LLM-MCP
  • Executes a tool with parameters
  • Handles the result

## Diagrams

### Mermaid.js Diagrams

Use Mermaid.js for diagrams when possible:

```markdown
```mermaid
graph TD;
  A[Client] -->|API Request| B(LLM-MCP Server);
  B --> C[Tool Registry];
  C -->|Lookup| D[Tool A];
  C -->|Lookup| E[Tool B];
  B -->|Execute| D;
  D -->|Return| B;
  B -->|Response| A;

### Diagram Guidelines

- Keep diagrams simple and focused
- Include a title and description
- Use consistent styling across diagrams
- Provide text explanation alongside diagrams

## Links and Cross-References

### Internal Links

Link to other documentation files using relative paths:

```markdown
For more information, see the [Getting Started Guide](guides/getting-started.md).

Include descriptive link text for external resources:

For more details, see the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0).

Use anchor links for sections within the same document:

See the [Code Examples](#code-examples) section for more details.

Images​

Image Guidelines​

  • Use images sparingly and only when they add value
  • Optimize images for web viewing
  • Include alt text for accessibility
  • Keep file sizes small (< 100KB where possible)

Image Formatting​

![Alt text describing the image](../assets/images/example-diagram.png)

*Caption: Brief description of the image*

Document Templates​

Guide Template​

# Guide Title

Brief overview of what this guide covers and who it's for.

## Table of Contents

- [Prerequisites](#prerequisites)
- [Section 1](#section-1)
- [Section 2](#section-2)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)
- [See Also](#see-also)

## Prerequisites

What the reader needs before starting:
- Requirement 1
- Requirement 2

## Section 1

Content for section 1...

## Section 2

Content for section 2...

## Examples

Practical examples...

## Troubleshooting

Common issues and solutions...

## See Also

- [Related Guide 1](path/to/related-guide-1.md)
- [Related Guide 2](path/to/related-guide-2.md)

Reference Template​

# Reference Title

Brief overview of this reference documentation.

## Table of Contents

- [Overview](#overview)
- [Reference Section 1](#reference-section-1)
- [Reference Section 2](#reference-section-2)
- [Examples](#examples)
- [See Also](#see-also)

## Overview

Detailed overview of the reference material...

## Reference Section 1

Reference content...

## Reference Section 2

Reference content...

## Examples

Example usage...

## See Also

- [Related Reference 1](path/to/related-reference-1.md)
- [Related Reference 2](path/to/related-reference-2.md)

API Documentation Template​

# API Endpoint Name

Brief description of the endpoint and its purpose.

## Endpoint

`METHOD /path/to/endpoint`

## Description

Detailed description of what this endpoint does and when to use it.

## Request

### Headers

| Header | Description | Required |
|--------|-------------|----------|
| `Authorization` | API key or token | Yes |
| `Content-Type` | Must be `application/json` | Yes |

### Parameters

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| `param1` | string | Description of param1 | Yes |
| `param2` | number | Description of param2 | No |

### Request Body

```json
{
  "field1": "value1",
  "field2": 123,
  "field3": {
    "nestedField": "value"
  }
}

Response​

Success Response​

Status Code: 200 OK

{
  "id": "example-id",
  "status": "success",
  "data": {
    "field1": "value1",
    "field2": 123
  }
}

Error Responses​

Status Code: 400 Bad Request

{
  "error": "InvalidParameters",
  "message": "Invalid value for param1",
  "details": {
    "field": "param1",
    "issue": "Must be a string"
  }
}

Status Code: 401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Examples​

Example Request​

curl -X POST "https://api.example.com/v1/endpoint" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "field1": "example",
    "field2": 123
  }'

Example Response​

{
  "id": "example-id",
  "status": "success",
  "data": {
    "field1": "example",
    "field2": 123
  }
}

See Also​


---

By following these standards, we ensure a consistent and high-quality documentation experience for all LLM-MCP users.