Class: Aspera::Cli::Plugins::Mcp

Inherits:
Base
  • Object
show all
Defined in:
lib/aspera/cli/plugins/mcp.rb

Overview

Plugin to start the MCP (Model Context Protocol) server. The server action accepts an optional Hash argument (extended value) to configure the MCP server and transport.

Supported keys in the options Hash:

transport:              "stdio" (default) or "http"
extra_args:             Array<String> - flags prepended to every ascli call
                      (default: ["--interactive=no", "--transfer.asynchronous=true"])
max_text_bytes:         Integer - max bytes of JSON text content for list results (default 100_000)
# stdio transport:
max_line_bytes:         Integer - max JSON frame size (default 4 MiB)
# http transport:
port:                   Integer - TCP port (default 3000)
bind:                   String  - bind address (default "127.0.0.1")
stateless:              Boolean - stateless mode (default false)
allowed_origins:        Array<String>
allowed_hosts:          Array<String>
session_idle_timeout:   Integer (seconds)
max_sessions:           Integer
# MCP::Server options:
instructions:           String  - hint shown to the AI client
protocol_version:       String  - e.g. "2024-11-05"
validate_tool_call_arguments: Boolean (default true)

Examples:

ascli mcp server
ascli mcp server @json:{"instructions":"Aspera transfers"}
ascli mcp server @json:{"transport":"http","port":3000}
ascli mcp server @json:{"protocol_version":"2024-11-05","max_line_bytes":1048576}

Constant Summary collapse

DEFAULT_INSTRUCTIONS =

Default instructions shown to the AI client when none are provided by the user.

<<~INST.strip
  This is the Aspera CLI (ascli) MCP server (IBM Aspera file transfer and management).
  It exposes a single tool, execute_ascli_command, which runs any ascli command in-process.
  Its description gives the syntax and the discovery sequence: follow it before any
  command whose syntax you have not verified in this session.

  Plugins: aoc (Aspera on Cloud), faspex5 (Faspex 5), node (Node API), server (FASP/SSH
  server), config (local configuration), console, orchestrator, ats, preview, shares,
  cos, httpgw, faspio, alee.

  CREDENTIALS
  Use saved presets by default: call ["config", "preset", "overview"] first, then pass
  --preset=<name>, or nothing if a default preset exists for the plugin.
  If the user provides credentials inline (--url, --username, --password, --private-key),
  use those exact values verbatim — never substitute a preset or another server.
  Some plugins support browser login (--auth=web).
  On error, report it as-is and stop.

  TRANSFERS
  Pass verbatim any flag the user requests (--transfer.agent=<agent>, --to-folder, …).
  Agents: direct (default, in-process ascp), desktop (IBM Aspera Desktop Client,
  graphical), node, transferd, httpgw, connect.
  Transfers are asynchronous: the command returns a job_id immediately — never retry it.
    monitor → ["config", "transfer", "status", "<job_id>"]
    list    → ["config", "transfer", "list"]
    cleanup → ["config", "transfer", "cleanup"]
INST

Constants inherited from Base

Base::FILTER_ARGS

Instance Attribute Summary

Attributes inherited from Base

#context, #help_path

Instance Method Summary collapse

Methods inherited from Base

#action_for, #add_manual_header, application_name, #bulk_result, command, command_registry, commands_under, #config, crud_commands, declare_options, define_action_method, #dispatch_child, #dispatch_from_registry, #dispatch_leaf, #dispatch_mount, #entity_create, #entity_delete, #entity_list, #entity_modify, entity_noun, #entity_res_path, #entity_show, #execute_action, #execute_leaf, file_matcher, #formatter, #generate_help, #http_config, #initialize, #invoke_action, operation_description, option_sources, option_specs, #options, #persistency, #presets, #progress_bar, #query_read_delete, register_option_spec, #resolve_argument, #resolve_arguments, #transfer, use_options, used_option_sources, #validate_registry

Methods included from OptionDeclarator

#declare_options, #option, #option_specs, #register_option_spec

Constructor Details

This class inherits a constructor from Aspera::Cli::Plugins::Base

Instance Method Details

#action_server(mcp_options: nil) ⇒ Object

Raises:



88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/aspera/cli/plugins/mcp.rb', line 88

def action_server(mcp_options: nil, **)
  require 'aspera/cli/mcp_tool'
  mcp_options = (mcp_options || {}).transform_keys(&:to_sym)
  unknown = mcp_options.keys - SERVER_KEYS - CONFIG_KEYS - STDIO_KEYS - HTTP_KEYS - TOOL_KEYS - %i[transport port bind]
  Aspera.assert(unknown.empty?, type: Cli::BadArgument) { "Unknown MCP option(s): #{unknown.join(', ')}" }
  Cli::McpTool.max_text_bytes = mcp_options.delete(:max_text_bytes)
  Cli::McpTool.extra_args     = mcp_options.delete(:extra_args)
  transport = mcp_options.delete(:transport) || 'stdio'
  raise Cli::BadArgument, "Unknown transport: #{transport}. Use 'stdio' or 'http'" \
    unless %w[stdio http].include?(transport.to_s)
  Log.log.info { "Starting MCP server (transport=#{transport})..." }
  start_mcp_server(transport: transport.to_sym, mcp_options: mcp_options)
  Result::Nothing.new
end