little_ghost 0.7.0 → 0.9.0

data/docs/guides/mcp.md

@@ -0,0 +1,288 @@
+# Connect agents to MCP servers
+
+Give an Agent access to operations published by a Model Context Protocol (MCP)
+server without changing how your application calls the Agent.
+`LittleGhost::MCP::Toolset` turns operations discovered by the official MCP Ruby
+client into LittleGhost Tool classes, which join the same `tools` declaration as
+local application Tools.
+
+MCP support is opt-in. Requiring `little_ghost` alone does not install or load
+the SDK or its transports.
+
+## Connect over Streamable HTTP
+
+Add the official SDK and its HTTP dependencies to your bundle:
+
+```ruby
+gem "mcp", "~> 1.3"
+gem "faraday", "~> 2.0"
+gem "event_stream_parser", "~> 1.0"
+```
+
+Require the integration explicitly, then create a Toolset with a `client`
+block. Return a new official client from the block:
+
+```ruby
+require "little_ghost/mcp"
+
+class HelpCenterTools < LittleGhost::MCP::Toolset
+  client do |_binding|
+    transport = MCP::Client::HTTP.new(
+      url: "https://mcp.example/rpc"
+    )
+    MCP::Client.new(transport:)
+  end
+end
+
+class CustomerSupportAgent < LittleGhost::Agent
+  system_prompt "Use help-center tools for published guidance."
+  tools HelpCenterTools
+end
+
+run = CustomerSupportAgent.ask("How long do refunds take?")
+run.response
+```
+
+LittleGhost calls the block once for each Agent run. It connects the client,
+discovers the server's Tools, and closes the transport when the run ends.
+
+The `client` block receives the current `Tool::Binding`. Use it to build headers
+or credentials from authenticated application context without storing them on
+the Toolset:
+
+```ruby
+class AccountTools < LittleGhost::MCP::Toolset
+  client do |binding|
+    token = McpAccessTokens.for_actor(binding.run.invocation.actor_id)
+    transport = MCP::Client::HTTP.new(
+      url: "https://mcp.example/rpc",
+      headers: {"Authorization" => "Bearer #{token}"}
+    )
+    MCP::Client.new(transport:)
+  end
+end
+```
+
+## Connect a local server over standard input and output
+
+A standard input and output (stdio) connection needs only the official SDK:
+
+```ruby
+gem "mcp", "~> 1.3"
+```
+
+Construct the SDK transport in the same `client` block:
+
+```ruby
+class LocalDatabaseTools < LittleGhost::MCP::Toolset
+  client do |_binding|
+    transport = MCP::Client::Stdio.new(
+      command: "bundle",
+      args: ["exec", "database-mcp"],
+      env: {"APP_ENV" => "production"},
+      read_timeout: 30
+    )
+    MCP::Client.new(transport:)
+  end
+end
+```
+
+A stdio server is a child process with the same operating-system permissions as
+your Ruby process. It is not a sandbox. Use an operating-system sandbox when
+you do not fully trust the executable.
+
+The `env` Hash changes only the variables you name. The child inherits every
+other variable from the parent process. Clear sensitive variables explicitly,
+or launch the server through an isolated wrapper when it must not receive
+ambient credentials.
+
+## Configure the official client
+
+Set timeouts, message limits, OAuth, middleware, and other transport behavior
+through the SDK. Keyword arguments on `client` go directly to
+`MCP::Client#connect`; use them for an explicit protocol mode, version, or client
+capability.
+
+### Respond to server requests
+
+A server may need more information while handling a Tool call. MCP calls this
+elicitation. Advertise the capability when connecting, then register a handler
+on the client:
+
+```ruby
+class InteractiveTools < LittleGhost::MCP::Toolset
+  client(capabilities: {elicitation: {}}) do |binding|
+    transport = MCP::Client::HTTP.new(url: "https://mcp.example/rpc")
+    MCP::Client.new(transport:).tap do |official_client|
+      official_client.on_elicitation do |request|
+        Elicitations.answer(request, run: binding.run)
+      end
+    end
+  end
+end
+```
+
+The handler can answer from the current Run or pass the request to an application
+interface. Sampling similarly lets a server request a model call, while roots
+tell a server which directories the application makes available. Configure
+these features on the official client.
+
+Treat every server-initiated handler request as untrusted. Authorize it against
+the current run, restrict roots to intended paths, constrain model sampling and
+its cost, and return only the application data that server is allowed to receive.
+
+Return a new, unconnected client for every run. Building it should not start
+remote work. LittleGhost closes transports that provide `close`, including when
+connection or discovery fails. If a custom transport owns other resources, it
+must release them itself.
+
+Set transport timeouts to match the application's deadline. LittleGhost passes
+Run cancellation and deadlines to Tool discovery and calls, but connection has
+its own timeout behavior.
+
+## Plan concurrency and cancellation
+
+Most applications only need transport timeouts. The details below matter when
+the application uses a Fiber scheduler or runs independent Tools concurrently.
+
+### Connection
+
+LittleGhost connects while it discovers the Agent's Tools. Run cancellation
+does not interrupt connection, so the transport's connection and read timeouts
+control how long it can wait. Choose a scheduler-compatible transport adapter
+when other fibers must continue during that time.
+
+### Tool discovery and calls
+
+Tool discovery and calls honor Run cancellation and deadlines. Cancelling an
+HTTP call returns control to the Run, but the underlying request may continue
+waiting until the server responds or the transport closes.
+
+All Tools for one run share the same client. HTTP calls may overlap when
+LittleGhost runs independent Tools concurrently, so choose a Faraday adapter
+that supports overlapping calls. If the server or transport requires one call
+at a time, mark the generated Tools exclusive:
+
+```ruby
+map_tool do |tool_class, mcp_tool:, binding:|
+  tool_class.exclusive true
+  tool_class
+end
+```
+
+LittleGhost serializes calls through the official stdio transport. If one of
+those calls is cancelled, it closes that run's session rather than risk reading
+a late response as the answer to a later call. A custom or decorated stdio
+transport must provide its own serialization, cancellation behavior, and
+cleanup.
+
+### Server handlers
+
+The server may invoke a handler while other work is active. Write handlers for
+concurrent use and capture the application values they need when building the
+client. Do not rely on fiber-local state inside a handler.
+
+## Select and map Tools
+
+By default, the Agent receives every Tool published by the server. LittleGhost
+normalizes each name for the model and keeps the server's original name for
+calls. Discovery stops after 1,000 Tools or 100 pages, which bounds the work an
+untrusted catalog can create in one run.
+
+Use `map_tool` to omit operations or configure their generated classes:
+
+```ruby
+class CuratedHelpCenterTools < HelpCenterTools
+  map_tool do |tool_class, mcp_tool:, binding:|
+    next unless %w[search fetch].include?(mcp_tool.name)
+
+    tool_class.tool_name "help_center_#{mcp_tool.name}"
+    tool_class
+  end
+end
+```
+
+`mcp_tool` is the Tool published by the official client. Return the generated
+class, a subclass, or `nil` to omit it. Renaming the generated Tool changes the
+name shown to the model, not the name sent back to the server.
+
+LittleGhost sends the server's input schema to the model unchanged. It does not
+validate arguments against that schema; the server must validate them before
+performing an operation. LittleGhost limits schema depth and node count during
+discovery. Configure the transport's message-size limit to bound the bytes
+accepted from a server.
+
+> **Safety note:** Server descriptions and results become visible to the model.
+> Treat them as untrusted content. Expose only the operations the Agent needs,
+> use narrowly scoped credentials, and have the server authorize every sensitive
+> call.
+
+## Convert results
+
+Without a mapping, LittleGhost returns `structuredContent` when the server sends
+it. Otherwise, it returns the text or remaining visible content blocks. MCP
+image blocks become Artifacts.
+
+Suppose the help-center server returns `structuredContent` with an `articles`
+array. Use `map_result` to present each article as a short line:
+
+```ruby
+map_result do |value, mcp_tool:, **|
+  next value unless mcp_tool.name == "search"
+
+  value.fetch("articles").map do |article|
+    "#{article.fetch("title")}: #{article.fetch("url")}"
+  end
+end
+```
+
+`value` is LittleGhost's default conversion, and `mcp_tool` identifies the
+server operation. Return `value` unchanged or replace it with any Ruby value or
+`Tool::Result`. The block can also receive the raw result, sent arguments, and
+current binding; see the [`MCP::Toolset`
+API](rdoc-ref:LittleGhost::MCP::Toolset) for their exact shapes.
+
+Image Artifacts remain attached to the mapped result. A server result marked
+`isError` remains a model-visible Tool error.
+
+For custom images, files, or deferred Artifacts, continue with [Structured
+Results and Content](structured_outputs_and_content.md). A deferred resolver
+must verify ownership, fetch only from the intended service, and limit response
+size.
+
+## Keep an optional server from blocking a run
+
+An optional server can fail discovery without preventing Agent construction:
+
+```ruby
+class OptionalHelpCenterTools < HelpCenterTools
+  optional true
+  on_error do |error, binding:|
+    McpAvailability.report(error, run_id: binding.run.invocation.run_id)
+  end
+end
+```
+
+`optional true` turns an expected connection or protocol error during discovery
+into an empty Tool set. Configuration errors, cancellation, deadlines, and
+failures in application callbacks still stop the run.
+
+## Let the SDK negotiate the protocol version
+
+The [official MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk)
+handles protocol negotiation and transport behavior. Without explicit connect
+options, it negotiates with the server using a protocol version the installed
+SDK supports. Pin `protocol_version` or `mode` only when interoperability
+requires it.
+
+Need sampling, roots, elicitation, or another client capability? Configure it
+on the client you build above. The installed SDK and negotiated protocol version
+determine what is available. Check the [Ruby SDK client
+documentation](https://ruby.sdk.modelcontextprotocol.io/client/) and the
+[versioned MCP specification](https://modelcontextprotocol.io/specification/)
+for the capability you need.
+
+Continue with [Tools](tools.md) for the local Tool boundary,
+[Integrations](integrations.md) to send Runs through AG-UI or OpenTelemetry, or
+the [`MCP::Toolset` API](rdoc-ref:LittleGhost::MCP::Toolset) for exact mapping
+and ownership contracts.

data/docs/guides/models_and_providers.md

@@ -62,11 +62,11 @@ run = CustomerSupportAgent.ask(
 Build these settings in application code instead of passing request parameters
 through unchanged. Settings can affect cost, latency, and model behavior.
 
-## Configure connections in one place
+## Connect the provider you chose
 
-LittleGhost includes adapters for OpenRouter, OpenAI-compatible APIs,
-Anthropic, Gemini, Vertex AI, and Bedrock. Connections may live in an
-initializer or in the conventional files under `config/little_ghost`.
+Connections may live in an initializer or in the conventional files under
+`config/little_ghost`. [Provider Support](providers.md) has copyable settings
+for each built-in adapter, compatible endpoints, Ollama, and LM Studio.
 
 Keep credentials in your application's secret manager. Agents refer to a role
 or configured connection; they don't need to contain credentials. If your
@@ -120,6 +120,11 @@ choose a structured-result strategy.
 Provider capabilities can change. Handle failed Runs and provider errors even
 when the catalog says a feature is supported.
 
+Most application code does not call the resolver directly. Declaring an
+Agent's model, or passing `model:` to generation or embedding, resolves the
+selection for you. Inspect model details when an interface needs to explain
+limits or your application wants to check an attachment before sending it.
+
 ## Call a model without an Agent
 
 Some application work needs one model response rather than an Agent. Use
@@ -141,57 +146,23 @@ response.usage.total_tokens
 ```
 
 The operation returns a `LittleGhost::RunResult`, the same result type returned
-by an Agent invocation, so
-application code can read `output`, `usage`, and the final message in the same
-way. Plain generation makes one model request without starting an Agent or
-creating a Run. Structured generation may make one additional repair request.
-
-Pass a strict object schema when application code needs checked JSON:
+by an Agent invocation. Application code can read `output`, `usage`, and the
+final message in the same way. Plain generation makes one model request without
+starting an Agent or creating a Run.
 
-```ruby
-response = LittleGhost.generate(
-  model: :customer_support,
-  messages: [{role: :user, content: "My transfer is still pending."}],
-  result_schema: {
-    name: "classification",
-    description: "Classify one support request",
-    schema: {
-      type: "object",
-      properties: {category: {type: "string"}},
-      required: ["category"],
-      additionalProperties: false
-    }
-  }
-)
-
-response.output
-```
-
-LittleGhost checks the result against the schema and gives the model one repair
-attempt by default. Add `structured_result_repair_attempts: 3` to the call
-above when a checked result warrants additional attempts. The setting accepts
-integers from zero through three.
-
-Read the checked value through `response.output`. If every permitted attempt is
-invalid, the call raises `LittleGhost::StructuredResultError`.
-
-A schema checks the shape of a value, not whether your application should act
-on it. Check identifiers, permissions, and business rules before using the
-result to change application state.
+Pass `result_schema:` when application code needs checked JSON. [Structured
+Results and Content](structured_outputs_and_content.md) covers strict schemas,
+provider strategies, repair behavior, and the application checks that still
+belong outside the schema.
 
 ## Create embeddings
 
 Use `LittleGhost.embed` when your application needs numeric representations for
 search, clustering, or another similarity-based feature:
 
-The example assumes application startup maps `search_embeddings` to an
-embedding model, following the role configuration shown earlier on this page.
-The selected provider adapter's API reference lists the model-specific
-settings.
-
 ```ruby
 response = LittleGhost.embed(
-  model: :search_embeddings,
+  model: "primary:openai/text-embedding-3-small",
   inputs: ["Reset a password", "Track a transfer"]
 )
 
@@ -202,14 +173,10 @@ response.usage.input_tokens
 
 The response keeps vectors in the same order as the inputs. LittleGhost rejects
 an incomplete or malformed response instead of returning a partial batch.
-Choose the embedding model and request settings in trusted application
-configuration, and keep each call within a workload size your application can
-retry safely.
-
-Embedding text is sent to the selected provider. Choose a provider that is
-appropriate for that data, just as you would for an Agent request. See
-`LittleGhost::Embeddings::Request` and your provider adapter's API reference for
-the supported settings and request bounds.
+Embedding text is sent to the selected provider, so choose one appropriate for
+that data. [Provider Support](providers.md) identifies adapters with embedding
+support; `LittleGhost::Embeddings::Request` documents settings and request
+bounds.
 
 Continue with [Prompts as Views](prompt_views.md) when an Agent's instructions
 outgrow one string. See [Structured Results and Content](structured_outputs_and_content.md)

data/docs/guides/production.md

@@ -37,7 +37,15 @@ class CustomerSupportAgent < LittleGhost::Agent
 end
 ```
 
-Provider connections and model roles can also live in YAML files under `config/little_ghost`, or in files you select explicitly. Values set in Ruby take priority. An explicitly selected file comes next, followed by conventional files and environment defaults. See `LittleGhost::Configuration` when you need every supported source and override.
+Provider connections and model roles can live in the Ruby initializer or in
+YAML under `config/little_ghost`. Values set in Ruby take priority. See
+`LittleGhost::Configuration` for custom files and the full precedence order.
+
+[Provider Support](providers.md) lists the credentials and endpoint settings
+for hosted and local providers. Choose connection names, model identifiers,
+and custom headers during application startup. Read secrets from deployment
+configuration or a secret manager; do not copy request parameters into these
+settings.
 
 Prompts, caller input and history, Tool results, and attachments may go to the
 selected provider. Choose configured providers that are appropriate for that
@@ -289,14 +297,15 @@ LittleGhost.configure do |config|
   end
   config.sandbox = {
     provider: :native,
-    files: {root: :read_write},
-    root_filesystem: :isolated,
-    environment: {inherit: false, set: {"LANG" => "C.UTF-8"}},
-    network: :none
+    files: {root: :read_write}
   }
 end
 ```
 
+The native backend isolates the host root, removes child-process network
+access, and starts with a scrubbed child environment unless you configure a
+different policy.
+
 The temporary Workspace above is useful when files should live for one Run. Use application-managed storage, with tenant isolation and concurrency control, when files must persist or several Runs share a root.
 
 The Run opens a Runtime-created Workspace before its Sandbox and closes them in reverse order after every outcome. Closing a Workspace invokes its configured teardown; it does not delete files by default. Cleanup failures raise because LittleGhost cannot confirm a clean shutdown of every owned resource. Existing instances passed by the application remain caller-owned.