sgcWebSockets 的 MCP stdio 传输

2026年6月1日 · 组件

sgcWebSockets 的 Model Context Protocol (MCP) 组件已经能让你在 Delphi 中通过 HTTP 和 Streamable HTTP 构建 MCP 服务器和客户端。本次发布为两端新增了第三种传输方式：stdio。你的 MCP 服务器现在可以通过标准输入和输出运行，而你的 MCP 客户端可以启动一个服务器可执行文件，并跨越该进程边界与之通信。本地使用时无需 HTTP 监听器、无需端口、无需 TLS 配置。

这一点很重要，因为 stdio 是现代 AI 编码代理连接 MCP 服务器的原生方式。Claude Code、Cursor 等 MCP 客户端会将服务器作为子进程启动，并通过其 stdin 和 stdout 交换 JSON-RPC。借助这种传输方式，Delphi MCP 服务器可以直接融入该生态系统。

stdio 传输是什么

在 stdio 传输中，服务器进程从 stdin 读取以换行符分隔的 JSON-RPC 消息，并将 JSON-RPC 响应写入 stdout，每行一个紧凑的 JSON 对象，以 UTF-8 编码。客户端掌控这一关系：它启动服务器可执行文件，将请求写入子进程的输入管道，并从其输出管道读取响应，通过 JSON-RPC id 将每个响应与对应的请求匹配。服务器发起的通知也通过同一通道传输。

与 HTTP 相比，这里完全没有套接字，也没有任何网络层面。一切都通过同一台机器上父进程与子进程之间继承的管道完成。

通过 stdio 运行 MCP 服务器

新的 TsgcAI_MCP_Server_Stdio 宿主封装了与 HTTP 服务器相同的 MCP 核心，因此你可以像以前一样注册工具、提示和资源。将其构建为控制台应用程序，注册你的工具，然后调用 Run 开始处理消息。

uses
  SysUtils, sgcAI_MCP_Server, sgcAI_MCP_Classes, sgcAI_MCP_Types;

type
  TServerHandler = class
    procedure OnRequestTool(Sender: TObject; const aSession: TsgcAI_MCP_Session;
      const aRequest: TsgcAI_MCP_Request_ToolsCall;
      const aResponse: TsgcAI_MCP_Response_ToolsCall);
  end;

procedure TServerHandler.OnRequestTool(Sender: TObject;
  const aSession: TsgcAI_MCP_Session;
  const aRequest: TsgcAI_MCP_Request_ToolsCall;
  const aResponse: TsgcAI_MCP_Response_ToolsCall);
var
  vA, vB: Double;
begin
  if aRequest.Params.Name = 'add' then
  begin
    vA := aRequest.Params.Arguments.Node['a'].Value;
    vB := aRequest.Params.Arguments.Node['b'].Value;
    aResponse.Result.Content.AddText(FloatToStr(vA + vB));
  end;
end;

var
  oServer: TsgcAI_MCP_Server_Stdio;
  oTool: TsgcAI_MCP_Tool;
  oHandler: TServerHandler;
begin
  oHandler := TServerHandler.Create;
  oServer := TsgcAI_MCP_Server_Stdio.Create(nil);
  try
    oServer.ServerInfo.Name := 'MyDelphiServer';
    oServer.ServerInfo.Version := '1.0';

    // register a tool, exactly like the HTTP server
    oTool := oServer.MCPServer.Tools.AddTool('add', 'Adds two numbers');
    oTool.InputSchema.Properties.AddProperty('a', True, aimcpjtNumber);
    oTool.InputSchema.Properties.AddProperty('b', True, aimcpjtNumber);

    oServer.MCPServer.OnMCPRequestTool := oHandler.OnRequestTool;

    // read JSON-RPC from stdin, write responses to stdout, blocks until EOF
    oServer.Run;
  finally
    oServer.Free;
    oHandler.Free;
  end;
end.

构建 stdio 服务器时有一条规则：stdout 是协议通道，因此绝不要向它写入横幅或日志。请将所有诊断信息发送到 stderr 或文件中。

通过 stdio 连接 MCP 客户端

在客户端这一侧，你保持相同的公共 API。选择 stdio 传输，并通过新的 StdioOptions 告诉客户端要启动哪个可执行文件。客户端会启动该进程、执行 initialize 握手，然后像 HTTP 客户端一样公开工具、提示和资源。

uses
  sgcAI_MCP_Client, sgcAI_MCP_Types;

var
  oClient: TsgcWSAPI_Client_MCP;
begin
  oClient := TsgcWSAPI_Client_MCP.Create(nil);
  try
    // select the stdio transport and point it at the server executable
    oClient.MCPOptions.Transport := aimcptrStdio;
    oClient.MCPOptions.StdioOptions.Command := 'C:\MyServer\MyDelphiServer.exe';
    oClient.MCPOptions.StdioOptions.Arguments := '--stdio';
    oClient.MCPOptions.StdioOptions.WorkingDir := 'C:\MyServer';
    oClient.MCPOptions.StdioOptions.Timeout := 20000;

    // the client launches the server and runs the MCP handshake
    oClient.Initialize;

    // discover tools and call one, the result arrives in OnMCPResponseTool
    oClient.ListTools;
    oClient.RequestTool('add', BuildArguments(2, 3));
  finally
    oClient.Free;
  end;
end;

响应通过常规的 OnMCPResponseTool 事件传递，服务器通知则通过 OnMCPLoggingMessage、OnMCPProgress 以及其他通知事件到达，与 HTTP 传输完全一致。当子进程需要特定的环境变量时，StdioOptions 还接受 Environment 条目。

与 Claude Code 及其他 AI 代理一起使用

由于该传输遵循 MCP stdio 约定，任何符合规范的 MCP 客户端都可以启动你的 Delphi 服务器。要在 Claude Code 中注册它，请在 MCP 配置中添加一个指向你的可执行文件的条目。

{
  "mcpServers": {
    "my-delphi-server": {
      "command": "C:\\MyServer\\MyDelphiServer.exe",
      "args": ["--stdio"]
    }
  }
}

代理会按需启动服务器，列出你注册的工具，并在工作时调用它们。你的 Delphi 代码就此成为 AI 助手的一流工具提供者，无需部署或保护任何 Web 服务器。

优势

没有网络层面。本地使用时无需开放端口、无需 HTTP 监听器、也无需配置 TLS 或身份验证。通信完全通过 stdin 和 stdout 进行。
原生的本地模式。Claude Code 和 Cursor 等 AI 编码工具通过 stdio 启动 MCP 服务器，因此你的服务器无需适配器即可集成。
干净的生命周期与隔离。服务器随客户端进程一起存续与终止。每个客户端对应一个服务器，没有共享状态，也不会留下残余的监听器。
相同的 MCP API。工具、提示和资源的注册方式与 HTTP 服务器完全相同。在客户端切换传输只需设置一个属性。
理想适用于桌面与离线场景。当公开 HTTP 端点既无必要也不可取时，stdio 让一切都留在本地机器内部。
稳健的帧封装。基于 UTF-8 的、以换行符分隔的 JSON-RPC，并在入站消息中容忍前导的字节顺序标记，以实现广泛的客户端兼容性。

升级

stdio 传输是一项即插即用的新增功能。现有的 HTTP 和 Streamable HTTP 服务器与客户端均保持不变，新传输复用了相同的工具、提示和资源模型，因此无需迁移任何内容。要采用它，请围绕 TsgcAI_MCP_Server_Stdio 将你的服务器构建为控制台应用程序，或在客户端将 Transport 设置为 aimcptrStdio。你可以从 sgcWebSockets 下载页面下载最新版本。

有问题、反馈或需要迁移帮助？联系我们，你将收到编写这些代码的人的回复。