Merge branch 'main' into main

Author: felixweinberger

.gitattribute

@@ -0,0 +1,2 @@
+# Generated
+uv.lock  linguist-generated=true

.github/ISSUE_TEMPLATE/config.yaml

@@ -1 +1 @@
-blank_issues_enabled: true
+blank_issues_enabled: false

.github/workflows/shared.yml

@@ -6,6 +6,9 @@ on:
 permissions:
   contents: read
 
+env:
+  COLUMNS: 150
+
 jobs:
   pre-commit:
     runs-on: ubuntu-latest
@@ -33,6 +36,7 @@ jobs:
     strategy:
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
+        dep-resolution: ["lowest-direct", "highest"]
         os: [ubuntu-latest, windows-latest]
 
     steps:
@@ -45,18 +49,11 @@ jobs:
           version: 0.7.2
 
       - name: Install the project
-        run: uv sync --frozen --all-extras --python ${{ matrix.python-version }}
+        run: uv sync --frozen --all-extras --python ${{ matrix.python-version }} --resolution ${{ matrix.dep-resolution }}
 
       - name: Run pytest
         run: uv run --frozen --no-sync pytest
 
-      # This must run last as it modifies the environment!
-      - name: Run pytest with lowest versions
-        run: |
-          uv sync --all-extras --upgrade
-          uv run --no-sync pytest
-        env:
-          UV_RESOLUTION: lowest-direct
   readme-snippets:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -52,6 +52,7 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+.ruff_cache/
 cover/
 
 # Translations
@@ -162,9 +163,12 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
 
 # vscode
 .vscode/
 .windsurfrules
 **/CLAUDE.local.md
+
+# claude code
+.claude/

.pre-commit-config.yaml

@@ -7,27 +7,40 @@ repos:
       - id: prettier
         types_or: [yaml, json5]
 
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.45.0
+    hooks:
+      - id: markdownlint
+        args:
+          [
+            "--fix",
+            "--config",
+            "pyproject.toml",
+            "--configPointer",
+            "/tool/markdown/lint",
+          ]
+        types: [markdown]
+
   - repo: local
     hooks:
       - id: ruff-format
         name: Ruff Format
-        entry: uv run ruff
+        entry: uv run --frozen ruff
         args: [format]
         language: system
         types: [python]
         pass_filenames: false
       - id: ruff
         name: Ruff
-        entry: uv run ruff
+        entry: uv run --frozen ruff
         args: ["check", "--fix", "--exit-non-zero-on-fix"]
         types: [python]
         language: system
         pass_filenames: false
         exclude: ^README\.md$
       - id: pyright
         name: pyright
-        entry: uv run pyright
-        args: [src]
+        entry: uv run --frozen pyright
         language: system
         types: [python]
         pass_filenames: false
@@ -39,7 +52,7 @@ repos:
         pass_filenames: false
       - id: readme-snippets
         name: Check README snippets are up to date
-        entry: uv run scripts/update_readme_snippets.py --check
+        entry: uv run --frozen python scripts/update_readme_snippets.py --check
         language: system
         files: ^(README\.md|examples/.*\.py|scripts/update_readme_snippets\.py)$
         pass_filenames: false

CLAUDE.md

@@ -16,7 +16,7 @@ This document contains critical information about working with this codebase. Fo
    - Public APIs must have docstrings
    - Functions must be focused and small
    - Follow existing patterns exactly
-   - Line length: 88 chars maximum
+   - Line length: 120 chars maximum
 
 3. Testing Requirements
    - Framework: `uv run --frozen pytest`
@@ -26,15 +26,19 @@ This document contains critical information about working with this codebase. Fo
    - Bug fixes require regression tests
 
 - For commits fixing bugs or adding features based on user reports add:
+
   ```bash
   git commit --trailer "Reported-by:<name>"
   ```
+
   Where `<name>` is the name of the user.
 
 - For commits related to a Github issue, add
+
   ```bash
   git commit --trailer "Github-Issue:#<number>"
   ```
+
 - NEVER ever mention a `co-authored-by` or similar aspects. In particular, never
   mention the tool used to create the commit message or PR.
 
@@ -116,3 +120,15 @@ This document contains critical information about working with this codebase. Fo
    - Follow existing patterns
    - Document public APIs
    - Test thoroughly
+
+## Exception Handling
+
+- **Always use `logger.exception()` instead of `logger.error()` when catching exceptions**
+  - Don't include the exception in the message: `logger.exception("Failed")` not `logger.exception(f"Failed: {e}")`
+- **Catch specific exceptions** where possible:
+  - File ops: `except (OSError, PermissionError):`
+  - JSON: `except json.JSONDecodeError:`
+  - Network: `except (ConnectionError, TimeoutError):`
+- **Only catch `Exception` for**:
+  - Top-level handlers that must not crash
+  - Cleanup blocks (log at debug level)

CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-[email protected].
+<[email protected]>.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the
@@ -116,13 +116,13 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
 
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

CONTRIBUTING.md

@@ -9,10 +9,17 @@ Thank you for your interest in contributing to the MCP Python SDK! This document
 3. Fork the repository
 4. Clone your fork: `git clone https://github.com/YOUR-USERNAME/python-sdk.git`
 5. Install dependencies:
+
 ```bash
 uv sync --frozen --all-extras --dev
 ```
 
+6. Set up pre-commit hooks:
+
+```bash
+uv tool install pre-commit --with pre-commit-uv --force-reinstall
+```
+
 ## Development Workflow
 
 1. Choose the correct branch for your changes:
@@ -25,27 +32,37 @@ uv sync --frozen --all-extras --dev
 3. Make your changes
 
 4. Ensure tests pass:
-```bash 
+
+```bash
 uv run pytest
 ```
 
 5. Run type checking:
+
 ```bash
 uv run pyright
 ```
 
 6. Run linting:
+
 ```bash
 uv run ruff check .
 uv run ruff format .
 ```
 
 7. Update README snippets if you modified example code:
+
 ```bash
 uv run scripts/update_readme_snippets.py
 ```
 
-8. Submit a pull request to the same branch you branched from
+8. (Optional) Run pre-commit hooks on all files:
+
+```bash
+pre-commit run --all-files
+```
+
+9. Submit a pull request to the same branch you branched from
 
 ## Code Style