llm.rb 13.0.0 → 14.0.0

data/resources/deepdive/protocols/mcp.md

@@ -0,0 +1,111 @@
+
+## MCP
+
+### Introduction
+
+#### Overview
+
+The Model Context Protocol (MCP) connects agents to external tools
+and data sources through a standardized interface. Instead of
+wiring each service directly into your agent, you run an MCP
+server that exposes its capabilities. The runtime translates the
+server's tool list into
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html)
+subclasses the model can call.
+
+#### How it works
+
+The stdio transport runs the server as a child process and
+communicates over stdin/stdout. Use
+[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session)
+to avoid launching the same process multiple times.
+
+```ruby
+require "llm"
+
+llm   = LLM.deepseek(key: ENV["KEY"])
+mcp   = LLM::MCP.stdio(argv: ["npx", "-y", "@forgejo/mcp-server"])
+agent = LLM::Agent.new(llm)
+
+mcp.session do
+  agent.talk "What's happening on forgejo?", tools: mcp.tools
+end
+```
+
+#### Why would I use it?
+
+MCP decouples tool implementation from the agent. Add tools by
+launching a new MCP server. Update them by restarting an existing
+one. Remove them without touching the agent's code.
+
+#### Notes
+
+For stdio, use
+[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session)
+to avoid launching the same process multiple times. For HTTP,
+[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session)
+carries little benefit.
+
+### HTTP
+
+#### Overview
+
+The HTTP transport connects to a remote MCP server over HTTP.
+It is the right choice for cloud-hosted servers like GitHub's
+MCP endpoint. Tools exposed by the server become
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html)
+subclasses the model can call. The server does not need to run
+locally or even on the same machine. Configure headers for
+authentication and pick a transport backend for connection
+management.
+
+#### How it works
+
+When you want to connect to a remote MCP server, provide a URL and
+optional headers. The server's tool list is fetched and translated
+into
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) subclasses the model can call.
+
+```ruby
+require "llm"
+
+llm   = LLM.deepseek(key: ENV["KEY"])
+mcp   = LLM::MCP.http(
+  url: "https://api.githubcopilot.com/mcp/",
+  headers: {
+    "Authorization" => "Bearer #{ENV.fetch('GITHUB_PAT')}"
+  },
+  transport: :net_http_persistent
+)
+agent = LLM::Agent.new(llm)
+agent.talk "What's happening on GitHub?", tools: mcp.tools
+```
+
+#### Why would I use it?
+
+The HTTP transport connects to remote MCP servers. This matters
+when the server is not running locally or when tools are maintained
+by a different team and exposed as a service.
+
+#### Notes
+
+For HTTP,
+[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session)
+carries little benefit.
+
+##### Persistent connections
+
+Set `persistent: true` to reuse HTTP connections across requests
+to the same MCP server. This uses
+[`Net::HTTP::Persistent`](https://github.com/drbrain/net-http-persistent)
+under the hood and avoids the overhead of opening a new TCP
+connection for every request.
+
+```ruby
+mcp = LLM::MCP.http(
+  url: "https://api.githubcopilot.com/mcp/",
+  headers: {"Authorization" => "Bearer #{ENV.fetch('GITHUB_PAT')}"},
+  persistent: true
+)
+```
+