How f/mcp-startup-boilerplate works
Project Type and Purpose
• This is a monolithic, full-stack Rails application boilerplate geared toward building AI-powered web apps.
• It provides user authentication (Devise), an OAuth2 provider (Doorkeeper), payment processing (Stripe), and integrates with Claude AI via the Model Context Protocol (fast-mcp).
• The frontend uses modern Rails asset tooling: Tailwind CSS for styling, Importmap/Hotwire (Turbo + Stimulus) for interactivity.
File Structure
• Top-level directories:
• app/: Rails MVC code (controllers, models, views, assets, jobs, mailers, tools, resources).
• config/: Rails and deployment configs (database, environment, OAuth, Stripe, cable/ActionCable).
• bin/, lib/, script/: utility scripts and custom deployment hooks (.kamal).
• db/: schema, migrations, seeds.
• public/: static assets and error pages.
• test/: automated tests.
• Key patterns:
• MVC for web and API endpoints.
• app/tools/ and app/resources/ implement MCP.
• Doorkeeper controllers under app/controllers/doorkeeper handle OAuth flows.
• Webhook controller (app/controllers/webhooks_controller.rb) for Stripe events.
• Configuration/build:
• Dockerfile + .dockerignore for containerization.
• Procfile.dev, Kamal hooks under .kamal/ for deployment automation.
• Importmap, Yarn/Node only for Stimulus controllers.
Insights from README
• Rails 8.0.2, Ruby 3.2+, PostgreSQL backend.
• Hotwired frontend (Turbo + Stimulus) with Tailwind CSS.
• Stripe integration for pay-per-use and subscription.
• OAuth2 server supporting multiple grant types and PKCE.
• MCP endpoints expose “tools” (app/tools) and “resources” (app/resources) over SSE or JSON.
Main Components & Their Interactions
a. Clients
• Web client (browser) – standard MVC pages, Hotwire streams.
• AI client (Claude) – connects to MCP SSE endpoint to invoke tools/resources.
b. Rails Application
• Web Server (Puma) – serves HTTP(S) requests.
• Controllers
– Devise controllers: user signup/login.
– Doorkeeper controllers: OAuth2 endpoints (/oauth/authorize, /oauth/token, etc.).
– MCP controllers (fast-mcp): /mcp/sse, /mcp/json.
– Webhooks controller: Stripe event webhooks.
• Models & Persistence
– User, Subscription, ToolUsage stored in PostgreSQL.
• MCP Layer
– app/tools/: business logic for AI-invoked “tools.”
– app/resources/: data endpoints for AI client resources.
• Background Jobs (ActiveJob) – handle asynchronous tasks (e.g., sending emails, processing webhooks).
• ActionCable – real-time streams if used (config/cable.yml).
c. External Services
• PostgreSQL – primary database.
• Stripe – payment gateway for charging users, handling subscriptions, invoking webhooks.
• Claude AI – external AI client connecting via MCP protocol.
Architectural Patterns & Design Principles
• MVC pattern at core for web UI.
• Separation of concerns between web controllers, API/OAuth controllers, and MCP controllers.
• Layered architecture: Presentation (views + Stimulus), Application (controllers), Domain (models, tools, resources), Infrastructure (Stripe, Doorkeeper, Devise).
• Single codebase monolith with clear component boundaries.