Merge remote-tracking branch 'origin/main' into jerome/feature/add-client-sampling

Author: jerome3o-anthropic

.git-blame-ignore-revs

@@ -0,0 +1,25 @@
+name: Check uv.lock
+
+on:
+  pull_request:
+    paths:
+      - "pyproject.toml"
+      - "uv.lock"
+  push:
+    paths:
+      - "pyproject.toml"
+      - "uv.lock"
+
+jobs:
+  check-lock:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Check uv.lock is up to date
+        run: uv lock --check

.github/workflows/check-lock.yml

@@ -1,4 +1,5 @@
 .DS_Store
+scratch/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -162,3 +163,6 @@ cython_debug/
 #  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/
+
+# vscode
+.vscode/

.gitignore

@@ -13,3 +13,12 @@ repos:
       - id: ruff-format
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
+
+  - repo: local
+    hooks:
+      - id: uv-lock-check
+        name: Check uv.lock is up to date
+        entry: uv lock --check
+        language: system
+        files: ^(pyproject\.toml|uv\.lock)$
+        pass_filenames: false

.pre-commit-config.yaml

@@ -1,73 +1,114 @@
-# Tool Usage Learnings
+# Development Guidelines
 
-This file is intended to be used by an LLM such as Claude.
+This document contains critical information about working with this codebase. Follow these guidelines precisely.
 
-## UV Package Manager
+## Core Development Rules
 
-- Use `uv run` to run Python tools without activating virtual environments
-- For formatting: `uv run ruff format .`
-- For type checking: `uv run pyright`
-- For upgrading packages:
-  - `uv add --dev package --upgrade-package package` to upgrade a specific package
-  - Don't use `@latest` syntax - it doesn't work
-  - Be careful with `uv pip install` as it may downgrade packages
+1. Package Management
+   - ONLY use uv, NEVER pip
+   - Installation: `uv add package`
+   - Running tools: `uv run tool`
+   - Upgrading: `uv add --dev package --upgrade-package package`
+   - FORBIDDEN: `uv pip install`, `@latest` syntax
 
-## Git and GitHub CLI
+2. Code Quality
+   - Type hints required for all code
+   - Public APIs must have docstrings
+   - Functions must be focused and small
+   - Follow existing patterns exactly
+   - Line length: 88 chars maximum
 
-- When using gh CLI for PRs, always quote title and body:
+3. Testing Requirements
+   - Framework: `uv run pytest`
+   - Async testing: use anyio, not asyncio
+   - Coverage: test edge cases and errors
+   - New features require tests
+   - Bug fixes require regression tests
+
+- For commits fixing bugs or adding features based on user reports add:
   ```bash
-  gh pr create --title "\"my title\"" --body "\"my body\""
+  git commit --trailer "Reported-by:<name>"
   ```
-- For git commits, use double quotes and escape inner quotes:
+  Where `<name>` is the name of the user.
+
+- For commits related to a Github issue, add
   ```bash
-  git commit -am "\"fix: my commit message\""
+  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.
+
+## Pull Requests
+
+- Create a detailed message of what changed. Focus on the high level description of
+  the problem it tries to solve, and how it is solved. Don't go into the specifics of the
+  code unless it adds clarity.
+
+- Always add `jerome3o-anthropic` and `jspahrsummers` as reviewer.
+
+- NEVER ever mention a `co-authored-by` or similar aspects. In particular, never
+  mention the tool used to create the commit message or PR.
 
 ## Python Tools
 
-### Ruff
-- Handles both formatting and linting
-- For formatting: `uv run ruff format .`
-- For checking: `uv run ruff check .`
-- For auto-fixing: `uv run ruff check . --fix`
-- Common issues:
-  - Line length (default 88 chars)
-  - Import sorting (I001 errors)
-  - Unused imports
-- When line length errors occur:
-  - For strings, use parentheses and line continuation
-  - For function calls, use multiple lines with proper indentation
-  - For imports, split into multiple lines
-
-### Pyright
-- Type checker
-- Run with: `uv run pyright`
-- Version warnings can be ignored if type checking passes
-- Common issues:
-  - Optional types need explicit None checks
-  - String operations need type narrowing
-
-## Pre-commit Hooks
-
-- Configuration in `.pre-commit-config.yaml`
-- Runs automatically on git commit
-- Includes:
-  - Prettier for YAML/JSON formatting
-  - Ruff for Python formatting and linting
-- When updating ruff version:
-  - Check available versions on PyPI
-  - Update `rev` in config to match available version
-  - Add and commit config changes before other changes
-
-## Best Practices
-
-1. Always check git status and diff before committing
-2. Run formatters before type checkers
-3. When fixing CI:
-   - Start with formatting issues
-   - Then fix type errors
-   - Then address any remaining linting issues
-4. For type errors:
-   - Get full context around error lines
-   - Consider optional types
-   - Add type narrowing checks when needed
+## Code Formatting
+
+1. Ruff
+   - Format: `uv run ruff format .`
+   - Check: `uv run ruff check .`
+   - Fix: `uv run ruff check . --fix`
+   - Critical issues:
+     - Line length (88 chars)
+     - Import sorting (I001)
+     - Unused imports
+   - Line wrapping:
+     - Strings: use parentheses
+     - Function calls: multi-line with proper indent
+     - Imports: split into multiple lines
+
+2. Type Checking
+   - Tool: `uv run pyright`
+   - Requirements:
+     - Explicit None checks for Optional
+     - Type narrowing for strings
+     - Version warnings can be ignored if checks pass
+
+3. Pre-commit
+   - Config: `.pre-commit-config.yaml`
+   - Runs: on git commit
+   - Tools: Prettier (YAML/JSON), Ruff (Python)
+   - Ruff updates:
+     - Check PyPI versions
+     - Update config rev
+     - Commit config first
+
+## Error Resolution
+
+1. CI Failures
+   - Fix order:
+     1. Formatting
+     2. Type errors
+     3. Linting
+   - Type errors:
+     - Get full line context
+     - Check Optional types
+     - Add type narrowing
+     - Verify function signatures
+
+2. Common Issues
+   - Line length:
+     - Break strings with parentheses
+     - Multi-line function calls
+     - Split imports
+   - Types:
+     - Add None checks
+     - Narrow string types
+     - Match existing patterns
+
+3. Best Practices
+   - Check git status before commits
+   - Run formatters before type checks
+   - Keep changes minimal
+   - Follow existing patterns
+   - Document public APIs
+   - Test thoroughly

CLAUDE.md

@@ -128,13 +128,41 @@ The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you bui
 The FastMCP server is your core interface to the MCP protocol. It handles connection management, protocol compliance, and message routing:
 
 ```python
+# Add lifespan support for startup/shutdown with strong typing
+from dataclasses import dataclass
+from typing import AsyncIterator
 from mcp.server.fastmcp import FastMCP
 
 # Create a named server
 mcp = FastMCP("My App")
 
 # Specify dependencies for deployment and development
 mcp = FastMCP("My App", dependencies=["pandas", "numpy"])
+
+@dataclass
+class AppContext:
+    db: Database  # Replace with your actual DB type
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
+    """Manage application lifecycle with type-safe context"""
+    try:
+        # Initialize on startup
+        await db.connect()
+        yield AppContext(db=db)
+    finally:
+        # Cleanup on shutdown
+        await db.disconnect()
+
+# Pass lifespan to server
+mcp = FastMCP("My App", lifespan=app_lifespan)
+
+# Access type-safe lifespan context in tools
+@mcp.tool()
+def query_db(ctx: Context) -> str:
+    """Tool that uses initialized resources"""
+    db = ctx.request_context.lifespan_context["db"]
+    return db.query()
 ```
 
 ### Resources
@@ -218,7 +246,7 @@ async def long_task(files: list[str], ctx: Context) -> str:
     for i, file in enumerate(files):
         ctx.info(f"Processing {file}")
         await ctx.report_progress(i, len(files))
-        data = await ctx.read_resource(f"file://{file}")
+        data, mime_type = await ctx.read_resource(f"file://{file}")
     return "Processing complete"
 ```
 
@@ -249,7 +277,7 @@ mcp install server.py
 mcp install server.py --name "My Analytics Server"
 
 # Environment variables
-mcp install server.py -e API_KEY=abc123 -e DB_URL=postgres://...
+mcp install server.py -v API_KEY=abc123 -v DB_URL=postgres://...
 mcp install server.py -f .env
 ```
 
@@ -334,7 +362,38 @@ def query_data(sql: str) -> str:
 
 ### Low-Level Server
 
-For more control, you can use the low-level server implementation directly. This gives you full access to the protocol and allows you to customize every aspect of your server:
+For more control, you can use the low-level server implementation directly. This gives you full access to the protocol and allows you to customize every aspect of your server, including lifecycle management through the lifespan API:
+
+```python
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+@asynccontextmanager
+async def server_lifespan(server: Server) -> AsyncIterator[dict]:
+    """Manage server startup and shutdown lifecycle."""
+    try:
+        # Initialize resources on startup
+        await db.connect()
+        yield {"db": db}
+    finally:
+        # Clean up on shutdown
+        await db.disconnect()
+
+# Pass lifespan to server
+server = Server("example-server", lifespan=server_lifespan)
+
+# Access lifespan context in handlers
+@server.call_tool()
+async def query_db(name: str, arguments: dict) -> list:
+    ctx = server.request_context
+    db = ctx.lifespan_context["db"]
+    return await db.query(arguments["query"])
+```
+
+The lifespan API provides:
+- A way to initialize resources when the server starts and clean them up when it stops
+- Access to initialized resources through the request context in handlers
+- Type-safe context passing between lifespan and request handlers
 
 ```python
 from mcp.server.lowlevel import Server, NotificationOptions
@@ -448,7 +507,7 @@ async def run():
             tools = await session.list_tools()
 
             # Read a resource
-            resource = await session.read_resource("file://some/path")
+            content, mime_type = await session.read_resource("file://some/path")
 
             # Call a tool
             result = await session.call_tool("tool-name", arguments={"arg1": "value"})
@@ -492,4 +551,4 @@ We are passionate about supporting contributors of all levels of experience and
 
 ## License
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+This project is licensed under the MIT License - see the LICENSE file for details.

README.md

@@ -0,0 +1 @@
+3.10