FastMCP

https://github.com/stevens507/fastmcp
Admin
FastMCP is a Python framework for building Model Context Protocol (MCP) servers, enabling...
Tokens:34,449
Snippets:385
Trust Score:4.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Run the Server

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Start the server in development mode.

```bash
# Ejecutar directamente
python main.py

# O usando el script
chmod +x run_fastmcp.sh
./run_fastmcp.sh
```

--------------------------------

### Define Environment Configuration

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Example content for the .env file.

```bash
# Archivo: .env
MCP_HOST=0.0.0.0
MCP_PORT=8001
MCP_TRANSPORT=http
BACKEND_URL=http://localhost:8002
CORS_ORIGINS=*
DEBUG=true
FORCE_HTTP_MODE=false
REQUEST_TIMEOUT=5
AGENT_TIMEOUT=3
LOG_LEVEL=INFO
```

--------------------------------

### Update Appointment Usage Examples

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/appointment-tools.md

Examples demonstrating how to update specific fields, multiple fields, or handle errors when no valid fields are provided.

```python
# Cambiar horario
result = appointment_tools.update_appointment(
    "apt-123",
    start_time="2024-12-20T15:00:00Z",
    end_time="2024-12-20T16:00:00Z"
)

# Cambiar ubicación
result = appointment_tools.update_appointment(
    "apt-123",
    location="https://meet.google.com/abc123"
)

# Cambiar múltiples campos
result = appointment_tools.update_appointment(
    "apt-123",
    title="Reunión urgente",
    description="Cambio de fecha por emergencia",
    status="scheduled"
)

# Error: sin campos válidos
result = appointment_tools.update_appointment("apt-123")
# {"error": "No se proporcionaron campos válidos para actualizar"}
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Initialize the .env file from the example template.

```bash
# Crear archivo de configuración
cp .env.example .env

# Editar con tus valores
nano .env  # o code .env
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Install the necessary Python packages for the FastMCP server.

```bash
pip install fastmcp requests pydantic aiofiles fastapi uvicorn python-dotenv
```

--------------------------------

### Clone and Prepare Environment

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Commands to clone the repository, set up a virtual environment, and install dependencies.

```bash
# Clonar el repositorio
git clone <tu-repositorio>
cd fastmcp

# Crear entorno virtual
python -m venv venv

# Activar entorno virtual
# En Linux/Mac:
source venv/bin/activate
# En Windows:
# venv\Scripts\activate

# Instalar dependencias
pip install -r requirements.txt
```

--------------------------------

### Environment Variable Configuration

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/task-tools.md

Example of setting the backend URL in a .env file.

```text
BACKEND_URL=https://api.empresa.com
```

--------------------------------

### Full Project Replication

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Steps to clone the project structure, create base files, and install dependencies.

```bash
# 1. Clonar estructura
mkdir mi-fastmcp && cd mi-fastmcp
mkdir tools

# 2. Crear archivos base
touch main.py config.py requirements.txt Dockerfile run_fastmcp.sh
touch __init__.py tools/__init__.py tools/task_tools.py tools/appointment_tools.py

# 3. Copiar dependencias
cat > requirements.txt << 'EOF'
fastmcp
requests
pydantic
aiofiles
fastapi
uvicorn[standard]
python-dotenv
EOF

# 4. Copiar configuración
cat > .env << 'EOF'
MCP_HOST=0.0.0.0
MCP_PORT=8001
MCP_TRANSPORT=http
BACKEND_URL=http://localhost:8002
CORS_ORIGINS=*
DEBUG=true
FORCE_HTTP_MODE=false
REQUEST_TIMEOUT=5
AGENT_TIMEOUT=3
LOG_LEVEL=INFO
EOF

# 5. Instalar y ejecutar
pip install -r requirements.txt
python main.py
```

--------------------------------

### Implementing Authentication

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/endpoints.md

Example of adding HTTPBearer authentication to a tool endpoint.

```python
from fastapi import Depends, HTTPException
from fastapi.security import HTTPBearer

security = HTTPBearer()

@http_app.post("/tools/{tool_name}")
async def call_tool(tool_name: str, request: Request, credentials = Depends(security)):
    # Verificar token en credentials.credentials
    # ...
```

--------------------------------

### Usage examples for list_tasks

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/task-tools.md

Demonstrates how to retrieve tasks using various filter combinations.

```python
# Listar todas las tareas
all_tasks = task_tools.list_tasks()

# Listar tareas pendientes
pending = task_tools.list_tasks(status="pending")

# Listar tareas urgentes de desarrollo
urgent = task_tools.list_tasks(
    priority="urgent",
    category="desarrollo"
)

# Listar tareas completadas
completed = task_tools.list_tasks(status="completed")
```

--------------------------------

### Verify System Prerequisites

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Check for required Python, pip, and curl versions before installation.

```bash
# Python 3.11 o superior
python --version  # >= 3.11

# pip para instalar dependencias
pip --version

# curl para verificaciones (opcional)
curl --version
```

--------------------------------

### Schedule Appointment Usage Examples

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/appointment-tools.md

Demonstrates scheduling a simple appointment and one with full details.

```python
from tools.appointment_tools import appointment_tools

# Cita simple
result = appointment_tools.schedule_appointment(
    title="Reunión de standup",
    start_time="2024-12-15T09:00:00Z"
)

# Cita con todos los detalles
result = appointment_tools.schedule_appointment(
    title="Presentación de proyecto",
    start_time="2024-12-20T14:00:00Z",
    duration_minutes=90,
    description="Presentación de resultados Q4",
    location="Sala de conferencias A",
    participants=[
        {"email": "jefe@empresa.com", "status": "accepted"},
        {"email": "cliente@empresa.com", "status": "pending"},
        {"email": "equipo@empresa.com", "status": "pending"}
    ]
)
```

--------------------------------

### Dockerfile Configuration

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

A lightweight Dockerfile setup for containerizing a FastMCP application.

```dockerfile
FROM python:3.11-slim      # Imagen base ligera
WORKDIR /app               # Directorio de trabajo
COPY requirements.txt .    # Copiar dependencias
RUN pip install --no-cache-dir -r requirements.txt  # Instalar
COPY . .                   # Copiar código fuente
EXPOSE 8001                # Puerto de exposición
CMD ["python", "main.py"]  # Comando de inicio
```

--------------------------------

### GET /tools

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/endpoints.md

Lists all MCP tools currently available on the server.

```APIDOC
## GET /tools

### Description
Lists all MCP tools available on the server.

### Method
GET

### Endpoint
/tools

### Response
#### Success Response (200)
- **tools** (array) - A list of available tool names.

#### Response Example
{
  "tools": [
    "create_task",
    "list_tasks",
    "update_task",
    "delete_task",
    "complete_task",
    "schedule_appointment",
    "check_availability",
    "list_appointments",
    "update_appointment",
    "cancel_appointment",
    "get_task_summary",
    "get_appointment_summary",
    "get_all_data"
  ]
}
```

--------------------------------

### Verificar Estado del Servicio

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/00-INICIO.md

Realiza una petición GET para comprobar la disponibilidad del servidor.

```bash
curl http://localhost:8001/health
```

--------------------------------

### Filter Tasks by Status and Priority

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/types.md

Example of a GET request using multiple query parameters to filter tasks.

```http
GET /api/v1/tasks?user_id=default-user&status=pending&priority=high
```

--------------------------------

### Participants List Format

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/appointment-tools.md

Example structure for the participants list parameter.

```python
participants = [
    {"email": "user1@empresa.com", "status": "pending"},
    {"email": "user2@empresa.com", "status": "pending"},
    {"email": "user3@empresa.com", "status": "accepted"}
]
```

--------------------------------

### Get Task Summary Tool

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Defines the tool to retrieve task statistics and provides an example of how to access the returned data.

```python
@mcp.tool
def get_task_summary() -> dict
```

```json
{
    "total_tasks": int,
    "by_status": {
        "pending": int,
        "in_progress": int,
        "completed": int,
        "cancelled": int
    },
    "by_priority": {
        "low": int,
        "medium": int,
        "high": int,
        "urgent": int
    }
}
```

```python
summary = mcp_tools.get_task_summary()
print(f"Total: {summary['total_tasks']}")
print(f"Pendientes: {summary['by_status']['pending']}")
print(f"Urgentes: {summary['by_priority']['urgent']}")
```

--------------------------------

### Production CORS Configuration

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/endpoints.md

Example of specifying allowed domains in the .env file.

```text
CORS_ORIGINS=https://app.empresa.com,https://dashboard.empresa.com
```

--------------------------------

### GET /api/v1/appointments/

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/appointment-tools.md

Lists all appointments.

```APIDOC
## GET /api/v1/appointments/

### Description
Retrieves a list of all appointments.

### Method
GET

### Endpoint
/api/v1/appointments/
```

--------------------------------

### Usage examples for update_task

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/task-tools.md

Demonstrates updating single or multiple task fields, including handling cases with no valid fields provided.

```python
# Actualizar un campo
result = task_tools.update_task(
    "task-123",
    status="in_progress"
)

# Actualizar múltiples campos
result = task_tools.update_task(
    "task-123",
    status="completed",
    priority="low",
    category="archived"
)

# Error: sin campos válidos
result = task_tools.update_task("task-123")
# {"error": "No se proporcionaron campos válidos para actualizar"}
```

--------------------------------

### GET /mcp

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/endpoints.md

The native MCP entry point for MCP clients connecting via HTTP.

```APIDOC
## GET /mcp

### Description
Punto de entrada para protocolo MCP nativo. Usado por clientes MCP que se conectan vía HTTP.

### Method
GET

### Endpoint
/mcp

### Response
#### Success Response (200)
- **OK** - Solicitud exitosa

#### Error Handling
- **400** - Bad Request: Parámetros inválidos o faltantes
- **404** - Not Found: Herramienta no existe
- **500** - Internal Server Error: Error no capturado
```

--------------------------------

### Get a task

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/task-tools.md

Retrieves the full details of a specific task by its ID.

```python
@staticmethod
def get_task(task_id: str) -> dict
```

```python
task = task_tools.get_task("task-123")
print(task["title"])
print(task["status"])
```

--------------------------------

### Appointment Duration Calculation Logic

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/appointment-tools.md

Illustrates how the system calculates the end time based on the start time and duration in minutes.

```text
# Entrada: start_time="2024-12-15T14:00:00Z", duration_minutes=90
# Cálculo: 14:00:00 + 90 minutos
# Salida: end_time="2024-12-15T15:30:00+00:00"
```

--------------------------------

### Get Appointment Summary Tool

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Defines the tool to retrieve appointment statistics.

```python
@mcp.tool
def get_appointment_summary() -> dict
```

```json
{
    "total_appointments": int,
    "by_status": {
        "scheduled": int,
        "completed": int,
        "cancelled": int,
        "missed": int
    }
}
```

--------------------------------

### User ID Parameter Implementation

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/task-tools.md

Example of modifying function signatures to accept a user_id for authentication.

```python
# Modificar en main.py o task_tools.py
def create_task(title: str, user_id: str = "default-user", ...):
    # ...
    params={"user_id": user_id}
```

--------------------------------

### Get All Data Tool

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Defines the tool to export all task and appointment data for backup or analysis purposes.

```python
@mcp.tool
def get_all_data() -> dict
```

```json
{
    "tasks": {...},           # Resultado de list_tasks()
    "appointments": {...},    # Resultado de list_appointments()
    "timestamp": "2024-01-01T10:00:00Z"
}
```

--------------------------------

### Filter Appointments by Date and Status

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/types.md

Example of a GET request to filter appointments using date and status parameters.

```http
GET /api/v1/appointments?user_id=default-user&date_filter=2024-12-15&status=scheduled
```

--------------------------------

### Retrieve Tasks with User ID

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/types.md

Example of a GET request to fetch tasks filtered by a specific user ID.

```http
GET /api/v1/tasks?user_id=default-user
```

--------------------------------

### Common Error Examples

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/types.md

Examples of specific error messages encountered during API operations.

```python
{
    "error": "Error al crear tarea: HTTPConnectionPool(host='localhost', port=8002): Max retries exceeded"
}
```

```python
{
    "error": "Error al crear tarea: Read timed out"
}
```

```python
{
    "error": "TypeError: missing required positional argument: 'title'"
}
```

```python
{
    "error": "Tool 'nonexistent_tool' not found"
}
```

```python
{
    "error": "No se proporcionaron campos válidos para actualizar"
}
```

```python
{
    "error": "Formato de fecha inválido: Invalid isoformat string: '2024-13-45T00:00:00'"
}
```

--------------------------------

### Log Server Initialization

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Prints startup information when running in HTTP mode.

```python
print(f"🚀 Iniciando servidor FastMCP")
print(f"🔗 Backend URL: {BACKEND_URL}")
print("📋 Servidor MCP con herramientas de tareas y citas")
```

--------------------------------

### Create a basic MCP server with FastMCP

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Initializes a FastMCP server instance and defines a tool using the @mcp.tool decorator.

```python
# ¡Crear un servidor MCP es así de simple!
from fastmcp import FastMCP

mcp = FastMCP("Mi Servidor")

@mcp.tool
def saludar(nombre: str) -> str:
    """Saluda a alguien"""
    return f"¡Hola {nombre}!"

if __name__ == "__main__":
    mcp.run()  # ¡Ya tienes un servidor MCP!
```

--------------------------------

### GET /api/v1/appointments/{id}

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/appointment-tools.md

Retrieves a specific appointment.

```APIDOC
## GET /api/v1/appointments/{id}

### Description
Fetches the details of a specific appointment by its ID.

### Method
GET

### Endpoint
/api/v1/appointments/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the appointment.
```

--------------------------------

### FastMCP Main Server Implementation

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Entry point for the FastMCP server, demonstrating tool registration and mode auto-detection.

```python
# Estructura básica
mcp = FastMCP("Gestor Tareas y Citas MCP")

# Herramientas de tareas
@mcp.tool
def create_task(...): pass
@mcp.tool  
def list_tasks(...): pass
# ... más herramientas

# Herramientas de citas
@mcp.tool
def schedule_appointment(...): pass
# ... más herramientas

# Auto-detección de modo
if __name__ == "__main__":
    # stdio para clientes MCP, HTTP para testing
    if not sys.stdin.isatty():
        mcp.run()  # modo stdio
    else:
        # modo HTTP con FastAPI wrapper
```

--------------------------------

### Testear herramientas individualmente

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Realiza una petición POST directa para verificar el funcionamiento de una herramienta específica.

```bash
# Test HTTP directo
curl -X POST http://localhost:8001/tools/create_task \
  -H "Content-Type: application/json" \
  -d '{"title": "Test task"}'
```

--------------------------------

### GET /health

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/endpoints.md

Verifies that the server is running and connected to the backend.

```APIDOC
## GET /health

### Description
Verifies that the server is running and that it can connect to the backend.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the server.
- **backend_url** (string) - The URL of the connected backend.

#### Response Example
{
  "status": "healthy",
  "backend_url": "http://localhost:8002"
}
```

--------------------------------

### Implement Main Server Logic

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Initialize the FastMCP server and define a tool using the @mcp.tool decorator.

```python
# main.py es el corazón del servidor
from fastmcp import FastMCP

# Crear servidor FastMCP
mcp = FastMCP("Gestor Tareas y Citas MCP")

# Decorador @mcp.tool convierte función Python en herramienta MCP
@mcp.tool
def create_task(title: str, description: str = "") -> dict:
    """Crear una nueva tarea"""
    return task_tools.create_task(title, description)
```

--------------------------------

### GET /health

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/RESUMEN-EJECUTIVO.md

Verifies the current operational status of the FastMCP server.

```APIDOC
## GET /health

### Description
Verifies the current operational status of the FastMCP server.

### Method
GET

### Endpoint
/health
```

--------------------------------

### Programar Cita vía HTTP

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/00-INICIO.md

Realiza una petición POST para programar una cita especificando título, hora de inicio y duración.

```bash
curl -X POST http://localhost:8001/tools/schedule_appointment \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Reunión",
    "start_time": "2024-12-15T14:00:00Z",
    "duration_minutes": 60
  }'
```

--------------------------------

### Production Deployment Commands

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Commands to configure environment variables and run the server using Gunicorn or Uvicorn.

```bash
# 1. Variables de entorno
export MCP_HOST=0.0.0.0
export MCP_PORT=8001
export BACKEND_URL=https://tu-api.com
export MCP_TRANSPORT=http

# 2. Usar servidor ASGI robusto
pip install gunicorn
gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:http_app

# 3. O usar uvicorn directamente
uvicorn main:http_app --host 0.0.0.0 --port 8001 --workers 4
```

--------------------------------

### schedule_appointment

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/appointment-tools.md

Schedules a new appointment with a title, start time, and duration.

```APIDOC
## schedule_appointment

### Description
Creates a new appointment. The start_time must be in ISO 8601 format with an explicit timezone.

### Parameters
- **title** (string) - Required - The title of the appointment.
- **start_time** (string) - Required - ISO 8601 timestamp (e.g., 2024-12-15T14:00:00Z).
- **duration_minutes** (integer) - Required - Duration of the appointment in minutes.

### Example
```python
result = appointment_tools.schedule_appointment(
    title="Reunión ahora",
    start_time="2024-12-15T14:00:00Z",
    duration_minutes=30
)
```
```

--------------------------------

### Acceder a logs del sistema

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Comandos para visualizar logs del servidor y habilitar el seguimiento de peticiones.

```bash
# Logs del servidor
tail -f /var/log/fastmcp.log

# Logs de requests al backend
export DEBUG=true  # Habilita logs de requests

# Logs de cliente MCP (Cursor)
# Ver en: Output > Model Context Protocol
```

--------------------------------

### Inicialización de Instancia FastMCP

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Creación del objeto global mcp necesario para registrar herramientas y configurar el servidor.

```python
mcp = FastMCP("Gestor Tareas y Citas MCP")
```

--------------------------------

### Estructura General del Servidor

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Esqueleto básico para inicializar el servidor FastMCP y manejar la ejecución en modo stdio o HTTP.

```python
from fastmcp import FastMCP

# Crear servidor FastMCP
mcp = FastMCP("Gestor Tareas y Citas MCP")

# Definir herramientas con decorador @mcp.tool
@mcp.tool
def create_task(...) -> dict: ...

# Más herramientas...

# Punto de entrada
if __name__ == "__main__":
    # Detección automática de modo
    if modo_stdio:
        mcp.run()  # Servidor stdio
    else:
        uvicorn.run(http_app)  # Servidor HTTP
```

--------------------------------

### Verify Server Functionality

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Test the server health, list tools, and invoke a tool via HTTP requests.

```bash
# Verificar servidor HTTP
curl http://localhost:8001/health

# Ver herramientas disponibles
curl http://localhost:8001/tools

# Llamar una herramienta
curl -X POST http://localhost:8001/tools/create_task \
     -H "Content-Type: application/json" \
     -d '{"title": "Mi primera tarea"}'
```

--------------------------------

### GET /api/v1/appointments

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/types.md

Retrieves a list of appointments based on user ID and date filters.

```APIDOC
## GET /api/v1/appointments

### Description
Retrieves appointments for a specific user filtered by date and status.

### Method
GET

### Endpoint
/api/v1/appointments

### Parameters
#### Query Parameters
- **user_id** (string) - Required - Identifier of the user
- **date_filter** (string) - Optional - Specific date (YYYY-MM-DD)
- **status** (string) - Optional - Status of the appointment
```

--------------------------------

### Configuración de entorno para desarrollo

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/configuration.md

Ejemplo de configuración básica para entornos de desarrollo local.

```env
# Servidor MCP
MCP_HOST=0.0.0.0
MCP_PORT=8001
MCP_TRANSPORT=http

# Backend API
BACKEND_URL=http://localhost:8002

# Desarrollo
DEBUG=true
LOG_LEVEL=INFO
FORCE_HTTP_MODE=false
```

--------------------------------

### GET /api/v1/tasks

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/types.md

Retrieves a list of tasks based on user ID and optional filters.

```APIDOC
## GET /api/v1/tasks

### Description
Retrieves tasks for a specific user with optional filtering by status, priority, and category.

### Method
GET

### Endpoint
/api/v1/tasks

### Parameters
#### Query Parameters
- **user_id** (string) - Required - Identifier of the user (default: "default-user")
- **status** (string) - Optional - Status of the task
- **priority** (string) - Optional - Priority level of the task
- **category** (string) - Optional - Category of the task
```

--------------------------------

### Listado de herramientas disponibles

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/errors.md

Comando para listar las herramientas registradas y evitar errores de tipo 404.

```bash
curl http://localhost:8001/tools
# {"tools": ["create_task", "list_tasks", ...]}
```

--------------------------------

### Ejecución del Servidor en Modo Stdio

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Inicia el servidor utilizando el protocolo MCP binario a través de la salida estándar.

```bash
python main.py
# o
echo "" | python main.py
```

--------------------------------

### FastMCP CLI Usage

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Using the FastMCP CLI to initialize, configure, and run a server.

```bash
# 1. Instalar FastMCP
pip install fastmcp

# 2. Crear servidor base
cat > mi_servidor.py << 'EOF'
from fastmcp import FastMCP

mcp = FastMCP("Mi Servidor")

@mcp.tool
def mi_herramienta(param: str) -> str:
    """Mi primera herramienta"""
    return f"Procesé: {param}"

if __name__ == "__main__":
    mcp.run()
EOF

# 3. Crear configuración
cat > fastmcp.json << 'EOF'
{
  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
  "entrypoint": {
    "file": "mi_servidor.py",
    "object": "mcp"
  },
  "environment": {
    "dependencies": ["requests", "pydantic"]
  },
  "deployment": {
    "transport": "http",
    "port": 8001
  }
}
EOF

# 4. Ejecutar
fastmcp run
```

--------------------------------

### Configuración de servidor MCP para Claude Desktop

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/RESUMEN-EJECUTIVO.md

Configuración necesaria en el archivo claude_desktop_config.json para integrar el servidor FastMCP.

```json
{
  "mcpServers": {
    "fastmcp-tareas": {
      "command": "python",
      "args": ["/ruta/absoluta/al/main.py"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

--------------------------------

### GET /api/v1/tasks/

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/task-tools.md

Retrieves a list of tasks based on optional status, priority, and category filters.

```APIDOC
## GET /api/v1/tasks/

### Description
List tasks with optional filtering capabilities. The request automatically includes a default user ID.

### Method
GET

### Endpoint
{BACKEND_URL}/api/v1/tasks/

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by status: pending, in_progress, completed, cancelled
- **priority** (string) - Optional - Filter by priority: low, medium, high, urgent
- **category** (string) - Optional - Filter by category

### Response
#### Success Response (200)
- **tasks** (list) - List of task objects

#### Response Example
{
  "tasks": []
}
```

--------------------------------

### Programar una cita con AppointmentTool

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/INDEX.md

Ejemplo de uso para programar una cita, incluyendo la definición de participantes y la duración en minutos.

```python
from tools.appointment_tools import appointment_tools

result = appointment_tools.schedule_appointment(
    title="Reunión de proyecto",
    start_time="2024-12-15T14:00:00Z",
    duration_minutes=90,
    participants=[
        {"email": "user1@empresa.com", "status": "pending"}
    ]
)
```

--------------------------------

### Configuración de variables de entorno

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/RESUMEN-EJECUTIVO.md

Variables necesarias para definir el comportamiento del servidor, backend y niveles de log.

```bash
# Servidor
MCP_HOST=0.0.0.0
MCP_PORT=8001
MCP_TRANSPORT=http

# Backend
BACKEND_URL=http://localhost:8002
REQUEST_TIMEOUT=5

# Desarrollo
DEBUG=true
LOG_LEVEL=INFO
```

--------------------------------

### Configuración de entorno para producción

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/configuration.md

Ejemplo de configuración optimizada para entornos de producción con seguridad y timeouts ajustados.

```env
# Servidor MCP
MCP_HOST=0.0.0.0
MCP_PORT=8001
MCP_TRANSPORT=http

# Backend API - URL de producción
BACKEND_URL=https://api.empresa.com

# Seguridad y CORS
CORS_ORIGINS=https://app.empresa.com,https://dashboard.empresa.com

# Desempeño
DEBUG=false
LOG_LEVEL=WARNING
FORCE_HTTP_MODE=true
REQUEST_TIMEOUT=10
AGENT_TIMEOUT=5
```

--------------------------------

### Importación de constantes de configuración

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/configuration.md

Importa las variables de entorno y constantes necesarias para el funcionamiento del servidor.

```python
from config import (
    MCP_HOST, MCP_PORT, MCP_TRANSPORT,
    BACKEND_URL, REQUEST_TIMEOUT, AGENT_TIMEOUT,
    LOG_LEVEL, DEBUG, CORS_ORIGINS, FORCE_HTTP_MODE,
    SERVER_NAME, SERVER_VERSION, SERVER_DESCRIPTION,
    AVAILABLE_TOOLS, AVAILABLE_RESOURCES
)
```

--------------------------------

### Verificar configuración en Python

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Inspecciona las variables de configuración cargadas en el entorno de ejecución.

```python
# En Python shell
from config import *
print(f"Backend: {BACKEND_URL}")
print(f"Transport: {MCP_TRANSPORT}")
```

--------------------------------

### Resolver error de módulo no encontrado

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Instala el paquete fastmcp o asegúrate de que el entorno virtual esté activo.

```bash
# Instalar dependencias
pip install fastmcp

# O verificar entorno virtual
source venv/bin/activate
```

--------------------------------

### Configuración de variables de entorno

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/RESUMEN-EJECUTIVO.md

Variables mínimas requeridas en el archivo .env para la ejecución del servidor.

```bash
BACKEND_URL=http://localhost:8002
MCP_PORT=8001
MCP_TRANSPORT=http
```

--------------------------------

### Implement HTTP Retries with Requests

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/task-tools.md

Use this pattern to configure a requests session with automatic retries using urllib3. Ensure the requests and urllib3 libraries are installed.

```python
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def requests_with_retries():
    session = requests.Session()
    retry = Retry(total=3, backoff_factor=0.5)
    adapter = HTTPAdapter(max_retries=retry)
    session.mount('http://', adapter)
    session.mount('https://', adapter)
    return session
```

--------------------------------

### Verificar estado del backend

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/errors.md

Comandos para diagnosticar la conectividad y el estado de escucha del puerto del backend.

```bash
# Health check del backend
curl http://localhost:8002/health

# Ver si está escuchando
netstat -tuln | grep 8002
lsof -i :8002

# Test de conectividad
ping localhost
telnet localhost 8002
```

--------------------------------

### Crear Tarea vía HTTP

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/00-INICIO.md

Realiza una petición POST para crear una nueva tarea con título, prioridad y fecha de vencimiento.

```bash
curl -X POST http://localhost:8001/tools/create_task \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mi tarea",
    "priority": "high",
    "due_date": "2024-12-31T23:59:59Z"
  }'
```

--------------------------------

### Project File Structure

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Visual representation of the project directory layout.

```text
fastmcp/
├── main.py                    # 🎯 Servidor FastMCP principal
├── config.py                  # ⚙️  Configuración y variables
├── requirements.txt           # 📦 Dependencias Python
├── Dockerfile                 # 🐳 Configuración Docker
├── run_fastmcp.sh            # 🚀 Script de ejecución
├── __init__.py               # 📝 Archivo de módulo Python
└── tools/                    # 🛠️ Herramientas MCP
    ├── __init__.py           # 📝 Inicializador de módulo
    ├── task_tools.py         # ✅ Herramientas de tareas
    └── appointment_tools.py  # 📅 Herramientas de citas
```

--------------------------------

### Implementación de create_task

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Lógica interna para delegar la creación de tareas al módulo task_tools.

```python
return task_tools.create_task(title, description, due_date, priority, category, tags or [])
```

--------------------------------

### Configuración de entorno para Docker Compose

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/configuration.md

Ejemplo de configuración para conectar servicios dentro de contenedores Docker.

```env
# Conectar entre contenedores
MCP_HOST=0.0.0.0
MCP_PORT=8001
MCP_TRANSPORT=http
BACKEND_URL=http://backend:8002

# Modo HTTP obligatorio en contenedor
FORCE_HTTP_MODE=true

# Logging
DEBUG=false
LOG_LEVEL=INFO
```

--------------------------------

### Conversión de fechas en Python

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/types.md

Métodos para parsear cadenas ISO 8601 y generar marcas de tiempo actuales utilizando datetime.

```python
from datetime import datetime

# Parsear con Z
dt = datetime.fromisoformat("2024-12-15T14:00:00Z".replace('Z', '+00:00'))

# Parsear con offset
dt = datetime.fromisoformat("2024-12-15T14:00:00+00:00")

# Generar actual
now = datetime.now(timezone.utc).isoformat()
```

--------------------------------

### Integración con Python

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/RESUMEN-EJECUTIVO.md

Ejemplo de importación y uso directo de las herramientas de tareas y citas en un script de Python.

```python
from tools.task_tools import task_tools
from tools.appointment_tools import appointment_tools

# Crear tarea
task = task_tools.create_task("Nueva tarea")
print(task["id"])

# Programar cita
apt = appointment_tools.schedule_appointment(
    "Reunión",
    "2024-12-15T14:00:00Z"
)
```

--------------------------------

### Backend URL Configuration

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/task-tools.md

Configuration for the backend URL using environment variables with a default fallback.

```python
BACKEND_URL = os.getenv("BACKEND_URL", "http://localhost:8002") + "/api/v1"
```

--------------------------------

### Ejecución de herramienta vía cURL

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/RESUMEN-EJECUTIVO.md

Ejemplo de solicitud POST para ejecutar una herramienta específica en el servidor.

```bash
curl -X POST http://localhost:8001/tools/create_task \
  -H "Content-Type: application/json" \
  -d '{"title": "Nueva tarea", "priority": "high"}'
```

--------------------------------

### Configuración con Variables de Entorno

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Define explícitamente el modo de transporte o fuerza el modo HTTP mediante variables de entorno.

```bash
export MCP_TRANSPORT=stdio
python main.py

# O HTTP obligatorio
export FORCE_HTTP_MODE=true
python main.py
```

--------------------------------

### Definición de create_task

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Firma del decorador para la herramienta de creación de tareas.

```python
@mcp.tool
def create_task(
    title: str,
    description: str = "",
    due_date: str = None,
    priority: str = "medium",
    category: str = "personal",
    tags: list = None
) -> dict
```

--------------------------------

### Dependencias del proyecto

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/RESUMEN-EJECUTIVO.md

Lista de paquetes requeridos para el funcionamiento del framework FastMCP y sus servicios asociados.

```text
fastmcp           # Framework MCP
fastapi           # Framework web
uvicorn           # Servidor ASGI
requests          # HTTP client
pydantic          # Validación de datos
python-dotenv     # Cargar .env
```

--------------------------------

### Obtener resumen de tareas

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/RESUMEN-EJECUTIVO.md

Ejemplo de invocación de la función get_task_summary para obtener estadísticas de tareas.

```python
get_task_summary()
# Respuesta:
# {
#     "total_tasks": 25,
#     "by_status": {"pending": 10, "in_progress": 8, ...},
#     "by_priority": {"low": 5, "medium": 12, ...}
# }
```

--------------------------------

### Verificar estado del servidor

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/errors.md

Utiliza comandos curl para comprobar la disponibilidad del servidor y listar las herramientas disponibles.

```bash
# Health check
curl http://localhost:8001/health

# Listar herramientas
curl http://localhost:8001/tools

# Prueba simple
curl -X POST http://localhost:8001/tools/get_task_summary \
  -H "Content-Type: application/json" \
  -d '{}'
```

--------------------------------

### POST /tools/{tool_name}

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/endpoints.md

Executes a specific MCP tool with the provided parameters.

```APIDOC
## POST /tools/{tool_name}

### Description
Executes a specific MCP tool with the parameters provided in the JSON request body.

### Method
POST

### Endpoint
/tools/{tool_name}

### Parameters
#### Path Parameters
- **tool_name** (string) - Required - The name of the tool to execute.

### Response
#### Success Response (200)
- **result** (object) - The result of the tool execution (varies by tool).

#### Error Response (404)
- **error** (string) - Error message when the tool is not found.

#### Error Response (400)
- **error** (string) - Error message for parameter validation issues.

#### Error Response (500)
- **error** (string) - Error message for internal server errors.
```

--------------------------------

### Validación de configuración activa

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/configuration.md

Script para imprimir y verificar los valores actuales de las variables de configuración cargadas en la aplicación.

```python
from config import (
    MCP_HOST, MCP_PORT, BACKEND_URL, MCP_TRANSPORT,
    DEBUG, LOG_LEVEL, CORS_ORIGINS
)

print(f"Host: {MCP_HOST}")
print(f"Puerto: {MCP_PORT}")
print(f"Backend: {BACKEND_URL}")
print(f"Transporte: {MCP_TRANSPORT}")
print(f"Debug: {DEBUG}")
print(f"Level: {LOG_LEVEL}")
print(f"CORS: {CORS_ORIGINS}")
```

--------------------------------

### Depurar conexión de cliente MCP

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Verifica el modo de transporte stdio y la configuración de rutas del cliente.

```bash
# Verificar modo stdio
export MCP_TRANSPORT=stdio
echo "" | python main.py

# Verificar ruta absoluta en configuración cliente
```

--------------------------------

### Diagnosticar error de backend no disponible

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Verifica el estado del backend mediante curl y ajusta la URL en el archivo .env.

```bash
# Verificar backend
curl http://localhost:8002/health

# Solución: Ajustar URL en .env
BACKEND_URL=http://tu-backend-real.com
```

--------------------------------

### Programar Cita con cURL

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/endpoints.md

Crea una nueva cita especificando horario, duración, ubicación y lista de participantes.

```bash
curl -X POST http://localhost:8001/tools/schedule_appointment \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Reunión de revisión",
    "start_time": "2024-12-15T14:00:00",
    "duration_minutes": 60,
    "location": "Sala de conferencias A",
    "participants": [
      {"email": "user1@empresa.com", "status": "pending"},
      {"email": "user2@empresa.com", "status": "pending"}
    ]
  }'
```

```json
{
  "id": "apt-456",
  "title": "Reunión de revisión",
  "start_time": "2024-12-15T14:00:00",
  "end_time": "2024-12-15T15:00:00",
  "location": "Sala de conferencias A",
  "participants": [
    {"email": "user1@empresa.com", "status": "pending"},
    {"email": "user2@empresa.com", "status": "pending"}
  ]
}
```

--------------------------------

### Activar logs detallados

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Configura las variables de entorno para habilitar el modo de depuración.

```bash
export DEBUG=true
export LOG_LEVEL=DEBUG
python main.py
```

--------------------------------

### Definición de herramientas disponibles

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/configuration.md

Lista de herramientas MCP registradas y disponibles para su uso en el servidor.

```python
AVAILABLE_TOOLS = [
    "create_task",           # Crear nueva tarea
    "list_tasks",            # Listar tareas con filtros
    "update_task",           # Actualizar tarea
    "delete_task",           # Eliminar tarea
    "complete_task",         # Marcar como completada
    "schedule_appointment",  # Programar cita
    "check_availability",    # Verificar disponibilidad
    "list_appointments",     # Listar citas
    "update_appointment",    # Actualizar cita
    "cancel_appointment",    # Cancelar cita
    "get_task_summary",      # Resumen de tareas
    "get_appointment_summary" # Resumen de citas
]
```

--------------------------------

### Crear tarea desde cliente MCP

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/RESUMEN-EJECUTIVO.md

Ejemplo de invocación de la función create_task con parámetros de título, prioridad y fecha de vencimiento.

```python
# Cliente MCP
create_task(
    title="Implementar feature X",
    priority="high",
    due_date="2024-12-25T17:00:00Z"
)
# Respuesta: {"id": "task-1", "status": "pending", ...}
```

--------------------------------

### Envolver herramientas de citas como funciones MCP

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/appointment-tools.md

Utiliza el decorador @mcp.tool para exponer funciones de gestión de citas al servidor MCP.

```python
from tools.appointment_tools import appointment_tools

@mcp.tool
def schedule_appointment(
    title: str, 
    start_time: str, 
    duration_minutes: int = 60, 
    ...
) -> dict:
    """Programar una nueva cita"""
    return appointment_tools.schedule_appointment(
        title, start_time, duration_minutes, ...
    )

@mcp.tool
def check_availability(start_time: str, end_time: str) -> dict:
    """Verificar disponibilidad de horario"""
    return appointment_tools.check_availability(start_time, end_time)

# ... más herramientas
```

--------------------------------

### Docker Compose Configuration

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Recommended docker-compose.yml for orchestrating the FastMCP service alongside a backend API.

```yaml
# docker-compose.yml
version: '3.8'
services:
  fastmcp:
    build: .
    ports:
      - "8001:8001"
    environment:
      - MCP_TRANSPORT=http
      - BACKEND_URL=http://backend:8002
      - FORCE_HTTP_MODE=true
    depends_on:
      - backend
      
  backend:
    image: tu-backend-api:latest
    ports:
      - "8002:8002"
    environment:
      - DATABASE_URL=postgresql://...
```

--------------------------------

### Crear una tarea con TaskTool

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/INDEX.md

Ejemplo de uso para crear una nueva tarea utilizando la clase task_tools. Verifica la presencia de errores en el resultado antes de acceder al ID de la tarea.

```python
from tools.task_tools import task_tools

result = task_tools.create_task(
    title="Nueva tarea",
    priority="high",
    category="desarrollo"
)

if "error" not in result:
    task_id = result["id"]
```

--------------------------------

### Ejecución del Servidor en Modo HTTP

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Inicia el servidor en modo HTTP, detectando automáticamente el TTY.

```bash
python main.py
# Detecta TTY y cambia a HTTP automáticamente
```

--------------------------------

### List Tools Endpoint Implementation and Usage

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/endpoints.md

Retrieves a list of all available MCP tools registered on the server.

```python
@http_app.get("/tools")
async def list_tools():
    return {"tools": list(TOOL_MAP.keys())}
```

```json
{
  "tools": [
    "create_task",
    "list_tasks",
    "update_task",
    "delete_task",
    "complete_task",
    "schedule_appointment",
    "check_availability",
    "list_appointments",
    "update_appointment",
    "cancel_appointment",
    "get_task_summary",
    "get_appointment_summary",
    "get_all_data"
  ]
}
```

```bash
curl http://localhost:8001/tools
```

--------------------------------

### MCP Tool Integration

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/task-tools.md

Wrapping task tools as MCP functions to enable documentation and automatic serialization.

```python
from tools.task_tools import task_tools

@mcp.tool
def create_task(title: str, description: str = "", ...) -> dict:
    """Crear una nueva tarea"""
    return task_tools.create_task(title, description, ...)

@mcp.tool
def list_tasks(status: str = None, ...) -> dict:
    """Listar tareas con filtros"""
    return task_tools.list_tasks(status, ...)

# ... más herramientas
```

--------------------------------

### Configuración de timeout

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/errors.md

Definición del tiempo de espera para las peticiones al backend.

```python
# En tools/task_tools.py y tools/appointment_tools.py
timeout=5  # segundos
```

--------------------------------

### Configure Cursor Integration

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Add the FastMCP server configuration to the Cursor MCP settings.

```json
{
  "mcpServers": {
    "fastmcp-tareas": {
      "command": "python",
      "args": ["/ruta/absoluta/al/main.py"]
    }
  }
}
```

--------------------------------

### Definición de complete_task

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Firma del decorador para la herramienta de marcado de tareas como completadas.

```python
@mcp.tool
def complete_task(task_id: str) -> dict
```

--------------------------------

### create_task

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Creates a new task with the specified details.

```APIDOC
## create_task

### Description
Creates a new task in the system.

### Parameters
- **title** (str) - Required - The title of the task.
- **description** (str) - Optional - A description of the task.
- **due_date** (str) - Optional - The due date for the task.
- **priority** (str) - Optional - The priority level (default: "medium").
- **category** (str) - Optional - The category (default: "personal").
- **tags** (list) - Optional - A list of tags associated with the task.
```

--------------------------------

### Required Imports

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/api-reference/main-server.md

Essential imports for FastMCP, FastAPI, and project-specific configurations.

```python
import os
import sys
import uvicorn
from fastmcp import FastMCP
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from fastapi.middleware.cors import CORSMiddleware
from tools.task_tools import task_tools
from tools.appointment_tools import appointment_tools
from config import (
    MCP_HOST, MCP_PORT, BACKEND_URL, MCP_TRANSPORT,
    FORCE_HTTP_MODE, CORS_ORIGINS, DEBUG
)
```

--------------------------------

### Manejo de tipos de parámetros en Python

Source: https://github.com/stevens507/fastmcp/blob/main/_autodocs/errors.md

Ejemplo de cómo asegurar que los tipos de datos pasados a las herramientas coincidan con los esperados.

```python
# Asegurar tipos correctos
result = appointment_tools.schedule_appointment(
    title="Reunión",              # string
    start_time="2024-12-15T14:00:00Z",  # string
    duration_minutes=60,          # int, no string
    participants=[{"email": "...", "status": "pending"}]  # list, no dict
)
```

--------------------------------

### Solucionar conflicto de puerto

Source: https://github.com/stevens507/fastmcp/blob/main/README.md

Cambia el puerto en la configuración o termina el proceso que está ocupando el puerto actual.

```bash
# Cambiar puerto en .env
MCP_PORT=8002

# O matar proceso
lsof -ti:8001 | xargs kill -9
```
Tokens:
Raw