fix: documentation and tools (#8)

bercianor · web-flow · commit e06ed87205f6 · 2025-10-24T21:01:41.000Z
- correct documentation info
- separate tools in files
- add mcp inspector
- add context class to share jwt
- upgrade development doc
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -23,7 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Technical Details
 
-- Python 3.10+ support
+- Python 3.11+ support
 - FastAPI-based HTTP server with SSE
 - JWT validation with local/external strategies
 - TOML configuration
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -32,46 +32,12 @@ config.toml          # Configuration example
 
 The current tools (`hello_world`, `whoami`) are examples. Here's how to replace them:
 
-### 1. Modify Tools
-
-Edit `src/mcp_app/tools/router.py`:
-
-```python
-from mcp import Tool
-from mcp.server import Server
-
-# Remove demo imports
-# from mcp_app.tools.hello_world import hello_world_tool
-# from mcp_app.tools.whoami import whoami_tool
-
-# Add your tools
-from my_app.tools.my_tool import my_tool_function
-
-def register_tools(server: Server) -> None:
-    """Register MCP tools with the server."""
-
-    # Remove demo tools
-    # server.register_tool(hello_world_tool)
-    # server.register_tool(whoami_tool)
-
-    # Register your tools
-    server.register_tool(my_tool_function)
-```
-
-### 2. Create Your Tools
+### 1. Create Your Tools
 
 Create `src/mcp_app/tools/my_tools.py`:
 
 ```python
-from mcp import Tool
-from mcp.server import Server
-from mcp_app.config import Configuration
-
-# Get config if needed
-config = None  # Will be set during app startup
-
-@server.tool()
-async def my_business_logic_tool(param1: str, param2: int) -> dict:
+def my_business_logic_tool(param1: str, param2: int) -> dict:
     """Execute your business logic.
 
     Args:
@@ -89,6 +55,31 @@ async def my_business_logic_tool(param1: str, param2: int) -> dict:
     return result
 ```
 
+#### Register Your Tools
+
+Edit `src/mcp_app/tools/router.py`:
+
+```python
+from mcp.server import FastMCP
+
+# Remove demo imports
+# from mcp_app.tools.hello_world import hello_world
+# from mcp_app.tools.whoami import whoami
+
+# Add your tools
+from my_app.tools.my_tools import my_business_logic_tool
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register MCP tools with the server."""
+
+    # Remove demo tools
+    # mcp.tool()(hello_world)
+    # mcp.tool()(whoami)
+
+    # Register your tools
+    mcp.tool()(my_business_logic_tool)
+```
+
 ### 3. Update Tests
 
 Modify `tests/test_tools.py` to test your new tools instead of the demo ones.
@@ -97,6 +88,33 @@ Modify `tests/test_tools.py` to test your new tools instead of the demo ones.
 
 Update README.md and DEVELOPMENT.md to document your tools instead of the demo ones.
 
+## JWT Validation Configuration
+
+The project includes JWT validation middleware for securing tools. By default, it's configured for local validation using a JWKS endpoint.
+
+### Using Keycloak
+
+To enable JWT validation with Keycloak:
+
+1. **Run Keycloak locally** (e.g., via Docker: `docker run -p 8080:8080 quay.io/keycloak/keycloak:latest start-dev`).
+2. **Create a realm and client** in Keycloak admin console.
+3. **Update `config.toml`**:
+   - Set `jwks_uri = "http://localhost:8080/realms/your-realm/protocol/openid-connect/certs"`
+   - Adjust `allow_conditions` to match your email domain, e.g., `payload.email.endswith("@yourdomain.com")`
+4. **Enable OAuth endpoints** if needed by setting `oauth_authorization_server.enabled = true` and `oauth_protected_resource.enabled = true`, updating issuer_uri and auth_servers accordingly.
+
+### Using Auth0
+
+To use Auth0 as your identity provider:
+
+1. **Get your Auth0 tenant details** (tenant name, client ID, etc.).
+2. **Update `config.toml`**:
+   - Set `jwks_uri = "https://your-tenant.auth0.com/.well-known/jwks.json"`
+   - Set `allow_conditions` to validate claims, e.g., `payload.iss == "https://your-tenant.auth0.com/" and payload.aud == "your-client-id"`
+3. **Ensure Auth0 is configured** to issue JWTs with the required claims.
+
+For external validation (e.g., via a proxy), set `strategy = "external"` and configure your proxy to forward validated JWTs in the `X-Validated-Jwt` header.
+
 ## Configuration Placeholders
 
 Before using this template, you must replace all placeholders with your actual values:
diff --git a/Justfile b/Justfile
@@ -81,3 +81,8 @@ run:
 [group('run')]
 run-stdio:
     uv run stdio
+
+# Run MCP Inspector
+[group('run')]
+dev:
+    bunx --yes @modelcontextprotocol/inspector uv run stdio
diff --git a/README-es.md b/README-es.md
@@ -183,7 +183,3 @@ Este proyecto está licenciado bajo Unlicense - consulta el archivo [LICENSE](LI
 ## Créditos
 
 Traducción completa a Python del proyecto [MCP Forge](https://github.com/achetronic/mcp-forge) (Go), manteniendo todas las funcionalidades y nivel de seguridad del original.
-
-```
-
-```
diff --git a/README.md b/README.md
@@ -185,7 +185,3 @@ This project is licensed under the Unlicense - see the [LICENSE](LICENSE) file f
 ## Credits
 
 Complete translation to Python of the [MCP Forge](https://github.com/achetronic/mcp-forge) project (Go), maintaining all functionalities and security level of the original.
-
-```
-
-```
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -5,11 +5,10 @@ plugins:
 
 title: "MCP Forge Python - Production-Ready MCP Server with OAuth"
 description: "A comprehensive MCP (Model Context Protocol) server template with OAuth support, JWT validation, and production-ready deployment options for Python developers."
-author: "Ruben"
+author: "bercianor"
 url: "https://bercianor.es/mcp-forge-python"
 social:
   name: MCP Forge Python
   links:
     - https://github.com/bercianor
     - https://github.com/bercianor/mcp-forge-python
-
diff --git a/src/mcp_app/context.py b/src/mcp_app/context.py
@@ -0,0 +1,37 @@
+"""
+Shared context for authentication data.
+
+This module provides context variables to share JWT-related data between
+middlewares and MCP tools in an async-safe way.
+"""
+
+from contextvars import ContextVar
+from typing import Any
+
+# Context variables for JWT data
+jwt_token: ContextVar[str | None] = ContextVar("jwt_token", default=None)
+jwt_payload: ContextVar[dict[str, Any] | None] = ContextVar("jwt_payload", default=None)
+
+
+def set_jwt_context(token: str, payload: dict[str, Any]) -> None:
+    """
+    Set the JWT token and its decoded payload.
+
+    Args:
+        token: The validated JWT token string.
+        payload: The decoded JWT payload.
+
+    """
+    jwt_token.set(token)
+    jwt_payload.set(payload)
+
+
+def get_jwt_payload() -> dict[str, Any] | None:
+    """
+    Get the decoded JWT payload.
+
+    Returns:
+        The JWT payload as a dictionary, or None if not set or decoding failed.
+
+    """
+    return jwt_payload.get()
diff --git a/src/mcp_app/middlewares/jwt_validation.py b/src/mcp_app/middlewares/jwt_validation.py
@@ -15,6 +15,8 @@
 from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.types import ASGIApp
 
+from mcp_app.context import set_jwt_context
+
 logger = logging.getLogger(__name__)
 
 
@@ -147,6 +149,9 @@ async def _validate_local(self, request: Request) -> None:
         # Set forwarded header
         request.headers.__dict__["_list"].append((self.forwarded_header.encode(), token.encode()))
 
+        # Set JWT in shared context for MCP tools
+        set_jwt_context(token, payload)
+
     def _check_condition(self, condition: str, payload: dict[str, Any]) -> bool:
         """Check simple CEL-like conditions."""
         # Basic implementation for common patterns
diff --git a/src/mcp_app/tools/hello_world.py b/src/mcp_app/tools/hello_world.py
@@ -0,0 +1,15 @@
+"""Tool to say hello."""
+
+
+def hello_world(name: str) -> str:
+    """
+    Say hello to someone.
+
+    Args:
+        name: Name of the person to greet.
+
+    Returns:
+        Greeting message.
+
+    """
+    return f"Hello, {name}! 👋"
diff --git a/src/mcp_app/tools/router.py b/src/mcp_app/tools/router.py
@@ -6,36 +6,8 @@
 
 from mcp.server import FastMCP
 
-
-def hello_world(name: str) -> str:
-    """
-    Say hello to someone.
-
-    Args:
-        name: Name of the person to greet.
-
-    Returns:
-        Greeting message.
-
-    """
-    return f"Hello, {name}! 👋"
-
-
-def whoami(jwt: str | None = None) -> str:
-    """
-    Expose information about the user.
-
-    Args:
-        jwt: Validated JWT from middleware.
-
-    Returns:
-        User information message.
-
-    """
-    if not jwt:
-        return "JWT is empty. Information is not available"
-
-    return f"Success! Data are in the following JWT. You have to decode it first. JWT: {jwt}"
+from mcp_app.tools.hello_world import hello_world
+from mcp_app.tools.whoami import whoami
 
 
 def register_tools(mcp: FastMCP) -> None:
diff --git a/src/mcp_app/tools/whoami.py b/src/mcp_app/tools/whoami.py
@@ -0,0 +1,20 @@
+"""Tool to expose user information."""
+
+from typing import Any
+
+from mcp_app.context import get_jwt_payload
+
+
+def whoami() -> dict[str, Any] | str:
+    """
+    Expose information about the user from the JWT payload.
+
+    Returns:
+        The JWT payload as a dictionary, or an error message if not available.
+
+    """
+    payload = get_jwt_payload()
+    if not payload:
+        return "JWT is empty or invalid. Information is not available"
+
+    return payload
diff --git a/tests/test_benchmarks.py b/tests/test_benchmarks.py
@@ -1,9 +1,11 @@
 """Benchmarks for MCP tools performance."""
 
 from collections.abc import Callable
+from typing import Any
 
 import pytest
 
+from mcp_app.context import jwt_payload
 from mcp_app.tools.router import hello_world, whoami
 
 
@@ -22,10 +24,11 @@ def run_hello_world() -> str:
     @pytest.mark.benchmark
     def test_whoami_benchmark(self, benchmark: Callable[[Callable], None]) -> None:  # type: ignore[PGH003]
         """Benchmark whoami tool performance."""
-        # Mock JWT for testing
-        mock_jwt = "mock.jwt.token"
+        # Mock payload for testing
+        mock_payload = {"sub": "user123", "roles": ["admin"]}
+        jwt_payload.set(mock_payload)
 
-        def run_whoami() -> str:
-            return whoami(jwt=mock_jwt)
+        def run_whoami() -> dict[str, Any] | str:
+            return whoami()
 
         benchmark(run_whoami)
diff --git a/tests/test_jwt_validation.py b/tests/test_jwt_validation.py
@@ -353,7 +353,8 @@ async def test_validate_local_success(
 
     await middleware._validate_local(request)
 
-    mock_decode.assert_called_once()
+    # jwt.decode is called once in _validate_local
+    assert mock_decode.call_count == 1
     assert len(request.headers.__dict__["_list"]) == 1
 
 
diff --git a/tests/test_tools.py b/tests/test_tools.py
@@ -2,7 +2,10 @@
 
 from unittest.mock import MagicMock
 
-from mcp_app.tools.router import hello_world, register_tools, whoami
+from mcp_app.context import jwt_payload
+from mcp_app.tools.hello_world import hello_world
+from mcp_app.tools.router import register_tools
+from mcp_app.tools.whoami import whoami
 
 NUM_TOOLS = 2
 
@@ -23,14 +26,14 @@ def test_hello_world_tool() -> None:
 
 def test_whoami_tool_no_jwt() -> None:
     """Test the whoami tool with no JWT."""
-    result = whoami(None)
-    assert result == "JWT is empty. Information is not available"
+    jwt_payload.set(None)  # Simulate no JWT
+    result = whoami()
+    assert result == "JWT is empty or invalid. Information is not available"
 
 
 def test_whoami_tool_with_jwt() -> None:
     """Test the whoami tool with JWT."""
-    result = whoami("test.jwt.token")
-    expected = (
-        "Success! Data are in the following JWT. You have to decode it first. JWT: test.jwt.token"
-    )
-    assert result == expected
+    test_payload = {"sub": "user123", "roles": ["admin"]}
+    jwt_payload.set(test_payload)  # Simulate decoded payload
+    result = whoami()
+    assert result == test_payload
diff --git a/uv.lock b/uv.lock
