Add initial project structure with MCP server template

- Created .gitignore to exclude Python-generated files and virtual environments.
- Added .python-version to specify Python version 3.12.
- Introduced pyproject.toml for project metadata and dependencies including httpx, mcp, starlette, and uvicorn.
- Added README.md with project overview, features, requirements, and getting started instructions.
- Implemented server.py with FastMCP server setup and example weather service integration.
- Included example weather service in protocals/example_weather.py.
- Added comprehensive MCP documentation in protocals/mcp.md.
- Created SDK documentation in protocals/sdk.md.
- Generated dependency lock file uv.lock for package management.

Author: sontallive

.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

.python-version

@@ -0,0 +1 @@
+3.12

README.md

@@ -0,0 +1,139 @@
+# MCP Server template for better AI Coding
+
+> Inspired by [MCP Official Tutorial](https://modelcontextprotocol.io/tutorials/building-mcp-with-llms)
+
+## Overview
+
+This template provides a streamlined foundation for building Model Context Protocol (MCP) servers in Python. It's designed to make AI-assisted development of MCP tools easier and more efficient.
+
+## Features
+
+- Ready-to-use MCP server implementation
+- Configurable transport modes (stdio, SSE)
+- Example weather service integration (NWS API)
+- Clean, well-documented code structure
+- Minimal dependencies
+- **Embedded MCP specifications and documentation** for improved AI tool understanding
+
+## Integrated MCP Documentation
+
+This template includes comprehensive MCP documentation directly in the project:
+
+- **Complete MCP Specification** (`protocals/mcp.md`): The full Model Context Protocol specification that defines how AI models can interact with external tools and resources. This helps AI assistants understand MCP concepts and implementation details without requiring external references.
+
+- **Python SDK Guide** (`protocals/sdk.md`): Detailed documentation for the MCP Python SDK, making it easier for AI tools to provide accurate code suggestions and understand the library's capabilities.
+
+- **Example Implementation** (`protocals/example_weather.py`): A practical weather service implementation demonstrating real-world MCP server patterns and best practices.
+
+Having these resources embedded in the project enables AI coding assistants to better understand MCP concepts and provide more accurate, contextually relevant suggestions during development.
+
+## Requirements
+
+- Python 3.12+
+- Dependencies:
+  - `mcp>=1.4.1`
+  - `httpx>=0.28.1`
+  - `starlette>=0.46.1`
+  - `uvicorn>=0.34.0`
+
+## Getting Started
+
+### Installation
+
+1. Clone this repository:
+   ```bash
+   git clone https://github.com/yourusername/mcp-server-python-template.git
+   cd mcp-server-python-template
+   ```
+
+2. Create a virtual environment and install dependencies:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   pip install -e .
+   ```
+
+### Running the Example Server
+
+The template includes a weather service example that demonstrates how to build MCP tools:
+
+```bash
+# Run with stdio transport (for CLI tools)
+python server.py --transport stdio
+
+# Run with SSE transport (for web applications)
+python server.py --transport sse --host 0.0.0.0 --port 8080
+```
+
+## Creating Your Own MCP Tools
+
+To create your own MCP tools:
+
+1. Import the necessary components from `mcp`:
+   ```python
+   from mcp.server.fastmcp import FastMCP
+   ```
+
+2. Initialize your MCP server with a namespace:
+   ```python
+   mcp = FastMCP("your-namespace")
+   ```
+
+3. Define your tools using the `@mcp.tool()` decorator:
+   ```python
+   @mcp.tool()
+   async def your_tool_function(param1: str, param2: int) -> str:
+       """
+       Your tool description.
+       
+       Args:
+           param1: Description of param1
+           param2: Description of param2
+           
+       Returns:
+           The result of your tool
+       """
+       # Your implementation here
+       return result
+   ```
+
+4. Run your server using the appropriate transport:
+   ```python
+   mcp.run(transport='stdio')  # or set up SSE as shown in server.py
+   ```
+
+## Project Structure
+
+- `server.py`: Main MCP server implementation with example weather tools
+- `main.py`: Simple entry point for custom code
+- `protocals/`: Documentation and example protocols
+  - `mcp.md`: Complete MCP specification (~7000 lines)
+  - `sdk.md`: MCP Python SDK documentation
+  - `example_weather.py`: Example weather service implementation
+- `pyproject.toml`: Project dependencies and metadata
+
+## Understanding MCP
+
+The Model Context Protocol (MCP) is a standardized way for AI models to interact with external tools and resources. Key concepts include:
+
+- **Tools**: Functions that models can call to perform actions or retrieve information
+- **Resources**: External data sources that models can reference
+- **Transports**: Communication channels between clients and MCP servers (stdio, SSE)
+- **Namespaces**: Logical groupings of related tools
+
+This template is specifically designed to make working with MCP more accessible, with the integrated documentation helping AI tools better understand and generate appropriate code for MCP implementations.
+
+## Learning Resources
+
+- [MCP Official Documentation](https://modelcontextprotocol.io/docs)
+- [Protocol Documentation](./protocals/mcp.md)
+- [SDK Guide](./protocals/sdk.md)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+

protocals/example_weather.py

@@ -0,0 +1,227 @@
+from typing import Any
+import httpx
+from mcp.server.fastmcp import FastMCP
+from starlette.applications import Starlette
+from mcp.server.sse import SseServerTransport
+from starlette.requests import Request
+from starlette.routing import Mount, Route
+from mcp.server import Server
+import uvicorn
+
+# Initialize FastMCP server for Weather tools (SSE)
+mcp = FastMCP("weather")
+
+# Constants for NWS (National Weather Service) API
+NWS_API_BASE = "https://api.weather.gov"
+USER_AGENT = "weather-app/1.0"
+
+
+async def make_nws_request(url: str) -> dict[str, Any] | None:
+    """Make a request to the NWS API with proper error handling.
+    
+    This function handles the HTTP request to the NWS API, setting appropriate
+    headers and handling potential errors during the request.
+    
+    Args:
+        url: The complete URL for the NWS API endpoint
+        
+    Returns:
+        A dictionary containing the JSON response if successful, None otherwise
+    """
+    # Set required headers for the NWS API
+    headers = {
+        "User-Agent": USER_AGENT,  # NWS API requires a user agent
+        "Accept": "application/geo+json"  # Request GeoJSON format
+    }
+    # Create an async HTTP client
+    async with httpx.AsyncClient() as client:
+        try:
+            # Make the GET request with timeout
+            response = await client.get(url, headers=headers, timeout=30.0)
+            response.raise_for_status()  # Raise exception for 4XX/5XX responses
+            return response.json()  # Parse and return JSON response
+        except Exception:
+            # Return None if any error occurs (connection, timeout, parsing, etc.)
+            return None
+
+
+def format_alert(feature: dict) -> str:
+    """Format an alert feature into a readable string.
+    
+    Extracts relevant information from a weather alert feature and formats it
+    into a human-readable string.
+    
+    Args:
+        feature: A dictionary containing a single weather alert feature
+        
+    Returns:
+        A formatted string with key alert information
+    """
+    # Extract properties from the feature
+    props = feature["properties"]
+    # Format the alert with important details
+    return f"""
+Event: {props.get('event', 'Unknown')}
+Area: {props.get('areaDesc', 'Unknown')}
+Severity: {props.get('severity', 'Unknown')}
+Description: {props.get('description', 'No description available')}
+Instructions: {props.get('instruction', 'No specific instructions provided')}
+"""
+
+
+@mcp.tool()
+async def get_alerts(state: str) -> str:
+    """Get weather alerts for a US state.
+    
+    Fetches active weather alerts from the NWS API for a specified US state.
+    
+    Args:
+        state: Two-letter US state code (e.g. CA, NY)
+        
+    Returns:
+        A formatted string containing all active alerts for the state,
+        or a message indicating no alerts or an error
+    """
+    # Construct the URL for the state's active alerts
+    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
+    # Make the API request
+    data = await make_nws_request(url)
+
+    # Check if the response is valid
+    if not data or "features" not in data:
+        return "Unable to fetch alerts or no alerts found."
+
+    # Check if there are any active alerts
+    if not data["features"]:
+        return "No active alerts for this state."
+
+    # Format each alert and join them with separators
+    alerts = [format_alert(feature) for feature in data["features"]]
+    return "\n---\n".join(alerts)
+
+
+@mcp.tool()
+async def get_forecast(latitude: float, longitude: float) -> str:
+    """Get weather forecast for a location.
+    
+    Fetches the weather forecast from the NWS API for a specified location
+    using latitude and longitude coordinates.
+    
+    Args:
+        latitude: Latitude of the location
+        longitude: Longitude of the location
+        
+    Returns:
+        A formatted string containing the forecast for the next 5 periods,
+        or an error message if the forecast couldn't be retrieved
+    """
+    # First get the forecast grid endpoint using the coordinates
+    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
+    points_data = await make_nws_request(points_url)
+
+    # Check if we received valid point data
+    if not points_data:
+        return "Unable to fetch forecast data for this location."
+
+    # Extract the forecast URL from the points response
+    # NWS API requires this two-step process to get the forecast
+    forecast_url = points_data["properties"]["forecast"]
+    forecast_data = await make_nws_request(forecast_url)
+
+    # Check if we received valid forecast data
+    if not forecast_data:
+        return "Unable to fetch detailed forecast."
+
+    # Extract and format the forecast periods
+    periods = forecast_data["properties"]["periods"]
+    forecasts = []
+    for period in periods[:5]:  # Only show next 5 periods
+        forecast = f"""
+{period['name']}:
+Temperature: {period['temperature']}°{period['temperatureUnit']}
+Wind: {period['windSpeed']} {period['windDirection']}
+Forecast: {period['detailedForecast']}
+"""
+        forecasts.append(forecast)
+
+    # Join all forecast periods with separators
+    return "\n---\n".join(forecasts)
+
+
+def create_starlette_app(mcp_server: Server, *, debug: bool = False) -> Starlette:
+    """Create a Starlette application that can serve the provided MCP server with SSE.
+    
+    Sets up a Starlette web application with routes for SSE (Server-Sent Events)
+    communication with the MCP server.
+    
+    Args:
+        mcp_server: The MCP server instance to connect
+        debug: Whether to enable debug mode for the Starlette app
+        
+    Returns:
+        A configured Starlette application
+    """
+    # Create an SSE transport with a base path for messages
+    sse = SseServerTransport("/messages/")
+
+    async def handle_sse(request: Request) -> None:
+        """Handler for SSE connections.
+        
+        Establishes an SSE connection and connects it to the MCP server.
+        
+        Args:
+            request: The incoming HTTP request
+        """
+        # Connect the SSE transport to the request
+        async with sse.connect_sse(
+                request.scope,
+                request.receive,
+                request._send,  # noqa: SLF001
+        ) as (read_stream, write_stream):
+            # Run the MCP server with the SSE streams
+            await mcp_server.run(
+                read_stream,
+                write_stream,
+                mcp_server.create_initialization_options(),
+            )
+
+    # Create and return the Starlette application with routes
+    return Starlette(
+        debug=debug,
+        routes=[
+            Route("/sse", endpoint=handle_sse),  # Endpoint for SSE connections
+            Mount("/messages/", app=sse.handle_post_message),  # Endpoint for posting messages
+        ],
+    )
+
+
+if __name__ == "__main__":
+    # Get the underlying MCP server from the FastMCP instance
+    mcp_server = mcp._mcp_server  # noqa: WPS437
+    
+    import argparse
+    
+    # Set up command-line argument parsing
+    parser = argparse.ArgumentParser(description='Run MCP server with configurable transport')
+    # Allow choosing between stdio and SSE transport modes
+    parser.add_argument('--transport', choices=['stdio', 'sse'], default='stdio', 
+                        help='Transport mode (stdio or sse)')
+    # Host configuration for SSE mode
+    parser.add_argument('--host', default='0.0.0.0', 
+                        help='Host to bind to (for SSE mode)')
+    # Port configuration for SSE mode
+    parser.add_argument('--port', type=int, default=8080, 
+                        help='Port to listen on (for SSE mode)')
+    args = parser.parse_args()
+
+    # Launch the server with the selected transport mode
+    if args.transport == 'stdio':
+        # Run with stdio transport (default)
+        # This mode communicates through standard input/output
+        mcp.run(transport='stdio')
+    else:
+        # Run with SSE transport (web-based)
+        # Create a Starlette app to serve the MCP server
+        starlette_app = create_starlette_app(mcp_server, debug=True)
+        # Start the web server with the configured host and port
+        uvicorn.run(starlette_app, host=args.host, port=args.port)