Fast MCP

Fast MCP 🚀

🌟 Conecta tus servidores con LLMs en minutos

Los modelos de IA son poderosos, pero necesitan interactuar con tus aplicaciones para ser realmente útiles. Los enfoques tradicionales implican lidiar con:

• 🔄 Protocolos de comunicación complejos y formatos JSON personalizados
• 🔌 Desafíos de integración con diferentes proveedores de modelos
• 🧩 Problemas de compatibilidad entre tu aplicación y las herramientas de IA
• 🧠 Gestionar el estado entre las interacciones de IA y tus datos

Fast MCP resuelve todos estos problemas al proporcionar una implementación limpia y centrada en Ruby del Protocolo de Contexto de Modelo, haciendo que la integración de IA sea un placer, no una tarea.

✨ Características

• 🛠️ API de Herramientas - Permite que los modelos de IA llamen a tus funciones Ruby de forma segura, con validación profunda de argumentos mediante Dry-Schema.
• 📚 API de Recursos - Comparte datos entre tu aplicación y los modelos de IA
• 🔄 Múltiples Transportes - Elige entre STDIO, HTTP o SSE según tus necesidades
• 🧩 Integración con Frameworks - Funciona perfectamente con Rails, Sinatra o cualquier aplicación Rack.
• 🔒 Soporte de Autenticación - Asegura tus endpoints impulsados por IA con facilidad
• 🚀 Actualizaciones en Tiempo Real - Suscríbete a cambios para aplicaciones interactivas
• 🎯 Filtrado Dinámico - Controla el acceso a herramientas/recursos según el contexto de la solicitud (permisos, versiones de API, etc.)

💎 Lo que hace genial a FastMCP

# Define tools for AI models to use
server = FastMcp::Server.new(name: 'popular-users', version: '1.0.0')

# Define a tool by inheriting from FastMcp::Tool
class CreateUserTool < FastMcp::Tool
  description "Create a user"
    # These arguments will generate the needed JSON to be presented to the MCP Client
    # And they will be validated at run time.
    # The validation is based off Dry-Schema, with the addition of the description.
  arguments do
    required(:first_name).filled(:string).description("First name of the user")
    optional(:age).filled(:integer).description("Age of the user")
    required(:address).description("The shipping address").hash do
      required(:street).filled(:string).description("Street address")
      optional(:city).filled(:string).description("City name")
      optional(:zipcode).maybe(:string).description("Postal code")
    end
  end

  def call(first_name:, age: nil, address: {})
    User.create!(first_name:, age:, address:)
  end
end

# Register the tool with the server
server.register_tool(CreateUserTool)

# Share data resources with AI models by inheriting from FastMcp::Resource
class PopularUsers < FastMcp::Resource
  uri "myapp:///users/popular"
  resource_name "Popular Users"
  mime_type "application/json"

  def content
    JSON.generate(User.popular.limit(5).as_json)
  end
end

class User < FastMcp::Resource
  uri "myapp:///users/{id}" # This is a resource template
  resource_name "user"
  mime_type "application/json"

  def content
    id = params[:id] # params are computed from the uri pattern

    JSON.generate(User.find(id).as_json)
  end
end

# Register the resource with the server
server.register_resources(PopularUsers, User)

# Accessing the resource through the server
server.read_resource(PopularUsers.uri)

# Notify the resource content has been updated to clients
server.notify_resource_updated(PopularUsers.variabilized_uri)

# Notifiy the content of a resource from a template has been updated to clients
server.notify_resource_updated(User.variabilized_uri(id: 1))

🎯 Filtrado Dinámico de Herramientas

Controla qué herramientas y recursos están disponibles según el contexto de la solicitud:

# Tag your tools for easy filtering
class AdminTool < FastMcp::Tool
  tags :admin, :dangerous
  description "Perform admin operations"

  def call
    # Admin only functionality
  end
end

# Filter tools based on user permissions
server.filter_tools do |request, tools|
  user_role = request.params['role']

  case user_role
  when 'admin'
    tools # Admins see all tools
  when 'user'
    tools.reject { |t| t.tags.include?(:admin) }
  else
    tools.select { |t| t.tags.include?(:public) }
  end
end

🚂 Implementación rápida para Ruby on Rails

bundle add fast-mcp
bin/rails generate fast_mcp:install

Esto agregará un inicializador configurable fast_mcp.rb

require 'fast_mcp'

FastMcp.mount_in_rails(
  Rails.application,
  name: Rails.application.class.module_parent_name.underscore.dasherize,
  version: '1.0.0',
  path_prefix: '/mcp', # This is the default path prefix
  messages_route: 'messages', # This is the default route for the messages endpoint
  sse_route: 'sse', # This is the default route for the SSE endpoint
  # Add allowed origins below, it defaults to Rails.application.config.hosts
  # allowed_origins: ['localhost', '127.0.0.1', 'example.com', /.*\.example\.com/],
  # localhost_only: true, # Set to false to allow connections from other hosts
  # whitelist specific ips to if you want to run on localhost and allow connections from other IPs
  # allowed_ips: ['127.0.0.1', '::1']
  # authenticate: true,       # Uncomment to enable authentication
  # auth_token: 'your-token' # Required if authenticate: true
) do |server|
  Rails.application.config.after_initialize do
    # FastMcp will automatically discover and register:
    # - All classes that inherit from ApplicationTool (which uses ActionTool::Base)
    # - All classes that inherit from ApplicationResource (which uses ActionResource::Base)
    server.register_tools(*ApplicationTool.descendants)
    server.register_resources(*ApplicationResource.descendants)
    # alternatively, you can register tools and resources manually:
    # server.register_tool(MyTool)
    # server.register_resource(MyResource)
  end
end

El script de instalación también:

• agregará la carpeta app/resources
• agregará la carpeta app/tools
• agregará app/tools/sample_tool.rb
• agregará app/resources/sample_resource.rb
• agregará ApplicationTool para heredar de él
• agregará ApplicationResource para heredar de él también

Convenciones de nombres de clases amigables con Rails

Para aplicaciones Rails, FastMCP proporciona nombres de clases estilo Rails para adaptarse mejor a las convenciones de Rails:

• ActionTool::Base - Un alias para FastMcp::Tool
• ActionResource::Base - Un alias para FastMcp::Resource

Estos se configuran automáticamente en aplicaciones Rails. Puedes usar cualquiera de las dos convenciones de nombres en tu código:

# Using Rails-style naming:
class MyTool < ActionTool::Base
  description "My awesome tool"

  arguments do
    required(:input).filled(:string)
  end

  def call(input:)
    # Your implementation
  end
end

# Using standard FastMcp naming:
class AnotherTool < FastMcp::Tool
  # Both styles work interchangeably in Rails apps
end

Al crear nuevas herramientas o recursos, los generadores usarán la convención de nombres de Rails por defecto:

# app/tools/application_tool.rb
class ApplicationTool < ActionTool::Base
  # Base methods for all tools
end

# app/resources/application_resource.rb
class ApplicationResource < ActionResource::Base
  # Base methods for all resources
end

Configuración fácil con Sinatra

Te dejo que revises la documentación de integración de sinatra dedicada.

🚀 Inicio Rápido

Crea un Servidor con Herramientas y Recursos y transporte STDIO

require 'fast_mcp'

# Create an MCP server
server = FastMcp::Server.new(name: 'my-ai-server', version: '1.0.0')

# Define a tool by inheriting from FastMcp::Tool
class SummarizeTool < FastMcp::Tool
  description "Summarize a given text"

  arguments do
    required(:text).filled(:string).description("Text to summarize")
    optional(:max_length).filled(:integer).description("Maximum length of summary")
  end

  def call(text:, max_length: 100)
    # Your summarization logic here
    text.split('.').first(3).join('.') + '...'
  end
end

# Register the tool with the server
server.register_tool(SummarizeTool)

# Create a resource by inheriting from FastMcp::Resource
class StatisticsResource < FastMcp::Resource
  uri "data/statistics"
  resource_name "Usage Statistics"
  description "Current system statistics"
  mime_type "application/json"

  def content
    JSON.generate({
      users_online: 120,
      queries_per_minute: 250,
      popular_topics: ["Ruby", "AI", "WebDev"]
    })
  end
end

# Register the resource with the server
server.register_resource(StatisticsResource)

# Start the server
server.start

🧪 Pruebas con el inspector

MCP ha desarrollado un inspector muy útil. Puedes usarlo para validar tu implementación. Sugiero que uses los ejemplos que proporcioné con este proyecto como una plantilla fácil. ¡Clona este proyecto y pruébalo!

npx @modelcontextprotocol/inspector examples/server_with_stdio_transport.rb

O para probar con un transporte SSE usando un middleware de rack:

npx @modelcontextprotocol/inspector examples/rack_middleware.rb

O para probar sobre SSE con un middleware de rack autenticado:

npx @modelcontextprotocol/inspector examples/authenticated_rack_middleware.rb

Puedes probar tu implementación personalizada con el inspector oficial de MCP usando:

# Test with a stdio transport:
npx @modelcontextprotocol/inspector path/to/your_ruby_file.rb

# Test with an HTTP / SSE server. In the UI select SSE and input your address.
npx @modelcontextprotocol/inspector

Sinatra

# app.rb
require 'sinatra'
require 'fast_mcp'

use FastMcp::RackMiddleware.new(name: 'my-ai-server', version: '1.0.0') do |server|
  # Register tools and resources here
  server.register_tool(SummarizeTool)
end

get '/' do
  'Hello World!'
end

Integración con Claude Desktop

Agrega tu servidor a la configuración de Claude Desktop en:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "my-great-server": {
      "command": "ruby",
      "args": ["/Users/path/to/your/awesome/fast-mcp/server.rb"]
    }
  }
}

¿Cómo agregar un servidor MCP a Claude, Cursor u otros clientes MCP?

Por favor, consulta configuring_mcp_clients

📊 Especificaciones Soportadas

Característica	Estado
✅ JSON-RPC 2.0	Implementación completa para la comunicación
✅ Definición y Llamada de Herramientas	Define y llama herramientas con tipos de argumentos enriquecidos
✅ Gestión de Recursos y Plantillas	Crea, lee, actualiza y suscríbete a recursos
✅ Opciones de Transporte	STDIO, HTTP y SSE para integración flexible
✅ Integración con Frameworks	Rails, Sinatra, Hanami y cualquier framework compatible con Rack
✅ Autenticación	Asegura tus endpoints de IA con autenticación por token
✅ Soporte de Esquemas	Esquema JSON completo para argumentos de herramientas con validación

🗺️ Casos de Uso

• 🤖 Aplicaciones impulsadas por IA: Conecta LLMs a la funcionalidad de tu aplicación Ruby
• 📊 Paneles en Tiempo Real: Crea paneles con información generada por IA en vivo
• 🔗 Comunicación entre Microservicios: Usa MCP como un protocolo limpio entre servicios
• 📚 Documentación Interactiva: Crea documentación de API mejorada con IA
• 💬 Chatbots y Asistentes: Construye asistentes de IA con acceso a los datos de tu aplicación

🔒 Características de Seguridad

Fast MCP incluye características de seguridad integradas para proteger tus aplicaciones:

Protección contra DNS Rebinding

El transporte HTTP/SSE valida el encabezado Origin en todas las conexiones entrantes para prevenir ataques de DNS rebinding, que podrían permitir que sitios web maliciosos interactúen con servidores MCP locales.

# Configure allowed origins (defaults to ['localhost', '127.0.0.1'])
FastMcp.rack_middleware(app,
  allowed_origins: ['localhost', '127.0.0.1', 'your-domain.com', /.*\.your-domain\.com/],
  localhost_only: false,
  allowed_ips: ['192.168.1.1', '10.0.0.1'],
  # other options...
)

Autenticación

Fast MCP admite autenticación basada en tokens para todas las conexiones:

# Enable authentication
FastMcp.authenticated_rack_middleware(app,
  auth_token: 'your-secret-token',
  # other options...
)

📖 Documentación

• 🚀 Guía de Inicio
• 🧩 Guía de Integración
• 🛤️ Integración con Rails
• 🌐 Integración con Sinatra
• 📚 Recursos
• 🛠️ Herramientas
• 🔒 Seguridad
• 🎯 Filtrado Dinámico

💻 Ejemplos

Consulta el directorio de ejemplos para ejemplos más detallados:

• 🔨 Ejemplos Básicos:
  • Servidor Simple
  • Ejemplos de Herramientas
• 🌐 Integración Web:
  • Middleware de Rack
  • Endpoints Autenticados

🧪 Requisitos

• Ruby 3.2+

👥 Contribuyendo

¡Damos la bienvenida a contribuciones a Fast MCP! Así es como puedes ayudar:

1. Haz un fork del repositorio
2. Crea tu rama de características (git checkout -b my-new-feature)
3. Haz commit de tus cambios (git commit -am 'Add some feature')
4. Haz push a la rama (git push origin my-new-feature)
5. Crea un nuevo Pull Request

Por favor, lee nuestra Guía de Contribución para más detalles.

📄 Licencia

Este proyecto está disponible como código abierto bajo los términos de la Licencia MIT.

🙏 Agradecimientos

• El equipo de Protocolo de Contexto de Modelo por crear la especificación
• El equipo de Dry-Schema por la validación de argumentos.
• Todos los contribuyentes de este proyecto