docs: add introductory paragraphs after all headings

Ensure every heading is followed by a paragraph before any code block,
list, table, or other content. Also add this as a documentation guideline
in CLAUDE.md.

Author: Kludex

CLAUDE.md

@@ -66,6 +66,11 @@ When making breaking changes, document them in `docs/migration.md`. Include:
 Search for related sections in the migration guide and group related changes together
 rather than adding new standalone sections.
 
+## Documentation
+
+- After a heading, always add an introductory paragraph before any code block, list, table, or
+  other content. Never go directly from a heading to non-paragraph content.
+
 ## Python Tools
 
 ## Code Formatting

docs/concepts.md

@@ -159,6 +159,8 @@ mcp = MCPServer("My App", lifespan=app_lifespan)
 
 ## Next steps
 
+Continue learning about MCP:
+
 - **[Quickstart](quickstart.md)** — build your first server
 - **[Testing](testing.md)** — test your server with the `Client` class
 - **[Authorization](authorization.md)** — securing your servers with OAuth 2.1

docs/index.md

@@ -11,6 +11,8 @@ This Python SDK implements the full MCP specification, making it easy to:
 
 ## Quick example
 
+A minimal MCP server with a single tool:
+
 ```python
 from mcp.server.mcpserver import MCPServer
 
@@ -31,12 +33,16 @@ uv run --with mcp server.py
 
 ## Getting started
 
+Follow these steps to start building with MCP:
+
 1. **[Install](installation.md)** the SDK
 2. **[Quickstart](quickstart.md)** — build your first MCP server
 3. **[Concepts](concepts.md)** — understand the protocol architecture and primitives
 
 ## Links
 
+Useful references for working with MCP:
+
 - [MCP specification](https://modelcontextprotocol.io)
 - [API Reference](api.md)
 - [Migration guide](migration.md) (v1 → v2)

docs/quickstart.md

@@ -50,6 +50,8 @@ if __name__ == "__main__":
 
 ## Run the server
 
+Start the server with uv:
+
 ```bash
 uv run --with mcp server.py
 ```
@@ -58,6 +60,8 @@ The server starts on `http://localhost:8000/mcp` using Streamable HTTP transport
 
 ## Connect a client
 
+You can connect to your running server using any MCP client:
+
 === "Claude Code"
 
     Add the server to [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp):
@@ -78,6 +82,8 @@ The server starts on `http://localhost:8000/mcp` using Streamable HTTP transport
 
 ## Next steps
 
+Now that you have a running server, explore these topics:
+
 - **[Concepts](concepts.md)** — understand the protocol architecture and primitives
 - **[Testing](testing.md)** — test your server with the `Client` class
 - **[API Reference](api.md)** — full API documentation