Fast MCP 🚀

🌟 在几分钟内实现服务器与大语言模型的对接

AI 模型功能强大，但只有与您的应用程序无缝交互，才能真正发挥其价值。传统的集成方式往往伴随着以下挑战：

• 🔄 复杂的通信协议和自定义 JSON 格式
• 🔌 不同模型提供商之间的集成难题
• 🧩 您的应用程序与 AI 工具之间的兼容性问题
• 🧠 需要在 AI 交互与您的数据之间管理状态

Fast MCP 通过提供基于 Model Context Protocol 的简洁、以 Ruby 为中心的实现，彻底解决了这些问题，让 AI 集成变得简单愉快，而非繁重的任务。

✨ 核心特性

• 🛠️ 工具 API - 允许 AI 模型安全地调用您的 Ruby 函数，并通过 Dry-Schema 进行深入的参数校验。
• 📚 资源 API - 在您的应用与 AI 模型之间共享数据。
• 🔄 多种传输方式 - 根据需求选择 STDIO、HTTP 或 SSE。
• 🧩 框架集成 - 与 Rails、Sinatra 或任何 Rack 应用无缝兼容。
• 🔒 认证支持 - 轻松保护您的 AI 驱动端点。
• 🚀 实时更新 - 订阅变化，构建交互式应用。
• 🎯 动态过滤 - 根据请求上下文（权限、API 版本等）控制工具和资源的访问权限。

💎 FastMCP 的优势

# 定义供 AI 模型使用的工具
server = FastMcp::Server.new(name: 'popular-users', version: '1.0.0')

# 继承 FastMcp::Tool 定义工具
class CreateUserTool < FastMcp::Tool
  description "创建用户"
    # 这些参数会生成传递给 MCP 客户端所需的 JSON，
    # 并在运行时进行验证。
    # 验证基于 Dry-Schema，并附加描述信息。
  arguments do
    required(:first_name).filled(:string).description("用户的名")
    optional(:age).filled(:integer).description("用户的年龄")
    required(:address).description("收货地址").hash do
      required(:street).filled(:string).description("街道地址")
      optional(:city).filled(:string).description("城市名称")
      optional(:zipcode).maybe(:string).description("邮政编码")
    end
  end

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

# 将工具注册到服务器
server.register_tool(CreateUserTool)

# 继承 FastMcp::Resource 与 AI 模型共享数据资源
class PopularUsers < FastMcp::Resource
  uri "myapp:///users/popular"
  resource_name "热门用户"
  mime_type "application/json"

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

class User < FastMcp::Resource
  uri "myapp:///users/{id}" # 这是一个资源模板
  resource_name "用户"
  mime_type "application/json"

  def content
    id = params[:id] # 参数由 URI 模式计算得出

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

# 将资源注册到服务器
server.register_resources(PopularUsers, User)

# 通过服务器访问资源
server.read_resource(PopularUsers.uri)

# 通知客户端资源内容已更新
server.notify_resource_updated(PopularUsers.variabilized_uri)

# 通知模板化资源的内容已更新
server.notify_resource_updated(User.variabilized_uri(id: 1))

🎯 动态工具过滤

根据请求上下文控制可用的工具和资源：

# 为工具打标签以便于过滤
class AdminTool < FastMcp::Tool
  tags :admin, :dangerous
  description "执行管理员操作"

  def call
    # 仅限管理员的功能
  end
end

# 根据用户权限过滤工具
server.filter_tools do |request, tools|
  user_role = request.params['role']

  case user_role
  when 'admin'
    tools # 管理员可见所有工具
  when 'user'
    tools.reject { |t| t.tags.include?(:admin) }
  else
    tools.select { |t| t.tags.include?(:public) }
  end
end

🚂 快速的 Ruby on Rails 实现

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

这将添加一个可配置的 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', # 这是默认的路径前缀
  messages_route: 'messages', # 这是消息端点的默认路由
  sse_route: 'sse', # 这是 SSE 端点的默认路由
  # 在下方添加允许的来源，它默认为 Rails.application.config.hosts
  # allowed_origins: ['localhost', '127.0.0.1', 'example.com', /.*\.example\.com/],
  # localhost_only: true, # 设置为 false 以允许来自其他主机的连接
  # 如果您想在本地运行并允许来自其他 IP 的连接，请列出特定的 IP 地址
  # allowed_ips: ['127.0.0.1', '::1']
  # authenticate: true,       # 取消注释以启用身份验证
  # auth_token: 'your-token' # 如果 authenticate: true，则需要此参数
) do |server|
  Rails.application.config.after_initialize do
    # FastMcp 将自动发现并注册：
    # - 所有继承自 ApplicationTool 的类（使用 ActionTool::Base）
    # - 所有继承自 ApplicationResource 的类（使用 ActionResource::Base）
    server.register_tools(*ApplicationTool.descendants)
    server.register_resources(*ApplicationResource.descendants)
    # 或者，您也可以手动注册工具和资源：
    # server.register_tool(MyTool)
    # server.register_resource(MyResource)
  end
end

安装脚本还将：

• 添加 app/resources 文件夹
• 添加 app/tools 文件夹
• 添加 app/tools/sample_tool.rb
• 添加 app/resources/sample_resource.rb
• 添加 ApplicationTool 作为基类
• 同时添加 ApplicationResource 作为基类

适合 Rails 的类命名规范

对于 Rails 应用程序，FastMCP 提供了符合 Rails 规范的类名：

• ActionTool::Base - 是 FastMcp::Tool 的别名
• ActionResource::Base - 是 FastMcp::Resource 的别名

这些会在 Rails 应用程序中自动设置。您可以在代码中使用任一种命名方式：

# 使用 Rails 风格的命名：
class MyTool < ActionTool::Base
  description "我的超棒工具"

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

  def call(input:)
    # 您的实现
  end
end

# 使用标准的 FastMcp 命名：
class AnotherTool < FastMcp::Tool
  # 在 Rails 应用程序中，这两种风格可以互换使用
end

当创建新的工具或资源时，生成器会默认使用 Rails 的命名规范：

# app/tools/application_tool.rb
class ApplicationTool < ActionTool::Base
  # 所有工具的基础方法
end

# app/resources/application_resource.rb
class ApplicationResource < ActionResource::Base
  # 所有资源的基础方法
end

简单的 Sinatra 设置

请参阅专门的 Sinatra 集成文档。

🚀 快速入门

创建带有工具和资源以及 STDIO 传输的服务器

require 'fast_mcp'

# 创建一个 MCP 服务器
server = FastMcp::Server.new(name: 'my-ai-server', version: '1.0.0')

# 定义一个工具，继承自 FastMcp::Tool
class SummarizeTool < FastMcp::Tool
  description "总结给定的文本"

  arguments do
    required(:text).filled(:string).description("要总结的文本")
    optional(:max_length).filled(:integer).description("摘要的最大长度")
  end

  def call(text:, max_length: 100)
    # 您的总结逻辑在这里
    text.split('.').first(3).join('.') + '...'
  end
end

# 将工具注册到服务器
server.register_tool(SummarizeTool)

# 创建一个资源，继承自 FastMcp::Resource
class StatisticsResource < FastMcp::Resource
  uri "data/statistics"
  resource_name "使用统计"
  description "当前系统统计信息"
  mime_type "application/json"

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

# 将资源注册到服务器
server.register_resource(StatisticsResource)

# 启动服务器
server.start

🧪 使用检查器进行测试

MCP 开发了一个非常 有用的检查器。您可以使用它来验证您的实现。我建议您使用随本项目提供的示例作为简单的样板。克隆该项目，然后开始尝试！

npx @modelcontextprotocol/inspector examples/server_with_stdio_transport.rb

或者使用 Rack 中间件通过 SSE 传输进行测试：

npx @modelcontextprotocol/inspector examples/rack_middleware.rb

或者使用经过身份验证的 Rack 中间件通过 SSE 进行测试：

npx @modelcontextprotocol/inspector examples/authenticated_rack_middleware.rb

您可以通过使用官方 MCP 检查器来测试您的自定义实现：

# 使用 stdio 传输进行测试：
npx @modelcontextprotocol/inspector path/to/your_ruby_file.rb

# 使用 HTTP / SSE 服务器进行测试。在 UI 中选择 SSE 并输入您的地址。
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|
  # 在这里注册工具和资源
  server.register_tool(SummarizeTool)
end

get '/' do
  'Hello World!'
end

与 Claude Desktop 集成

将您的服务器添加到 Claude Desktop 的配置中，路径如下：

• 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"]
    }
  }
}

如何将 MCP 服务器添加到 Claude、Cursor 或其他 MCP 客户端？

请参阅 configuring_mcp_clients。

📊 支持的规范

功能	状态
✅ JSON-RPC 2.0	完整实现用于通信
✅ 工具定义与调用	定义并调用具有丰富参数类型的工具
✅ 资源及资源模板管理	创建、读取、更新和订阅资源
✅ 传输选项	STDIO、HTTP 和 SSE，支持灵活集成
✅ 框架集成	Rails、Sinatra、Hanami 以及任何兼容 Rack 的框架
✅ 认证	使用令牌认证保护您的 AI 端点
✅ 模式支持	完整的 JSON Schema，用于工具参数验证

🗺️ 使用场景

• 🤖 AI 驱动的应用程序: 将 LLM 连接到您的 Ruby 应用程序功能
• 📊 实时仪表盘: 构建带有实时 AI 生成洞察的仪表盘
• 🔗 微服务通信: 使用 MCP 作为服务之间的清晰协议
• 📚 交互式文档: 创建 AI 增强的 API 文档
• 💬 聊天机器人和助手: 构建可访问您应用数据的 AI 助手

🔒 安全特性

Fast MCP 包含内置的安全特性，以保护您的应用程序：

DNS 重绑定防护

HTTP/SSE 传输会验证所有传入连接的 Origin 头，以防止 DNS 重绑定攻击。这种攻击可能允许恶意网站与本地 MCP 服务器进行交互。

# 配置允许的来源（默认为 ['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'],
  # 其他选项...
)

认证

Fast MCP 支持所有连接的基于令牌的认证：

# 启用认证
FastMcp.authenticated_rack_middleware(app,
  auth_token: 'your-secret-token',
  # 其他选项...
)

📖 文档

• 🚀 入门指南
• 🧩 集成指南
• 🛤️ Rails 集成
• 🌐 Sinatra 集成
• 📚 资源
• 🛠️ 工具
• 🔒 安全
• 🎯 动态过滤

💻 示例

请查看 examples 目录，获取更多详细示例：

• 🔨 基本示例:

  • 简单服务器
  • 工具示例

• 🌐 Web 集成:

  • Rack 中间件
  • 认证端点

🧪 要求

• Ruby 3.2+

👥 贡献

我们欢迎对 Fast MCP 的贡献！以下是您可以帮助的方式：

1. 分支仓库
2. 创建您的功能分支 (git checkout -b my-new-feature)
3. 提交更改 (git commit -am '添加一些功能')
4. 推送到分支 (git push origin my-new-feature)
5. 创建新的 Pull Request

请阅读我们的 贡献指南，以获取更多详细信息。

📄 许可证

本项目以开源形式提供，遵循 MIT 许可证 的条款。

🙏 致谢

• Model Context Protocol 团队，感谢他们创建了该规范
• Dry-Schema 团队，感谢他们提供的参数验证。
• 本项目的全体贡献者

Fast MCP 快速上手指南

Fast MCP 是一个专为 Ruby 设计的 Model Context Protocol (MCP) 实现，旨在让 AI 模型轻松与你的 Ruby 应用（如 Rails、Sinatra）交互。它屏蔽了复杂的协议细节，让你能用优雅的 Ruby 代码定义工具和数据资源。

环境准备

• 系统要求: macOS, Linux 或 Windows (需安装 Ruby 环境)
• Ruby 版本: 建议 Ruby 3.0+
• 前置依赖:
  • Bundler (Ruby 包管理工具)
  • (可选) Node.js & npm：用于运行官方 MCP Inspector 进行测试调试

安装步骤

1. 在现有项目中安装

在你的 Ruby 项目根目录下运行：

bundle add fast-mcp

2. Rails 项目专用安装

如果是 Rails 项目，安装后请运行生成器以自动配置初始化文件和目录结构：

bin/rails generate fast_mcp:install

该命令会自动创建 app/tools 和 app/resources 目录，并生成基类 ApplicationTool 和 ApplicationResource。

基本使用

以下是一个独立运行的最小示例，展示如何创建一个包含“工具”和“资源”的 MCP 服务器，并通过 STDIO 启动。

1. 创建服务器文件

新建一个文件 server.rb，写入以下代码：

require 'fast_mcp'

# 1. 创建 MCP 服务器实例
server = FastMcp::Server.new(name: 'my-ai-server', version: '1.0.0')

# 2. 定义一个工具 (Tool) - 供 AI 调用的函数
class SummarizeTool < FastMcp::Tool
  description "Summarize a given text"

  # 定义参数验证 (基于 Dry-Schema)
  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)
    # 简单的模拟逻辑：取前三句话
    text.split('.').first(3).join('.') + '...'
  end
end

# 注册工具
server.register_tool(SummarizeTool)

# 3. 定义一个资源 (Resource) - 供 AI 读取的数据
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

# 注册资源
server.register_resource(StatisticsResource)

# 4. 启动服务器 (默认使用 STDIO 传输)
server.start

2. 运行与测试

方式 A：直接在终端运行 (STDIO 模式) 此模式通常由客户端（如 Claude Desktop）直接调用，手动测试时可输入 JSON-RPC 请求。

ruby server.rb

方式 B：使用官方 Inspector 调试 (推荐) 如果你安装了 Node.js，可以使用官方提供的可视化工具来测试你的服务器实现：

npx @modelcontextprotocol/inspector server.rb

3. 集成到 Claude Desktop

若要让 Claude Desktop 调用此服务器，需修改其配置文件。

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

添加如下配置：

{
  "mcpServers": {
    "my-great-server": {
      "command": "ruby",
      "args": ["/绝对路径/到/你的/server.rb"]
    }
  }
}

(注意：请将 /绝对路径/到/你的/server.rb 替换为你实际的 server.rb 文件路径)