From 530c5e096785370cfcf38a74fc7078b7a950d713 Mon Sep 17 00:00:00 2001 From: Marcelo Trylesinski Date: Fri, 3 Oct 2025 14:14:05 +0100 Subject: [PATCH] Add documentation structure --- docs/authorization.md | 5 ++++ docs/concepts.md | 13 +++++++++ docs/index.md | 58 +++++++++++++++++++++++++++++++++++++--- docs/installation.md | 31 +++++++++++++++++++++ docs/low-level-server.md | 5 ++++ mkdocs.yml | 7 ++++- 6 files changed, 115 insertions(+), 4 deletions(-) create mode 100644 docs/authorization.md create mode 100644 docs/concepts.md create mode 100644 docs/installation.md create mode 100644 docs/low-level-server.md diff --git a/docs/authorization.md b/docs/authorization.md new file mode 100644 index 000000000..4b6208bdf --- /dev/null +++ b/docs/authorization.md @@ -0,0 +1,5 @@ +# Authorization + +!!! warning "Under Construction" + + This page is currently being written. Check back soon for complete documentation. diff --git a/docs/concepts.md b/docs/concepts.md new file mode 100644 index 000000000..a2d6eb8d3 --- /dev/null +++ b/docs/concepts.md @@ -0,0 +1,13 @@ +# Concepts + +!!! warning "Under Construction" + + This page is currently being written. Check back soon for complete documentation. + + diff --git a/docs/index.md b/docs/index.md index 42ad9ca0c..139afca4a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,57 @@ -# MCP Server +# MCP Python SDK -This is the MCP Server implementation in Python. +The **Model Context Protocol (MCP)** allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. -It only contains the [API Reference](api.md) for the time being. +This Python SDK implements the full MCP specification, making it easy to: + +- **Build MCP servers** that expose resources, prompts, and tools +- **Create MCP clients** that can connect to any MCP server +- **Use standard transports** like stdio, SSE, and Streamable HTTP + +If you want to read more about the specification, please visit the [MCP documentation](https://modelcontextprotocol.io). + +## Quick Example + +Here's a simple MCP server that exposes a tool, resource, and prompt: + +```python title="server.py" +from mcp.server.fastmcp import FastMCP + +mcp = FastMCP("Test Server") + + +@mcp.tool() +def add(a: int, b: int) -> int: + """Add two numbers""" + return a + b + + +@mcp.resource("greeting://{name}") +def get_greeting(name: str) -> str: + """Get a personalized greeting""" + return f"Hello, {name}!" + + +@mcp.prompt() +def greet_user(name: str, style: str = "friendly") -> str: + """Generate a greeting prompt""" + return f"Write a {style} greeting for someone named {name}." +``` + +Test it with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector): + +```bash +uv run mcp dev server.py +``` + +## Getting Started + + +1. **[Install](installation.md)** the MCP SDK +2. **[Learn concepts](concepts.md)** - understand the three primitives and architecture +3. **[Explore authorization](authorization.md)** - add security to your servers +4. **[Use low-level APIs](low-level-server.md)** - for advanced customization + +## API Reference + +Full API documentation is available in the [API Reference](api.md). diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 000000000..6e20706a8 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,31 @@ +# Installation + +The Python SDK is available on PyPI as [`mcp`](https://pypi.org/project/mcp/) so installation is as simple as: + +=== "pip" + + ```bash + pip install mcp + ``` +=== "uv" + + ```bash + uv add mcp + ``` + +The following dependencies are automatically installed: + +- [`httpx`](https://pypi.org/project/httpx/): HTTP client to handle HTTP Streamable and SSE transports. +- [`httpx-sse`](https://pypi.org/project/httpx-sse/): HTTP client to handle SSE transport. +- [`pydantic`](https://pypi.org/project/pydantic/): Types, JSON schema generation, data validation, and [more](https://docs.pydantic.dev/latest/). +- [`starlette`](https://pypi.org/project/starlette/): Web framework used to build the HTTP transport endpoints. +- [`python-multipart`](https://pypi.org/project/python-multipart/): Handle HTTP body parsing. +- [`sse-starlette`](https://pypi.org/project/sse-starlette/): Server-Sent Events for Starlette, used to build the SSE transport endpoint. +- [`pydantic-settings`](https://pypi.org/project/pydantic-settings/): Settings management used in FastMCP. +- [`uvicorn`](https://pypi.org/project/uvicorn/): ASGI server used to run the HTTP transport endpoints. +- [`jsonschema`](https://pypi.org/project/jsonschema/): JSON schema validation. +- [`pywin32`](https://pypi.org/project/pywin32/): Windows specific dependencies for the CLI tools. + +This package has the following optional groups: + +- `cli`: Installs `typer` and `python-dotenv` for the MCP CLI tools. diff --git a/docs/low-level-server.md b/docs/low-level-server.md new file mode 100644 index 000000000..a5b4f3df3 --- /dev/null +++ b/docs/low-level-server.md @@ -0,0 +1,5 @@ +# Low-Level Server + +!!! warning "Under Construction" + + This page is currently being written. Check back soon for complete documentation. diff --git a/mkdocs.yml b/mkdocs.yml index b907cb873..cf583c9b3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,7 +11,12 @@ site_url: https://modelcontextprotocol.github.io/python-sdk # copyright: © Model Context Protocol 2025 to present nav: - - Home: index.md + - Introduction: index.md + - Installation: installation.md + - Documentation: + - Concepts: concepts.md + - Low-Level Server: low-level-server.md + - Authorization: authorization.md - API Reference: api.md theme: