.windsurfrules

# Cursor Rules for MCP Tool Generation

## Tool Definition Guidelines

1. **Use the @mcp.tool() decorator**
   - All tools must be defined using the `@mcp.tool()` decorator
   - This properly registers the function as an MCP tool
   - Include proper type hints for parameters and return values

2. **Methods must be async**
   - All tool methods should be defined as async functions
   - Use `async def` for all tool definitions
   - Use appropriate async libraries and patterns (e.g., httpx.AsyncClient instead of requests)

3. **Include descriptive docstrings**
   - Each tool must have a clear, descriptive docstring
   - Docstrings should explain what the tool does and describe parameters

## Examples of correct tool implementations:

```python
@mcp.tool()
async def calculate_bmi(weight_kg: float, height_m: float) -> float:
    """Calculate BMI given weight in kg and height in meters"""
    return weight_kg / (height_m**2)


@mcp.tool()
async def fetch_weather(city: str) -> str:
    """Fetch current weather for a city"""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.weather.com/{city}")
        return response.text
```

## Common Mistakes to Avoid

1. **Don't use synchronous functions**
   - Incorrect: `def my_tool():`
   - Correct: `async def my_tool():`

2. **Don't forget the decorator**
   - Incorrect: `async def my_tool():`
   - Correct: `@mcp.tool()\nasync def my_tool():`

3. **Don't use blocking HTTP libraries**
   - Incorrect: `requests.get(...)`
   - Correct: `async with httpx.AsyncClient() as client: await client.get(...)`


---
title: "Don't use uvicorn or fastapi with MCP"
description: "MCP has native server capabilities, external web servers are not needed"
severity: warning
---

# Don't use uvicorn or fastapi with MCP/FastMCP

## Rule Details

MCP and FastMCP have their own server implementations that can run directly without external web servers like uvicorn or fastapi.

### ❌ Incorrect

```python
# Incorrect: Using uvicorn with MCP
import uvicorn
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("MyServer")

if __name__ == "__main__":
    uvicorn.run(mcp.app, host="0.0.0.0", port=8000)  # Wrong
```

### ✅ Correct

```python
# Correct: Using MCP's native run method
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("MyServer")

if __name__ == "__main__":
    mcp.run()  # Correct
```

## Implementation Details

This rule enforces:
- Not using uvicorn or fastapi with MCP servers
- Using the native `mcp.run()` method instead
- Not adding unnecessary web server dependencies

## Dependencies

When working with MCP and Python 3.13, avoid unnecessary dependencies:
- For basic MCP implementation, only `mcp` or `fastmcp` and possibly `requests` are needed
- Do not include web server packages unnecessarily
- Take advantage of Python 3.13's built-in typing features (using `list[str]` instead of `List[str]`)

## Configuration in pyproject.toml

```toml
[project]
requires-python = ">=3.13"
dependencies = [
    "mcp>=0.2.0",
    "requests>=2.28.0",
    # No uvicorn or fastapi
]
```

## Import fastmcp from mcp

**FastMCP imports must use the correct package path**
- All imports concerning FastMCP must be done under `mcp.server.fastmcp`
- Example: `from mcp.server.fastmcp import FastMCP` instead of direct imports


---
title: "Use pyproject.toml with uv instead of requirements.txt"
description: "Modern Python projects should use pyproject.toml with uv for dependency management"
severity: warning
---

# Use pyproject.toml with uv instead of requirements.txt

## Rule Details

This project uses pyproject.toml for dependency management with uv, not requirements.txt.

### ❌ Incorrect

Using requirements.txt:

```
requests>=2.28.0
mcp>=0.2.0
fastapi>=0.68.0  # Unnecessary
uvicorn>=0.15.0  # Unnecessary
```

Or incorrect installation:

```bash
pip install -r requirements.txt
```

### ✅ Correct

Using pyproject.toml:

```toml
[project]
name = "my-mcp-server"
version = "0.1.0"
description = "My MCP server"
requires-python = ">=3.13"
dependencies = [
    "mcp>=0.2.0",
    "requests>=2.28.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "ruff>=0.0.272",
]
```

With correct installation:

```bash
uv sync
# or with dev dependencies
uv sync --with dev
```

## Implementation Details

This rule enforces:
- Using pyproject.toml for dependency management
- Using uv for package installation
- Properly specifying dependencies with version constraints
- Not creating or using requirements.txt
- Specifying Python 3.13 as the minimum required version

## Python 3.13 Features

Take advantage of Python 3.13's modern features:
- Use built-in type annotations (`dict[str, Any]` instead of importing `Dict` from typing)
- Use the pipe operator for union types (`str | None` instead of `Optional[str]`)
- Remove unnecessary typing imports as many are now in the standard builtins

## Benefits

- Faster dependency resolution with uv
- Better project metadata with pyproject.toml
- Cleaner separation of development dependencies
- More standardized approach to modern Python packaging
- Ability to leverage the latest Python 3.13 features

## Base directory

- Ensure all code is placed within the `src/gg_api_mcp_server` directory
- Handle imports accordingly by using the appropriate package path
- the main file is `src/gg_api_mcp_server/server.py`

## HTTP request client

Use httpx to make all HTTP requests

## Typing

- use python typing for python > 3.12
- use direct python type instead of importing from typing.

### ❌ Incorrect
from typing import Dict, List

def my_func(my_dict: Dict, my_list: List):
    ...


### ✅ Correct

def my_func(my_dict: dict, my_list: list):
    ...