Add mkdocs

.github/workflows/publish-pypi.yml

@@ -53,3 +53,28 @@ jobs:
 
     - name: Publish package distributions to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
+
+  docs-publish:
+    runs-on: ubuntu-latest
+    needs: ["pypi-publish"]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: uv sync --frozen --group docs
+      - run: uv run --no-sync mkdocs gh-deploy --force

docs/api.md

@@ -0,0 +1 @@
+::: mcp

docs/index.md

@@ -0,0 +1,5 @@
+# MCP Server
+
+This is the MCP Server implementation in Python.
+
+It only contains the [API Reference](api.md) for the time being.

mkdocs.yml

@@ -0,0 +1,119 @@
+site_name: MCP Server
+site_description: MCP Server
+strict: true
+
+repo_name: modelcontextprotocol/python-sdk
+repo_url: https://github.com/modelcontextprotocol/python-sdk
+edit_uri: edit/main/docs/
+
+# TODO(Marcelo): Add Anthropic copyright?
+# copyright: © Model Context Protocol 2025 to present
+
+nav:
+  - Home: index.md
+  - API Reference: api.md
+
+theme:
+  name: "material"
+  palette:
+    - media: "(prefers-color-scheme)"
+      scheme: default
+      primary: pink
+      accent: pink
+      toggle:
+        icon: material/lightbulb
+        name: "Switch to light mode"
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: pink
+      accent: pink
+      toggle:
+        icon: material/lightbulb-outline
+        name: "Switch to dark mode"
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: pink
+      accent: pink
+      toggle:
+        icon: material/lightbulb-auto-outline
+        name: "Switch to system preference"
+  features:
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.annotate
+    - content.code.copy
+    - content.code.select
+    - navigation.path
+    - navigation.indexes
+    - navigation.sections
+    - navigation.tracking
+    - toc.follow
+  # logo: "img/logo-white.svg"
+  # TODO(Marcelo): Add a favicon.
+  # favicon: "favicon.ico"
+
+# https://www.mkdocs.org/user-guide/configuration/#validation
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+  anchors: warn
+
+markdown_extensions:
+  - tables
+  - admonition
+  - attr_list
+  - md_in_html
+  - pymdownx.details
+  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.mark
+  - pymdownx.superfences
+  - pymdownx.snippets
+  - pymdownx.tilde
+  - pymdownx.inlinehilite
+  - pymdownx.highlight:
+      pygments_lang_class: true
+  - pymdownx.extra:
+      pymdownx.superfences:
+        custom_fences:
+          - name: mermaid
+            class: mermaid
+            format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      options:
+        custom_icons:
+          - docs/.overrides/.icons
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - sane_lists # this means you can start a list from any number
+
+watch:
+  - src/mcp
+
+plugins:
+  - search
+  - social
+  - glightbox
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src/mcp]
+          options:
+            relative_crossrefs: true
+            members_order: source
+            separate_signature: true
+            show_signature_annotations: true
+            signature_crossrefs: true
+            group_by_category: false
+            # 3 because docs are in pages with an H2 just above them
+            heading_level: 3
+          import:
+            - url: https://docs.python.org/3/objects.inv
+            - url: https://docs.pydantic.dev/latest/objects.inv
+            - url: https://typing-extensions.readthedocs.io/en/latest/objects.inv

pyproject.toml

@@ -42,7 +42,10 @@ mcp = "mcp.cli:app [cli]"
 
 [tool.uv]
 resolution = "lowest-direct"
-dev-dependencies = [
+default-groups = ["dev", "docs"]
+
+[dependency-groups]
+dev = [
     "pyright>=1.1.391",
     "pytest>=8.3.4",
     "ruff>=0.8.5",
@@ -51,6 +54,13 @@ dev-dependencies = [
     "pytest-xdist>=3.6.1",
     "pytest-examples>=0.0.14",
 ]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-glightbox>=0.4.0",
+    "mkdocs-material[imaging]>=9.5.45",
+    "mkdocstrings-python>=1.12.2",
+]
+
 
 [build-system]
 requires = ["hatchling", "uv-dynamic-versioning"]

tests/client/test_list_roots_callback.py

@@ -3,6 +3,7 @@
 
 from mcp.client.session import ClientSession
 from mcp.server.fastmcp.server import Context
+from mcp.server.session import ServerSession
 from mcp.shared.context import RequestContext
 from mcp.shared.memory import (
     create_connected_server_and_client_session as create_session,
@@ -35,7 +36,7 @@ async def list_roots_callback(
         return callback_return
 
     @server.tool("test_list_roots")
-    async def test_list_roots(context: Context, message: str):  # type: ignore[reportUnknownMemberType]
+    async def test_list_roots(context: Context[ServerSession], message: str):  # type: ignore[reportUnknownMemberType]
         roots = await context.session.list_roots()
         assert roots == callback_return
         return True