VectorMCP

VectorMCP

VectorMCP 是模型上下文协议（MCP）服务端规范的 Ruby 实现。它提供一个框架，让你通过 MCP 可流式传输的 HTTP 传输方式公开工具、资源、提示词、根目录、采样、中间件和安全功能。

亮点

• 内置传输方式为可流式传输的 HTTP，支持会话管理、恢复能力，并符合 MCP 2025-11-25
• 通过 VectorMCP::Tool 定义基于类的工具，同时保留原有的基于代码块的 register_tool API
• 通过 server.rack_app 挂载到 Rack 和 Rails
• 可选启用身份验证和授权、结构化日志记录及中间件钩子
• 请求范围的身份信息：每个请求都会通过独立的调用进行分派，因此同一会话上的并发请求绝不会读取到彼此的标头或身份验证信息
• 支持图像的工具、资源和提示词、根目录，以及由服务端发起的采样
• 基于令牌的字段匿名化中间件，可避免敏感值进入大模型上下文

要求

• Ruby 3.2+

安装

gem install vector_mcp

gem "vector_mcp"

快速入门

require "vector_mcp"

class Greet < VectorMCP::Tool
  description "Say hello to someone"
  param :name, type: :string, desc: "Name to greet", required: true

  def call(args, _session)
    "Hello, #{args["name"]}!"
  end
end

server = VectorMCP::Server.new(name: "MyApp", version: "1.0.0")
server.register(Greet)
server.run(port: 8080)

基于类的 DSL 为可选项。现有的基于代码块的 API 仍然可用：

server.register_tool(
  name: "echo",
  description: "Echo back the supplied text",
  input_schema: {
    type: "object",
    properties: { text: { type: "string" } },
    required: ["text"]
  }
) { |args| args["text"] }

Rack 和 Rails

VectorMCP 可以作为独立的 HTTP 服务运行，也可以挂载到现有的 Rack 应用中：

require "vector_mcp"

server = VectorMCP::Server.new(name: "MyApp", version: "1.0.0")
server.register(Greet)

MCP_APP = server.rack_app

在 Rails 中，将其挂载到 config/routes.rb：

mount MCP_APP => "/mcp"

对于由 ActiveRecord 支持的工具，可选择使用 VectorMCP::Rails::Tool：

require "vector_mcp/rails/tool"

class FindUser < VectorMCP::Rails::Tool
  description "Find a user by id"
  param :id, type: :integer, required: true

  def call(args, _session)
    user = find!(User, args[:id])
    { id: user.id, email: user.email }
  end
end

完整的设置指南请参阅 docs/rails-setup-guide.md。

工具、资源和提示词

公开可调用的工具：

server.register_tool(
  name: "calculate",
  description: "Performs basic math",
  input_schema: {
    type: "object",
    properties: {
      operation: { type: "string", enum: ["add", "subtract", "multiply"] },
      a: { type: "number" },
      b: { type: "number" }
    },
    required: ["operation", "a", "b"]
  }
) do |args|
  case args["operation"]
  when "add" then args["a"] + args["b"]
  when "subtract" then args["a"] - args["b"]
  when "multiply" then args["a"] * args["b"]
  end
end

公开可读取的资源：

server.register_resource(
  uri: "file://config.json",
  name: "App Configuration",
  description: "Current application settings"
) { File.read("config.json") }

定义提示词模板：

server.register_prompt(
  name: "code_review",
  description: "Reviews code for best practices",
  arguments: [
    { name: "language", description: "Programming language", required: true },
    { name: "code", description: "Code to review", required: true }
  ]
) do |args|
  {
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: "Review this #{args["language"]} code:\n\n#{args["code"]}"
      }
    }]
  }
end

VectorMCP::Tool 还支持 type: :date 和 type: :datetime，它们在 JSON Schema 中会作为字符串进行验证，并在运行 #call 前转换为 Date 和 Time。

接受第二个参数的处理程序会收到每个请求各自的调用对象，其中集中提供会话身份、请求的标头和参数，以及经过身份验证的用户：

server.register_tool(
  name: "whoami",
  description: "Reports the caller's identity",
  input_schema: { type: "object", properties: {} }
) do |_args, invocation|
  {
    session: invocation.id,
    user: invocation.user,
    api_key_header: invocation.request_header("X-API-Key")
  }
end

资源处理程序也会将相同的调用对象作为第二个参数接收（它还支持常见的 user / authenticated? / can? 查询，因此针对旧版安全上下文参数编写的处理程序无需修改即可继续工作）。

安全与中间件

VectorMCP 默认不启用安全功能，但内置了相关基础组件：

server.enable_authentication!(
  strategy: :api_key,
  keys: [ENV.fetch("MCP_API_KEY")],
  rate_limit: { max_attempts: 10, window_seconds: 60 }
)

server.enable_authorization! do
  authorize_tools do |user, _action, tool|
    user[:role] == "admin" || !tool.name.start_with?("admin_")
  end
end

也支持自定义身份验证：

server.enable_authentication!(strategy: :custom) do |request|
  api_key = request[:headers]["X-API-Key"]
  user = User.find_by(api_key: api_key)
  user ? { user_id: user.id, role: user.role } : false
end

启用身份验证后，VectorMCP 会集中对内置和自定义请求／通知处理器应用身份验证。只有 initialize、ping 和 initialized 通知是公开的；HTTP GET 流和 DELETE 会话请求也需要凭据。

对于公开部署，可通过 rate_limit: true 启用身份验证失败限流（默认每 60 秒尝试 10 次），也可以指定 max_attempts、window_seconds 和 max_entries。系统会根据客户端 IP 和单向凭据指纹跟踪重复失败；被阻止的请求会返回 HTTP 429、JSON-RPC -32029 和 Retry-After。限流器在进程内运行，因此多进程或分布式部署还应在代理或网关处实施共享限流。生成 API 密钥时至少使用 256 位熵，例如 ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'，并从密钥管理器或环境变量中加载密钥。

对于使用 OAuth 2.1 的 MCP 客户端（例如 Claude Desktop），传入 resource_metadata_url: 即可启用 RFC 9728 发现。向 /mcp 发送未经身份验证的请求时，会返回带有 WWW-Authenticate 标头的 401，指向配置的元数据文档，客户端会自动完成后续 OAuth 流程。有关功能参考，请参阅 docs/oauth_resource_server.md；有关完整的 Rails + Doorkeeper 配置方案，请参阅 docs/rails_oauth_integration.md。

中间件可挂接到工具、资源、提示词、采样、身份验证和传输事件，包括 before_auth、after_auth、on_auth_error、before_request、after_response 和 on_transport_error。

完整的安全指南请参阅 security/README.md。

字段匿名化

将敏感字符串替换为稳定的不透明令牌，避免其进入大模型上下文。向外发送工具结果时会对值进行令牌化，接收传入的工具参数时则会还原这些值，因此大模型只能看到令牌，而处理器会收到原始数据。

anonymizer = VectorMCP::Middleware::Anonymizer.new(
  store: VectorMCP::TokenStore.new,
  field_rules: [
    { pattern: /email/i, prefix: "EMAIL" },
    { pattern: /\bssn\b/i, prefix: "SSN" }
  ]
)
anonymizer.install_on(server)

传输说明

• VectorMCP 内置的传输方式为可流式 HTTP
• POST /mcp 接受单个 JSON-RPC 请求、通知或响应；不接受批量数组
• GET /mcp 会打开 SSE 流，用于服务器发起的消息
• DELETE /mcp 会终止会话
• 服务器声明支持 MCP 协议 2025-11-25，并接受 2025-03-26 和 2024-11-05 标头以兼容旧版本
• 默认仅允许 localhost 和环回地址作为来源
• POST 请求正文默认上限为 16 MiB；如有需要，可在 run 或 rack_app 上配置 max_body_bytes:
• 对于挂载的 Rack 应用，请在前置 Web 服务器或反向代理中配置相同的限制，以便在 Rack 缓冲请求前拒绝超限请求

使用 curl 初始化会话：

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

更多功能

• 通过 register_root 和 register_root_from_path 注册根目录
• 图像资源，以及支持图像的工具／提示词
• 带有组件日志记录器的结构化日志
• 支持流式传输／工具调用的服务器发起采样
• 由中间件驱动的请求整形与可观测性

文档

• CHANGELOG.md
• examples/
• docs/rails-setup-guide.md
• docs/rails_oauth_integration.md
• docs/oauth_resource_server.md
• docs/streamable-http-spec-compliance.md
• security/README.md
• MCP 规范

参与贡献

欢迎通过 GitHub 提交错误报告和拉取请求。

许可证

根据 MIT License 以开源形式提供。